Bolgia

Bolgia, an helper module for the config hell.

It recursively clone, mix, update and improve configuration objects/hashes with nested properties.

˝..non ragioniam di lor, ma guarda e passa..˝

Install

$ npm install bolgia [-g]
// clone repo
$ git clone [email protected]:rootslab/bolgia.git

require

var Bolgia  = require( 'bolgia' );

require returns an helper hash/obj with some properties/methods. See examples.

Run Tests

$ cd bolgia/
$ npm test

Properties

/*
 * Property that holds all possible types/strings returned by Object#toString,
 * with some custom types like for node Buffers: "[object Buffer]".
 *
 * See Bolgia#toString method.
 *
 */
Bolgia#circles : Object

Methods

Arguments within [ ] are optional.

/*
 * simple object/hash cloning
 */
Bolgia#clone( Object obj ) : Object

/*
 * mix/update dest object with all properties
 * from src, with no recursion.
 * It brutally overwrites dest properties/values.
 * It returns the dest Object.
 */
Bolgia#mix( Object dest, Object src ) : Object

/* 
 * improve a dest object with all properties/values
 * from a src object, with recursion.
 * It doesn't overwrite properties/values that already
 * exist in the dest object.
 * It returns the dest Object.
 */
Bolgia#improve( Object dest, Object src ) : Object

/* 
 * update a dest object with all properties/values
 * from a src object, with recursion.
 * It brutally overwrites dest properties/values.
 * It returns the dest object.
 */
Bolgia#update( Object dest, Object src ) : Object

/* 
 * A methods that returns a toString() representation of an object.
 *
 * NOTE: It differs from Object.toString(), because for default, it
 * returns:
 *
 * - "[object Buffer]" for node Buffers
 * - "[object Null]" for NaN
 * - "[object Null]" for empty string ''
 *
 * NOTE: If custom is true, it returns:
 *
 * - "[object NaN]" for NaN
 * - "[object NullString]" for ''
 */
Bolgia#toString( Object o [, Boolean custom ] ) : String

/*
 * #toString alias.
 */
Bolgia#doString( Object o [, Boolean custom ] ) : String

/*
 * Recursively convert an obj/hash to an array.
 * It optionally accepts a boolean to activate recursion
 * and an array to collect results.
 *
 * NOTE: when using indexed arrays, every element will be
 * preceded by its index.
 */
Bolgia#toArray( Object obj [, Boolean recur [, Array result ] ] ) : Array

/*
 * Same as the method above, but it lists only enumerable properties
 */
Bolgia#toArrayEnum( Object obj [, Boolean recur [, Array result ] ] ) : Array

/*
 * Recursively convert an indexed array to an hash/obj;
 * optionally it converts Buffers to Strings and Strings
 * representing numbers to Numbers.
 *
 * NOTE: Array elements are interpreted as a series of key/value pairs.
 * NOTE: Pay attention to possible keys collisions/overwritings.
 * NOTE: Every nested array will be converted to an obj/hash.
 */
Bolgia#toHash( Array array [, Boolean recur [, Object result [, Boolean convert ] ] ] ) : Object

/*
 * Recursively convert a nested Array of Buffer items to Strings and Numbers.
 *
 * NOTE the max integer precision is +/- 2^53, if a string/buffer represents a numeber
 * that is >= 9007199254740992, or <= -9007199254740992, than it will be not converted
 * to Number.
 *
 * NOTE: It returns/converts the same array instance passed as argument.
 */
Bolgia#reveal( Array array ) : Array

/*
 * Recursively count obj properties, or
 * only non-object properties (leafs).
 */
Bolgia#count( Object obj [, Boolean leaf ] ) : Number

/*
 * Method to output a (query)string representation of an hash.
 * It requires an object to parse and optionally a configuration object.
 * It is possible to specify custom symbols for delimiting and equality,
 * defaults are '&' and '='.
 *
 * NOTE: for default, null, undefined and function values are filtered
 * away; to bypass this behaviour, it is possible to specify a custom 
 * function, for choosing which types are allowed for querystring.
 * This function gets 3 args: Object field, String ftype, Object circles.
 *
 * default configuration:
 *
 * {
 *   dl : '&'
 *   , eq : '='
 *   , filter : function ( field, ftype, circles ) {
 *      switch ( ftype ) {
 *          case circles.nul:
 *          case circles.und:
 *          case circles.fun:
 *          break;
 *          default:
 *              return true;
 *          break;
 *      };
 *   }
 * }
 */
Bolgia#qs( Object hash [, Object opt ] ) : String

/*
 * Method to output a (query)object representation of an hash.
 * It converts all paths, to the object's nested values ( leafs ),
 * to querystring keys.
 */
Bolgia#flatten( Object hash ) : Object

Sample Usage

require libs:

var log = console.log,
    , util = require( 'util' )
    , Bolgia = require( 'bolgia' );

define a default configuration object/hash:

var cfg = {
    letters : [ 'aaa', 'bbb', 'ccc','ddd' ]
    , numbers : {
        1 : false
        , 2 : false
        , 3 : false
        , 4 : false
    }
    , hell : {
        h1 : {
            a : [ 'a1!', 'a2!', 'a3!' ]
            , b : [ 'b1!', 'b2!', 'b3!' ]
        }
        , h3 : {
            1 : 0
            , 2 : 0
        }
    }
};

define a custom update object/hash:

var upd = {
    letters : [ undefined, 'BBB', 'CCC', undefined, 'EEE' ]
    , numbers : {
        1 : true
        , 3 : Infinity
        , 4 : null
    }
    , hell : {
        h1 : {
            a : [ undefined, 'A2!' ]
            , b : [ 'B1!', undefined, 'B3!' ]
            , e : [ undefined, 'E2!', 'E3!' ]
        }
        , h2 : 'BLAH'
        , h3 : {
            2 : new Date( '1913' )
        }
    }
};

update cfg with upd, and output results to console:

Bolgia.update( cfg, upd );

log( util.inspect( cfg, !true, null, true ) );

/* 
 * NOTE: sub-properties like arrays and hashes 
 * are not brutally overwritten, but finely updated
 */

{
    letters: [ 'aaa', 'BBB', 'CCC', 'ddd', 'EEE' ]
    , numbers : {
        1 : true
        , 2 : false
        , 3 : Infinity
        , 4 : null
    }
    , hell : {
        h1 : { a: [ 'a1!', 'A2!', 'a3!' ]
        , h2 : 'BLAH'
            b : [ 'B1!', 'b2!', 'B3!' ]
            , e : [ undefined, 'E2!', 'E3!' ] }
        h3 : {
            1 : 0
            , 2 : Wed Jan 01 1913 01:00:00 GMT+0100 (CET)
        }
    }
}

See readme-example

MIT License

Copyright (c) 2013-present < Guglielmo Ferri : [email protected] >

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.