This package has been deprecated

    Author message:

    This module is no longer maintained. If you're interested in taking over maintenance of this repo, please contact the author

    conifer

    1.0.0 • Public • Published

    Conifer

    A multi-format, file-based configuration library for Node. It streamlines reading and parsing configurations from JSON, CSON and YAML files, with support for adding your own file-type handlers.

    Current Stable Version: 1.0.0
    Automated Build Status: Build Status

    Installing

    Install Conifer through npm. Either with the command:

    npm install conifer

    or by adding conifer to the dependencies in your project package.json.

    Basic Usage

    You can use Conifer with JavaScript or CoffeeScript:

    var conifer = require('conifer');
    conifer = require 'conifer'

    In the examples below, it's assumed that you've required Conifer as above.


    conifer.parse

    This function parses a config file asynchronously. It accepts two arguments – a file path and a callback function. The file path must be an unempty string and the callback should accept two arguments itself: an error object and the parsed config.

    conifer.parse('example.json', function (err, config) {
        if (err !== null) {
            throw err;
        }
        // do something with `config`
    });

    In the callback, err will be null on success, or an Error object on failure. config will be either an object containing your configurations on success or null.


    conifer.parseSync

    This function parses a config file synchronously. It accepts a single argument – a file path. The file path must be an unempty string. This function returns an object containing your configurations on success, and throws if parsing fails.

    config = conifer.parseSync('example.json');

    Configuration Importing

    Your config files are able to import other configurations as properties, or by merging them into the current object. This allows for a single entry-point for your configuration, as well as a more managable and reusable set of config files.

    Examples below are mostly in JSON but this will work for all supported file types, as well as allowing for cross-file-type importing.

    Import Properties

    Import properties allow you to import the contents of another config file into a property. They work on a property whose (string) value begins with <<. So if we have the following files:

    config/main.json:

    {
        "name": "Hello World",
        "routes": "<< ./routes.json"
    }

    config/routes.json:

    {
        "/": "controller/index",
        "/about": "controller/about",
    }

    Parsing config/main.json will result in the following structure:

    {
        "name": "Hello World",
        "routes": {
            "/": "controller/index",
            "/about": "controller/about",
        }
    }

    Import Merges

    Import merges allow you to merge the contents of another config file into the current object. Merges are indicated by the << property of an object, which should be set to an array of file names. If we have the following files:

    config/main.json:

    {
        "name": "Hello World",
        "outputErrors": true,
        "<<": [
            "./production.json"
        ]
    }

    config/production.json:

    {
        "outputErrors": false,
        "logErrors": true
    }

    Parsing config/main.json will result in the following structure:

    {
        "name": "Hello World",
        "outputErrors": false,
        "logErrors": true
    }

    Extending With File Handlers

    Conifer can be extended to work with almost any configuration format. It's just a case of writing a handler for that file type. The handler API is extremely simple:

    conifer.handler.setHandler

    This function adds a new handler. It accepts two arguments – a file extension and a handler function. The handler function should accept a content string and return a successfully parsed object or throw an error.

    conifer.handler.setHandler('xml', function (fileContent) {
        try {
            return myMagicXmlLib.parse(fileContent);
        } catch (error) {
            throw error;
        }
    });

    With the above code, any call to conifer.parse or conifer.parseSync with a file path that has a .xml extension will use the specified handler function to parse the file content.


    conifer.handler.getHandler

    This function gets a handler that's been set already. This function accepts a single argument – the file extension to get the handler for, and returns the requested function.

    conifer.handler.getHandler('json'); // [Function]

    conifer.handler.removeHandler

    This function removes a handler that's been set already. This function accepts a single argument – the file extension to get the handler for.

    conifer.handler.removeHandler('json');
    conifer.handler.getHandler('json'); // undefined

    Development

    In order to develop Conifer, you'll need to install the following npm modules globally like so:

    npm install -g coffee-script
    npm install -g jake
    

    And then install development dependencies locally with:

    npm install
    

    Once you have these dependencies, you will be able to run the following commands:

    jake build: Build JavaScript from the CoffeeScript source.

    jake lint: Run CoffeeLint on the CoffeeScript source.

    jake test: Run all unit tests.

    License

    Conifer is licensed under the MIT license.

    Keywords

    none

    Install

    npm i conifer

    DownloadsWeekly Downloads

    1

    Version

    1.0.0

    License

    none

    Last publish

    Collaborators

    • rowanmanning