mongo-query-tools

A lightweight TypeScript utility that converts API query params into safe MongoDB query objects for filtering, searching, sorting, and pagination.

Why mongo-query-tools?

Most backend applications repeatedly implement:

• search
• filters
• pagination
• sorting
• whitelist validation

This package centralizes those concerns into a small reusable utility.

Install

npm install mongo-query-tools

Example

import { buildMongoQuery } from "mongo-query-tools";

const query = {
  page: "1",
  limit: "20",
  search: "john",
  sort: "-createdAt",
  status: "active",
};

const options = buildMongoQuery(query, {
  searchableFields: ["name", "email"],
  allowedFilters: ["status", "role"],
  allowedSorts: ["createdAt", "name"],
  defaultFilters: { isDeleted: false },
  defaultSort: "-createdAt",
  maxLimit: 100,
});

// options.skip uses (page - 1) * limit unless query.skip is explicitly set
const cursor = db.collection("users")
  .find(options.filter)
  .sort(options.sort)
  .skip(options.skip)
  .limit(options.limit);

await User.find(options.filter)
  .sort(options.sort)
  .skip(options.skip)
  .limit(options.limit);

Conditional Filters

Use conditionalFilters to layer Mongo conditions from your app (auth, feature flags, multi-tenant rules) without importing Express/Next into this package. when and filter receive the same query reference passed to buildMongoQuery.

import { buildMongoQuery, type QueryParams } from "mongo-query-tools";

type AppQuery = QueryParams & { mode?: string };

const userId = "current-user-id";

const options = buildMongoQuery(req.query as AppQuery, {
  defaultFilters: {
    isDeleted: false,
    isActive: true,
  },
  searchableFields: ["name", "email", "designation"],
  allowedFilters: ["role"],
  conditionalFilters: [
    {
      when: (query) => query.mode === "personal",
      filter: () => ({ _id: { $ne: userId } }),
    },
  ],
});

Reserved Query Keys

These keys drive pagination/search/sorting and never become filter fields—even if erroneously listed in allowedFilters:

page, limit, skip, sort, search

Sort Format

Comma-separated Mongo-style prefixes:

| Query | Sort | |-------|------| | name | { name: 1 } | | -createdAt | { createdAt: -1 } | | -createdAt,name | { createdAt: -1, name: 1 } |

Documentation

Full Documentation: https://mongoquerytools.com

License

MIT