express-query-parser2

A parser helps you parse request for your express server. You may usually encounter some req.query issues like parsing 'null', 'true' and any numbered string. This parser converts them to the right type.

• Forked from express-query-parser
• ✅ Full Express v5 compatibility - Works seamlessly with both Express v4 and v5
• ✅ TypeScript support - Written in TypeScript with full type definitions
• ✅ Zero breaking changes - Drop-in replacement for the original package

Scenarios

Query with Object

// GET http://localhost/?a=null&b=true&c[d]=false&c[e]=3.14

// without this parser
req.query = {a: 'null', b: 'true', c: {d: 'false', e: '3.14'}}

// with this parser
req.query = {a: null, b: true, c: {d: false, e: 3.14}}

Query with Array

// GET http://localhost/?a[]=null&a[]=false

// without this parser
req.query = {a: ['null', 'false']}

// with this parser
req.query = {a: [null, false]}

Express v5 Compatibility

This package is fully compatible with both Express v4 and Express v5. It automatically detects the Express version and uses the appropriate method to parse query parameters:

• Express v4: Direct assignment to req.query
• Express v5: Property descriptor override (respects Express v5's read-only req.query)

Features

• Parse your query for null / boolean / undefined
• Support nested query
• Support array
• Support numbered string convert
• Full Express v4 and v5 compatibility
• TypeScript support with full type definitions

Installing

You can install via Yarn or npm

yarn add express-query-parser2

npm install express-query-parser2

Supported Versions

• Express: v4.17.1+ and v5.0.0+
• Node.js: v14+ (follows Express requirements)
• TypeScript: v4.0+ (optional, includes full type definitions)

Usage

ES6/TypeScript

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

const app = express()

// For nested object support (user[name]=john -> {user: {name: 'john'}})
// Set query parser to 'extended' before using the middleware
app.set('query parser', 'extended')

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

CommonJS

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

const app = express()

// For nested object support
app.set('query parser', 'extended')

app.use(queryParser())

Important: Nested Object Support

To parse nested query parameters like user[name]=john into {user: {name: 'john'}}, you must configure Express to use the extended query parser:

app.set('query parser', 'extended')

Without this setting, Express uses the simple query parser which keeps bracket notation as literal keys: {'user[name]': 'john'}.

Config Options

| field | desc | type | default | |---|---|---|---| | parseNull | convert all "null" to null | boolean | true | | parseUndefined | convert all "undefined" to undefined | boolean | true | | parseBoolean | convert all "true" to true and "false" to false | boolean | true | | parseNumber | convert all numbered string to int and float | boolean | true |

Local Development and Contributing

I am more than happy to accept PRs for bugs, improvements or new features. Developing your own changes locally is easy, you just need to clone the repo

git clone [email protected]/reediculous456/express-query-parser.git

Then navigate to the project folder

cd express-query-parser

and install the dependencies with either npm or yarn

npm i

yarn

Tests can be ran with the test script

npm run test

yarn test