seraphim

Configuration loader

Loading configuration files in Node.js have always been a very tedious task, especially when you need to merge objects in cascade, load files asynchronously, load data from external sources like a database, redis, etc., read the CLI options and the environment variables, etc.

This module brings to you a powerful API for loading and merging your configuration data in a few lines.

var seraphim = require ("seraphim");

seraphim.createVault ()
    .on ("error", function (error){
      console.error (error);
    })
    .on ("end", function (config){
      console.log (config);
      /*
      {
        web: {
          log: {
            type: "circular",
            backup: "1week"
          },
          hostname: "a.b.c",
          port: 1234
        }
      }
      */
    })
    //Default settings
    .load ("default.json")
    //NODE_ENV (development) settings
    .load (process.env.NODE_ENV + ".json")
    //Override/merge the previous settings with any object, eg: CLI options
    .load ({ web: { hostname: "a.b.c" } });

//default.json
{
  "web": {
    "log": {
      "type": "circular",
      "backup": "1week"
    }
  }
}

//development.json
{
  "web": {
    "hostname": "1.2.3.4",
    "port": 1234
  }
}

Check this complete example for further details.

Functions

• module.createVault([options]) : Seraphim

Objects

• Seraphim

module.createVault([options]) : Seraphim

Returns a new Seraphim instance.

Options are:

• extensionError - Boolean
  Set it to false if unknown extensions shouldn't emit an error. Default is true.

Seraphim

Events

• end
• error

Methods

• Seraphim#extension(extension, fn) : Seraphim
• Seraphim#get() : Object
• Seraphim#load(resource[, onLoad]) : Seraphim
• Seraphim#merge(o1[, o2]) : undefined | Object

end

Arguments: config.

This event is emitted multiple times, when there are no more pending tasks to load.

config is the final merged object.

Look at the end-event.js example for further details.

error

Arguments: error.

Emitted when an error occurs.

Seraphim#extension(extension, fn) : Seraphim

Allows you to load files with an extension different from .json using the load() function.

extension is a string or an array of strings.

fn is the function that is called when the file to load has the same extension. It has two arguments: the path of the file and a callback. The callback must be called with two parameters: the error and the object with the configuration data.

seraphim.createVault ()
    .on ("error", function (error){
      console.error (error);
    })
    .on ("end", function (config){
      ...
    })
    .extension ([".yaml", ".yml"], function (p, cb){
      fs.readFile (p, { encoding: "utf8" }, function (error, data){
        if (error) return cb (error);
        var obj = parseFile (data);
        cb (null, obj);
      });
    })
    .load ("file1.yaml")
    .load ("file2.yml");

Seraphim#get() : Object

Returns the internal merged object.

Seraphim#load(resource[, onLoad]) : Seraphim

Loads and merges a resource. resource can be a string, object or function.

String

It must be a valid file path.

.load ("file.json");

Object

.load ({ a: { b: 1 } });

Function

Synchronous. Return the object to be merged. Errors thrown here are catched and forwarded to the error event. If a falsy value is returned (null, undefined, false, etc.) it won't be merged.

.load (function (){
  if (condition){
    return { a: 1 };
  }
});

Asynchronous. Use the callback to load the next resource. The first parameter is the error, the second is the object to be merged.

.load (function (cb){
  process.nextTick (function (){
    cb (null, { a: 1 });
  });
});

onLoad is a callback that is executed when load() finishes. It has two arguments: the object to be merged and a callback. The callback allows you to execute any asynchronous function between two load() calls. Please note that if you use the onLoad callback the object is not merged automatically and you'll need to merge it explicitly. This callback it's also try-catched, errors thrown inside the onLoad callback are redirected to the error event.

.load ("file.json", function (o, cb){
  //'o' is the json object
  var me = this;
  asyncFn (function (error, foo){
    //The error is forwarded to the "error" event
    if (error) return cb (error);
    if (foo) o.bar = "baz";
    me.merge (o);
    cb ();
  });
});

The onLoad function can be used to load files without an extension.

Seraphim#merge(o1[, o2]) : undefined | Object

If o2 is not used, o1 is merged with the internal object.
If o2 is used, o2 is merged with o1 and o1 is returned.

console.log (vault.merge ({ a: 1, b: 1 }, { a: 2 }));
//{ a: 2, b: 1 }