Skip to content package
picoquery v2.3.0 A small library for parsing and serialisation query strings
node any 1 deps esm types open source
overview readme
license MIT
deps 1
unpacked 30.5 kB
files 15
node any $ npm install picoquery@2.3.0n npmREADME GitHub-flavored package documentation.
downloads Across all versions.
Download trend unavailable.
compatibility Runtime metadata.
keywords Tagged topics.
qs querystring query query-string url
install size Estimated unpacked size across 1 packages.
37.6 kB
Includes dependencies.
versions Latest published Nov 11, 2026
maintainers Registry package owners.
contents picoquery
A lightweight query string parser/stringifier with support for nesting and some
configurability.
Built on top of fast-querystring .
Install
-S
picoquery
copy
CommonJS vs ESM 2.x and above are ESM only (i.e. if you're running Node.js older than
v20.17.0/v22.0.0, your project will need type: "module" in the package.json).
If you cannot update Node.js or move to ESM yet, you may continue to use 1.x which will still
receive non-breaking changes, backported from main.
Usage import {parse} from 'picoquery' ;
parse ( 'foo.bar=abc&baz=def' );
/*
{
foo: {
bar: 'abc'
},
baz: 'def'
}
*/ copy import {stringify} from 'picoquery' ;
stringify ({
foo: {
bar: 123
}
});
/*
foo.bar=123
*/ copy
API
stringify(object[, options])Converts the given object into a query string, optionally with configured
options.
parse(str[, options])Parses the given query string into an object, optionally with configured
options.
Options
Default options The default options are as follows:
{
nesting : true ,
nestingSyntax : 'dot' ,
arrayRepeat : false ,
arrayRepeatSyntax : 'repeat' ,
delimiter : '&' ,
allowSparseArrays : false
} copy
nestingWhen true, nested objects are supported.
For example, when parsing:
parse ( 'foo.bar=baz' , {nesting: true });
// {foo: {bar: 'baz'}} copy stringify ({foo: {bar: 'baz' }}, {nesting: true });
// foo.bar=baz copy This also results in arrays being supported:
parse ( 'foo.0=bar' , {nesting: true });
// {foo: ['bar']}
stringify ({foo: [ 'bar' ]}, {nesting: true });
// foo.0=bar copy
nestingSyntaxSets which style of nesting syntax should be used. The choices are:
dot (e.g. foo.bar=baz)
index (e.g. foo[bar]=baz)
js (e.g. foo.bar[0]=baz, i.e. arrays are indexed and properties are
dotted or indexed)
arrayRepeatIf true, this will treat repeated keys as arrays.
parse ( 'foo=x&foo=y' , {arrayRepeat: true });
// {foo: ['x', 'y']}
stringify ({foo: [ 'x' , 'y' ]}, {arrayRepeat: true });
// foo=x&foo=y copy
arrayRepeatSyntaxSets which style of array repetition syntax should be used. The choices are:
bracket (e.g. foo[]=x&foo[]=y)
repeat (e.g. foo=x&foo=y)
delimiterSets the delimiter to be used instead of &.
parse ( 'foo=x;bar=y' , {delimiter: ';' });
// {foo: 'x', bar: 'y'}
stringify ({foo: 'x' , bar: 'y' }, {delimiter: ';' });
// foo=x;bar=y copy
allowSparseArraysIf true, arrays parsed with gaps in their indices will be kept as sparse
arrays.
By default (false), parsed arrays are truncated at the first missing index.
parse ( 'foo[0]=x&foo[2]=y' , {nestingSyntax: 'index' });
// {foo: ['x']}
parse ( 'foo[0]=x&foo[2]=y' , {nestingSyntax: 'index' , allowSparseArrays: true });
// {foo: ['x', <empty>, 'y']} copy This option only applies when parsing.
valueDeserializerCan be set to a function which will be used to deserialize each value during
parsing.
It will be called with the value and the already deserialized
key (i.e. (value: string, key: PropertyKey) => *).
parse ( 'foo=300' , {
valueDeserializer : (value) => {
const asNum = Number (value);
return Number. isNaN (asNum) ? value : asNum;
}
});
// {foo: 300} copy
keyDeserializerCan be set to a function which will be used to deserialize each key during
parsing.
It will be called with the key from the query string
(i.e. (key) => PropertyKey).
parse ( '300=foo' , {
keyDeserializer : (key) => {
const asNum = Number (key);
return Number. isNaN (asNum) ? key : asNum;
}
});
// {300: 'foo'} copy
shouldSerializeObjectCan be set to a function which determines if an object-like value should be
serialized instead of being treated as a nested object.
All non-object primitives will always be serialized.
// Assuming `StringifableObject` returns its constructor value when `toString`
// is called.
stringify({
foo: new StringifiableObject('test')
}, {
shouldSerializeObject(val) {
return val instanceof StringifableObject;
},
valueSerializer: (value) => {
return String(value);
}
});
// foo=test copy If you want to fall back to the default logic, you can import the default
function:
import {defaultShouldSerializeObject, stringify} from 'picoquery';
stringify({
foo: new StringifiableObject('test')
}, {
shouldSerializeObject(val) {
if (val instanceof StringifableObject) {
return true;
}
return defaultShouldSerializeObject(val);
}
}); copy
valueSerializerCan be set to a function which will be used to serialize each value during
stringifying.
It will be called with the value and the key
(i.e. (value: unknown, key: PropertyKey) => string).
stringify ({foo: 'bar' }, {
valueSerializer : (val) => String (val) + String (val)
});
// foo=barbar copy Note that you can import the default serializer if you only want to handle
some cases.
import {defaultValueSerializer, stringify} from 'picoquery' ;
stringify ({foo: 'bar' }, {
valueSerializer : (val, key) => {
if (val instanceof Date ) {
return val. toISOString ();
}
// Call the original serializer otherwise
return defaultValueSerializer (val, key);
}
}); copy
Benchmarks IMPORTANT : there are a few things to take into account with these
benchmarks:
fast-querystring is not capable of parsing or stringifying nested objects,
so the results are incomparible (but here as reference)
all libraries have their own level of configurability. It will be possible
to increase perf in each of them by disabling various features, but these are
just the 'happy path'
Parse Benchmark: Basic (no nesting)
┌─────────┬─────────────────────────────────┬─────────────┬────────────────────┬──────────┬─────────┐
│ (index) │ Task Name │ ops/sec │ Average Time (ns) │ Margin │ Samples │
├─────────┼─────────────────────────────────┼─────────────┼────────────────────┼──────────┼─────────┤
│ 0 │ 'picoquery' │ '2,393,539' │ 417.79130492907393 │ '±0.42%' │ 1196770 │
│ 1 │ 'qs' │ '382,933' │ 2611.4212945313157 │ '±1.04%' │ 191467 │
│ 2 │ 'fast-querystring (no nesting)' │ '2,633,148' │ 379.77342802356833 │ '±1.58%' │ 1316575 │
└─────────┴─────────────────────────────────┴─────────────┴────────────────────┴──────────┴─────────┘
Benchmark: Dot-syntax nesting
┌─────────┬─────────────────────────────────┬─────────────┬───────────────────┬──────────┬─────────┐
│ (index) │ Task Name │ ops/sec │ Average Time (ns) │ Margin │ Samples │
├─────────┼─────────────────────────────────┼─────────────┼───────────────────┼──────────┼─────────┤
│ 0 │ 'picoquery' │ '1,406,039' │ 711.2176054736389 │ '±0.56%' │ 703020 │
│ 1 │ 'qs' │ '205,611' │ 4863.536155478235 │ '±0.98%' │ 102806 │
│ 2 │ 'fast-querystring (no nesting)' │ '2,588,560' │ 386.3151031345139 │ '±0.66%' │ 1294281 │
└─────────┴─────────────────────────────────┴─────────────┴───────────────────┴──────────┴─────────┘ copy
Stringify Benchmark: Basic (no nesting)
┌─────────┬─────────────────────────────────┬─────────────┬────────────────────┬──────────┬─────────┐
│ (index) │ Task Name │ ops/sec │ Average Time (ns) │ Margin │ Samples │
├─────────┼─────────────────────────────────┼─────────────┼────────────────────┼──────────┼─────────┤
│ 0 │ 'picoquery' │ '4,163,092' │ 240.20605684139227 │ '±0.16%' │ 2081547 │
│ 1 │ 'qs' │ '843,630' │ 1185.352608720127 │ '±0.76%' │ 421816 │
│ 2 │ 'fast-querystring (no nesting)' │ '3,795,565' │ 263.46536774751036 │ '±0.24%' │ 1897783 │
└─────────┴─────────────────────────────────┴─────────────┴────────────────────┴──────────┴─────────┘
Benchmark: Dot-syntax nesting
┌─────────┬─────────────────────────────────┬─────────────┬────────────────────┬──────────┬─────────┐
│ (index) │ Task Name │ ops/sec │ Average Time (ns) │ Margin │ Samples │
├─────────┼─────────────────────────────────┼─────────────┼────────────────────┼──────────┼─────────┤
│ 0 │ 'picoquery' │ '1,768,770' │ 565.3644818387182 │ '±1.08%' │ 884387 │
│ 1 │ 'qs' │ '332,254' │ 3009.743667534287 │ '±1.38%' │ 166128 │
│ 2 │ 'fast-querystring (no nesting)' │ '7,227,031' │ 138.36940410118828 │ '±1.15%' │ 3613517 │
└─────────┴─────────────────────────────────┴─────────────┴────────────────────┴──────────┴─────────┘ copy
License