api-query-params

Convert query parameters from API urls to MongoDB queries (advanced querying, filtering, sorting, …)

Features

Powerful. Supports most of MongoDB operators ($in, $regexp, …) and features (nested objects, projection, type casting, …)
Custom. Allows customization of keys (ie, fields vs select) and options
Agnostic. Works with any web frameworks (Express, Koa, …) and/or MongoDB libraries (mongoose, mongoskin, …)
Simple. ~200 LOCs, dependency-free ES6 code
Fully tested. 100% code coverage

Install

npm i --save api-query-params

Usage

API

aqp(queryString, [opts])

Converts queryString into a MongoDB query object

Arguments

queryString: query string part of the requested API URL (ie, firstName=John&limit=10). Works with already parsed object too (ie, {status: 'success'}) [required]
opts: object for advanced options (See below) [optional]

Returns

The resulting object contains the following properties:

filter which contains the query criteria
projection which contains the query projection
sort, skip, limit which contains the cursor modifiers

Example

import aqp from 'api-query-params';

const query = aqp('status=sent&timestamp>2016-01-01&author.firstName=/john/i&limit=100&skip=50&sort=-timestamp&fields=id');
//  {
//    filter: {
//      status: 'sent',
//      timestamp: { $gt: Fri Jan 01 2016 01:00:00 GMT+0100 (CET) },
//      'author.firstName': /john/i
//    },
//    sort: { timestamp: -1 },
//    skip: 50,
//    limit: 100,
//    projection: { id: 1 }
//  }

Example with Express and mongoose

import express from 'express';
import aqp from 'api-query-params';
import User from './models/User';

const app = express();

app.get('/users', (req, res, next) => {
  const { filter, skip, limit, sort, projection } = aqp(req.query);
  User
    .find(filter)
    .skip(skip)
    .limit(limit)
    .sort(sort)
    .select(projection)
    .exec((err, users) => {
      if (err) {
        return next(err);
      }

      res.send(users);
    });
});

That's it. Your /users endpoint can now query, filter, sort your User mongoose model and more.

Supported features

Filtering operators

MongoDB	URI	Example	Result
`$eq`	`key=val`	`type=public`	`{filter: {type: 'public'}}`
`$gt`	`key>val`	`count>5`	`{filter: {count: {$gt: 5}}}`
`$gte`	`key>=val`	`rating>=9.5`	`{filter: {rating: {$gte: 9.5}}}`
`$lt`	`key<val`	`createdAt<2016-01-01`	`{filter: {createdAt: {$lt: Fri Jan 01 2016 01:00:00 GMT+0100 (CET)}}}`
`$lte`	`key<=val`	`score<=-5`	`{filter: {score: {$lte: -5}}}`
`$ne`	`key!=val`	`status!=success`	`{filter: {status: {$ne: 'success'}}}`
`$in`	`key=val1,val2`	`country=GB,US`	`{filter: {country: {$in: ['GB', 'US']}}}`
`$nin`	`key!=val1,val2`	`lang!=fr,en`	`{filter: {lang: {$nin: ['fr', 'en']}}}`
`$exists`	`key`	`phone`	`{filter: {phone: {$exists: true}}}`
`$exists`	`!key`	`!email`	`{filter: {email: {$exists: false}}}`
`$regex`	`key=/value/<opts>`	`email=/@gmail\.com$/i`	`{filter: {email: /@gmail.com$/i}}`
`$regex`	`key!=/value/<opts>`	`phone!=/^06/`	`{filter: {phone: { $not: /^06/}}}`

For more advanced usage ($or, $type, $elemMatch, etc.), pass any MongoDB query filter object as JSON string in the filter query parameter, ie:

aqp('filter={"$or":[{"key1":"value1"},{"key2":"value2"}]}');
//  {
//    filter: {
//      $or: [
//        { key1: 'value1' },
//        { key2: 'value2' }
//      ]
//    },
//  }

Skip / Limit operators

Useful to limit the number of records returned.
Default operator keys are skip and limit.

aqp('skip=5&limit=10');
//  {
//    skip: 5,
//    limit: 10
//  }

Projection operator

Useful to limit fields to return in each records.
Default operator key is fields.
It accepts a comma-separated list of fields. Default behavior is to specify fields to return. Use - prefixes to return all fields except some specific fields.
Due to a MongoDB limitation, you cannot combine inclusion and exclusion semantics in a single projection with the exception of the _id field.

aqp('fields=id,url');
//  {
//    projection: { id: 1, url: 1}
//  }

aqp('fields=-_id,-email');
//  {
//    projection: { _id: 0, email: 0 }
//  }

Sort operator

Useful to sort returned records.
Default operator key is sort.
It accepts a comma-separated list of fields. Default behavior is to sort in ascending order. Use - prefixes to sort in descending order.

