URL-encoded Parser

Middleware for parsing URL-encoded form data. Only parses requests where the Content-Type header matches the type option and supports automatic inflation of compressed bodies.

Capabilities

URL-encoded Parser Factory

Creates middleware that parses URL-encoded bodies and populates req.body with the parsed data as key-value pairs.

/**
 * Create middleware to parse URL-encoded bodies
 * @param {object} [options] - Configuration options
 * @returns {function} Express middleware function
 */
function urlencoded(options?: {
  extended?: boolean;
  inflate?: boolean;
  limit?: number | string;
  parameterLimit?: number;
  type?: string | string[] | ((req: IncomingMessage) => boolean);
  verify?: (req: IncomingMessage, res: ServerResponse, buf: Buffer, encoding: string) => void;
  defaultCharset?: string;
  charsetSentinel?: boolean;
  interpretNumericEntities?: boolean;
  depth?: number;
}): (req: IncomingMessage, res: ServerResponse, next: (err?: any) => void) => void;

Options

extended

• Type: boolean
• Default: false
• Description: When false, uses querystring library (strings/arrays only). When true, uses qs library allowing rich objects and arrays

inflate

• Type: boolean
• Default: true
• Description: When true, deflated (compressed) bodies will be inflated; when false, deflated bodies are rejected

limit

• Type: number | string
• Default: '100kb'
• Description: Controls the maximum request body size. If a number, specifies bytes; if a string, passed to the bytes library for parsing

parameterLimit

• Type: number
• Default: 1000
• Description: Maximum number of parameters allowed in the URL-encoded data. Returns 413 if exceeded

type

• Type: string | string[] | function
• Default: 'application/x-www-form-urlencoded'
• Description: Determines what media type the middleware will parse. Can be an extension name, MIME type, MIME type with wildcard, or function

verify

• Type: function
• Default: undefined
• Description: Called as verify(req, res, buf, encoding) where buf is the raw request body Buffer. Can abort parsing by throwing an error

defaultCharset

• Type: string
• Default: 'utf-8'
• Description: Default charset to parse as if not specified in Content-Type. Must be either 'utf-8' or 'iso-8859-1'

charsetSentinel

• Type: boolean
• Default: false
• Description: Whether to let the value of the utf8 parameter take precedence as charset selector

interpretNumericEntities

• Type: boolean
• Default: false
• Description: Whether to decode numeric entities like ☺ when parsing iso-8859-1 forms

depth

• Type: number
• Default: 32
• Description: Maximum depth for qs library when extended is true. Limits the amount of keys parsed to prevent abuse

Usage Examples

Basic URL-encoded parsing (simple mode):

const bodyParser = require('body-parser');
const express = require('express');

const app = express();

// Simple parsing - strings and arrays only
app.use(bodyParser.urlencoded({ extended: false }));

app.post('/form', (req, res) => {
  console.log(req.body); // { name: "John", age: "30", hobbies: ["reading", "coding"] }
  res.send('Form received');
});

Extended parsing for rich objects:

// Extended parsing - supports nested objects
app.use(bodyParser.urlencoded({ extended: true }));

app.post('/form', (req, res) => {
  console.log(req.body); 
  // { user: { name: "John", profile: { age: 30, active: true } } }
  res.send('Form received');
});

Custom options:

app.use(bodyParser.urlencoded({
  extended: true,
  limit: '10mb',
  parameterLimit: 5000,
  depth: 10,
  defaultCharset: 'iso-8859-1'
}));

Charset handling:

app.use(bodyParser.urlencoded({
  extended: false,
  charsetSentinel: true,
  interpretNumericEntities: true,
  defaultCharset: 'iso-8859-1'
}));

Custom type checking:

app.use(bodyParser.urlencoded({
  extended: true,
  type: (req) => {
    return req.headers['content-type'] && 
           req.headers['content-type'].includes('form-urlencoded');
  }
}));

With verification:

app.use(bodyParser.urlencoded({
  extended: false,
  verify: (req, res, buf, encoding) => {
    // Ensure form data isn't too complex
    const paramCount = buf.toString().split('&').length;
    if (paramCount > 100) {
      throw new Error('Too many form parameters');
    }
  }
}));

Parsing Modes

Simple Mode (extended: false)

• Uses Node.js built-in querystring library
• Supports strings and arrays only
• Suitable for basic HTML forms
• Example: name=John&age=30&hobbies=reading&hobbies=coding

Extended Mode (extended: true)

• Uses qs library for rich parsing
• Supports nested objects, arrays, and complex structures
• JSON-like experience with URL-encoded data
• Example: user[profile][name]=John&user[profile][age]=30

Error Handling

The URL-encoded parser can throw several types of errors:

• 400 Bad Request: Parse error or range error from depth limit
• 413 Payload Too Large: Body exceeds size limit or too many parameters
• 415 Unsupported Media Type: Unsupported charset

app.use(bodyParser.urlencoded({ extended: false }));

app.use((err, req, res, next) => {
  if (err.type === 'parameters.too.many') {
    return res.status(413).send('Too many form parameters');
  }
  if (err.type === 'querystring.parse.rangeError') {
    return res.status(400).send('Form data too deep');
  }
  if (err.type === 'charset.unsupported') {
    return res.status(415).send('Unsupported charset');
  }
  next(err);
});