yaml-reader

YAML Reader

This is a lightweight reader of yaml files. It's only purpose is to read yaml files to use its attributes in a node app. Therefore it keeps simple and its dependencies low.

The asynchronous read provides promise based and callback based support, thus you can choose the style you like better.

Notes

yaml-reader is written in ECMA 6 (Node version 8.11.1). Be sure your node version can handle this or use babel for older node versions. No guarantee that everything works fine when using babel.

Installation

npm install --save yaml-reader

Usage

yaml-reader resolves the path from your project root onwards, i.e. lets assume the project structure given below. Then you will call yamlReader.read('configs/app-config.yml') wherever you want to read the yaml file. Thus the call will look the same in both bin/app.js and some/deep/project/path/someService.js.

+-- package.json
+-- README.md
+-- bin
+---- app.js
+-- some
+---- deep
+------ project
+-------- path
+---------- someService.js
+---- ...
+-- configs
+---- app-config.yml

Synchronous read

Read a yaml file synchronously. This is like requiring a json config file via require():

const config = require('yaml-reader').read('path/from/project/root/to/yml.yml');

Asynchronous read

You can also read a yaml asynchronously. The result will be returned as a Promise or, if a callback function is provided, with a callback.

Promise based:

const yamlReader = require('yaml-reader');

yamlReader.readAsync('path/from/project/root/to/yml.yml')
.then((config) => {
    ...
})
.catch((err) => {
    ...
})

Callback based:

const yamlReader = require('yaml-reader');

// without options, thus null as 2nd arg
yamlReader.readAsync('path/from/project/root/to/yml.yml', null, (err, config) => {
    if (err) {
        ...
    }
    else {
        ...
    }
})

In all cases you can pass in the encoding of the file with an option object. If this is not passed, utf8 will be used by default.

const options = {
    encoding: yamlReader.constants.ENCODING.UTF_16_LE
};
const config = require('yaml-reader').read('path/from/project/root/to/yml.yml', options);

// or async

yamlReader.readAsync('path/from/project/root/yml.yml', options, (err, config) => {
    ...
}

yamlReader.readAsync('path/from/project/root/yml.yml', options)
.then((config) => {
    ...
})

API

yamlReader.read(file [, options])

yamlReader.readYaml(file [, options])

Read a yaml file synchronously .

• file <string> : The path to the yaml file to read. Resolves from project root onwards. Read "Usage" section to see how it is resolved if unclear
• options <Object | null> : Options parsed to the reader
  • options.encoding <string | null>: The encoding of the yaml file. Is 'utf-8' by default. You can use yaml-reader.constants.ENCODING for supported encodings.

const config = require('yaml-reader').read('path/from/project/root/to/yml.yml');

Or with encoding specified:

const options = {
    encoding: yamlReader.constants.ENCODING.UTF_8
};
const config = require('yaml-reader').read('path/from/project/root/to/yml.yml', options);

yamlReader.readAsync(file [, options, callback])

yamlReader.readYamlAsync(file [, options, callback])

Read a yaml file asynchronously. The yaml attributes will be returned with a Promise.

• file <string> : The path to the yaml file to read. Resolves from project root onwards. Read "Usage" section to see how it is resolved if unclear
• options <Object | null> : Options parsed to the reader
  • options.encoding <string | null>: The encoding of the yaml file. Is 'utf-8' by default. You can use yaml-reader.constants.ENCODING for supported encodings.
• callback <function | null> : An optional callback. If this is null the reader assumes you use Promises instead. So take care to use the promise syntax if you do not provide a callback.

The config is either returned as a Promise<Object>.resolve if the file was readable or rejected otherwise, or with the callback if invoked with a callback.

const yamlReader = require('yaml-reader');
const options = { ... }
//
// awaiting promises
//

yamlReader.readAsync('path/from/project/root/to/yml.yml', options)
.then((config) => {
    // access properties of your yaml
    // console.log(config.myProperty)
})
.catch((err) => {
    // handle errors (like FileNotFoundError)
})

//
// or with callback
//

yamlReader.readAsync('path/from/project/root/to/yml.yml', options, (err, config) => {
    ...
}