Bureaucat NPM | npm.io

bureaucat

Transforms & normalizes JSON structures like a bureaucat ( using templates )

Install

$ npm install --save bureaucat

Usage

To use bureaucat you must first create a transform function by passing a template. This will return a function which can then be used for transforming a document compatible with the initially set template.

var bureaucat = require('bureaucat'),
    template  = require('./template'),
    bc        = bureaucat(template);

bc({
    "cats": ["Tardar Sauce", "Garfield"]
});

// returns transformed template

1.1 Example invocation

options

bureaucat supports the following options which are passed as an optional second arguments as an object.

var bc = bureaucat(template, {
        prefix: 'bc::'    // should resolvable values be prefixed with a token?
    });

prefix values which are to be resolved should follow the format of .value>

Templates

A template defines the rules used for transformation, and generally reflects what the result will look like after transformation.

// template.js
module.exports = {
    "cats": {
        "famous": {
            "real"   : "cats[0]",
            "cartoon": "cats[1]"
        }
    }
};
// result
{
    "cats": {
        "famous": {
            "real"   : "Tardar Sauce",
            "cartoon": "Garfield"
        }
    }
}

1.2 An example of a template

Values

Each key value in a template represents a dot notation string which is used to access data from the original document.

some.data.value
some.array0.value
some.array0.value

1.3 An example of keys

Note any value will be interpreted as a possible key. Or traversed in the case of an Array or Object, in search of a key.

Specify a prefix via options for more control over this behavior.

Advanced

A ::bc transformation object can be used to provide finer control over the transformation of a value. To use this feature you must structure your template as per the below example.

module.exports = {
    "cats": {
        "::bc": {
            "key"      : "cats"
            "normalize": [function () {}, function () {}],
            "template": {
                "name": "@this"
            }
        }
    }
}

1.4 An example of an advanced template

Note @this denotes the current value within the context of an Array / Input.

key

Where to obtain the value from

template

This is particularly useful when the value is an array. It allows a transformation to applied based on the specified template to each value in the array. Using the template example in figure 1.4 the following transformation would occur.

// from

transform({
    "cats": ["Tardar Sauce", "Garfield"],
});

// to
{
    "cats": [
        { "name": "Tardar Sauce" },
        { "name": "Garfield"     }
    ]
}

1.5 A transformation using an advanced template

template function

A template can also be a function. When used a resolved value is passed to the template. This permits a different template to be selected depending upon the value passed.

module.exports = {
    "cats": {

        "::bc": {
            "key"      : "cats"
            "normalize": [function () {}, function () {}],
            "template" : function (value) {

                if (value === 'Garfield') {
                    return {
                        "name"    : "@this",
                        "dislikes": ['Monday']
                    };
                }

                if (value === 'Tardar Sauce') {
                    return {
                        "name"    : "@this",
                        "dislikes": ['everything']
                    };
                }

                return {
                    "name": "@this"
                };

            }
        }

    }
};

1.6 A transformation using an advanced template function

normalize

This is used to specify 1 or more functions to run against the currenty selected value. A normalizer should have the following interface.

function a_normalizer(value) {
    ... do something ...
    return modifiedValue;
}

1.7 Defining a normalizer

pre & post normalize

Normalizers are run prior to transforming via a template if specified, but can also be run post transformation using the format below.

module.exports = {
    "cats": {
        "::bc": {
            "key"      : "cats",
            "normalize": {
                    pre : [function () {}, function () {}],
                    post: [function () {}, function () {}]
            },
            "template": {
                    .....
            }
        }
    }
};

pre: run before template transform
post: run after tremplate transform

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using npm test

Release History

2.0.2 Fix ::bc lookup when key undefined
2.0.1 Ensure booleans & like booleans are retained ( eg: 0 || false )
2.0.0 If a value cannot be resolved it is excluded. Use options.prefix to avoid this behavior
1.0.3 Fixed regression introduced in 1.0.1 with advanced object
1.0.2 Move string check higher in execution order for process
1.0.1
- skip non-parsable inputs eg: number
- added support for options.prefix for value resolution
1.0.0 If a value cannot be resolved fallback to passed value
0.1.3 Added support for processing Arrays
0.1.2 node 12 & iojs fixes
0.1.1 Lint fixes
0.1.0 Initial release