Nutritious Pomegranate Muffins

    koa-json-mask

    1.0.4 • Public • Published

    koa-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 koa-json-mask
    

    In order to use this plugin with the previous version of Koa using generator functions, please use version 0.3.2

    $ npm install koa-json-mask@0.3.2
    

    Options

    • name querystring param name defaulting to "fields"

    Example

    Object responses

    Script:

    const Koa = require('koa');
    const mask = require('koa-json-mask');
     
    const app = new Koa();
     
    app.use(mask());
     
    app.use(async ctx => {
      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('koa-json-mask');
     
    const app = new Koa();
     
    app.use(mask());
     
    app.use(async ctx => {
      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

    Install

    npm i koa-json-mask

    DownloadsWeekly Downloads

    17

    Version

    1.0.4

    License

    MIT

    Unpacked Size

    5.54 kB

    Total Files

    4

    Last publish

    Collaborators

    • nemtsov