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 | { endret: { $gte: "2014-01-01T00:00:00.000Z", $lt: "2015-01-01T00:00:00.000Z" } } | | between | ?between=1388534400|1420088400 | { endret: { $gte: "2014-01-01T00:00:00.000Z", $lt: "2015-01-01T00:00:00.000Z" } } |

Install

npm install mongo-querystring --save

API

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

new MongoQS(object options)

• Array ops - list of supported operators (default: ['!', '^', '$', '~', '>', '<', '$in'])
• 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