BranchesTags

Repository files navigation

api-query-params

NPM version

Coveralls StatusDependency StatusDownloads

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

importaqpfrom'api-query-params';constquery=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

importexpressfrom'express';importaqpfrom'api-query-params';importUserfrom'./models/User';constapp=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){returnnext(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

MongoDBURIExampleResult
$eqkey=valtype=public{filter: {type: 'public'}}
$gtkey>valcount>5{filter: {count: {$gt: 5}}}
$gtekey>=valrating>=9.5{filter: {rating: {$gte: 9.5}}}
$ltkey<valcreatedAt<2016-01-01{filter: {createdAt: {$lt: Fri Jan 01 2016 01:00:00 GMT+0100 (CET)}}}
$ltekey<=valscore<=-5{filter: {score: {$lte: -5}}}
$nekey!=valstatus!=success{filter: {status: {$ne: 'success'}}}
$inkey=val1,val2country=GB,US{filter: {country: {$in: ['GB', 'US']}}}
$ninkey!=val1,val2lang!=fr,en{filter: {lang: {$nin: ['fr', 'en']}}}
$existskeyphone{filter: {phone: {$exists: true}}}
$exists!key!email{filter: {email: {$exists: false}}}
$regexkey=/value/<opts>email=/@gmail\.com$/i{filter: {email: /@gmail.com$/i}}
$regexkey!=/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.
  • 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

About

Convert URL query parameters to MongoDB queries

Topics

apimongodbmongodb-querymongoosequery-builderurl

Resources

Readme
License
Activity

Stars

179 stars

Watchers

2 watching

Forks

35 forks
Report repository

Releases

Packages

Used by

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
BranchesTags
Repository files navigation
api-query-params
NPM version
Coveralls StatusDependency StatusDownloads
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
importaqpfrom'api-query-params';constquery=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
importexpressfrom'express';importaqpfrom'api-query-params';importUserfrom'./models/User';constapp=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){returnnext(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
MongoDBURIExampleResult
$eqkey=valtype=public{filter: {type: 'public'}}
$gtkey>valcount>5{filter: {count: {$gt: 5}}}
$gtekey>=valrating>=9.5{filter: {rating: {$gte: 9.5}}}
$ltkey<valcreatedAt<2016-01-01{filter: {createdAt: {$lt: Fri Jan 01 2016 01:00:00 GMT+0100 (CET)}}}
$ltekey<=valscore<=-5{filter: {score: {$lte: -5}}}
$nekey!=valstatus!=success{filter: {status: {$ne: 'success'}}}
$inkey=val1,val2country=GB,US{filter: {country: {$in: ['GB', 'US']}}}
$ninkey!=val1,val2lang!=fr,en{filter: {lang: {$nin: ['fr', 'en']}}}
$existskeyphone{filter: {phone: {$exists: true}}}
$exists!key!email{filter: {email: {$exists: false}}}
$regexkey=/value/<opts>email=/@gmail\.com$/i{filter: {email: /@gmail.com$/i}}
$regexkey!=/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.
  • 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
About
Convert URL query parameters to MongoDB queries
Topics
apimongodbmongodb-querymongoosequery-builderurl
Resources
Readme
License
Activity
Stars
179 stars
Watchers
2 watching
Forks
35 forks
Report repository
Releases
Packages
Used by
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
api-query-params
NPM version
Coveralls StatusDependency StatusDownloads
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
importaqpfrom'api-query-params';constquery=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
importexpressfrom'express';importaqpfrom'api-query-params';importUserfrom'./models/User';constapp=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){returnnext(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
MongoDBURIExampleResult
$eqkey=valtype=public{filter: {type: 'public'}}
$gtkey>valcount>5{filter: {count: {$gt: 5}}}
$gtekey>=valrating>=9.5{filter: {rating: {$gte: 9.5}}}
$ltkey<valcreatedAt<2016-01-01{filter: {createdAt: {$lt: Fri Jan 01 2016 01:00:00 GMT+0100 (CET)}}}
$ltekey<=valscore<=-5{filter: {score: {$lte: -5}}}
$nekey!=valstatus!=success{filter: {status: {$ne: 'success'}}}
$inkey=val1,val2country=GB,US{filter: {country: {$in: ['GB', 'US']}}}
$ninkey!=val1,val2lang!=fr,en{filter: {lang: {$nin: ['fr', 'en']}}}
$existskeyphone{filter: {phone: {$exists: true}}}
$exists!key!email{filter: {email: {$exists: false}}}
$regexkey=/value/<opts>email=/@gmail\.com$/i{filter: {email: /@gmail.com$/i}}
$regexkey!=/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.
  • 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
About
Convert URL query parameters to MongoDB queries
Topics
apimongodbmongodb-querymongoosequery-builderurl
Resources
Readme
License
Activity
Stars
179 stars
Watchers
2 watching
Forks
35 forks
Report repository
Releases
Packages
Used by
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
api-query-params
NPM version
Coveralls StatusDependency StatusDownloads
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
importaqpfrom'api-query-params';constquery=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
importexpressfrom'express';importaqpfrom'api-query-params';importUserfrom'./models/User';constapp=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){returnnext(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
MongoDBURIExampleResult
$eqkey=valtype=public{filter: {type: 'public'}}
$gtkey>valcount>5{filter: {count: {$gt: 5}}}
$gtekey>=valrating>=9.5{filter: {rating: {$gte: 9.5}}}
$ltkey<valcreatedAt<2016-01-01{filter: {createdAt: {$lt: Fri Jan 01 2016 01:00:00 GMT+0100 (CET)}}}
$ltekey<=valscore<=-5{filter: {score: {$lte: -5}}}
$nekey!=valstatus!=success{filter: {status: {$ne: 'success'}}}
$inkey=val1,val2country=GB,US{filter: {country: {$in: ['GB', 'US']}}}
$ninkey!=val1,val2lang!=fr,en{filter: {lang: {$nin: ['fr', 'en']}}}
$existskeyphone{filter: {phone: {$exists: true}}}
$exists!key!email{filter: {email: {$exists: false}}}
$regexkey=/value/<opts>email=/@gmail\.com$/i{filter: {email: /@gmail.com$/i}}
$regexkey!=/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.
  • 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
About
Convert URL query parameters to MongoDB queries
Topics
apimongodbmongodb-querymongoosequery-builderurl
Resources
Readme
License
Activity
Stars
179 stars
Watchers
2 watching
Forks
35 forks
Report repository
Releases
Packages
Used by
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
BranchesTags
Repository files navigation
api-query-params
NPM version
Coveralls StatusDependency StatusDownloads
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
importaqpfrom'api-query-params';constquery=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
importexpressfrom'express';importaqpfrom'api-query-params';importUserfrom'./models/User';constapp=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){returnnext(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
MongoDBURIExampleResult
$eqkey=valtype=public{filter: {type: 'public'}}
$gtkey>valcount>5{filter: {count: {$gt: 5}}}
$gtekey>=valrating>=9.5{filter: {rating: {$gte: 9.5}}}
$ltkey<valcreatedAt<2016-01-01{filter: {createdAt: {$lt: Fri Jan 01 2016 01:00:00 GMT+0100 (CET)}}}
$ltekey<=valscore<=-5{filter: {score: {$lte: -5}}}
$nekey!=valstatus!=success{filter: {status: {$ne: 'success'}}}
$inkey=val1,val2country=GB,US{filter: {country: {$in: ['GB', 'US']}}}
$ninkey!=val1,val2lang!=fr,en{filter: {lang: {$nin: ['fr', 'en']}}}
$existskeyphone{filter: {phone: {$exists: true}}}
$exists!key!email{filter: {email: {$exists: false}}}
$regexkey=/value/<opts>email=/@gmail\.com$/i{filter: {email: /@gmail.com$/i}}
$regexkey!=/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.
  • 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
About
Convert URL query parameters to MongoDB queries
Topics
apimongodbmongodb-querymongoosequery-builderurl
Resources
Readme
License
Activity
Stars
179 stars
Watchers
2 watching
Forks
35 forks
Report repository
Releases
Packages
Used by
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
api-query-params
NPM version
Coveralls StatusDependency StatusDownloads
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
importaqpfrom'api-query-params';constquery=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
importexpressfrom'express';importaqpfrom'api-query-params';importUserfrom'./models/User';constapp=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){returnnext(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
MongoDBURIExampleResult
$eqkey=valtype=public{filter: {type: 'public'}}
$gtkey>valcount>5{filter: {count: {$gt: 5}}}
$gtekey>=valrating>=9.5{filter: {rating: {$gte: 9.5}}}
$ltkey<valcreatedAt<2016-01-01{filter: {createdAt: {$lt: Fri Jan 01 2016 01:00:00 GMT+0100 (CET)}}}
$ltekey<=valscore<=-5{filter: {score: {$lte: -5}}}
$nekey!=valstatus!=success{filter: {status: {$ne: 'success'}}}
$inkey=val1,val2country=GB,US{filter: {country: {$in: ['GB', 'US']}}}
$ninkey!=val1,val2lang!=fr,en{filter: {lang: {$nin: ['fr', 'en']}}}
$existskeyphone{filter: {phone: {$exists: true}}}
$exists!key!email{filter: {email: {$exists: false}}}
$regexkey=/value/<opts>email=/@gmail\.com$/i{filter: {email: /@gmail.com$/i}}
$regexkey!=/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.
  • 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
About
Convert URL query parameters to MongoDB queries
Topics
apimongodbmongodb-querymongoosequery-builderurl
Resources
Readme
License
Activity
Stars
179 stars
Watchers
2 watching
Forks
35 forks
Report repository
Releases
Packages
Used by
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
api-query-params
NPM version
Coveralls StatusDependency StatusDownloads
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
importaqpfrom'api-query-params';constquery=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
importexpressfrom'express';importaqpfrom'api-query-params';importUserfrom'./models/User';constapp=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){returnnext(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
MongoDBURIExampleResult
$eqkey=valtype=public{filter: {type: 'public'}}
$gtkey>valcount>5{filter: {count: {$gt: 5}}}
$gtekey>=valrating>=9.5{filter: {rating: {$gte: 9.5}}}
$ltkey<valcreatedAt<2016-01-01{filter: {createdAt: {$lt: Fri Jan 01 2016 01:00:00 GMT+0100 (CET)}}}
$ltekey<=valscore<=-5{filter: {score: {$lte: -5}}}
$nekey!=valstatus!=success{filter: {status: {$ne: 'success'}}}
$inkey=val1,val2country=GB,US{filter: {country: {$in: ['GB', 'US']}}}
$ninkey!=val1,val2lang!=fr,en{filter: {lang: {$nin: ['fr', 'en']}}}
$existskeyphone{filter: {phone: {$exists: true}}}
$exists!key!email{filter: {email: {$exists: false}}}
$regexkey=/value/<opts>email=/@gmail\.com$/i{filter: {email: /@gmail.com$/i}}
$regexkey!=/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.
  • 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
About
Convert URL query parameters to MongoDB queries
Topics
apimongodbmongodb-querymongoosequery-builderurl
Resources
Readme
License
Activity
Stars
179 stars
Watchers
2 watching
Forks
35 forks
Report repository
Releases
Packages
Used by
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
BranchesTags
Repository files navigation
api-query-params
NPM version
Coveralls StatusDependency StatusDownloads
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
importaqpfrom'api-query-params';constquery=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
importexpressfrom'express';importaqpfrom'api-query-params';importUserfrom'./models/User';constapp=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){returnnext(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
MongoDBURIExampleResult
$eqkey=valtype=public{filter: {type: 'public'}}
$gtkey>valcount>5{filter: {count: {$gt: 5}}}
$gtekey>=valrating>=9.5{filter: {rating: {$gte: 9.5}}}
$ltkey<valcreatedAt<2016-01-01{filter: {createdAt: {$lt: Fri Jan 01 2016 01:00:00 GMT+0100 (CET)}}}
$ltekey<=valscore<=-5{filter: {score: {$lte: -5}}}
$nekey!=valstatus!=success{filter: {status: {$ne: 'success'}}}
$inkey=val1,val2country=GB,US{filter: {country: {$in: ['GB', 'US']}}}
$ninkey!=val1,val2lang!=fr,en{filter: {lang: {$nin: ['fr', 'en']}}}
$existskeyphone{filter: {phone: {$exists: true}}}
$exists!key!email{filter: {email: {$exists: false}}}
$regexkey=/value/<opts>email=/@gmail\.com$/i{filter: {email: /@gmail.com$/i}}
$regexkey!=/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.
  • 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
About
Convert URL query parameters to MongoDB queries
Topics
apimongodbmongodb-querymongoosequery-builderurl
Resources
Readme
License
Activity
Stars
179 stars
Watchers
2 watching
Forks
35 forks
Report repository
Releases
Packages
Used by
Contributors
Languages