Leer y escribir YAML en un archivo en Node.js / JavaScript

Introducción

En los últimos años, YAML, que significa YAML Ain’t Markup Language, se ha vuelto muy popular para su uso en el almacenamiento de datos de manera serializada, generalmente archivos de configuración. Dado que YAML es esencialmente un formato de datos, la especificación YAML es bastante breve. Por lo tanto, la única funcionalidad requerida de las bibliotecas YAML es la capacidad de analizar o generar archivos con formato YAML.

En este artículo, veremos cómo puede utilizar YAML con una aplicación Node.js. Comenzaremos viendo cómo se almacenan los datos en un archivo YAML, y luego cargaremos esos datos en un objeto JavaScript. Por último, aprenderemos cómo almacenar un objeto JavaScript en un archivo YAML.

Hay algunas bibliotecas de node populares que se utilizan para analizar y generar YAML: yaml y js-yaml. js-yaml es la más popular de las dos bibliotecas, por lo que nos centraremos en este artículo.

Antes de seguir adelante, existen algunos requisitos previos para este tutorial. Debe tener un conocimiento básico de la sintaxis de JavaScript, específicamente para el tiempo de ejecución de Node.js. También querrá tener Node.js y NPM instalados en su sistema para seguir adelante. Aparte de eso, el tutorial es bastante simple y fácil de seguir para principiantes.

Instalación

Como con cualquier paquete de Node, la instalación es bastante simple usando NPM:

$ npm install js-yaml

Solo asegúrese de usar los indicadores correctos para guardar la dependencia en su archivo package.json. Por ejemplo, si js-yaml solo se usa con fines de desarrollo, luego use --save-dev, de lo contrario use --save si se usa en el entorno de producción de su aplicación.

Puede verificar que esté instalado correctamente abriendo el REPL desde el mismo directorio e importando el paquete con lo siguiente:

$ node
> const yaml = require('js-yaml')
>

los js-yaml La biblioteca también admite el uso de CLI, lo que le permite inspeccionar archivos YAML desde la línea de comandos. Puede habilitar esto instalando el paquete globalmente:

$ npm install -g js-yaml

Leyendo archivos YAML en Node.js

Comenzaremos leyendo un archivo con formato YAML y analizándolo en un objeto JS. Por el bien de este tutorial, digamos que tenemos un archivo, data.yaml, que tiene el siguiente contenido:

--- # Article data
  title: "Reading and Writing YAML to a File in Node.js/JavaScript"
  url path: "/reading-and-writing-yaml-to-a-file-in-node-js-javascript"
  domain: "Pharos.sh.com"
  port: 443
  is-https: true
  meta:
    published-at: "Nov. 1st, 2019"
    author:
      name: "Scott Robinson"
      contact: "[email protected]"
    tags:
      - javascript
      - node.js
      - web development

Para leer y analizar este archivo, usaremos el .safeLoad() método:

// read.js
const fs = require('fs');
const yaml = require('js-yaml');

try {
    let fileContents = fs.readFileSync('./data.yaml', 'utf8');
    let data = yaml.safeLoad(fileContents);

    console.log(data);
} catch (e) {
    console.log(e);
}

La ejecución de este código generará lo siguiente:

$ node read.js
{ title: 'Reading and Writing YAML to a File in Node.js/JavaScript',
  'url path': '/reading-and-writing-yaml-to-a-file-in-node-js-javascript',
  domain: 'Pharos.sh.com',
  port: 443,
  'is-https': true,
  meta:
   { 'published-at': 'Nov. 1st, 2019',
     author: { name: 'Scott Robinson', contact: '[email protected]' },
     tags: [ 'javascript', 'node.js', 'web development' ] } }

Puede ver que los datos del archivo YAML ahora se convierten en objetos y literales JS en la misma estructura que el archivo.

los .safeLoad() Se recomienda el método para analizar contenido YAML, ya que es seguro para datos que no son de confianza. Una limitación que vale la pena señalar es que este método no admite fuentes de varios documentos. Si está familiarizado con YAML, sabrá que YAML puede contener varios «documentos» dentro de un solo archivo, que están separados por el --- sintaxis. Por ejemplo:

--- # Programming language
  language: "JavaScript"
  created-at: "December 4, 1995"
  domain: "Pharos.sh.com"
  creator: "Brendan Eich"
--- # Website
  domain: "wikipedia.org"
  created-at: "January 15, 2001"
  num-languages: 304
  num-articles: 51360771
  creator:
    - Jimmy Wales
    - Larry Sanger

Cargando este archivo con .safeLoad() lanzará una excepción. En su lugar, debe utilizar el .safeLoadAll() método, así:

// read-all.js
const fs = require('fs');
const yaml = require('js-yaml');

try {
    let fileContents = fs.readFileSync('./data-multi.yaml', 'utf8');
    let data = yaml.safeLoadAll(fileContents);

    console.log(data);
} catch (e) {
    console.log(e);
}

