Json-Transmute - Simplify Your Code
Simplify your code (and your data) by defining JSON data maps that return only the data you need in common denominator formats.
Install
Install from npm:
$ npm install json-transmuteExample
var transmute = require('json-transmute');
var scope = {
"Product": {
"title": "ACME super soaker",
"price": "25.00",
"variants": [
{ "color": "red", "stock": "5" },
{ "color": "blue", "stock": "3" },
{ "color": "green", "stock": "0" }
],
"shipping": {
"methods": {
"nextDay": { "name": "Next Day Air", "cost": "45.00" },
"secondDay": { "name": "Second Day Air", "cost": "30.00" },
"economy": { "name": "Free Economy Shipping", "cost": "0.00" }
}
}
}
};
var map = {
"productArr[Product.variants]": [
{
"title": "^Product.title",
"price": "^Product.price",
"'color'": "color",
"inStock": "stock | bool"
}
]
};
var simpleData = transmute(scope, map);
// {
// "productArr": [
// {
// "title": "ACME super soaker",
// "price": "25.00",
// "color": "red",
// "inStock": true
// },
// {
// "title": "ACME super soaker",
// "price": "25.00",
// "color": "blue",
// "inStock": true
// },
// {
// "title": "ACME super soaker",
// "price": "25.00",
// "color": "green",
// "inStock": false
// }
// ]
// }Expressions
Expressions enable us to extract data from our Scope object (source data) and transform / restructure it into our target data structure via JSON mappings. Expressions may be used within both map keys and values similarly, with some caveats with respect to expressions in keys that are discussed in more depth below.
Operators
| Operator | Example | Expression Handling |
|---|---|---|
| ! | !expr | Ignore key. Child object key value pairs will be assigned directly to the parent, and not under the prefixed key. |
| ' | 'expr' | Not evaluated |
| ^ | ^expr | Evaluated against Scope at the root / top level |
| . | expr1.expr2 | Chainable direct child element selector. May be used to directly access array elements (e.g. expr.0 or expr.5) |
| | | expr1 | expr2 | Chainable filter processing |
| [] | [expr1]expr2 | Modifies scope to expr1 for following (or preceding) expr2. Can be used within escaped {{}} expressions. |
| {{}} | {{expr1}}{{expr2}} | Expression escape delimiter. May be nested. |
| space | expr1 expr2 | Expression delimiter. Can be used in conjunction with leading or trailing [] scope modifier |
Filter Functions
Filter function static parameters (even numerics) must be enclosed in single quotes ' to avoid the parser attempting to resolve them as key values and ultimately returning undefined. Filter functions are case sensitive and must be written in all lower case.
var map = {
"stockout": "Product.variants | filter(stock | eq('0'))"
};
// { "color": "green", "stock": "0" }| Function | Description |
|---|---|
| add(x1,x2,..xn) | Add one or more values to a piped value |
| and(x1,x2,..xn) | Boolean AND result of a piped value and one or more additional parameter values |
| bool | Boolean format a piped value |
| concat(x1,x2,..xn) | Return a string catenation of a piped value combined with one or more additional parameter values. Call without parameters for toString() functionality. |
| count | Count the number of keys, values, or characters in a piped object, array, or string |
| date(x1) | Date format a piped value where x1 is one of: 'milliseconds' or 'json' (default) |
| decrement | Reduces piped value by 1 |
| default(x1) | Returns x1 if the piped value is falsey |
| divide(x1,x2,..xn) | Divide one or more values from a piped value |
| eq(x1) | Returns true if piped value == x1 |
| filter(x1) | Filter a piped array of objects or values to include only those x1 expression evaluates as true. By default, x1 is evaluated against the local scope of each array item. If the piped value is an array of objects, the expression will be evaluated against each object in the array. If the piped value is an array of singletons, you may use get() to refer to the singleton value in your expressions. The root ^ operator is also supported for access to non-local scope. |
| float(x1) | Float format a piped value with precision x1 (or 2 if x1 is not specified) |
| get(x1) | Returns element x1 from a piped object, array, or string. May also be used without a piped value to reference field values in scope - useful when field names included spaces etc. Supports child dot . notation. Returns current scope when no parameters are passed as in get(). |
| gt(x1) | Returns true if piped value is greater than value x1 |
| gte(x1) | Returns true if piped value is greater than or equal to value x1 |
| hash | Returns a md5 hash string based upon the piped value |
| if(x1,x2) | Returns x1 if piped value is true, otherwise returns x2 |
| increment | Increases piped value by 1 |
| int | Integer format a piped value |
| join(x1) | Joins array elements from a piped value together into a string delimited by x1 (or , if x1 is not specified) |
| json | Returns JSON.parse() on a piped value for embedded JSON |
| keys | Returns an array of keys for the piped object |
| lt(x1) | Returns true if piped value is less than value x1 |
| lte(x1) | Returns true if piped value is less than or equal to value x1 |
| lowercase | Returns .toLowerCase() of the piped string |
| match(x1, x2) | Returns .match(x1[, x2]) of the piped string (in array format). Default value for x2 if not provided is 'i'. |
| multiply(x1,x2,..xn) | Multiply one or more values with a piped value |
| not(x1) | Returns the boolean opposite of x1 |
| now(x1) | Returns the current date (new Date()) where x1 is one of: 'milliseconds', 'json' (default) |
| or(x1,x2,..xn) | Boolean OR result of a piped value and one or more additional parameter values |
| pluck(x1) | Returns an array of key values from a piped array of objects having x1 as a key |
| pop | Returns the last element in an array |
| prune(x1,x2,..xn) | Removes all key values from the piped object not specified as a parameter |
| push(x1,x2,..xn) | Add one or more additional elements to a piped array. Ensures piped value is in array format. |
| reduce(x1,x2) | Reduce array of piped values to a single element where element key x1 has the "largest", or "smallest" (specified by x2) value. In the absence of key x1, element values will be compared directly |
| replace(x1,x2[,x3, x4]) | Returns .replace(x1, x2) of the piped string. Defaults to x3 (if specified) or the original piped value if no expression match for x1. Use x4 to specify regular expression flags |
| set(x1, x2) | Sets element x1 from a piped object, array, or string equal to x2 |
| slice(x1,x2) | Returns .slice(x1, x2) of the piped array or string |
| split(x1) | Returns .split(x1) of the piped string. Default split character is ,
|
| subtract(x1,x2,..xn) | Subtract one or more values from a piped value |
| trim | Removes leading and trailing whitespace from the piped string |
| uppercase | Returns .toUpperCase() of the piped string |
| values(x1) | Formats piped value as an array. Objects are converted to an array of key values, and any values for keys specified in x1 (comma delimited string) are excluded. If the key values are themselves objects, the _key key is appended and references the parent key. |
Scope Modifiers
Only the root level of the Scope object is checked for map references by default. Modify the scope by specifying the reserved @path or @root key.
@path
A @path key expression modifies Scope for all siblings and child elements.
var map = {
"@path": "Product",
"'title'": "title"
};
// { "title": "ACME super soaker" }@root
A @root key expression modifies the default Root Scope for all siblings and child elements. Subsequent (sibling and child element) use of the ^ operator will resolve expressions against the new root scope. To set the Root Scope equal to the Local Scope, assign the @path value to the @root key. Conversely, to set the Local Scope equal to the Root Scope, assign the @root value to the @path key.
var map = {
"@root": "Product",
"'title'": "^title"
};
// { "title": "ACME super soaker" }Alternatively you may use Bracket Notation [] which may be used inline in both key and key values. When used within keys, the scope change is inherited by child elements.
[] Bracket Inline Scope Modification
map = {
"variantColors[Product.variants]": [
{ "'color'": "color" }
]
};
// {
// "variantColors": [
// { "color": "red" },
// { "color": "blue" },
// { "color": "green" }
// ]
// }