roman-numerals-dm v1.0.2

Números romanos

Índice

• 1. Preámbulo
• 2. Resumen del proyecto
• 3. Objetivos de aprendizaje
• 4. Consideraciones generales
• 5. Criterios de aceptación mínimos del proyecto
• 6. Pistas, tips y lecturas complementarias

1. Preámbulo

La numeración romana es un sistema de numeración que se desarrolló en la Antigua Roma y se utilizó en todo el Imperio romano, manteniéndose con posterioridad a su desaparición y todavía utilizado en algunos ámbitos.

Este sistema emplea algunas letras mayúsculas como símbolos para representar ciertos valores. Los números se escriben como combinaciones de letras. Por ejemplo, el año 2020 se escribe como MMXX, donde cada M representa 1000 unidades y cada X representa 10 unidades más.

Está basado en la numeración etrusca, la cual, a diferencia de la numeración decimal que está basada en un sistema posicional, se basa en un sistema aditivo (cada signo representa un valor que se va sumando al anterior). La numeración romana posteriormente evolucionó a un sistema sustractivo, en el cual algunos signos en lugar de sumar, restan. Por ejemplo el 4 en la numeración etrusca se representaba como IIII (1+1+1+1), mientras que en la numeración romana moderna se representa como IV (1 restado a 5).

Fuente: Numeración romana - Wikipedia

2. Resumen del proyecto

En este proyecto construirás un módulo de JavaScript (instalable via npm) que permita al usuario converir números arábigos en números romanos y viceversa. El paquete (lo que instalamos a través de npm) también debe incluir un script ejecutable que nos permita usar la librería desde el terminal (CLI).

Además de ofrecer la funcionalidad directamente en JavaScript como módulo que podemos requerir o importar, y la interfaz de línea de comando, te invitamos también a construir alguna interfaz más (y en otro ambiente) que haga uso de dicha librería:

• Un slash command de Slack que nos permita usar el módulo desde la interfaz de Slack.
• Un conversor de números arábigos a romanos como aplicación nativa para celular
• Una extensión para el navegador (Firefox o Chrome) que permita hacer la conversión de números.

Esto podríá organizarse como un equipo o más, cada uno con un entregable distinto, pero que integren el módulo construido como parte central.

3. Objetivos de aprendizaje

Reflexiona y luego marca los objetivos que has llegado a entender y aplicar en tu proyecto. Piensa en eso al decidir tu estrategia de trabajo.

Node.js

• Instalar y usar módulos con npm

  • Sitio oficial de npm (en inglés)

• Configuración de package.json

  • package.json - Documentación oficial (en inglés)

• Configuración de npm-scripts

  • scripts - Documentación oficial (en inglés)

• process (env, argv, stdin-stdout-stderr, exit-code)

  • Process - Documentación oficial (en inglés)

JavaScript

• Tipos de datos primitivos

  • Valores primitivos - MDN

• Diferenciar entre tipos de datos primitivos y no primitivos

• Strings (cadenas de caracteres)

  • Strings
  • String — Cadena de caracteres - MDN

• Arrays (arreglos)

  • Arreglos
  • Array - MDN
  • Array.prototype.sort() - MDN
  • Array.prototype.forEach() - MDN
  • Array.prototype.map() - MDN
  • Array.prototype.filter() - MDN
  • Array.prototype.reduce() - MDN

• Objetos (key, value)

  • Objetos en JavaScript

• Variables (declaración, asignación, ámbito)

  • Valores, tipos de datos y operadores
  • Variables

• Uso de condicionales (if-else, switch, operador ternario, lógica booleana)

  • Estructuras condicionales y repetitivas
  • Tomando decisiones en tu código — condicionales - MDN

• Uso de bucles/ciclos (while, for, for..of)

  • Bucles (Loops)
  • Bucles e iteración - MDN

• Funciones (params, args, return)

  • Funciones (control de flujo)
  • Funciones clásicas
  • Arrow Functions
  • Funciones — bloques de código reutilizables - MDN

• Pruebas unitarias (unit tests)

  • Empezando con Jest - Documentación oficial

• Módulos de CommonJS

  • Modules: CommonJS modules - Node.js Docs

• Uso de linter (ESLINT)

• Uso de identificadores descriptivos (Nomenclatura y Semántica)

Control de Versiones (Git y GitHub)

• Git: Instalación y configuración

• Git: Control de versiones con git (init, clone, add, commit, status, push, pull, remote)

• Git: Integración de cambios entre ramas (branch, checkout, fetch, merge, reset, rebase, tag)

