mongo-query-builder

An API query parser for Mongoose and MongoDB. Automatically converts URL search parameters (filters, pagination, sorting, field selection, population) directly into MongoDB query parameters and chains them onto your Mongoose query.

Features

• 🚀 Zero dependencies — extremely fast and clean.
• 🔍 Dynamic Filtering — converts logical operators (e.g. age[gte]=18 -> { age: { $gte: 18 } }).
• 🔢 Auto Type Coercion — parses string values (e.g. "true", "false", "null", "123") into proper JavaScript primitives.
• 📑 Built-in Pagination — automatically calculates skip and limit from page and limit.
• 🔀 Comma-separated Lists — parses lists for sorting, selection, enums, and population (e.g. sort=-createdAt,name -> '-createdAt name').
• 🔗 Mongoose Integration — single .apply(query) method to easily chain properties onto Mongoose models.

Installation

npm install mongo-query-buils

Note: mongoose is listed as a peer dependency.

Usage

1. Parsing Raw Queries

const { MongoQueryBuilder } = require('mongo-query-buils');

// Express req.query: /api/users?status=active&age[gte]=18&sort=-createdAt&select=name,email&page=2&limit=5
const reqQuery = {
  status: 'active',
  age: { gte: '18' },
  sort: '-createdAt',
  select: 'name,email',
  page: '2',
  limit: '5'
};

const builder = new MongoQueryBuilder(reqQuery);
const parsed = builder.build();

console.log(parsed);
/* Output:
{
  filter: { status: 'active', age: { '$gte': 18 } },
  sort: '-createdAt',
  select: 'name email',
  page: 2,
  limit: 5,
  skip: 5,
  populate: []
}
*/

2. Applying to Mongoose Models

const express = require('express');
const { MongoQueryBuilder } = require('mongo-query-builder');
const User = require('./models/User'); // Mongoose model

const app = express();

app.get('/api/users', async (req, res) => {
  try {
    const builder = new MongoQueryBuilder(req.query);
    
    // Parse filters and automatically execute Mongoose queries
    const query = User.find();
    builder.apply(query);
    
    const users = await query;
    res.json({ success: true, data: users });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

Supported Operators

| URL Syntax | MongoDB Representation | |---|---| | ?field[gt]=value | { field: { $gt: value } } | | ?field[gte]=value | { field: { $gte: value } } | | ?field[lt]=value | { field: { $lt: value } } | | ?field[lte]=value | { field: { $lte: value } } | | ?field[ne]=value | { field: { $ne: value } } | | ?field[in]=v1,v2 | { field: { $in: [v1, v2] } } | | ?field[nin]=v1,v2 | { field: { $nin: [v1, v2] } } | | ?field[exists]=true | { field: { $exists: true } } | | ?field[regex]=v | { field: { $regex: 'v' } } |

License

MIT