Need help with api-query-params?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

loris
151 Stars 28 Forks Other 168 Commits 14 Opened issues

Description

Convert URL query parameters to MongoDB queries

Services available

!
?

Need anything else?

Contributors list

# 56,001
TypeScr...
interva...
cronjob
HTML
136 commits
# 45,149
PHP
node
youtube...
paging
3 commits
# 696,210
JavaScr...
Mongoos...
MongoDB
query-b...
1 commit
# 152,528
React
HTML
PHP
url-par...
1 commit
# 497,985
JavaScr...
Mongoos...
MongoDB
query-b...
1 commit
# 63,658
vue-res...
vuejs2
CSS
JavaScr...
1 commit

api-query-params

NPM version Build Status Coveralls Status Dependency Status Downloads

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
  • population
    which contains the query population (mongoose feature only)

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&populate=logs&fields=id,logs.ip' ); // { // 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 }, // population: [ { path: 'logs', select: { ip: 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, population } = aqp(req.query); User.find(filter) .skip(skip) .limit(limit) .sort(sort) .select(projection) .populate(population) .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            | 
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/
|
email=/@gmail\.com$/i
|
{filter: {email: /@gmail.com$/i}}
| |
$regex
|
key!=/value/
|
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.
  • It also accepts JSON string to use more powerful projection operators (
    $
    ,
    $elemMatch
    or
    $slice
    )
aqp('fields=id,url');
//  {
//    projection: { id: 1, url: 1}
//  }
aqp('fields=-_id,-email');
//  {
//    projection: { _id: 0, email: 0 }
//  }
aqp('fields={"comments":{"$slice":[20,10]}}');
//  {
//    projection: { comments: { $slice: [ 20, 10 ] } }
//  }

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 }
//  }

Population operator

  • Useful to populate (reference documents in other collections) returned records. This is a mongoose-only feature.
  • Default operator key is
    populate
    .
  • It accepts a comma-separated list of fields.
  • It extracts projection on populated documents from the
    projection
    object.
aqp('populate=a,b&fields=foo,bar,a.baz');
// {
//    population: [ { path: 'a', select: { baz: 1 } } ],
//    projection: { foo: 1, bar: 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
    )
  • populationKey
    : custom populate operator key (default is
    populate
    )
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). Note that you can also override built-in casting functions:
boolean
,
date
,
null
,
number
,
regex
and
string
.
  • 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)&key3=true', {
  casters: {
    lowercase: val => val.toLowerCase(),
    int: val => parseInt(val, 10),
    boolean: val => (val === 'true' ? '1' : '0'),
  },
});
// {
//   filter: {
//     key1: 'value',
//     key2: 10,
//     key3: '1',
//   }
// }

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',
//   }
// }

License

MIT © Loris Guignard

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.