aqp('sort=-points,createdAt');
//  {
//    sort: { points: -1, createdAt: 1 }
//  }

Keys with multiple values

Any operators which process a list of fields ($in, $nin, sort and projection) can accept a comma-separated string or multiple pairs of key/value:

country=GB,US is equivalent to country=GB&country=US
sort=-createdAt,lastName is equivalent to sort=-createdAt&sort=lastName

Embedded documents using `.` notation

Any operators can be applied on deep properties using . notation:

aqp('followers[0].id=123&sort=-metadata.created_at');
//  {
//    filter: {
//      'followers[0].id': 123,
//    },
//    sort: { 'metadata.created_at': -1 }
//  }

Automatic type casting

The following types are automatically casted: Number, RegExp, Date and Boolean. null string is also casted:

aqp('date=2016-01-01&boolean=true&integer=10&regexp=/foobar/i&null=null');
// {
//   filter: {
//     date: Fri Jan 01 2016 01:00:00 GMT+0100 (CET),
//     boolean: true,
//     integer: 10,
//     regexp: /foobar/i,
//     null: null
//   }
// }

If you need to disable or force type casting, you can wrap the values with string(), date() built-in casters or by specifying your own custom functions (See below):

aqp('key1=string(10)&key2=date(2016)&key3=string(null)');
// {
//   filter: {
//     key1: '10',
//     key2: Fri Jan 01 2016 01:00:00 GMT+0100 (CET),
//     key3: 'null'
//   }
// }

Available options (`opts`)

Customize operator keys

The following options are useful to change the operator default keys:

skipKey: custom skip operator key (default is skip)
limitKey: custom limit operator key (default is limit)
projectionKey: custom projection operator key (default is fields)
sortKey: custom sort operator key (default is sort)
filterKey: custom filter operator key (default is filter)

aqp('organizationId=123&offset=10&max=125', {
  limitKey: 'max',
  skipKey: 'offset'
});
// {
//   filter: {
//     organizationId: 123,
//   },
//   skip: 10,
//   limit: 125
// }

Blacklist / Whitelist

The following options are useful to specify which keys to use in the filter object. (ie, avoid that authentication parameter like apiKey ends up in a mongoDB query). All operator keys are (sort, limit, etc.) already ignored.

blacklist: filter on all keys except the ones specified
whitelist: filter only on the keys specified

aqp('id=e9117e5c-c405-489b-9c12-d9f398c7a112&apiKey=foobar', {
  blacklist: ['apiKey']
});
// {
//   filter: {
//     id: 'e9117e5c-c405-489b-9c12-d9f398c7a112',
//   }
// }

Add custom casting functions

You can specify you own casting functions to apply to query parameter values, either by explicitly wrapping the value in URL with your custom function name (See example below) or by implictly mapping a key to a function (See Specify casting per param keys below)

casters: object to specify custom casters, key is the caster name, and value is a function which is passed the query parameter value as parameter.

aqp('key1=lowercase(VALUE)&key2=int(10.5)', {
  casters: {
    lowercase: val => val.toLowerCase(),
    int: val => parseInt(val, 10),
  },
});
// {
//   filter: {
//     key1: 'value',
//     key2: 10,
//   }
// }

Specify casting per param keys

You can specify how query parameter values are casted by passing an object.

castParams: object which map keys to casters (built-in or custom ones using the casters option).

aqp('key1=VALUE&key2=10.5&key3=20&key4=foo', {
  casters: {
    lowercase: val => val.toLowerCase(),
    int: val => parseInt(val, 10),
  },
  castParams: {
    key1: 'lowercase',
    key2: 'int',
    key3: 'string',
    key4: 'unknown',
  },
});
// {
//   filter: {
//     key1: 'value',
//     key2: 10,
//     key3: '20',
//     key4: 'foo',
//   }
// }

bolzon/api-query-params

api-query-params

Features

Install

Usage

API

Arguments

Returns

Example

Example with Express and mongoose

Supported features

Filtering operators

Skip / Limit operators

Projection operator

Sort operator

Keys with multiple values

Embedded documents using `.` notation

Automatic type casting

Available options (`opts`)

Customize operator keys

Blacklist / Whitelist

Add custom casting functions

Specify casting per param keys

License

bolzon/api-query-params

api-query-params

Features

Install

Usage

API

Arguments

Returns

Example

Example with Express and mongoose

Supported features

Filtering operators

Skip / Limit operators

Projection operator

Sort operator

Keys with multiple values

Embedded documents using . notation

Automatic type casting

Available options (opts)

Customize operator keys

Blacklist / Whitelist

Add custom casting functions

Specify casting per param keys

License

Embedded documents using `.` notation

Available options (`opts`)