express-query-parser

1.3.3 verified Sat Apr 25 auth: no javascript

An Express.js middleware that automatically parses and transforms query string values from strings to native JavaScript types: null, undefined, boolean, and number. Version 1.3.3 (May 2022) adds empty string conversion. It recursively handles nested objects and arrays. Compared to alternatives like qs (used by Express by default), this package provides a focused, zero-dependency solution with TypeScript type declarations and an ESBuild-based bundle, updated periodically since 2018.

Common errors

error TypeError: queryParser is not a function ↓

cause Default import used instead of named import in ESM environment.

fix

Use named import: import { queryParser } from 'express-query-parser'

error req.query is undefined after using queryParser ↓

cause Middleware is executed after route handler or not applied at all.

fix

Ensure app.use(queryParser(...)) is called before any routes.

error Expected null but got 'null' string ↓

cause parseNull option is disabled (default is true, but may be overridden).

fix

Set parseNull: true in options, or explicitly check version compatibility.

error Number '0' is converted to 0, but I wanted to keep it as string ↓

cause parseNumber is enabled by default.

fix

Disable parseNumber: false if you need to preserve numeric strings.

Warnings

gotcha Parsing options are not part of the user-facing API and cannot be omitted; invalid options object shape will cause fallback to defaults. ↓

fix Always pass an options object even if all defaults are used: queryParser({ parseNull: true, parseUndefined: true, parseBoolean: true, parseNumber: true })

gotcha The middleware does not modify the original req.query object; it creates a new one. This may affect references stored elsewhere. ↓

fix Access parsed values via req.query after middleware runs. Do not rely on previous references.

gotcha Empty strings are converted to null (since v1.3.3). This may break code expecting empty strings. ↓

fix Handle null checks or disable parseNull if you need to preserve empty strings.

gotcha Number conversion uses JavaScript's Number() function; scientific notation like '1e2' becomes 100. May produce NaN for non-numeric strings. ↓

fix Set parseNumber: false if you want to keep numeric strings as strings, or validate numeric strings before parsing.

deprecated The package has not been updated since May 2022. No major bugs or CVEs reported, but it's in low-maintenance mode. ↓

fix Consider alternatives like qs with custom decoder or a more actively maintained parser.

Install

npm install express-query-parser

yarn add express-query-parser

pnpm add express-query-parser

Imports

queryParser

wrong

const queryParser = require('express-query-parser')

correct

import { queryParser } from 'express-query-parser'

Named export; package supports both ESM and CJS.

queryParser

wrong

const queryParser = require('express-query-parser').default

correct

const { queryParser } = require('express-query-parser')

CJS users must destructure the named export; no default export exists.

QueryParserOptions

wrong

import { QueryParserOptions } from 'express-query-parser'

correct

import type { QueryParserOptions } from 'express-query-parser'

TypeScript users should import types with 'type' keyword to avoid runtime inclusion.

Quickstart

Demonstrates basic setup of the queryParser middleware with all parsing options enabled and shows the transformed query object.

import express from 'express';
import { queryParser } from 'express-query-parser';

const app = express();

app.use(
  queryParser({
    parseNull: true,
    parseUndefined: true,
    parseBoolean: true,
    parseNumber: true
  })
);

app.get('/', (req, res) => {
  // GET /?a=null&b=true&c=3.14&d[]=false&d[]=undefined
  // req.query will be: { a: null, b: true, c: 3.14, d: [false, undefined] }
  res.json(req.query);
});

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