API Query Parameters to MongoDB

6.1.0 · active · verified Tue Apr 21

api-query-params is a JavaScript library designed to convert standard API URL query parameters into MongoDB query objects, facilitating advanced filtering, sorting, and projection directly from HTTP requests. Currently at version 6.1.0, the package sees active maintenance with minor versions and patches released regularly to address bug fixes and introduce new features. Key differentiators include its comprehensive support for most MongoDB operators ($in, $regexp, $gt, etc.), nested object querying, and type casting, while remaining agnostic to the specific web framework (e.g., Express, Koa) or MongoDB library (e.g., Mongoose). It offers customization for query keys and options and is noted for its compact, dependency-free ES6 codebase, aiming for simplicity and full test coverage.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use `require()` syntax with `api-query-params` v6.0.1 or newer, which is an ES Module (ESM) library.

fix Change your import statement from `const aqp = require('api-query-params');` to `import aqp from 'api-query-params';`. Ensure your Node.js environment is configured for ESM (e.g., `"type": "module"` in `package.json`).
```
TypeError: aqp is not a function
```
cause Incorrectly importing `aqp` as a named import when it is a default export, or attempting to use a CommonJS default export in an ESM context incorrectly.

fix Ensure you are using `import aqp from 'api-query-params';` for ESM, or if in a CJS context (pre-v6), `const aqp = require('api-query-params');`.
```
TS2305: Module '"api-query-params"' has no exported member 'AqpQuery'.
```
cause Attempting to import the `AqpQuery` type using a value import statement instead of a type-only import in TypeScript, or incorrect version usage.

fix Use `import type { AqpQuery } from 'api-query-params';` to correctly import the type. Also, ensure you are on a version that ships types (>=5.1.0, with improvements in 5.4.0).

Warnings

breaking Version 6.0.1 of `api-query-params` migrated the entire library to ES Modules (ESM), which breaks existing CommonJS `require()` statements. Applications must migrate to ESM `import` syntax.
Fix: Update your import statements from `const aqp = require('api-query-params');` to `import aqp from 'api-query-params';`. Ensure your project's `package.json` has `"type": "module"` or uses `.mjs` file extensions for ESM compatibility.
gotcha The `population` field returned by `aqp` is specifically formatted for Mongoose's `populate()` method. It will not work out-of-the-box with other MongoDB drivers or ORMs without custom adaptation.
Fix: If not using Mongoose, you will need to manually parse the `population` array and apply it according to your specific ODM/driver's API for managing relationships or joins.
gotcha Prior to v6.1.0, query parameters containing file paths with slashes or regex wildcards could be incorrectly split during parsing, leading to malformed or unintended filters.
Fix: Upgrade to `api-query-params@6.1.0` or newer to ensure correct handling of complex path and regex values in query strings.
gotcha Before v6.1.0, custom casters for object values could erroneously generate a `$not` operator instead of the intended `$ne` (not equal), leading to unexpected query behavior in MongoDB.
Fix: Upgrade to `api-query-params@6.1.0` or newer. If upgrading is not immediately possible, review and potentially adjust custom casters to manually enforce `$ne` where required.
gotcha Versions prior to v5.3.1 had issues correctly parsing multiple query parameters with the same key but different operators (e.g., `field>10&field<20`), leading to incorrect or incomplete query criteria.
Fix: Upgrade to `api-query-params@5.3.1` or newer to correctly handle duplicate keys with distinct operators.

Install

npm install api-query-params npm
yarn add api-query-params yarn
pnpm add api-query-params pnpm

Imports

aqp
wrong:
```
const aqp = require('api-query-params');
```
correct:
```
import aqp from 'api-query-params';
```
The library migrated to ES Modules in v6.0.1, breaking CommonJS `require()` usage. `aqp` is the default export.
AqpQuery
wrong:
```
import { AqpQuery } from 'api-query-params';
```
correct:
```
import type { AqpQuery } from 'api-query-params';
```
Import `AqpQuery` as a type for TypeScript projects to get proper type inference for the return object.

aqp (parsed object)

wrong:

import aqp from 'api-query-params';
// ... later ...
const query = aqp(new URLSearchParams(req.query).toString());

correct:

import aqp from 'api-query-params';
// ... later ...
const query = aqp(req.query);

The `aqp` function can directly accept an already parsed query object (e.g., `req.query` from Express) in addition to a raw query string.

Quickstart

Demonstrates integrating `api-query-params` with Express and Mongoose to build a dynamic API endpoint, parsing request query parameters into MongoDB-compatible queries for filtering, sorting, pagination, and projection.

import express from 'express';
import aqp from 'api-query-params';
import mongoose from 'mongoose';

const app = express();

// Dummy Mongoose Setup (replace with your actual connection and model)
mongoose.connect(process.env.MONGODB_URI ?? 'mongodb://localhost:27017/testdb');

const UserSchema = new mongoose.Schema({
  name: String,
  email: String,
  age: Number,
  status: String,
  createdAt: Date
});
const User = mongoose.model('User', UserSchema);

app.get('/users', async (req, res, next) => {
  try {
    const { filter, skip, limit, sort, projection, population } = aqp(req.query);

    // Populate with a dummy 'logs' model if needed for example
    // In a real app, ensure 'population' paths correspond to actual schemas.
    const users = await User.find(filter)
      .skip(skip)
      .limit(limit)
      .sort(sort)
      .select(projection)
      .populate(population)
      .exec();

    res.json(users);
  } catch (err) {
    next(err);
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

view raw JSON →