npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@geekbears/gb-mongoose-query-parser

v1.3.22

Published

Convert url query string to MongooseJs friendly query object including advanced filtering, sorting, population, deep population, string template, type casting and many more...

Downloads

262

Readme

gb-mongoose-query-parser

This is a fork from: mongoose-quey-parser

Convert url query string to MongooseJs friendly query object including advanced filtering, sorting, lean, population, string template, type casting and many more...

The library is built highly inspired by api-query-params

Features

  • Supports the most of MongoDB operators ($in, $regexp, $exists) and features including skip, sort, limit, lean & MongooseJS population
  • Auto type casting of Number, RegExp, Date, Boolean and null
  • String templates/predefined queries (i.e. firstName=${my_vip_list})
  • Allows customization of keys and options in query string

Installation

npm install gb-mongoose-query-parser -S

Basic Usage

This package exposes a helper class: QueryParser

Get documents based on query string

Import the helper and make sure to have the model available. Call the docByQuery method, specifying the generic type to avoid type inference. The result will be available in the data property of the response.

import { QueryParser } from '@geekbears/gb-mongoose-query-parser';

const res = await QueryParser.docByQuery<UserDocument>(userModel, query);
const data = res.data as UserDocument[];

Count documents based on query string

Import the helper and make sure to have the model available. Call the docByQuery method, specifying the generic type to avoid type inference. Set the count flag to true The result will be available in the data property of the response.

import { QueryParser } from '@geekbears/gb-mongoose-query-parser';

const res = await QueryParser.docByQuery<UserDocument>(userModel, query, true);
const data = res.data as number;

Promise rejection

The docByQuery method returns a Promise. In the event of a runtime error, the promise will be rejected.

Advanced Usage

API

import { MongooseQueryParser } from '@geekbears/gb-mongoose-query-parser';

const parser = new MongooseQueryParser(options?: ParserOptions)
parser.parse(query: string, predefined: any) : QueryOptions
Arguments
  • ParserOptions: object for advanced options (See below) [optional]
  • query: query string part of the requested API URL (ie, firstName=John&limit=10). Works with already parsed object too (ie, {status: 'success'}) [required]
  • predefined: object for predefined queries/string templates [optional]

Returns

  • QueryOptions: object contains the following properties:
    • filter which contains the query criteria
    • populate which contains the query population. Please see Mongoose Populate for more details
    • deepPopulate which contains the query population Oobject. Please see Mongoose Deep Populate for more details
    • select which contains the query projection
    • lean which contains the definition of the query records format
    • sort, skip, limit, which contains the cursor modifiers for paging purpose

Example

import { MongooseQueryParser } from '@geekbears/gb-mongoose-query-parser';

const parser = new MongooseQueryParser();
const predefined = {
  vip: { name: { $in: ['Google', 'Microsoft', 'NodeJs'] } },
  sentStatus: 'sent'
};
const parsed = parser.parse('${vip}&status=${sentStatus}&timestamp>2017-10-01&author.firstName=/john/i&limit=100&skip=50&sort=-timestamp&select=name&populate=children.firstName,children.lastName&lean=true', predefined);
{
  select: { name : 1 },
  populate: [{ path: 'children', select: 'firstName lastName' }],
  sort: { timestamp: -1 },
  skip: 50,
  limit: 100,
  lean: true,
  filter: {
    name: {{ $in: ['Google', 'Microsoft', 'NodeJs'] }},
    status: 'sent',
    timestamp: { '$gt': 2017-09-30T14:00:00.000Z },
    'author.firstName': /john/i
  }
}

Supported features

Filtering operators

| MongoDB | URI | Example | Result | | --------- | -------------------- | ----------------------- | -------------------------------------------------------- | | $eq | key=val | type=public | {filter: {type: 'public'}} | | $gt | key>val | count>5 | {filter: {count: {$gt: 5}}} | | $gte | key>=val | rating>=9.5 | {filter: {rating: {$gte: 9.5}}} | | $lt | key<val | createdAt<2017-10-01 | {filter: {createdAt: {$lt: 2017-09-30T14:00:00.000Z}}} | | $lte | key<=val | score<=-5 | {filter: {score: {$lte: -5}}} | | $ne | key!=val | status!=success | {filter: {status: {$ne: 'success'}}} | | $in | key=val1,val2 | country=GB,US | {filter: {country: {$in: ['GB', 'US']}}} | | $nin | key!=val1,val2 | lang!=fr,en | {filter: {lang: {$nin: ['fr', 'en']}}} | | $exists | key | phone | {filter: {phone: {$exists: true}}} | | $exists | !key | !email | {filter: {email: {$exists: false}}} | | $regex | key=/value/<opts> | email=/@gmail\.com$/i | {filter: {email: /@gmail.com$/i}} | | $regex | key!=/value/<opts> | phone!=/^06/ | {filter: {phone: { $not: /^06/}}} |

For more advanced usage ($or, $type, $elemMatch, etc.), pass any MongoDB query filter object as JSON string in the filter query parameter, ie:

