jm

json-mask

Tiny language and engine for selecting specific parts of a JS object, hiding the rest.

Showing:

Popularity

Downloads/wk

39.5K

GitHub Stars

597

Maintenance

Last Commit

4mos ago

Contributors

10

Package

Dependencies

0

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

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.

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

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

  Props ::= Prop | Prop "," Props
   Prop ::= Object | Array
 Object ::= NAME | NAME "/" Prop
  Array ::= NAME "(" Props ")"
   NAME ::= ? all visible characters ?

Examples

Identify the fields you want to keep:

var fields = 'url,object(content,attachments/url)';

From this sample object:

var originalObj = {
  id: 'z12gtjhq3qn2xxl2o224exwiqruvtda0i',
  url: 'https://plus.google.com/102817283354809142195/posts/F97fqZwJESL',
  object: {
    objectType: 'note',
    content:
      'A picture... of a space ship... launched from earth 40 years ago.',
    attachments: [
      {
        objectType: 'image',
        url: 'http://apod.nasa.gov/apod/ap110908.html',
        image: { height: 284, width: 506 }
      }
    ]
  },
  provider: { title: 'Google+' }
};

Here's what you'll get back:

var expectObj = {
  url: 'https://plus.google.com/102817283354809142195/posts/F97fqZwJESL',
  object: {
    content:
      'A picture... of a space ship... launched from earth 40 years ago.',
    attachments: [
      {
        url: 'http://apod.nasa.gov/apod/ap110908.html'
      }
    ]
  }
};

Let's test that:

var mask = require('json-mask');
var assert = require('assert');

var maskedObj = mask(originalObj, fields);
assert.deepEqual(maskedObj, expectObj);

Partial Responses Server Example

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

var http = require('http');
var url = require('url');
var mask = require('json-mask');
var server;

server = http.createServer(function(req, res) {
  var fields = url.parse(req.url, true).query.fields;
  var data = {
    firstName: 'Mohandas',
    lastName: 'Gandhi',
    aliases: [
      {
        firstName: 'Mahatma',
        lastName: 'Gandhi'
      },
      {
        firstName: 'Bapu'
      }
    ]
  };
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify(mask(data, fields)));
});

server.listen(4000);

Let's test it:

$ curl 'http://localhost:4000'
{"firstName":"Mohandas","lastName":"Gandhi","aliases":[{"firstName":"Mahatma","lastName":"Gandhi"},{"firstName":"Bapu"}]}

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

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

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 "<fields>" <input> [<output>]

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

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial