4.1.1 • Published 9 years ago

mongo-querystring

Licence

MIT

Version

4.1.1

Deps

Vulns

Weekly

Stars

103

Summary Dependency Versions

MongoDB QueryString Parser

Accept MongoDB query parameters through URI queries safe and easy. This is useful when building an API and accepting various user specificed queries.

Features

Aliased query parameters
Blacklisted query parameters
Whitelisted query parameters
Basic operators
- $eq
- $gt
- $gte
- $lt
- $lte
- $ne
- $in
- $nin
- $exists
- $regex
Parse string integers and floats to numbers
Parse string boolean to ture/false booleans

operation	query string	query object
equal	`?foo=bar`	`{ foo: "bar" }`
unequal	`?foo=!bar`	`{ foo: { $ne: "bar" }}`
exists	`?foo=`	`{ foo: { $exists: true }}`
not exists	`?foo=!`	`{ foo: { $exists: false }}`
greater than	`?foo=>10`	`{ foo: { $gt: 10 }}`
less than	`?foo=<10`	`{ foo: { $lt: 10 }}`
greater than or equal to	`?foo=>=10`	`{ foo: { $gte: 10 }}`
less than or equal to	`?foo=<=10`	`{ foo: { $lte: 10 }}`
starts with	`?foo=^bar`	`{ foo: { $regex: "^bar", $options: "i" }}`
ends with	`?foo=$bar`	`{ foo: { $regex: "bar$", $options: "i" }}`
contains	`?foo=~bar`	`{ foo: { $regex: "bar", $options: "i" }}`
in array	`?foo[]=bar&foo[]=baz`	`{ foo: { $in: ['bar', 'baz'] }}`
not in array	`?foo[]=!bar&foo[]=!baz`	`{ foo: { $nin: ['bar', 'baz'] }}`

Geospatial operators
- $geoWithin (polygon)
- $near (point)

operation	query string	query object
bbox	`?bbox=0,1,2,3`	`{ geojson: { $geoWithin: { $geometry: { … } } } }`
near	`?near=0,1`	`{ geojson: { $near: { $geometry: { … } } } }`
near (max distance)	`?near=0,1,2`	`{ geojson: { $near: { …, $maxDistance: 2 } } }`
near (max & min distance)	`?near=0,1,2,3`	`{ geojson: { $near: { …, $minDistance: 3 } } }`

Custom query functions
- after (date)
- before (date)
- between (date|date)

operation	query string	query object
after	`?after=2014-01-01`	`{ endret: { $gte: "2014-01-01T00:00:00.000Z" } }`
after	`?after=1388534400`	`{ endret: { $gte: "2014-01-01T00:00:00.000Z" } }`
before	`?before=2014-01-01`	`{ endret: { $lt: "2014-01-01T00:00:00.000Z" } }`
before	`?before=1388534400`	`{ endret: { $lt: "2014-01-01T00:00:00.000Z" } }`
between	`?between=2014-01-01	2015-01-01`
between	`?between=1388534400	1420088400`

Install

npm install mongo-querystring --save

API

var MongoQS = require('mongo-querystring');

new MongoQS(`object` options)

Array ops - list of supported operators (default: ['!', '^', ')


object alias - query param aliases (default: {})
object blacklist - blacklisted query params (default: {})
object whitelist - whitelisted query params (default: {})
object custom - custom query params (default: {})
object string - string parsing
boolean toBoolean - parse "true", "false" string to booleans (default: true)
boolean toNumber - parse string integer and float values to numbers (default: true)


regexp keyRegex - allowed key names (default: /^[a-zæøå0-9-_.]+$/i)
regexp arrRegex - allowed array key names (default: /^[a-zæøå0-9-_.]+(\[\])?$/i)


Bult in custom queries

bbox - bounding box geostatial query
near - proximity geostatial query
after - modified since query

var qs = new MongoQS({
  custom: {
    bbox: 'geojson',        // your geometry field
    near: 'geojson',        // your geometry field
    after: 'updated_on'     // your last modified field
  }
});
Define custom queries
Custom queries are on the folling form; you define the URL query parameter name
that your users will be using and a function which takes the result query object
and the value for query parameter.
var qs = new MongoQS({
  custom: {
    urlQueryParamName: function(query, input) {
      // do some processing of input value
      // add your queries to the query object
      query['someField'] = input;
      query['someOtherFiled'] = 'some value';
    }
  }
});
qs.parse(object params)
Params is an object with URI query params and their values. Ex. req.params
if you are working with ExpressJS.
var query = qs.parse(req.params);

mongo.collection('mycol').find(query, field).toArray(function(err, documents) {
  // matching documents
});
Collaborators
Individuals making significant and valuable contributions are made Collaborators
and given commit-access to the project. These individuals are identified by the
existing Collaborators and their addition as Collaborators is discussed as a
pull request to this project's README.md.
Note: If you make a significant contribution and are not considered for
commit-access log an issue or contact one of the Collaborators directly.

Andy Klimczak - @andyklimczak
Hans Kristian Flaatten - @Starefossen
Edward Knowles - @eknowles

MIT Licensed
, '~', '>', '<', '$in']

)

__INLINE_CODE_60__ alias - query param aliases (default: __INLINE_CODE_61__)

__INLINE_CODE_62__ blacklist - blacklisted query params (default: __INLINE_CODE_63__)

__INLINE_CODE_64__ whitelist - whitelisted query params (default: __INLINE_CODE_65__)

__INLINE_CODE_66__ custom - custom query params (default: __INLINE_CODE_67__)

__INLINE_CODE_68__ string - string parsing

__INLINE_CODE_69__ toBoolean - parse __INLINE_CODE_70__, __INLINE_CODE_71__ string to booleans (default: __INLINE_CODE_72__)
__INLINE_CODE_73__ toNumber - parse string integer and float values to numbers (default: __INLINE_CODE_74__)

__INLINE_CODE_75__ keyRegex - allowed key names (default: __INLINE_CODE_76__)

__INLINE_CODE_77__ arrRegex - allowed array key names (default: __INLINE_CODE_78__)

Bult in custom queries

__INLINE_CODE_79__ - bounding box geostatial query
__INLINE_CODE_80__ - proximity geostatial query
__INLINE_CODE_81__ - modified since query

var qs = new MongoQS({
  custom: {
    bbox: 'geojson',        // your geometry field
    near: 'geojson',        // your geometry field
    after: 'updated_on'     // your last modified field
  }
});

Define custom queries

Custom queries are on the folling form; you define the URL query parameter name that your users will be using and a function which takes the result query object and the value for query parameter.

var qs = new MongoQS({
  custom: {
    urlQueryParamName: function(query, input) {
      // do some processing of input value
      // add your queries to the query object
      query['someField'] = input;
      query['someOtherFiled'] = 'some value';
    }
  }
});

qs.parse(__INLINE_CODE_82__ params)

Params is an object with URI query params and their values. Ex. __INLINE_CODE_83__ if you are working with ExpressJS.

var query = qs.parse(req.params);

mongo.collection('mycol').find(query, field).toArray(function(err, documents) {
  // matching documents
});

Individuals making significant and valuable contributions are made Collaborators and given commit-access to the project. These individuals are identified by the existing Collaborators and their addition as Collaborators is discussed as a pull request to this project's README.md.

Note: If you make a significant contribution and are not considered for commit-access log an issue or contact one of the Collaborators directly.

Andy Klimczak - @andyklimczak
Hans Kristian Flaatten - @Starefossen
Edward Knowles - @eknowles