API Query Parameters to MongoDB

Common errors

Warnings

Install

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'));