qss: Tiny Query String Serializer

Common errors

• TypeError: qss is not a function or TypeError: qss_1.default is not a function

  cause Attempting to use `qss` as a default export after upgrading to v2.0.0 or later.
  fix Update your import statement to use named exports: `import { encode, decode } from 'qss'`.

• ERR_PACKAGE_PATH_NOT_EXPORTED

  cause Using `qss` in Node.js versions 13.0-13.7 due to the `exports` map in `package.json` introduced in v3.0.0.
  fix Upgrade your Node.js runtime to a stable, actively maintained LTS version (e.g., Node.js 14 or newer).

• Query string is missing separator or malformed after encoding.

  cause Incorrect usage of the `prefix` argument in `qss.encode`, expecting it to automatically add `?` or `&`.
  fix Ensure the `prefix` argument includes the full desired prefix with its own separator, e.g., `encode(obj, '?')` or `encode(obj, 'foo=bar&')`.

Warnings

• breaking Version 3.0.0 introduced 'exports' map support, which may cause module loading issues in Node.js versions 13.0 through 13.7. These were development releases and are officially End-of-Life.
  Fix: Upgrade Node.js to a stable LTS version (e.g., Node.js 14+).
• breaking Version 2.0.0 removed the default export. The primary `stringify` functionality is now available as the named `encode` export.
  Fix: Change your import statements from `import qss from 'qss'` to `import { encode } from 'qss'`.
• gotcha qss is optimized for browser environments. While it works in Node.js, the native `querystring.stringify` is significantly faster for encoding operations in Node.js, making qss less performant for server-side encoding tasks.
  Fix: Consider using Node.js's built-in `querystring` module for server-side encoding (e.g., `require('querystring').stringify`).
• gotcha The `prefix` argument for `qss.encode` is appended directly. No checks or automatic glue characters (like `?` or `&`) are added. If you want a prefix, it must include your desired joiner.
  Fix: Always provide the full prefix string, including any desired separators, e.g., `encode({foo: 'bar'}, '?')` or `encode({baz: 'qux'}, 'existing=param&')`.

Install

• npm install qss npm
• yarn add qss yarn
• pnpm add qss pnpm

Imports

• encode
  wrong:

  import qss from 'qss'

  correct:

  import { encode } from 'qss'

  Since v2.0.0, `encode` is a named export. The default export was removed.
• decode
  wrong:

  const { decode } = require('qss')

  correct:

  import { decode } from 'qss'

  Primarily designed for ESM usage in browsers, though CJS is supported. Type definitions are included for TypeScript.
• qss (CommonJS)

  const { encode, decode } = require('qss')

  For CommonJS environments, destructure `encode` and `decode` directly. Older Node.js versions (13.0-13.7) may have issues due to `exports` map.

Quickstart

Demonstrates how to encode JavaScript objects into query strings and decode query strings back into objects, including usage with prefixes and array values.

import { encode, decode } from 'qss';

// Example 1: Basic object encoding
const params1 = { foo: 'hello world', bar: [1, 2, 3], baz: true };
const queryString1 = encode(params1);
console.log('Encoded 1:', queryString1);
// Expected: 'foo=hello%20world&bar=1&bar=2&bar=3&baz=true'

// Example 2: Encoding with a custom prefix
const params2 = { limit: 10, offset: 0 };
const queryString2 = encode(params2, '?');
console.log('Encoded 2 with prefix:', queryString2);
// Expected: '?limit=10&offset=0'

// Example 3: Decoding a query string
const decodedParams1 = decode('foo=hello%20world&bar=1&bar=2&bar=3&baz=true');
console.log('Decoded 1:', decodedParams1);
// Expected: { foo: 'hello world', bar: [1, 2, 3], baz: true }

// Example 4: Decoding from location.search (browser context)
// In a browser, you might do:
// const browserQueryString = location.search.substring(1);
// const decodedBrowserParams = decode(browserQueryString);
// console.log('Decoded from browser search:', decodedBrowserParams);