qss

library0.2.5jsnpmunverified

qss (query string stringify) is a minimalist, 305-byte browser utility designed for efficiently serializing JavaScript objects into URL query strings and parsing query strings back into objects. The current stable version is 3.0.0. It distinguishes itself by its extreme lightness and strong performance for decoding compared to other libraries like `qs`, `query-string`, and even Node.js's native `querystring.decode` in browser contexts. While suitable for browsers, its `encode` function is significantly slower than Node.js's native `querystring.stringify`, making it less ideal for server-side encoding. qss ships with TypeScript type definitions, providing a robust development experience. Releases are feature-driven rather than on a strict cadence, with major versions introducing breaking changes as needed for improvements or modernizations.

http-networking serialization

npm install qss

github ↗package ↗

INSTALL

IMPORT

SIG · QSS

qss

http-networkingjavascriptv0.2.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

encode

✓ import { encode } from 'qss'

✗ import qss from 'qss'

Since v2.0.0, `encode` is a named export. The default export was removed.

decode

✓ import { decode } from 'qss'

✗ const { decode } = require('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.

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);

Debug

Known issues

breakingVersion 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+).

affects: 3.x

breakingVersion 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'`.

affects: >=2.0.0

gotchaqss 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`).

affects: >=1.0.0

gotchaThe `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&')`.

affects: >=1.0.0

Errors

Common errors & fixes

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

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

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.

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&')`.

Upgrade

Version history

0.2.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lukeed/qss ↗

packagehttps://www.npmjs.com/package/qss ↗