mongo-querystring

library4.1.1jsnpmunverified

A library to parse URL query strings into MongoDB query objects. Version 4.1.1 is the latest stable release. It supports basic operators ($eq, $gt, $gte, $lt, $lte, $ne, $in, $nin, $exists, $regex), geospatial operators ($geoWithin, $near), custom query functions (after, before, between), and features like aliased, blacklisted, and whitelisted parameters. It automatically parses numbers and booleans from strings. Useful for building APIs that accept user-specified MongoDB queries via URL parameters. Differentiators: simple syntax for common MongoDB operations, support for geo queries, and built-in aliasing/blacklisting for security.

database

npm install mongo-querystring

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGO-QUERYSTRING

mongo-querystring

databasejavascriptv4.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import MongoQS from 'mongo-querystring'

✗ const MongoQS = require('mongo-querystring').default

The default export is the constructor. CommonJS require() works as MongoQS = require('mongo-querystring').

MongoQS

✓ const MongoQS = require('mongo-querystring')

✗ const { MongoQS } = require('mongo-querystring')

CommonJS require returns the constructor directly, not an object.

TypeScript types

✓ import MongoQS from 'mongo-querystring'

Library does not ship TypeScript definitions; you may need @types/mongo-querystring or declare module.

Shows using MongoQS with whitelist, blacklist, aliases, and parsing a query string with geospatial near operator.

import MongoQS from 'mongo-querystring'; const qs = new MongoQS({ whitelist: { foo: ['bar', 'baz'] }, blacklist: ['secret'], aliases: { q: 'name' } }); const query = qs.parse('foo=bar&q=test&secret=x&near=0,1,2'); // query: { foo: 'bar', name: 'test', geojson: { $near: { $geometry: { type: 'Point', coordinates: [0,1] }, $maxDistance: 2 } } } console.log(query);

Debug

Known issues

gotchaWhitelist and blacklist are case-sensitive and match the raw query parameter name, not the aliased name.

fix

Use the original parameter name (before alias) in whitelist/blacklist.

affects: >=1.0.0

gotchaThe `$options` in regex queries is always hardcoded to 'i' (case-insensitive) and cannot be changed via query string.

fix

If you need different regex options, use the full $regex syntax with a custom parser.

affects: >=1.0.0

gotchaGeospatial operators (`bbox`, `near`) rely on a field named 'geojson' by default; if your schema uses a different field, you must configure it.

fix

Pass a custom field name in options: `{ geoField: 'location' }`.

affects: >=1.0.0

gotchaThe `between` query function uses '|' as separator, not comma. A common mistake is using comma.

fix

Use pipe: `?between=2014-01-01|2015-01-01`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: MongoQS is not a constructor

Using destructured require: const { MongoQS } = require('mongo-querystring')

fix

Use const MongoQS = require('mongo-querystring')

Cannot find module 'mongo-querystring' or its corresponding type declarations.

Missing TypeScript definitions.

fix

Install @types/mongo-querystring if available, or create a declaration file: declare module 'mongo-querystring';

Expected property whitelist to be an object, got array

Passing an array to whitelist instead of an object mapping parameter names to allowed values.

fix

Use whitelist: { param: ['value1', 'value2'] } instead of whitelist: ['param'].

Upgrade

Version history

4.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/Turistforeningen/node-mongo-querystring ↗

packagemongo-querystring ↗

homepagehttps://github.com/Turistforeningen/node-mongo-querystring#readme ↗