Product
Introducing SSO
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
api-query-params
Advanced tools
Readme
Convert query parameters from API urls to MongoDB queries (advanced querying, filtering, sorting, …)
$in
, $regexp
, …) and features (nested objects, projection, type casting, …)fields
vs select
) and optionsnpm i --save api-query-params
aqp(queryString, [opts])
Converts
queryString
into a MongoDB query object
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]The resulting object contains the following properties:
filter
which contains the query criteriaprojection
which contains the query projectionsort
, skip
, limit
which contains the cursor modifierspopulation
which contains the query population (mongoose feature only)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 } } ]
// }
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.
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
and limit
.aqp('skip=5&limit=10');
// {
// skip: 5,
// limit: 10
// }
fields
.-
prefixes to return all fields except some specific fields.$
, $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
.-
prefixes to sort in descending order.aqp('sort=-points,createdAt');
// {
// sort: { points: -1, createdAt: 1 }
// }
populate
.projection
object.aqp('populate=a,b&fields=foo,bar,a.baz');
// {
// population: [ { path: 'a', select: { baz: 1 } } ],
// projection: { foo: 1, bar: 1 },
// }
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
.
notationAny 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 }
// }
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®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):
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'
// }
// }
opts
)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
// }
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 specifiedwhitelist
: filter only on the keys specifiedaqp('id=e9117e5c-c405-489b-9c12-d9f398c7a112&apiKey=foobar', {
blacklist: ['apiKey'],
});
// {
// filter: {
// id: 'e9117e5c-c405-489b-9c12-d9f398c7a112',
// }
// }
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',
// }
// }
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',
// }
// }
MIT © Loris Guignard
FAQs
Convert query parameters from API urls to MongoDB queries
The npm package api-query-params receives a total of 2,353 weekly downloads. As such, api-query-params popularity was classified as popular.
We found that api-query-params demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.