mongoose-query-find

A fluent, chainable query builder for Mongoose that handles filtering, global search, sorting, field projection, population, and pagination — all driven directly from URL query parameters with zero boilerplate.

Table of Contents

• Installation
• Quick Start
• Constructor
• Builder Methods
  • .allowFields()
  • .filter()
  • .where()
  • .globalSearch()
  • .sort()
  • .limitFields()
  • .populate()
• Terminal Method
  • .paginate()
• Query Parameter Reference
• Full Example (Express)
• TypeScript Types
• Security
• Links
• License

Installation

npm install mongoose-query-find

yarn add mongoose-query-find

pnpm add mongoose-query-find

Peer dependency: requires mongoose ^8 or mongoose ^9 installed in your project.

Quick Start

import { queryFind } from 'mongoose-query-find';
import UserModel from './models/user';

const result = await queryFind(UserModel.find(), req.query)
  .allowFields(['name', 'email', 'role', 'createdAt'])
  .where({ deletedAt: null })
  .filter()
  .globalSearch(['name', 'email'])
  .sort()
  .limitFields('-password -__v')
  .paginate();

result will look like:

{
  "data": [...],
  "total": 84,
  "page": 2,
  "totalPages": 9,
  "limit": 10,
  "hasNextPage": true,
  "hasPrevPage": true
}

Constructor

new QueryFind(query, queryString, options?);
// or use the factory function (recommended):
queryFind(query, queryString, options?);

| Parameter | Type | Description | | ------------- | ----------------------------------- | ----------------------------------------------------- | | query | Query<TRawDocType[], TRawDocType> | A Mongoose query, e.g. Model.find() | | queryString | QueryParams | The parsed URL query object, e.g. req.query | | options | QueryFindOptions (optional) | Configuration options (see Options below) |

Options

| Option | Type | Default | Description | | ----------- | -------- | ------- | ---------------------------------------------------------------------- | | maxTimeMS | number | 5000 | Max milliseconds MongoDB may spend on each query. Pass 0 to disable. |

Builder Methods

All builder methods return this and are fully chainable. The recommended call order is:

allowFields → where → filter → globalSearch → sort → limitFields → populate → paginate

.allowFields(fields: string[])

Declares which fields may appear in URL filters, sort parameters, and field projections. Acts as an allowlist — any field not listed is silently stripped from client input before it reaches MongoDB.

Call this before .filter(), .sort(), and .limitFields().

.allowFields(['name', 'email', 'role', 'createdAt'])

.filter()

Parses the URL query string into a Mongoose filter. Automatically:

• Strips reserved keys (page, limit, sort, fields, q)
• Converts comparison operator names to MongoDB $ syntax (gt → $gt, lte → $lte, etc.)
• Recursively coerces string booleans to real booleans ("true" → true, "false" → false)
• Coerces date-like strings to Date instances for fields named createdAt, updatedAt, deletedAt, date, birthDate, or expiresAt
• Recursively validates and rejects banned operators ($where, $expr, $function, etc.)

Supported operators: eq, ne, gt, gte, lt, lte, in, nin

GET /users?age[gte]=18&isActive=true&role=admin

.filter()
// → { age: { $gte: 18 }, isActive: true, role: 'admin' }

.where(conditions)

Applies mandatory server-side conditions that the URL cannot override. Use this for multi-tenancy, soft-delete exclusion, and any security-critical constraints.

.where({ orgId: req.user.orgId, deletedAt: null })

.where() always wins — conditions are merged after .filter() and will overwrite any conflicting URL params.

.globalSearch(fields: string[])

Adds a case-insensitive $or regex search across the specified fields when the ?q= query parameter is present. If q is absent or exceeds 200 characters, this method is a no-op.

Search terms are regex-escaped to prevent ReDoS attacks.

GET /users?q=john

.globalSearch(['name', 'email'])
// → { $or: [{ name: /john/i }, { email: /john/i }] }

If a $or clause already exists in the filter (e.g. from .filter()), both are safely merged under $and.

.sort()

Applies sort order from the ?sort= query parameter. Prefix a field with - for descending order. Multiple fields are comma-separated, capped at 5 fields.

GET /users?sort=-createdAt,name

.sort()
// → sorts by createdAt DESC, then name ASC

Defaults to { createdAt: -1 } when the sort param is absent. Fields not in the allowlist are silently skipped.

.limitFields(defaultFields?: string)

Controls which fields are returned (projection). Uses the ?fields= query param when present, otherwise falls back to defaultFields.

Fields requested via ?fields= are filtered against the allowlist — clients cannot project sensitive fields like password or resetToken.

Priority order:

1. ?fields= query param — always wins when present (allowlist-filtered)
2. defaultFields argument — used as fallback when no query param
3. No projection when both are absent (all fields returned)

