Used in React with use-query-params.
Installation
Using npm:
$ npm install --save serialize-query-params
By default, serialize-query-params uses URLSearchParams to handle interpreting the location string, which means it does not decode null
and has limited handling of other more advanced URL parameter configurations. If you want access to those features, add a third-party library like query-string and provide its functions to updateLocation and updateInLocation as needed.
API
Param Types
See all param definitions here. You can define your own parameter types by creating an object with an encode
and a decode
function. See the existing definitions for examples.
Note that all null and empty values are typically treated as follows:
value | encoding |
---|
null | ?foo |
"" | ?foo= |
undefined | ? (removed from URL) |
Examples in this table assume query parameter named qp
.
Param | Type | Example Decoded | Example Encoded |
---|
StringParam | string | 'foo' | ?qp=foo |
NumberParam | number | 123 | ?qp=123 |
ObjectParam | { key: string } | { foo: 'bar', baz: 'zzz' } | ?qp=foo-bar_baz-zzz |
ArrayParam | string[] | ['a','b','c'] | ?qp=a&qp=b&qp=c |
JsonParam | any | { foo: 'bar' } | ?qp=%7B%22foo%22%3A%22bar%22%7D |
DateParam | Date | Date(2019, 2, 1) | ?qp=2019-03-01 |
DateTimeParam | Date | Date(2019, 2, 1) | ?qp=2019-02-28T22:00:00.000Z |
BooleanParam | boolean | true | ?qp=1 |
NumericObjectParam | { key: number } | { foo: 1, bar: 2 } | ?qp=foo-1_bar-2 |
DelimitedArrayParam | string[] | ['a','b','c'] | ?qp=a_b_c' |
DelimitedNumericArrayParam | number[] | [1, 2, 3] | ?qp=1_2_3' |
Enum Param
You can define enum param using createEnumParam
. It works as StringParam
but restricts decoded output to a list of allowed strings:
import { createEnumParam } from 'serialize-query-params';
const SortOrderEnumParam = createEnumParam(['asc', 'desc'])
Array Enum Param
You can define array enum param using createEnumArrayParam
or createEnumDelimitedArrayParam
. It will restricts decoded output to a list of allowed values.
import { createEnumArrayParam } from 'serialize-query-params';
type Color = 'red' | 'green' | 'blue'
const ColorArrayEnumParam = createEnumArrayParam<Color[]>(['red', 'green', 'blue'])
Setting a default value
If you'd like to have a default value, you can wrap your param with withDefault()
:
import { withDefault, ArrayParam } from 'serialize-query-params';
const NeverNullArrayParam = withDefault(ArrayParam, []);
const NeverUndefinedArrayParam = withDefault(ArrayParam, [], false);
Example with Custom Param
You can define your own params if the ones shipped with this package don't work for you. There are included serialization utility functions to make this easier, but you can use whatever you like.
import {
encodeDelimitedArray,
decodeDelimitedArray
} from 'serialize-query-params';
const CommaArrayParam = {
encode: (array: string[] | null | undefined): string | undefined =>
encodeDelimitedArray(array, ','),
decode: (arrayStr: string | string[] | null | undefined): string[] | undefined =>
decodeDelimitedArray(arrayStr, ',')
};
decodeQueryParams
decodeQueryParams<QPCMap extends QueryParamConfigMap>(
paramConfigMap: QPCMap,
encodedQuery: Partial<EncodedValueMap<QPCMap>>
): Partial<DecodedValueMap<QPCMap>>
Convert the values in query from strings to their natural types via the
decode functions configured in paramConfigMap.
Example
import {
stringify,
decodeQueryParams,
NumberParam,
DelimitedArrayParam
} from 'serialize-query-params';
const decodedQuery = decodeQueryParams(
{ foo: NumberParam, bar: DelimitedArrayParam },
{ foo: '123', bar: 'a_b' }
);
encodeQueryParams
encodeQueryParams<QPCMap extends QueryParamConfigMap>(
paramConfigMap: QPCMap,
query: Partial<DecodedValueMap<QPCMap>>
): Partial<EncodedValueMap<QPCMap>>
Convert the values in query to strings via the encode functions configured
in paramConfigMap. This can be useful for constructing links using decoded
query parameters.
Example
import {
encodeQueryParams,
DelimitedArrayParam,
NumberParam,
} from 'serialize-query-params';
import { stringify } from 'query-string';
const encodedQuery = encodeQueryParams(
{ foo: NumberParam, bar: DelimitedArrayParam },
{ foo: 123, bar: ['a', 'b'] }
);
const link = `/?${stringify(encodedQuery)}`;
searchStringToObject
function searchStringToObject(searchString: string): EncodedQuery
Default implementation of searchStringToObject powered by URLSearchParams
This converts a search string like ?foo=123&bar=x
to { foo: '123', bar: 'x' }
This is only a very basic version, you may prefer the advanced versions offered
by third party libraries like query-string ("parse") or qs.
Example
import { searchStringToObject } from 'serialize-query-params';
const obj = searchStringToObject('?foo=a&bar=x&foo=z');
objectToSearchString
function objectToSearchString(encodedParams: EncodedQuery): string
Default implementation of objectToSearchString powered by URLSearchParams.
Does not support null values. Does not prefix with "?"
This converts an object { foo: '123', bar: 'x' } to a search string ?foo=123&bar=x
This is only a very basic version, you may prefer the advanced versions offered
by third party libraries like query-string ("stringify") or qs.
Example
import { objectToSearchString } from 'serialize-query-params';
const obj = objectToSearchString({ foo: ['a', 'z'], bar: 'x' });
updateLocation
function updateLocation(
encodedQuery: EncodedQuery,
location: Location,
objectToSearchStringFn = objectToSearchString
): Location {
Creates a new location-like object with the new query string (the search
field)
based on the encoded query parameters passed in via encodedQuery
. Parameters not
specified in encodedQuery
will be dropped from the URL.
Example
import { updateLocation } from 'serialize-query-params';
const newLocation = updateLocation({ foo: '555' }, location);
updateInLocation
function updateInLocation(
encodedQueryReplacements: EncodedQuery,
location: Location,
objectToSearchStringFn = objectToSearchString,
searchStringToObjectFn = searchStringToObject
): Location {
Creates a new location-like object with the new query string (the search
field)
based on the encoded query parameters passed in via encodedQueryReplacements
. Only
parameters specified in encodedQueryReplacements
are affected by this update,
all other parameters are retained.
Example
import { updateInLocation } from 'serialize-query-params';
const newLocation = updateLocation({ foo: '555' }, location);
Development
Run the typescript compiler in watch mode:
npm run dev