mongo-query-kit

A lightweight utility for MongoDB and Mongoose that handles filtering, searching, sorting, pagination, and date range queries for Express APIs — all from req.query.

Installation

npm install mongo-query-kit

Quick Start

import mongoQuery from "mongo-query-kit";

// Pass your Mongoose model, req.query, and options
const result = await mongoQuery(User, req.query, {
  searchFields: ["name", "email"],
});

// result = {
//   data: [...],     // Documents for current page
//   total: 100,      // Total matching documents
//   page: 1,         // Current page number
//   limit: 10,       // Items per page
//   pages: 10        // Total pages
// }

Example — step by step

1. Define a Mongoose model

import mongoose from "mongoose";

const userSchema = new mongoose.Schema(
  {
    name: String,
    email: String,
    role: { type: String, default: "user" },
    status: { type: String, default: "active" },
  },
  { timestamps: true }
);

const User = mongoose.model("User", userSchema);

2. Use it in an Express route

import express from "express";
import mongoQuery from "mongo-query-kit";
import User from "./models/User.js";

const app = express();

app.get("/users", async (req, res) => {
  try {
    const result = await mongoQuery(User, req.query, {
      searchFields: ["name", "email"],
    });
    res.json(result);
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

3. Make requests

# Basic pagination
GET /users?page=1&limit=10

# Search by name or email
GET /users?search=karthik

# Filter by field
GET /users?role=admin&status=active

# Sort (prefix with - for descending)
GET /users?sort=-createdAt

# Date range
GET /users?startDate=2025-01-01&endDate=2025-12-31

# Everything together
GET /users?page=1&limit=10&search=karthik&sort=-createdAt&role=admin

That's it — no manual query building, no repetitive code.

API

mongoQuery(model, queryParams, options)

| Param | Type | Default | Description | | ----------- | ------ | ------- | -------------------- | | model | Model | required | Mongoose model | | queryParams | object | {} | Express req.query | | options | object | {} | See options below |

Options

| Option | Type | Default | Description | | ------------ | -------- | ------- | --------------------------- | | searchFields | string[] | [] | Fields to search by keyword | | select | string | null | Field projection string |

Return value

{
  data: [],    // Paginated documents
  total: 100,  // Total matching documents
  page: 1,     // Current page
  limit: 10,   // Items per page
  pages: 10    // Total pages
}

Query parameters reference

| Param | Type | Example | Description | | --------- | ------ | ------------------------------ | ------------------------ | | page | number | ?page=2 | Page number (default: 1) | | limit | number | ?limit=20 | Items per page (default: 10) | | sort | string | ?sort=-createdAt or ?sort=name | Sort field (prefix - for descending) | | search | string | ?search=karthik | Keyword search across specified fields | | startDate | string | ?startDate=2025-01-01 | Filter records created on or after this date | | endDate | string | ?endDate=2025-12-31 | Filter records created on or before this date | | Any field | string | ?role=admin&status=active | Direct field filter on the model |

Security

The following query parameters are automatically ignored to prevent dangerous query injection:

• password
• __proto__
• constructor
• prototype

Running tests

node test.js

License

MIT — feel free to use it in any project.