@slimkit/query-string

Parse and stringify URL query strings. A zero-dependency, drop-in replacement for query-string.

• Zero runtime dependencies
• Works with both require() (CommonJS) and import (ESM)
• Full TypeScript types included
• Same API as query-string — swap the import and go

Install

npm install @slimkit/query-string

Usage

import queryString from '@slimkit/query-string';

queryString.parse('foo=bar');
//=> {foo: 'bar'}

queryString.stringify({foo: 'bar'});
//=> 'foo=bar'

CommonJS:

const queryString = require('@slimkit/query-string');

Named imports also work:

import {parse, stringify} from '@slimkit/query-string';

API

.parse(string, options?)

Parses a query string into an object. Leading ?, #, or & are stripped, so it works directly with location.search or location.hash.

queryString.parse('foo=bar&abc=xyz&abc=zyx');
//=> {foo: 'bar', abc: ['xyz', 'zyx']}

queryString.parse('foo');
//=> {foo: null}

queryString.parse('foo=1&bar=2', {parseNumbers: true});
//=> {foo: 1, bar: 2}

options

• decode (boolean, default true) — decode keys/values (also treats + as a space).
• arrayFormat (default 'none') — one of 'bracket', 'index', 'comma', 'separator', 'bracket-separator', 'colon-list-separator', 'none'. See Array formats.
• arrayFormatSeparator (string, default ',') — separator used by 'separator' / 'bracket-separator'.
• sort ((a, b) => number | false, default sorts ascending) — pass false to keep insertion order, or a compare function for custom ordering.
• parseNumbers (boolean, default false) — convert numeric-looking values to number.
• parseBooleans (boolean, default false) — convert 'true'/'false' to boolean; valueless keys become true.
• types (Record<string, 'boolean' | 'number' | 'string' | 'string[]' | 'number[]' | (value: string) => unknown>) — per-key type overrides.

.stringify(object, options?)

Turns an object into a query string, with keys sorted by default.

queryString.stringify({foo: 'bar'});
//=> 'foo=bar'

queryString.stringify({a: 'b', c: 'd'});
//=> 'a=b&c=d'

queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'});
//=> 'foo[]=1&foo[]=2&foo[]=3'

Accepts string, number, bigint, boolean, null, undefined, and arrays of those.

• null → rendered as a valueless key (foo)
• undefined → key is omitted entirely
• false → rendered as foo=false

options

• strict (boolean, default true) — also percent-encode ! ' ( ) *.
• encode (boolean, default true) — set to false to disable encoding.
• arrayFormat / arrayFormatSeparator — same as parse.
• sort ((a, b) => number | false) — same as parse.
• skipNull (boolean, default false) — omit keys whose value is null.
• skipEmptyString (boolean, default false) — omit keys whose value is ''.
• replacer ((key, value) => unknown) — transform (or drop, by returning undefined) each key/value pair before stringifying.

.extract(url)

Extracts the query string portion of a URL.

queryString.extract('https://foo.bar?abc=def#hash');
//=> 'abc=def'

.parseUrl(url, options?)

Splits a URL into {url, query} (and fragmentIdentifier, if requested). Accepts all .parse() options plus:

• parseFragmentIdentifier (boolean, default false) — also return the decoded fragment.

queryString.parseUrl('https://foo.bar?foo=bar#hash', {parseFragmentIdentifier: true});
//=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'hash'}

.stringifyUrl(object, options?)

Builds a URL from {url, query, fragmentIdentifier}. Accepts all .stringify() options. Any query string already on url is merged with (and overridden by) query; fragmentIdentifier overrides any hash already on url.

queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar'}});
//=> 'https://foo.bar?foo=bar'

queryString.stringifyUrl({url: 'https://foo.bar?foo=bar', query: {foo: 'baz'}});
//=> 'https://foo.bar?foo=baz'

.pick(url, keysOrFilter, options?)

Returns a URL with only the given query keys kept. keysOrFilter is either an array of keys or a (key, value) => boolean predicate. Accepts .parse() + .stringify() options.

queryString.pick('https://foo.bar?a=1&b=2&c=3', ['a', 'c']);
//=> 'https://foo.bar?a=1&c=3'

.exclude(url, keysOrFilter, options?)

The inverse of .pick() — removes the given keys.

queryString.exclude('https://foo.bar?a=1&b=2&c=3', ['b']);
//=> 'https://foo.bar?a=1&c=3'

Array formats

| arrayFormat | Parse example | Stringify example (foo: [1, 2, 3]) | | ----------------------- | --------------------------------------- | ------------------------------------- | | none (default) | foo=1&foo=2 → {foo: ['1','2']} | foo=1&foo=2 | | bracket | foo[]=1&foo[]=2 → {foo: ['1','2']} | foo[]=1&foo[]=2&foo[]=3 | | index | foo[0]=1&foo[1]=2 → {foo: ['1','2']}| foo[0]=1&foo[1]=2&foo[2]=3 | | comma | foo=1,2,3 → {foo: ['1','2','3']} | foo=1,2,3 | | separator | foo=1\|2\|3 → {foo: ['1','2','3']} | foo=1\|2\|3 (with arrayFormatSeparator: '\|') | | bracket-separator | foo[]=1\|2\|3 → {foo: ['1','2','3']}| foo[]=1\|2\|3 | | colon-list-separator | foo:list=1&foo:list=2 → {foo: ['1','2']} | foo:list=1&foo:list=2 |

License

MIT