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.array[0].value
• some.array[0][1].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

License

Copyright (c) 2015 Jonathan Barnett. Licensed under the MIT license.