json-forge

This README outlines the details of collaborating on this library.

This library serves as client-side json 'forge' to remap a where object to waterline syntax, and as a server-side type interpreter to handle special types that cannot be represented purely in JSON. A good example would be Mongo Object ID's or Date Objects. A forge instance will rebuild and return a new object without disrupting the original object.

Prerequisites

You will need the following things properly installed on your computer.

• Git
• Node.js (with NPM)

Installation

• git clone <repository-url> this repository
• cd json-forge
• npm install

Running / Development

• npm start
• Visit your app at http://localhost:3000.

Testing

• npm run test

Code Formatting

• npm run format

Linting

• npm run lint
• npm run lint:tests

Building

• npm run build

!!!WARNING!!!

Ensure that you do not send objects with circular references to JSONForge! You will crash your JS VM!

Usage

This library exports a single class called JSONForge.

When creating a new forge instance a single input object options is expected.

This options object can have the following definition keys:

map, prune, compressors.

All are expected to be objects/maps.

map is expected to be a map of literals, where the left-hand value of the map will be substituted for the right-hand value of the map at every level of the input object.

prune is expected to be a map of truthy values, where all branches that match the left-hand value of the prune map will be discarded at every level of the input object.

compressors is expected to be a map of synchronous functions that returns a replacement object for the current object level if there is a left-hand key within the object level that matches the compressor key. Compressors can therefore be used to "mutate" an object level, or "compress" an object level down to a special type like a Date object or a Mongo ID.

Creating a basic forge instance would looke like:

importJSONForgefrom'json-forge';constforge=newJSONForge({compressors: {$date(v,k){returnnewDate(v);}}});

Invoking a forge is as easy as:

constnewObject=forge.process({"publishedAt": {"<=": {"$date": "2018-03-08T09:05:24.447Z"}}});

The above forge would compress $date objects like:

{"publishedAt": {"<=": {"$date": "2018-03-08T09:05:24.447Z"}}}

to:

{"publishedAt": {"<=": newDate("2018-03-08T09:05:24.447Z")}}

For simple remapping, a forge like the following can be useful:

constforge=newJSONForge({map: {$and: 'and',$or: 'or',like: 'contains'}});

This forge would convert the following object:

{$and: [{title: {like: 'This'}},{$or: [{description: {contains: 'Text'}},{classification: {contains: 'U'}}]}]}

to:

{and: [{title: {contains: 'This'}},{or: [{description: {contains: 'Text'}},{classification: {contains: 'U'}}]}]}

Additionally, forges can also prune values out of an object tree.

The following forge would prune all branches starting with key _title_:

constforge=newJSONForge({prune: {_title_: true}});

Which would convert the following object:

{_title_: 'A Good Day to Die',topics: ['a','b','c']}

to:

{topics: ['a','b','c']}

Putting it all together, the following forge:

importJSONForgefrom'json-forge';constforge=newJSONForge({map: {$and: 'and',$or: 'or',like: 'contains',DATE: '$date'},prune: {_title_: true},compressors: {$date(v,k){returnnewDate(v);},$objectId(v,k){if(Array.isArray(v)){returnv.map(e=>{returne;//here you would handle wrapping many objectIds (if needed)});}returnv;//here you would wrap a single element}}});

Would convert this object:

{"_title_": "A Good Day to Die","topics": ["a","b","c"],"updatedAt": {"<=": {"DATE": "2018-03-08T09:05:24.447Z"}},"$and": [{"title": {"like": "This"}},{"$or": [{"description": {"contains": "Text"}},{"classification": {"contains": "U"}}]}],"publishedAt": {"<=": {"$date": "2018-03-08T09:05:24.447Z"}}}

to:

{"topics": ["a","b","c"],"updatedAt": {"<=": newDate("2018-03-08T09:05:24.447Z")},"and": [{"title": {"contains": "This"}},{"or": [{"description": {"contains": "Text"}},{"classification": {"contains": "U"}}]}],"publishedAt": {"<=": newDate("2018-03-08T09:05:24.447Z")}}

You may have noticed, that re-mapped keys can flow seamlessly into compressors!

Forge On!