• GitHub: Creación de cuenta y repos, configuración de llaves SSH

• GitHub: Colaboración en Github (branches | forks | pull requests | code review | tags)

• GitHub: Organización en Github (projects | issues | labels | milestones | releases)

4. Consideraciones generales

• El equipo de coaches te dará un tiempo sugerido e indicaciones sobre si trabajar sola o en equipo. Recuerda que cada una aprende a diferente ritmo.

• La librería y el script ejecutable (herramienta de línea de comando - CLI) deben estar implementados en JavaScript para ser ejecutados con Node.js. Está permitido usar librerías externas.

• Tu módulo debe ser instalable via npm install <github-user>/roman-numerals. Este módulo debe incluir tanto un ejecutable que podamos invocar en la línea de comando como una interfaz que podamos importar con require para usarlo programáticamente.

• Las pruebas unitarias deben cubrir un mínimo del 80% de statements, functions, lines y branches. Te recomendamos explorar Jest para tus pruebas unitarias.

5. Criterios de aceptación mínimos del proyecto

Módulo instalable

Tu módulo debe estar alojado en un repo en GitHub y debe contener un archivo package.json. Estas dos cosas hacen posible que el módulo se pueda instalar usando npm y la ruta del repo en GitHub. Por ejemplo:

npm install usuario-de-github/roman-numerals

API de JavaScript

El módulo debe exportar un objeto con dos métodos:

• parse(str): Recibe un String como único argumento y retorna un número (Number) en caso que sea un número romano válido, en caso contrario arrojará un error especificando la causa.
• stringify(num): Recibe un número (Number) y retorna un String con la representación del número recibido como número romano. En caso de que el número esté fuera de rango (1 <= num <= 3999).

Ejemplo de uso:

const { parse, stringify } = require('usuario-de-github/roman-numerals');

console.log(parse('I') === 1); // true
console.log(parse('III') === 3); // true
console.log(parse('IV') === 4); // true
console.log(parse('IX') === 9); // true
console.log(parse('MCMXLIV') === 1944); // true

console.log(stringify(1) === 'I'); // true
console.log(stringify(3) === 'III'); // true
console.log(stringify(4) === 'IV'); // true
console.log(stringify(9) === 'IX'); // true
console.log(stringify(1944) === 'MCMXLIV'); // true

console.log(parse(stringify(1)) === 1); // true
console.log(parse(stringify(3)) === 3); // true
console.log(parse(stringify(4)) === 4); // true
console.log(parse(stringify(9)) === 9); // true
console.log(parse(stringify(1944)) === 1944); // true

Interfaz de línea de comando (CLI - Command Line Interface)

Asegúrate que tu package.json incluye la llave bin para que tu módulo explícitamente exponga la interfaz de línea de comando. Esto nos va a permitir instalar el comando roman-numerals de forma global y quede siempre disponible en tu terminal, además de permitir que se invoque usando el comando npx (una herramienta que viene con node y npm).

Esta interfaz debe ofrecer dos sub-comandos (parse y stringify) además de opciones para mostrar ayuda (-h y --help) y la versión del módulo (-v y --version).

Ambos parse y stringify deben permitir input como argumento de línea de comando (argv) o alternativa a través de stdin.

Ejemplos

Ejecutando directamente a través de la ruta relativa al script bin/cli.js:

$ ./bin/cli.js parse MMXX
2020

$ ./bin/cli.js stringify 2020
MMXX

Usando npx:

$ npx roman-numerals parse MMXX
2020

$ npx roman-numerals stringify 2020
MMXX

Usando stdin:

$ echo MMXX | npx roman-numerals parse
2020

$ echo 2020 | npx roman-numerals stringify
MMXX

Mostrar versión:

$ npx roman-numerals -v
1.0.0

Mostrar ayuda:

$ npx roman-numerals -h
Usage: roman-numerals [opttions] <command> [<input>]

Commands:
  parse <input>      Parse a roman numeral string into an integer.
  stringify <input>  Takes an integer and converts it to a roman numeral.

Options:
  -h,--help     Show this help.
  -v,--version  Show version number.

6. Pistas, tips y lecturas complementarias

• Acerca de Node.js - Documentación oficial
• learnyounode
• ¿Qué es Node.js y para qué sirve? - drauta.com
• ¿Qué es Nodejs? Javascript en el Servidor - Fazt en YouTube
• ¿Simplemente qué es Node.js? - IBM Developer Works, 2011
• Node.js y npm
• process.stdin - Node.js Docs
• process.argv