rsql-mongodb

library3.0.2jsnpmunverified

Converts RSQL (RESTful Service Query Language) / FIQL query strings into MongoDB query filter objects. v3.0.2 supports comparison operators (=gt=, =lt=, =in=, etc.), logical operators (; for AND, , for OR), parenthesized grouping, regex matching, and automatic type coercion for strings, numbers, booleans, dates, and ObjectId. Released under MIT license. Lightweight, no external dependencies, ships TypeScript definitions.

database

npm install rsql-mongodb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RSQL-MONGODB

rsql-mongodb

databasejavascriptv3.0.2

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.

rsql-mongodb

✓ import rsql from 'rsql-mongodb';

✗ const { rsql } = require('rsql-mongodb');

Default export is the parsing function. ESM default import.

rsql (CommonJS)

✓ const rsql = require('rsql-mongodb');

✗ const { default: rsql } = require('rsql-mongodb');

CommonJS require returns the default export directly. No named export.

TypeScript usage

✓ import rsql from 'rsql-mongodb';

✗ import { rsql } from 'rsql-mongodb';

Type definitions provided. The default import is the correct way.

type import for options

✓ import type { RSQLOptions } from 'rsql-mongodb';

TypeScript only. Options type available for customizing parsing.

Parses a complex RSQL query string with logical operators into a MongoDB filter object.

import rsql from 'rsql-mongodb'; const query = rsql('(age=gt=18;age=lt=65),name=="john"'); console.log(query); // Output: { $or: [ { $and: [ { age: { $gt: 18 } }, { age: { $lt: 65 } } ] }, { name: "john" } ] } // Use directly in MongoDB find // db.collection.find(query);

Debug

Known issues

gotchaDate strings are parsed using the default Date constructor; timezone handling may differ across environments.

fix

Ensure date strings are in ISO 8601 format (e.g., '2023-10-21T00:00:00.000Z') to avoid ambiguous interpretation.

affects: >=1.0.0

gotchaObjectId detection is based on hex string length of 24 characters; may misidentify other 24-character strings (e.g., 'aaaaaaaaaaaaaaaaaaaaaaaa') as ObjectIds.

fix

If not intended, wrap the value in quotes to force string type: _id=="650a7389a7ab39ddcfbc6832"

affects: >=2.0.0

deprecatedRSQL operators =like= and =notlike= were renamed to =regex= and =notregex= in v2.0. The old operators still work but emit deprecation warnings.

fix

Use =regex= and =notregex= instead.

affects: >=2.0.0

gotchaSpecial characters (like parentheses, semicolons, commas) in values must be escaped with backslash. Forgetting to escape leads to parse errors.

fix

Escape characters: \(, \), \;, \,

affects: >=1.0.0

gotchaEmpty query string ('') returns null, not an empty object or error.

fix

Check for null before passing to MongoDB find() — passing null is equivalent to no filter.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Unable to parse RSQL query

Invalid RQL syntax, e.g., missing operator or unmatched parentheses.

fix

Validate the RSQL string with a parser tool or ensure correct bracket pairing and operator usage.

TypeError: rsql is not a function

Import or require path incorrect; likely using a named export instead of default.

fix

Use default import: import rsql from 'rsql-mongodb' or const rsql = require('rsql-mongodb');

MongoDB error: unknown operator: $regex. Did you mean $regex?

mismatched version? Actually this won't happen — $regex is valid. But users might see this if using older mongo driver?

fix

Ensure you are using a recent MongoDB driver that supports $regex.

Cannot find module 'rsql-mongodb'

Package not installed or version mismatch in package.json.

fix

Run npm install rsql-mongodb

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node