parser.parse('filter={"$or":[{"key1":"value1"},{"key2":"value2"}]}&name=Telstra');
// {
//   filter: {
//     $or: [
//       { key1: 'value1' },
//       { key2: 'value2' }
//     ],
//     name: 'Telstra'
//   },
// }

Populate operators

  • Useful to populate sub-document(s) in query. Works with MongooseJS. Please see Mongoose Populate for more details
  • Allows to populate only selected fields
  • Clean, leaner and easier syntax
  • Default operator key is populate
parser.parse('populate=class,school.name');
// {
//   populate: [{
//     path: 'class'
//   }, {
//     path: 'school',
//     select: 'name'
//   }]
// }

Deep Populate operators

  • For more advanced usage (Deep field population) Please see Mongoose Deep Populate for more details
  • Allows to populate multiple paths with multiple fields
  • Default operator key is deepPopulate
  • Can be used along with the populate option
parser.parse('deepPopulate={"path":"path",  "populate": { "path":"deepPath", "select":"deepField"  }}');

// {
//   populate: {
//     path: 'path'
//     populate:{
//        path:"deepPath",
//        select:"deepField"
//     }
//  }
//

Skip / Limit operators

  • Useful to limit the number of records returned
  • Default operator keys are skip and limit
parser.parse('skip=5&limit=10');
// {
//   skip: 5,
//   limit: 10
// }

Select operator

  • Useful to limit fields to return in each records
  • Default operator key is select
  • 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
parser.parse('select=id,url');
// {
//   select: { id: 1, url: 1}
// }
parser.parse('select=-_id,-email');
// {
//   select: { _id: 0, email: 0 }
// }

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
parser.parse('sort=-points,createdAt');
//  {
//    sort: { points: -1, createdAt: 1 }
//  }

Lean operator

  • Useful to get leaner records
  • Default operator key is lean
  • If lean is set true, it will return true, otherwise it will retun false. If not value provided, the lean operator wil be omitted from the parsed object.
parser.parse('lean=true');
//  {
//    lean: true
//  }

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:

parser.parse('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, Boolean and null string is also casted:

parser.parse('date=2017-10-01&boolean=true&integer=10&regexp=/foobar/i&null=null');
// {
//   filter: {
//     date: 2017-09-30T14:00:00.000Z,
//     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):

parser.parse('key1=string(10)&key2=date(2017-10-01)&key3=string(null)');
// {
//   filter: {
//     key1: '10',
//     key2: 2017-09-30T14:00:00.000Z,
//     key3: 'null'
//   }
// }

String template for predefined query/variable

Best to reducing the complexity/length of the query string with the ES template literal delimiter as an "interpolate" delimiter (i.e. ${something})

const parser = new MongooseQueryParser();
const preDefined = {
  isActive: { status: { $in: ['In Progress', 'Pending'] } },
  secret: 'my_secret'
};
parser.parse('${isActive}&secret=${secret}', preDefined);
// {
//   filter: {
//     status: { $in: ['In Progress', 'Pending'] },
//     secret: 'my_secret'
//   }
// }

Available options (opts)

Customize operator keys

The following options are useful to change the operator default keys:

  • populateKey: custom populate operator key (default is populate)
  • skipKey: custom skip operator key (default is skip)
  • leanKey: custom lean operator key (default is lean)
  • limitKey: custom limit operator key (default is limit)
  • selectKey: custom select operator key (default is select)
  • sortKey: custom sort operator key (default is sort)
  • filterKey: custom filter operator key (default is filter)
  • deepPopulateKey: custom filter operator key (default is deepPopulate)
const parser = new MongooseQueryParser({
  limitKey: 'max',
  skipKey: 'offset',
  leanKey: 'planeRecords'
});
parser.parse('organizationId=123&offset=10&max=125');
// {
//   filter: {
//     organizationId: 123,
//   },
//   skip: 10,
//   limit: 125,
//   lean: true
// }

Date format

  • dateFormat: set date format for auto date casting. Default is ISO_8601 format
  • Allows multiple formats. Works with moment
const parser = new MongooseQueryParser({dateFormat: ['YYYYMMDD', 'YYYY-MM-DD']});
parser.parse('date1=20171001&date2=2017-10-01');
// {
//   filter: {
//     date1: 2017-09-30T14:00:00.000Z
//     date2: 2017-09-30T14:00:00.000Z
//   }
// }

Blacklist

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
parser.parse('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 implicitly mapping a key to a function

  • 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.
const parser = new MongooseQueryParser({
  casters: {
    lowercase: val => val.toLowerCase(),
    int: val => parseInt(val, 10),
  },
  castParams: {
   key3: 'lowercase'
  }});
parser.parse('key1=lowercase(VALUE)&key2=int(10.5)&key3=ABC');
// {
//   filter: {
//     key1: 'value',
//     key2: 10,
//     key3: 'abc'
//   }
// }

License

MIT