JSON Mask

Tiny language and engine for selecting specific parts of a JS object, hidin...

nemtsov/json-maskjson-mask

README

JSON Mask Build Status NPM version js-standard-style



This is a tiny language and an engine for selecting specific parts of a JS object, hiding/masking the rest.

  1. ``` js
  2. var mask = require('json-mask');
  3. mask({ p: { a: 1, b: 2 }, z: 1 }, 'p/a,z'); // {p: {a: 1}, z: 1}
  4. ```

The main difference between JSONPath / JSONSelect and this engine is that JSON Mask
preserves the structure of the original input object.
Instead of returning an array of selected sub-elements (e.g. [{a: 1}, {z: 1}] from example above),
it filters-out the parts of the object that you don't need,
keeping the structure unchanged: {p: {a: 1}, z: 1}.

This is important because JSON Mask was designed with HTTP resources in mind,
the structure of which I didn't want to change after the unwanted fields
were masked / filtered.

If you've used the Google APIs, and provided a ?fields= query-string to get a
Partial Response, you've
already used this language. The desire to have partial responses in
my own Node.js-based HTTP services was the reason I wrote JSON Mask.

_For express users, there's an
express-partial-response middleware.
It will integrate with your existing services with no additional code
if you're using res.json() or res.jsonp(). And if you're already using koa
check out the koa-json-mask middleware._

This library has no dependencies. It works in Node as well as in the browser.

Note: the 1.5KB (gz), or 4KB (uncompressed) browser build is in the /build folder.

Syntax


The syntax is loosely based on XPath:

- a,b,c comma-separated list will select multiple fields
- a/b/c path will select a field from its parent
- a(b,c) sub-selection will select many fields from a parent
- `a//c the star ` wildcard will select all items in a field

Take a look at test/index-test.js for examples of all of these and more.

Grammar


  1. ```
  2.      Props ::= Prop | Prop "," Props
  3.       Prop ::= Object | Array
  4.     Object ::= NAME | NAME "/" Prop
  5.      Array ::= NAME "(" Props ")"
  6.       NAME ::= ? all visible characters except "\" ? | EscapeSeq | Wildcard
  7.   Wildcard ::= "*"
  8. EscapeSeq ::= "\" ? all visible characters ?
  9. ```

Examples


Identify the fields you want to keep:

  1. ``` js
  2. var fields = 'url,object(content,attachments/url)';
  3. ```

From this sample object:

  1. ``` js
  2. var originalObj = {
  3.   id: 'z12gtjhq3qn2xxl2o224exwiqruvtda0i',
  4.   url: 'https://plus.google.com/102817283354809142195/posts/F97fqZwJESL',
  5.   object: {
  6.     objectType: 'note',
  7.     content:
  8.       'A picture... of a space ship... launched from earth 40 years ago.',
  9.     attachments: [
  10.       {
  11.         objectType: 'image',
  12.         url: 'http://apod.nasa.gov/apod/ap110908.html',
  13.         image: { height: 284, width: 506 }
  14.       }
  15.     ]
  16.   },
  17.   provider: { title: 'Google+' }
  18. };
  19. ```

Here's what you'll get back:

  1. ``` js
  2. var expectObj = {
  3.   url: 'https://plus.google.com/102817283354809142195/posts/F97fqZwJESL',
  4.   object: {
  5.     content:
  6.       'A picture... of a space ship... launched from earth 40 years ago.',
  7.     attachments: [
  8.       {
  9.         url: 'http://apod.nasa.gov/apod/ap110908.html'
  10.       }
  11.     ]
  12.   }
  13. };
  14. ```

Let's test that:

  1. ``` js
  2. var mask = require('json-mask');
  3. var assert = require('assert');

  5. var maskedObj = mask(originalObj, fields);
  6. assert.deepEqual(maskedObj, expectObj);
  7. ```

Escaping


It is also possible to get keys that contain ,*()/ using \ (backslash) as escape character.

  1. ``` json
  2. {
  3.   "metadata": {
  4.     "labels": {
  5.       "app.kubernetes.io/name": "mysql",
  6.       "location": "WH1"
  7.     }
  8.   }
  9. }
  10. ```

You can filter out the location property by metadata(labels(app.kubernetes.io\/name)) mask.

NOTE: In JavaScript String you must escape backslash with another backslash:
  1. ``` js
  2. var fields = 'metadata(labels(app.kubernetes.io\\/name))'
  3. ```

Partial Responses Server Example


Here's an example of using json-mask to implement the
Google API Partial Response

  1. ``` js
  2. var http = require('http');
  3. var url = require('url');
  4. var mask = require('json-mask');
  5. var server;

  7. server = http.createServer(function(req, res) {
  8.   var fields = url.parse(req.url, true).query.fields;
  9.   var data = {
  10.     firstName: 'Mohandas',
  11.     lastName: 'Gandhi',
  12.     aliases: [
  13.       {
  14.         firstName: 'Mahatma',
  15.         lastName: 'Gandhi'
  16.       },
  17.       {
  18.         firstName: 'Bapu'
  19.       }
  20.     ]
  21.   };
  22.   res.writeHead(200, { 'Content-Type': 'application/json' });
  23.   res.end(JSON.stringify(mask(data, fields)));
  24. });

  26. server.listen(4000);
  27. ```

Let's test it:

  1. ``` sh
  2. $ curl 'http://localhost:4000'
  3. {"firstName":"Mohandas","lastName":"Gandhi","aliases":[{"firstName":"Mahatma","lastName":"Gandhi"},{"firstName":"Bapu"}]}

  5. $ # Let's just get the first name
  6. $ curl 'http://localhost:4000?fields=lastName'
  7. {"lastName":"Gandhi"}

  9. $ # Now, let's just get the first names directly as well as from aliases
  10. $ curl 'http://localhost:4000?fields=firstName,aliases(firstName)'
  11. {"firstName":"Mohandas","aliases":[{"firstName":"Mahatma"},{"firstName":"Bapu"}]}
  12. ```

Note: a few more examples are in the /example folder.

Command Line Interface - CLI


When installed globally using npm i -g json-mask you can use it like:

`json-mask "" []`

Examples


Stream from online resource:

curl https://api.myjson.com/bins/krrxw | json-mask "url,object(content,attachments/url)"

Read from file and write to output file:

json-mask "url,object(content,attachments/url)" input.json > output.json

Read from file and print redirect to file:

json-mask "url,object(content,attachments/url)" input.json > output.json

CDN


unpkg

- https://unpkg.com/json-mask/build/jsonMask.js
- https://unpkg.com/json-mask/build/jsonMask.min.js

License


MIT