Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/loris/api-query-params
Convert URL query parameters to MongoDB queries
https://github.com/loris/api-query-params
api mongodb mongodb-query mongoose query-builder url
Last synced: 3 months ago
JSON representation
Convert URL query parameters to MongoDB queries
- Host: GitHub
- URL: https://github.com/loris/api-query-params
- Owner: loris
- License: other
- Created: 2016-01-12T18:12:42.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2023-03-04T03:23:22.000Z (over 1 year ago)
- Last Synced: 2024-07-16T12:34:49.839Z (4 months ago)
- Topics: api, mongodb, mongodb-query, mongoose, query-builder, url
- Language: JavaScript
- Homepage:
- Size: 940 KB
- Stars: 174
- Watchers: 4
- Forks: 34
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# api-query-params
[![NPM version][npm-image]][npm-url]
[![Build Status][travis-image]][travis-url]
[![Coveralls Status][coveralls-image]][coveralls-url]
[![Dependency Status][depstat-image]][depstat-url]
[![Downloads][download-badge]][npm-url]
> 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
```sh
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](https://mongoosejs.com/docs/populate.html))
#### Example
```js
import aqp from 'api-query-params';
const query = aqp(
'status=sent×tamp>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
```js
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` | `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:
```js
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`.
```js
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`)
```js
aqp('fields=id,url');
// {
// projection: { id: 1, url: 1}
// }
```
```js
aqp('fields=-_id,-email');
// {
// projection: { _id: 0, email: 0 }
// }
```
```js
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.
```js
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](https://mongoosejs.com/docs/populate.html).
- Default operator key is `populate`.
- It accepts a comma-separated list of fields.
- It extracts projection on populated documents from the `projection` object.
```js
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:
```js
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:
```js
aqp('date=2016-01-01&boolean=true&integer=10®exp=/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):
```js
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`)
```js
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
```js
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.
```js
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).
```js
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](http://github.com/loris)
[npm-url]: https://npmjs.org/package/api-query-params
[npm-image]: https://img.shields.io/npm/v/api-query-params.svg?style=flat-square
[travis-url]: https://travis-ci.org/loris/api-query-params
[travis-image]: https://img.shields.io/travis/loris/api-query-params.svg?style=flat-square
[coveralls-url]: https://coveralls.io/r/loris/api-query-params
[coveralls-image]: https://img.shields.io/coveralls/loris/api-query-params.svg?style=flat-square
[depstat-url]: https://david-dm.org/loris/api-query-params
[depstat-image]: https://david-dm.org/loris/api-query-params.svg?style=flat-square
[download-badge]: http://img.shields.io/npm/dm/api-query-params.svg?style=flat-square