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.jsmodule.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.