Esto da como resultado una matriz de documentos YAML analizados:

$ node read-all.js
[ { language: 'JavaScript',
    'created-at': 'December 4, 1995',
    domain: 'Pharos.sh.com',
    creator: 'Brendan Eich' },
  { domain: 'wikipedia.org',
    'created-at': 'January 15, 2001',
    'num-languages': 304,
    'num-articles': 51360771,
    creator: [ 'Jimmy Wales', 'Larry Sanger' ] } ]

Otro método que vale la pena mencionar es el .load() método, que es muy similar a .safeLoad(), excepto que es compatible con todos Tipos de esquema YAML. Los tipos adicionales admitidos son específicos de JavaScript (!!js/undefined, !!js/regexpy !!js/function) y debe confiar absolutamente en los datos de estos archivos YAML, ya que pueden cargar código que no es de confianza.

Por ejemplo, una función se puede definir en YAML como la siguiente:

'toString': !<tag:yaml.org,2002:js/function> function() {console.log('Malicious code execuited!');}

Esa etiqueta le dice a nuestra biblioteca YAML que la analice como una función, que luego se puede ejecutar más tarde. Como se señala en la documentación, un método común que se ejecuta en objetos JS es toString, que podemos explotar así:

// unsafe.js
const yaml = require('js-yaml');

let yamlStr = "'toString': !<tag:yaml.org,2002:js/function> function() {console.log('Malicious code execuited!');}";
let loadedYaml = yaml.load(yamlStr) + '';
console.log(loadedYaml);

Y ejecutar este código muestra que el console.log de hecho se ejecuta el método:

$ node unsafe.js 
Malicious code execuited!
undefined

Escribir YAML en archivos en Node.js

Ahora que sabe cómo leer archivos YAML con Node.js, veamos cómo podemos escribir objetos / datos JavaScript en un archivo YAML.

Para este ejemplo, usaremos el siguiente objeto JS, que puede reconocer de los ejemplos anteriores:

let data = {
    title: 'Reading and Writing YAML to a File in Node.js/JavaScript',
    'url path': '/reading-and-writing-yaml-to-a-file-in-node-js-javascript',
    domain: 'Pharos.sh.com',
    port: 443,
    'is-https': true,
    meta: {
        'published-at': 'Nov. 1st, 2019',
        author: {
            name: 'Scott Robinson',
            contact: '[email protected]'
        },
        tags: [
            'javascript', 'node.js', 'web development'
        ]
    }
};

Para serializar este objeto y guardarlo en un archivo con formato YAML, usaremos el .safeDump() método, que nuevamente usa js-yamles DEFAULT_SAFE_SCHEMA:

// write.js
const fs = require('fs');
const yaml = require('js-yaml');

let data = { /* Same as above */};

let yamlStr = yaml.safeDump(data);
fs.writeFileSync('data-out.yaml', yamlStr, 'utf8');

Al ejecutar este código, se escribirá un archivo YAML que se ve así:

title: Reading and Writing YAML to a File in Node.js/JavaScript
url path: /reading-and-writing-yaml-to-a-file-in-node-js-javascript
domain: Pharos.sh.com
port: 443
is-https: true
meta:
  published-at: 'Nov. 1st, 2019'
  author:
    name: Scott Robinson
    contact: [email protected]
  tags:
    - javascript
    - node.js
    - web development

Esta salida es casi idéntica al YAML original que leímos anteriormente en el artículo, excepto que el separador de documentos (---) no esta incluido.

Tipos de datos

Es importante tener en cuenta que no todos los tipos de datos de JavaScript se pueden serializar directamente en YAML y viceversa. En algunos casos, se utilizará el tipo de datos más cercano cuando sea posible si no se admite directamente. Por ejemplo, un YAML !!seq type se analizará como una matriz de JavaScript.

De acuerdo con la documentación js-yaml, se admiten los siguientes tipos de datos:

Ejemplo de tipo YAML Tipo JS

Como se mencionó anteriormente, también se pueden admitir otros tipos específicos de JS, pero solo si no está utilizando los métodos «seguros».

Conclusión

YAML es un formato cada vez más popular que se usa para estructurar datos para aplicaciones, generalmente como archivos de configuración, pero también como reemplazo de cualquier cosa para la que se usa JSON. Debido a su alta flexibilidad y sintaxis fácil de leer, está reemplazando rápidamente a JSON en muchos proyectos, aunque ambos todavía tienen su lugar.

En este artículo mostramos cómo puede utilizar el js-yaml biblioteca para analizar archivos YAML en objetos JavaScript en Node.js y cómo se pueden serializar objetos JavaScript en un archivo YAML. También mostramos qué tipos de JS se utilizan para varios tipos de datos YAML. Para obtener más detalles sobre esta biblioteca, consulte la documentación oficial.

.