api-query-params

library6.1.0jsnpmunverified

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.

database web-framework http-networking

npm install api-query-params

github ↗package ↗

INSTALL

IMPORT

SIG · API-QUERY-PARAMS

api-query-params

databasejavascriptv6.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

aqp

✓ import aqp from 'api-query-params';

✗ const aqp = require('api-query-params');

The library migrated to ES Modules in v6.0.1, breaking CommonJS `require()` usage. `aqp` is the default export.

AqpQuery

✓ import type { AqpQuery } from 'api-query-params';

✗ import { 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)

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

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

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

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

Debug

Known issues

breakingVersion 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.

affects: >=6.0.1

gotchaThe `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.

affects: >=5.1.0

gotchaPrior 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.

affects: <6.1.0

gotchaBefore 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.

affects: <6.1.0

gotchaVersions 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.

affects: <5.3.1

Errors

Common errors & fixes

ReferenceError: require is not defined

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

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'.

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).

Upgrade

Version history

6.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/loris/api-query-params ↗

packagehttps://www.npmjs.com/package/api-query-params ↗