NeXTSTEP Programming Mastermind

    serialize-query-params
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.6 • Public • Published

    serialize-query-params

    A library for simplifying encoding and decoding URL query parameters.

    npm Travis (.com)


    Installation | API | useQueryParams


    Used in React with use-query-params.

    Installation

    Using npm:

    $ npm install --save serialize-query-params query-string
    

    Note: There is a peer dependency on query-string. For IE11 support, use v5.1.1, otherwise use v6.

    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';
    
    // values other than 'asc' or 'desc' will be decoded as undefined
    const SortOrderEnumParam = createEnumParam(['asc', 'desc'])

    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';
    
    // by default, nulls are converted to defaults
    const NeverNullArrayParam = withDefault(ArrayParam, []);
    
    // if you don't want nulls to be included, pass false as a third arg
    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';
    
    /** Uses a comma to delimit entries. e.g. ['a', 'b'] => qp?=a,b */
    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';
    
    // encode each parameter according to the configuration
    const decodedQuery = decodeQueryParams(
      { foo: NumberParam, bar: DelimitedArrayParam },
      { foo: '123', bar: 'a_b' }
    );
    // produces: { 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';
    
    // encode each parameter according to the configuration
    const encodedQuery = encodeQueryParams(
      { foo: NumberParam, bar: DelimitedArrayParam },
      { foo: 123, bar: ['a', 'b'] }
    );
    // produces: { foo: '123', bar: 'a_b' }
    
    const link = `/?${stringify(encodedQuery)}`;

    updateLocation

    export function updateLocation(
      encodedQuery: EncodedQuery,
      location: Location
    ): Location {

    Updates a location object to have a 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';
    
    // location has search: ?foo=123&bar=abc
    const newLocation = updateLocation({ foo: '555' }, location);
    
    // newLocation has search: ?foo=555
    // note that unspecified query parameters (bar in this case) are not retained.

    updateInLocation

    export function updateInLocation(
      encodedQueryReplacements: EncodedQuery,
      location: Location
    ): Location {

    Updates a location object to have a 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';
    
    // location has search: ?foo=123&bar=abc
    const newLocation = updateLocation({ foo: '555' }, location);
    
    // newLocation has search: ?foo=555&bar=abc
    // note that unspecified query parameters (bar in this case) are retained.

    Development

    Run the typescript compiler in watch mode:

    npm run dev
    

    Install

    npm i serialize-query-params

    DownloadsWeekly Downloads

    196,809

    Version

    1.3.6

    License

    ISC

    Unpacked Size

    103 kB

    Total Files

    35

    Last publish

    Collaborators

    • pbeshai