# json-mask
> Tiny language and engine for selecting specific parts of a JS object, hiding the rest.
Latest version **2.0.0** (published 2022-05-14) · MIT license · 0 weekly downloads
## Install
```sh
npm install json-mask
pnpm add json-mask
yarn add json-mask
bun add json-mask
```
Provides the command `json-mask`.
## Health
**Score 33/100 (F)** — status: abandoned.
Positive: has types package; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support.
Negative: abandoned.
## Facts
| | |
|---|---|
| Version | 2.0.0 |
| Published | 2022-05-14 |
| First published | 2013-07-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/json-mask) |
| Module format | CommonJS |
| Node | >=14.0.0 |
| Dependencies | 0 |
| Unpacked size | 26.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 871 |
| Author | nemtsov@gmail.com |
| Maintainers | nemtsov |
| Keywords | mask, filter, select, fields, projection, query, json, cli |
## Links
- npm: https://www.npmjs.com/package/json-mask
- Repository: https://github.com/nemtsov/json-mask
- Homepage: https://github.com/nemtsov/json-mask#readme
- Issues: https://github.com/nemtsov/json-mask/issues
- npm.io page: https://npm.io/package/json-mask
## Alternatives
- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads
## Recent versions
- 2.0.0 (latest) — 2022-05-14
- 1.0.4 — 2020-10-30
- 1.0.3 — 2020-10-30
- 1.0.2 — 2020-09-07
- 1.0.1 — 2020-02-14
- 1.0.0 — 2020-02-14
- 0.3.9 — 2019-12-14
- 0.3.8 — 2016-05-22
- 0.3.7 — 2016-05-22
- 0.3.6 — 2016-05-22
- 0.3.5 — 2015-08-14
- 0.3.4 — 2015-02-24
- 0.3.3 — 2015-02-24
- 0.3.2 — 2014-09-09
- 0.3.1 — 2014-07-18
- … 4 more at https://npm.io/package/json-mask/versions
## README
# JSON Mask [](https://github.com/nemtsov/json-mask/actions/workflows/node.js.yml) [](https://www.npmjs.com/package/json-mask) [](http://standardjs.com/)
This is a tiny language and an engine for selecting specific parts of a JS object, hiding/masking the rest.
```js
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](https://developers.google.com/gdata/docs/2.0/reference#PartialResponse), 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](http://expressjs.com/) users, there's an
[express-partial-response](https://github.com/nemtsov/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](https://github.com/koajs/koa.git)
check out the [koa-json-mask](https://github.com/nemtsov/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 except "\" ? | EscapeSeq | Wildcard
Wildcard ::= "*"
EscapeSeq ::= "\" ? all visible characters ?
```
## Examples
Identify the fields you want to keep:
```js
var fields = 'url,object(content,attachments/url)';
```
From this sample object:
```js
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:
```js
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:
```js
var mask = require('json-mask');
var assert = require('assert');
var maskedObj = mask(originalObj, fields);
assert.deepEqual(maskedObj, expectObj);
```
### Escaping
It is also possible to get keys that contain `,*()/` using `\` (backslash) as escape character.
```json
{
"metadata": {
"labels": {
"app.kubernetes.io/name": "mysql",
"location": "WH1"
}
}
}
```
You can filter out the location property by `metadata(labels(app.kubernetes.io\/name))` mask.
NOTE: In [JavaScript String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#escape_sequences) you must escape backslash with another backslash:
```js
var fields = 'metadata(labels(app.kubernetes.io\\/name))'
```
### Partial Responses Server Example
Here's an example of using `json-mask` to implement the
[Google API Partial Response](https://developers.google.com/gdata/docs/2.0/reference#PartialResponse)
```js
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:
```bash
$ 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 "" [
This is a tiny language and an engine for selecting specific parts of a JS object, hiding/masking the rest.
```js
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](https://developers.google.com/gdata/docs/2.0/reference#PartialResponse), 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](http://expressjs.com/) users, there's an
[express-partial-response](https://github.com/nemtsov/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](https://github.com/koajs/koa.git)
check out the [koa-json-mask](https://github.com/nemtsov/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 except "\" ? | EscapeSeq | Wildcard
Wildcard ::= "*"
EscapeSeq ::= "\" ? all visible characters ?
```
## Examples
Identify the fields you want to keep:
```js
var fields = 'url,object(content,attachments/url)';
```
From this sample object:
```js
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:
```js
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:
```js
var mask = require('json-mask');
var assert = require('assert');
var maskedObj = mask(originalObj, fields);
assert.deepEqual(maskedObj, expectObj);
```
### Escaping
It is also possible to get keys that contain `,*()/` using `\` (backslash) as escape character.
```json
{
"metadata": {
"labels": {
"app.kubernetes.io/name": "mysql",
"location": "WH1"
}
}
}
```
You can filter out the location property by `metadata(labels(app.kubernetes.io\/name))` mask.
NOTE: In [JavaScript String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#escape_sequences) you must escape backslash with another backslash:
```js
var fields = 'metadata(labels(app.kubernetes.io\\/name))'
```
### Partial Responses Server Example
Here's an example of using `json-mask` to implement the
[Google API Partial Response](https://developers.google.com/gdata/docs/2.0/reference#PartialResponse)
```js
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:
```bash
$ 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 "