Querymen

2.1.4 verified Sat Apr 25 auth: no javascript maintenance

Querymen is a querystring parsing middleware for Express.js and MongoDB, enabling automatic pagination, sorting, field selection, and custom query filters from URL parameters. Version 2.1.4 is the current stable release, with infrequent updates. It provides a declarative schema to map query parameters to MongoDB query operators like `$gte`, `$in`, and `$exists`, and integrates with mongoose-keywords for full-text search. Compared to alternatives like express-api-query-parser, it offers a more opinionated and schema-driven approach with built-in pagination defaults.

Common errors

error Cannot read property 'query' of undefined ↓

cause Attempting to access req.querymen before the middleware has run or the route is incorrectly configured.

fix

Ensure the middleware is applied to the route: app.get('/posts', query(), handler).

error export 'middleware' was not found in 'querymen' ↓

cause Using a bundler that does not support named exports from CommonJS modules (e.g., Webpack with strict ESM).

fix

Use import querymen from 'querymen' and then const query = querymen.middleware or enable esModuleInterop in TypeScript.

error Schema is not a constructor ↓

cause Using `import { Schema } from 'querymen'` but expecting a default export instead of a named export.

fix

Use import { Schema } from 'querymen' (named export) or const { Schema } = require('querymen').

Warnings

gotcha The parsed query object is attached to req.querymen, not req.query. Overwriting req.query is not supported. ↓

fix Access parsed data via req.querymen (e.g., req.querymen.query).

gotcha Boolean parameters like `active=true` are parsed as JSON booleans, not strings. Ensure your MongoDB schema expects boolean values. ↓

fix Use `{ type: Boolean }` in schema definition; query values become `true`/`false`.

deprecated The default `q` parameter for full-text search is designed for mongoose-keywords and may not work with other search setups. ↓

fix Define a custom schema with a `RegExp` type parameter and specify `paths` and `operator` for custom search behavior.

gotcha Array parameters like `tags=world,travel` are split by comma and used with `$in` operator. No support for other array operators out of the box. ↓

fix For other array operators (e.g., `$all`), define a custom schema with a custom formatter.

gotcha Date parameters are parsed via `new Date(value)`. Invalid date strings may result in `Invalid Date` objects or unexpected behavior. ↓

fix Ensure date strings are ISO 8601 compliant (e.g., '2016-04-23') to avoid parsing issues.

Install

npm install querymen

yarn add querymen

pnpm add querymen

Imports

middleware

wrong

const query = require('querymen').middleware

correct

import { middleware as query } from 'querymen'

ESM style is recommended; CJS require is also supported but less common.

Schema

wrong

import Schema from 'querymen'

correct

import { Schema } from 'querymen'

Schema is a named export, not a default export.

querymen object
wrong
```
const { query } = req;
```
correct
```
const { querymen } = req;
```
The parsed data is attached to req.querymen, not req.query.

Quickstart

Demonstrates basic usage of Querymen middleware with Express, handling pagination and sorting from query string parameters.

import express from 'express';
import { middleware as query } from 'querymen';

const app = express();

app.get('/posts', query(), (req, res) => {
  const { query, select, cursor } = req.querymen;
  // Example: fetch posts with pagination and sorting from query string
  // User requests: /posts?page=2&limit=10&sort=-createdAt
  Post.find(query, select, cursor, (err, posts) => {
    res.json(posts);
  });
});

app.listen(3000);