Yargs en Node, pasar parámetros en aplicaciones javascript desde consola

Desarrollo Web

Yargs es una librería muy popular y usada dentro del mundo JavaScript, con la cual, podemos parsear parámetros de nuestra aplicación hecha en NodeJs desde la consola de comandos. Aquí te enseñamos como usar este paquete.

Yargs es un paquete que podemos instalar en nuestras propias aplicaciones, con la finalidad de parsear los parámetros que podamos recibir.

En ocasiones, necesitamos crear ciertos scripts que nos ayuden a hacer tareas, como leer archivos, ejecutar scripts cada cierto tiempo, hacer tareas automatizadas, etc. Para esto, normalmente, estos scripts necesitarán que les sean proporcionados ciertos parámetros para que pueda comportarse de forma adecuado de acuerdo a estos.

Parsear parámetros

Hemos visto en muchas aplicaciones que descargamos cuando desarrollamos en JS como webpack, grunt, gulp, nodemon, el mismo npm, etc, y vemos que todos ellos reciben un conjunto de parámetros. Estos son algunos ejemplos

npm install --save-dev paquete
webpack file.js bundle.js
nodemon aplicacion.js
grunt task

Como vemos, la primera palabra se refiere al nombre del comando o del script (npm, webpack, nodemon y grunt) y lo siguiente son parámetros. 

Si eres un programador, sabrás que se torna complicado el poder hacer un módulo por nosotros mismos para controlar estas situaciones, ya que, pueden venir en orden diferente, con abreviaturas, con valores separados por un igual (=) o por un espacio, ser solo banderas, con valores por default, etc. Además, tenemos que agregar una documentación para cada uno de los parámetros que recibe nuestro módulo. Para esto existe Yargs.

Crear ejemplo

Vamos crear un archivo index.js, después, debemos inicializar el módulo con npm init -y. Dentro del archivo index.js vamos a crear un script que imprima los valores usando un número inicial, uno final y un salto entre cada número.

const args = require('yargs').argv

let desde = 1
let hasta = 10
let salto = 2

for(let i = desde; i <= hasta; i+=salto)
    console.log(i)

Como podemos apreciar, si queremos cambiar los tres valores desde, hasta y salto tenemos que cambiarlo directamente en nuestro script, pero imagina que tenemos algo más grande y elaborado y que van a usar muchas más personas, ahí es donde se vuelve tedioso estar modificando las variables, además, estás pueden cambiar de acuerdo al valor de otros, tienen valores default, etc.

Instalar Yargs

En nuestro proyecto de Node, desde la terminal, lo instalamos de la siguiente forma

npm install --save yargs

Uso de Yargs

Importamos el módulo

const arg = require('yargs').argv

Para obtener los valores pasados por consola de la siguiente forma

const arg = require('yargs').argv

console.log(arg.parametro)

Suponiendo que el comando se ejecutó de cualquiera de las siguientes maneras

node index --parametro=10
node index --parametro 10

El resultado del console.log sería de 10.

Definir comandos y opciones

Un comando es aquel que ejecuta una acción y que puede recibir o no opciones adicionales. Una opción es solo un parámetro y su valor. Las opciones pueden ser parte de un comando como también pueden ir independientes.

Un comando tiene la forma

npm index listar --desde=5 --hasta=10

Donde index sería nuestro archivo, listar es el comando y recibe dos parámetros, desde y hasta.

Una opción es solo un parámetro

npm index --formato 2

Index es nuestro archivo y formato nuestra opción. Las características sintácticas de los comandos y opciones son:

  • Los parámetros se definen con dos signos menos (--) antes de la palabra.
  • Los comandos van sin los signos menos (--).
  • Los comandos pueden o no llevar opciones.
  • Las opciones pueden ir sin un comando.
  • No se pueden repetir las opciones, ya sea que estén o no dentro de un comando.
  • Una opción puede o no llevar valores, si los llevasen, deben ir asignados con el signo igual (=) o con un espacio.
  • Las opciones pueden tener una abreviación corta con un signo menos - y una palabra (ejemplo, --desde una abreviación puede ser -d).
  • Los comandos también tienen abreviaciones cortas de solo una letra (ejemplo, install una abreviación puede ser i).

Modificar el ejemplo

Debemos incluir el módulo yargs y obtenemos los parámetros solo obteniendo la propiedad del objeto args.

const args = require('yargs').argv

let desde = args.desde
let hasta = args.hasta
let salto = args.salto

for(let i = desde; i <= hasta; i+=salto)
    console.log(i)

Si ejecutamos en nuestra terminal lo siguiente

node index --desde=10 --hasta=5 --salto=3

Veremos en la consola

PS C:/path/from/your/app> node indes --desde=10 --hasta=5 --salto=3
10
13
16
19
22
25
28
PS C:/path/from/your/app> 

Pero qué pasa si no pasamos uno o más opciones, nos puede marcar un error o bien, el comportamiento no sería el esperado.

Vamos a definir los comandos y las opciones desde el inicio y así, podremos controlar si alguna opción no es definida pueda tomar valores por default

const args = require('yargs')
    .option('desde', {
        alias: 'd',
        default: 1
    })
    .option('hasta', {
        alias: 'h',
        default: 10
    })
    .option('salto', {
        alias: 's',
        default: 1
    })
    .argv

let desde = args.desde
let hasta = args.hasta
let salto = args.salto

for(let i = desde; i <= hasta; i+=salto)
    console.log(i)

Vemos que definimos las opciones usando la función option de yargs, la cual recibe 2 parámetros, el primero es el nombre de la opción y el segundo un objeto con opciones. Las opciones son alias y default, donde alias vendría siendo la bandera corta si es que no queremos usar toda la palabra completa y default el valor predeterminado en caso de no pasarse ningún parámetro. Entonces, podemos prescindir de cualquier parámetro y tendrá un comportamiento adecuado.

PS C:/path/from/your/app> node index --desde=5
5
6
7
8
9
10
PS C:/path/from/your/app>

Como vemos, al tener como default 10 la opción de hasta y 1 la opción de salto, vemos que nos imprime del 1 al 10.

Ahora, supongamos que deseamos que la opción desde sea obligatoria, entonces lo definimos en la función demandOption

const args = require('yargs')
    .option('desde', {
        alias: 'd'
    })
    .option('hasta', {
        alias: 'h',
        default: 10
    })
    .option('salto', {
        alias: 's',
        default: 1
    })
    .demandOption('desde', 'La opción desde es obligatoria')
    .argv

Si necesitamos que sea más de una opción, el primer parámetro lo ponemos como array y dentro las opciones a ser necesarias. Obsérvese que se eliminó el valor default, esto porque si lo dejamos, no serviría de nada poner la opción como obligatoria y lo ignoraría yargs.

Finalmente, puedes consultar el API completa en su página en GitHub, ahí explica como agregar opciones, comandos, hacerlos obligatorios, tratarlos como banderas, poner una descripción, usar la bandera help y más.

Conclusión

Yargs es un módulo útil para crear scripts que puedan ser adaptables de acuerdo a las necesidades de un usuario, nos ayuda a gestionar los parámetros de una manera fácil y sencilla.