sensitivemix / koa1-json-mask

💨 json-mask for koa1.x

koa1-json-mask

Middleware allowing the client to mask / filter the response to only what they need, reducing the amount of traffic over the wire using the ?fields=foo,bar,baz querystring parameter.

If you've used the Google APIs, provided a ?fields= query-string to get a Partial Response, and wanted to do the same for your own server, you can do so with this middleware.

The difference between koa-json-filter and koa-json-mask is that this middleware supports filtering parts deep within objects. If you only need to be able to filter top-level params of objects in the response use filter, and if you need more power user mask.

Underneath, this middleware uses json-mask. Use it directly without this middleware if you need more flexibility.

Installation

$ npm install koa1-json-mask

$ npm install [email protected]

Options

• name querystring param name defaulting to "fields"

Example

Object responses

Script:

const Koa = require('koa');
const mask = require('koa1-json-mask');

const app = new Koa();

app.use(mask());

app.use(function * () {
  ctx.body = {
    name: 'tobi',
    packages: 5,
    friends: ['abby', 'loki', 'jane'],
    location: {
      id: '342',
      name: 'London'
    }
  };
});

app.listen(3000)
console.log('app listening on port 3000')

Response:

$ GET /?fields=name,location/name
{
  "name": "tobi",
  "location": {
    "name": "London"
  }
}

Array responses

Script:

const Koa = require('koa');
const mask = require('koa1-json-mask')

const app = new Koa()

app.use(mask())

app.use(funtion * () {
  ctx.body = [
    {
      name: 'tobi',
      packages: 5,
      friends: ['abby', 'loki', 'jane'],
      location: {
        id: '342',
        name: 'London'
      }
    },
    {
      name: 'loki',
      packages: 2,
      friends: ['loki', 'jane'],
      location: {
        id: '62',
        name: 'New York'
      }
    }
  ];
});

app.listen(3000)
console.log('app listening on port 3000')

Response:

$ GET /?fields=name,location/name
[
  {
    "name": "tobi",
    "location": {
      "name": "London"
    }
  },
  {
    "name": "loki",
    "location": {
      "name": "New York"
    }
  }
]

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

More examples

For more examples, take a look at the examples section of the json-mask README.

License

MIT License

koa1-json-mask's Issues

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please delete the greenkeeper/initial branch in this repository, and then remove and re-add this repository to the Greenkeeper App’s white list on Github. You'll find this list on your repo or organization’s settings page, under Installed GitHub Apps.

koa2