qs: Querystring Parser and Stringifier

Common errors

• TypeError: qs.parse is not a function

  cause Attempting to use `qs.parse` or `qs.stringify` as a named import (e.g., `import { parse } from 'qs';`) instead of accessing it as a property of the default exported `qs` object.
  fix For CommonJS, use `const qs = require('qs'); const obj = qs.parse('...');`. For ESM, use `import qs from 'qs'; const obj = qs.parse('...');`.

• Input depth exceeded depth option of X and strictDepth is true

  cause The parsed querystring exceeded the maximum allowed nesting depth (`depth` option), and the `strictDepth` option was set to `true`, causing an error to be thrown instead of silently truncating the nested keys.
  fix Either increase the `depth` option to accommodate the expected nesting level (`qs.parse(str, { depth: <new_depth> })`) or adjust the input to reduce nesting. If truncation is acceptable, remove `strictDepth: true`.

• Unexpected parsed object structure, e.g., `{ 'a[b]': 'c' }` instead of `{ a: { b: 'c' } }` or `{ 'a.b': 'c' }` instead of `{ a: { b: 'c' } }`

  cause This often occurs due to misunderstanding the `allowDots` or `depth` options. For instance, `allowDots` defaults to `true` in v6, preventing dot notation from creating nested objects by default. The `depth` limit can also cause key concatenation.
  fix To parse `a.b=c` into `{ a: { b: 'c' } }`, use `qs.parse(str, { allowDots: false })`. To handle deep nesting, adjust the `depth` option (e.g., `qs.parse(str, { depth: 10 })`).

Warnings

• breaking The `allowDots` option's default value changed from `false` to `true` in `qs` v6.0.0. This means by default, query strings like `a.b=c` will now parse into `{ 'a.b': 'c' }` instead of `{ a: { b: 'c' } }` in previous versions. If you relied on dot notation for nested objects, you might need to explicitly set `allowDots: false` or update your parsing logic.
  Fix: If nested object parsing via dots is desired, set `qs.parse(str, { allowDots: false })`. If you were relying on `{ 'a.b': 'c' }` behavior and upgraded from v5, ensure your code handles the new default.
• breaking The default `arrayLimit` for parsing arrays changed multiple times across major versions (e.g., to 20 in v5, and later). If your application parses arrays with more than the default limit of items (e.g., `a=1&a=2&...&a=21`), elements beyond the limit will be truncated or ignored, potentially leading to data loss if not handled.
  Fix: Always explicitly set `arrayLimit` in `qs.parse(str, { arrayLimit: <your_desired_limit> })` if you expect arrays with a variable or large number of elements to prevent unexpected truncation.
• gotcha By default, `qs.parse` limits object nesting depth to 5 to prevent potential Denial of Service (DoS) attacks from excessively deep query strings. If a query string exceeds this depth, subsequent nested keys are concatenated into a single key, leading to unexpected parsed object structures.
  Fix: For deeply nested structures, provide a higher `depth` option to `qs.parse(string, { depth: <max_depth> })`. Consider also using `strictDepth: true` to throw an error instead of truncating, making unexpected depth explicit.
• breaking Setting `allowPrototypes: true` in `qs.parse` or `qs.stringify` can introduce severe prototype pollution vulnerabilities. This option allows user-controlled input to modify properties on `Object.prototype`, which can impact all objects in the application and lead to remote code execution or other critical security flaws.
  Fix: NEVER set `allowPrototypes: true` with untrusted user input. By default, `qs` prevents this. If you need to handle keys like `__proto__`, `constructor`, or `prototype` as actual data keys, use `plainObjects: true` to return a null-prototype object (`Object.create(null)`), which isolates the parsed data from the global `Object.prototype`.

Install

• npm install qs npm
• yarn add qs yarn
• pnpm add qs pnpm

Imports

• qs
  wrong:

  import qs from 'qs';

  correct:

  const qs = require('qs');

  CommonJS is the primary documented import style. While `import qs from 'qs'` generally works in modern environments due to bundler/Node.js interop, `require()` is explicitly shown in documentation examples and offers more direct compatibility.
• qs.parse
  wrong:

  import { parse } from 'qs';

  correct:

  const { parse } = require('qs');

  The `qs` module exports a single default object. Named imports like `import { parse } from 'qs'` will not work directly as `parse` is a method of the default exported object, not a top-level named export. Destructuring from the `require`'d object is the correct way.
• qs.stringify
  wrong:

  import { stringify } from 'qs';

  correct:

  const qs = require('qs');
  const stringify = qs.stringify;

  `stringify` is a method on the default `qs` object. Attempting to directly import it as a named export will result in an error.

Quickstart

Demonstrates basic `qs.parse` and `qs.stringify` functionality, including nested objects, arrays, and the default depth limit behavior.

const qs = require('qs');
const assert = require('assert');

// Parsing a simple querystring
let obj = qs.parse('a=c&b=d');
assert.deepEqual(obj, { a: 'c', b: 'd' });

// Stringifying an object
let str = qs.stringify({ a: 'c', b: 'd' });
assert.equal(str, 'a=c&b=d');

// Parsing a nested object
obj = qs.parse('foo[bar]=baz');
assert.deepEqual(obj, { foo: { bar: 'baz' } });

// Parsing an array
obj = qs.parse('a=b&a=c');
assert.deepEqual(obj, { a: ['b', 'c'] });

// Demonstrating depth limit (default 5)
const deepString = 'a[b][c][d][e][f][g]=h';
obj = qs.parse(deepString);
assert.deepEqual(obj, {
    a: {
        b: { c: { d: { e: { f: { '[g]': 'h' } } } } }
    }
});

console.log('All assertions passed!');