Thanks to this package, you can parse and convert query parameters into MongoDB query criteria and options.

npm install qs-to-mongo

import qs2m from 'qs-to-mongo' // or const qs2m = require('qs-to-mongo')
const result = qs2m('name=john&age>21&fields=name,age&sort=name,-age&offset=10&limit=10')

The result will be

{
  criteria: {
    name: 'john',
    age: { $gt: 21 }
  },
  options: {
    fields: { name: true, age: true },
    sort: { name: 1, age: -1 },
    offset: 10,
    limit: 10
  }
}

Resulting object props (criteria and options) are usable as parameters for any MongoDB driver or ODM. For example:

import qs2m from 'qs-to-mongo'
import { MongoClient } from 'mongodb'

;(async function() {
    const { db } = await MongoClient.connect(connectionString)
    const result = qs2m('name=john&age>21&fields=name,age&sort=name,-age&offset=10&limit=10')
    const documents = await db('dbName')
      .collection('collectionName')
      .find(result.criteria, result.options)
})().catch(console.log)

qs2m(query: string, options: {
  ignoredFields?: string | string[]
  parser?: {
    parse(query: string, options?: any): any
    stringify(obj: object, options?: any): string
  }
  parserOptions?: object
  dateFields?: string | string[]
  objectIdFields?: string | string[]
  fullTextFields?: string | string[]
  parameters?: Partial<typeof defaultParameters>
  maxLimit?: number
})

• ignoredFields: array of query parameters that are ignored, in addition to default ones: "fields", "omit", "sort", "offset", "limit", "q";
• parser: custom query parser, must implement parse(query: string, options?: any): any and stringify(obj: object, options?: any): string. The default parser is qs;
• parserOptions: options to pass to the query parser;
• dateFields: fields that will be converted to Date. If no fields are passed, any valid date string will be converted to ISOString;
• objectIdFields: fields that will be converted to ObjectId;
• fullTextFields: fields that will be used as criteria when passing the q query parameter;
• parameters: override default parameters used as query options ("fields", "omit", "sort", "offset", "limit", "q"). For example: {fields:'$fields', omit:'$omit', sort:'$sort', offset:'$offset', limit:'$limit'};
• maxLimit: maximum limit that could be passed to the limit option.

{
    criteria: {
        [key: string]: any
    }
    options: {
      projection: {
        [key: string]: 0 | 1
      }
      sort: {
        [key: string]: 1 | -1
      }
      skip: number
      limit: number
    }
    links: (url: string, totalCount: number) => {
        prev: string
        first: string
        next: string
        last: string
    } | null
}

import qs2m from 'qs-to-mongo' //or const qs2m = require('qs-to-mongo')
const query = qs2m('name=john&age>21&offset=20&limit=10')
query.links('http://localhost/api/v1/users', 100)

This will generate an object that could be used by the Express res.links(http://expressjs.com/en/4x/api.html#res.links) method.

{ prev: 'http://localhost/api/v1/users?name=john&age%3E21=&offset=10&limit=10',
  first: 'http://localhost/api/v1/users?name=john&age%3E21=&offset=0&limit=10',
  next: 'http://localhost/api/v1/users?name=john&age%3E21=&offset=30&limit=10',
  last: 'http://localhost/api/v1/users?name=john&age%3E21=&offset=90&limit=10' }

Any query parameters other than the special parameters fields, omit, sort, offset, limit, and q are interpreted as query criteria. For example name=john&age>21 results in a criteria value of:

{
  'name': 'john',
  'age': { $gt: 21 }
}

• Supports standard comparison operations (=, !=, >, <, >=, <=).
• Numeric values, where Number(value) != NaN, are compared as numbers (i.e., field=10 yields {field:10}).
• Values of true and false are compared as booleans (ie. {field: true})
• ObjectId hex strings can be compared as ObjectId instances if `objectIdFields`` is passed.
• Values that are dates are compared as dates (except for YYYY, which matches the number rule) if dateFields is passed. If not, they will be converted to Date ISOString.
• null values are compared as null. For example bar=null yields {bar: null}
• special q query parameter could be used to perform a full-text search on fields passed in the fullTextFields argument.
• Multiple equals comparisons are merged into a $in operator. For example, id=a&id=b yields {id:{$in:['a','b']}}.
• Multiple not-equals comparisons are merged into a $nin operator. For example, id!=a&id!=b yields {id:{$nin:['a','b']}}. Comma-separated values in equals or not-equals yield an $inor$ninoperator. For example,id=a,byields{id:{$in:['a','b']}}`.
• Regex patterns. For example, name=/^john/i yields {id: /^john/i}.
• Parameters without a value check that the field is present. For example, foo&bar=10 yields {foo: {$exists: true}, bar: 10}.
• Parameters prefixed with a not (!) and without a value check that the field is not present. For example, !foo&bar=10 yields {foo: {$exists: false}, bar: 10}.
• Supports some of the named comparison operators ($type, $size and $all). For example, foo:type=string, yeilds { foo: {$type: 'string} }.
• Support for forced string comparison; value in single or double quotes (field='10' or field="10") would force a string compare. Allows for a string with an embedded comma (field="a,b") and quotes (field="that's all folks").

Comparisons on embedded documents should use mongo's dot notation instead of qs (Use foo.bar=value instead of foo[bar]=value) 'extended' syntax.

Although exact matches are handled for either method, comparisons (such as foo[bar]!=value) are not supported because the qs parser expects an equals sign after the nested object reference; if it's not an equals, the remainder is discarded.

You can adjust the default parameters (fields, omit, sort, offset, limit and q) by providing an alternate set as an option. For example:

const parameters = {
  fields:'$fields',
  omit:'$omit',
  sort:'$sort',
  offset:'$offset',
  limit:'$limit',
  q: '$q',
}

const query = q2m(res.query, { parameters: parameters });

This will then interpret the default parameters as query parameters instead of options. For example a query of age>21&omit=false&$omit=a results in a criteria value of:

query.criteria = {
  'age': { $gt: 21 },
  'omit': false
}

and an option value of:

query.option = {
  fields: { a: false }
}

This module also takes parsed query as input, so that it could be used by Fastify or express routes without any further addition.

const querystring = require('querystring')
const qs2m = require('qs-to-mongo')
const query = 'name=john&age>21&fields=name,age&sort=name,-age&offset=10&limit=10'
const q = q2m(querystring.parse(query))

This makes it easy to use it in fastify route:

fastify.get('/api/v1/mycollection', (req, reply) =>{
  const q = q2m(req.query);
  ...
}

or in express one:

router.get('/api/v1/mycollection', function(req, res, next) {
  const q = q2m(res.query);
  ...
}

The format and names for query parameters were inspired by this article about best practices for RESTful APIs.

This package started as a hard fork of https://github.com/pbatey/query-to-mongo. This is a TypeScript port, with some fixes and many improvements. However, this is not a drop-in replacement because of the changes to the public API.

• uses qs instead of querystring for default query parsing
• adds support for null and ObjectId hex string values
• adds passing options to parser with parserOptions parameter
• adds support for fulltext search on predefined fields (using fullTextFields parameter)
• opt-ins date-string conversion to Date with dateFields parameter
• opt-ins hexstring ObjectId parsing with objectIdFields parameter
• renames keywords parameter to parameters
• renames ignore to ignoredFields
• renames fields to projection in returnd mongo options
• removes unused and old code
• written in TypeScript, typed out of the box

MIT