GET /users?fields=name,email,role

.limitFields('-password -__v')
// With ?fields=name,email,role  → selects only name, email, role
// Without ?fields               → excludes password and __v

.populate(path: string | PopulateOptions, select?: string)

Registers a populate directive. Chainable — each call appends to the internal list. All registered populates are applied inside paginate().

Accepts the same arguments as Mongoose's own .populate():

// Plain path string
.populate('author')

// Path + select string
.populate('author', 'name email')

// Full PopulateOptions object
.populate({ path: 'comments', select: 'text createdAt', match: { visible: true } })

// Multiple calls — fully chainable
.populate('author')
.populate({ path: 'comments', select: 'text createdAt' })

Terminal Method

.paginate()

Executes the query and returns a Promise<PaginatedResult<T>>.

• countDocuments and find run in parallel via Promise.all (saves one network round-trip).
• Uses estimatedDocumentCount as a fast-path when no filter is applied (O(1) vs O(n)).
• .lean() is applied for ~3–5× faster reads on plain object responses.
• maxTimeMS is applied to both count and find to prevent runaway collection scans.
• If the requested page exceeds totalPages (e.g. after a deletion), page 1 is returned automatically.

GET /users?page=2&limit=20

Returns:

{
  data: T[];
  total: number;        // Total matching documents across all pages
  page: number;         // Current page (auto-corrects to 1 if out of range)
  totalPages: number;
  limit: number;
  hasNextPage: boolean;
  hasPrevPage: boolean;
}

Defaults: page=1, limit=10, max limit=100.

Query Parameter Reference

| Parameter | Example | Description | | ----------- | ------------------------- | ------------------------------------------------------ | | page | ?page=3 | Page number (default: 1, min: 1) | | limit | ?limit=25 | Documents per page (default: 10, max: 100) | | sort | ?sort=-createdAt,name | Sort fields; prefix - for descending (max: 5 fields) | | fields | ?fields=name,email | Comma-separated fields to include in the response | | q | ?q=john | Global search term (max: 200 chars) | | (any key) | ?role=admin&age[gte]=18 | Field-level filters processed by .filter() |

Full Example (Express)

import { Request, Response } from 'express';
import { queryFind } from 'mongoose-query-find';
import UserModel from '../models/user';

export const getUsers = async (req: Request, res: Response) => {
  const result = await queryFind(UserModel.find(), req.query)
    .allowFields(['name', 'email', 'username', 'role', 'isActive', 'createdAt'])
    .where({ orgId: req.user.orgId, deletedAt: null })
    .filter()
    .globalSearch(['name', 'email', 'username'])
    .sort()
    .limitFields('-password -__v')
    .populate('role', 'name permissions')
    .paginate();

  res.json({ status: 'success', ...result });
};

Example requests:

# Page 2, 15 per page, only active admins sorted by name
GET /users?page=2&limit=15&role=admin&isActive=true&sort=name

# Search "alice" across name, email, and username
GET /users?q=alice

# Users older than 25, return only name and email
GET /users?age[gt]=25&fields=name,email

# Filter by exact date
GET /users?createdAt=2024-06-01

# Filter by date range
GET /users?createdAt[gte]=2024-01-01&createdAt[lte]=2024-12-31

# Combined: search + filter + sort + pagination
GET /users?q=john&role=editor&sort=-createdAt&page=1&limit=5

TypeScript Types

All types are exported:

import {
  queryFind,
  QueryFind,
  QueryParams,
  PaginatedResult,
  QueryFindOptions,
} from 'mongoose-query-find';

interface QueryParams {
  page?: string;
  limit?: string;
  sort?: string;
  fields?: string;
  q?: string;
  [key: string]: unknown;
}

interface PaginatedResult<T> {
  data: T[];
  total: number;
  page: number;
  totalPages: number;
  limit: number;
  hasNextPage: boolean;
  hasPrevPage: boolean;
}

interface QueryFindOptions {
  maxTimeMS?: number; // default: 5000
}

Security

| Protection | Detail | | --------------------------- | ---------------------------------------------------------------------------------------- | | NoSQL injection | Allowlist enforced on filters, sort, and projection via .allowFields() | | Banned operators | $where, $expr, $function, and others are rejected recursively at any nesting depth | | ReDoS | Search terms are regex-escaped before compilation | | Oversized search | ?q= capped at 200 characters | | Deep nesting DoS | Filter object nesting capped at depth 5 | | Page size DoS | limit hard-capped at 100 | | Sort abuse | Sort fields hard-capped at 5 | | Runaway queries | maxTimeMS applied to both count and find (default: 5s) | | Sensitive field leakage | ?fields= projection stripped against allowlist |

Links

• npm
• GitHub
• Issues

License

ISC © [email protected]