{"id":15959,"library":"api-query-params","title":"API Query Parameters to MongoDB","description":"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.","status":"active","version":"6.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/loris/api-query-params","tags":["javascript","node","api","query parameters","mongodb","typescript"],"install":[{"cmd":"npm install api-query-params","lang":"bash","label":"npm"},{"cmd":"yarn add api-query-params","lang":"bash","label":"yarn"},{"cmd":"pnpm add api-query-params","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library migrated to ES Modules in v6.0.1, breaking CommonJS `require()` usage. `aqp` is the default export.","wrong":"const aqp = require('api-query-params');","symbol":"aqp","correct":"import aqp from 'api-query-params';"},{"note":"Import `AqpQuery` as a type for TypeScript projects to get proper type inference for the return object.","wrong":"import { AqpQuery } from 'api-query-params';","symbol":"AqpQuery","correct":"import type { AqpQuery } from 'api-query-params';"},{"note":"The `aqp` function can directly accept an already parsed query object (e.g., `req.query` from Express) in addition to a raw query string.","wrong":"import aqp from 'api-query-params';\n// ... later ...\nconst query = aqp(new URLSearchParams(req.query).toString());","symbol":"aqp (parsed object)","correct":"import aqp from 'api-query-params';\n// ... later ...\nconst query = aqp(req.query);"}],"quickstart":{"code":"import express from 'express';\nimport aqp from 'api-query-params';\nimport mongoose from 'mongoose';\n\nconst app = express();\n\n// Dummy Mongoose Setup (replace with your actual connection and model)\nmongoose.connect(process.env.MONGODB_URI ?? 'mongodb://localhost:27017/testdb');\n\nconst UserSchema = new mongoose.Schema({\n  name: String,\n  email: String,\n  age: Number,\n  status: String,\n  createdAt: Date\n});\nconst User = mongoose.model('User', UserSchema);\n\napp.get('/users', async (req, res, next) => {\n  try {\n    const { filter, skip, limit, sort, projection, population } = aqp(req.query);\n\n    // Populate with a dummy 'logs' model if needed for example\n    // In a real app, ensure 'population' paths correspond to actual schemas.\n    const users = await User.find(filter)\n      .skip(skip)\n      .limit(limit)\n      .sort(sort)\n      .select(projection)\n      .populate(population)\n      .exec();\n\n    res.json(users);\n  } catch (err) {\n    next(err);\n  }\n});\n\napp.listen(3000, () => console.log('Server running on port 3000'));","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=6.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.1.0"},{"fix":"Upgrade to `api-query-params@6.1.0` or newer to ensure correct handling of complex path and regex values in query strings.","message":"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.","severity":"gotcha","affected_versions":"<6.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<6.1.0"},{"fix":"Upgrade to `api-query-params@5.3.1` or newer to correctly handle duplicate keys with distinct operators.","message":"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.","severity":"gotcha","affected_versions":"<5.3.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use `require()` syntax with `api-query-params` v6.0.1 or newer, which is an ES Module (ESM) library.","error":"ReferenceError: require is not defined"},{"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');`.","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.","error":"TypeError: aqp is not a function"},{"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).","cause":"Attempting to import the `AqpQuery` type using a value import statement instead of a type-only import in TypeScript, or incorrect version usage.","error":"TS2305: Module '\"api-query-params\"' has no exported member 'AqpQuery'."}],"ecosystem":"npm"}