query-string

  • Version 7.1.0
  • Published
  • 46.8 kB
  • 4 dependencies
  • MIT license

Install

npm i query-string
yarn add query-string
pnpm add query-string

Overview

Parse and stringify URL query strings

Index

Functions

function exclude

exclude: {
(
url: string,
keys: readonly string[],
options?: ParseOptions & StringifyOptions
): string;
(
url: string,
filter: (key: string, value: string | number | boolean) => boolean,
options?: { parseBooleans: true; parseNumbers: true } & ParseOptions &
StringifyOptions
): string;
(
url: string,
filter: (key: string, value: string | boolean) => boolean,
options?: { parseBooleans: true } & ParseOptions & StringifyOptions
): string;
(
url: string,
filter: (key: string, value: string | number) => boolean,
options?: { parseNumbers: true } & ParseOptions & StringifyOptions
): string;
};
  • Exclude query parameters from a URL. Like .pick() but reversed.

    Parameter url

    The URL containing the query parameters to exclude.

    Parameter keys

    The names of the query parameters to remove. All other query parameters will remain in the URL.

    Parameter filter

    A filter predicate that will be provided the name of each query parameter and its value. The parseNumbers and parseBooleans options also affect value.

    Returns

    The URL without the excluded the query parameters.

    Example 1

    queryString.exclude('https://foo.bar?foo=1&bar=2#hello', ['foo']);
    //=> 'https://foo.bar?bar=2#hello'
    queryString.exclude('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true});
    //=> 'https://foo.bar?foo=1#hello'

function extract

extract: (url: string) => string;
  • Extract a query string from a URL that can be passed into .parse().

    Note: This behaviour can be changed with the skipNull option.

function parse

parse: {
(
query: string,
options: { parseBooleans: true; parseNumbers: true } & ParseOptions
): ParsedQuery<string | boolean | number>;
(query: string, options: { parseBooleans: true } & ParseOptions): ParsedQuery<
string | boolean
>;
(query: string, options: { parseNumbers: true } & ParseOptions): ParsedQuery<
string | number
>;
(query: string, options?: ParseOptions): ParsedQuery<string>;
};
  • Parse a query string into an object. Leading ? or # are ignored, so you can pass location.search or location.hash directly.

    The returned object is created with [Object.create(null)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create) and thus does not have a prototype.

    Parameter query

    The query string to parse.

function parseUrl

parseUrl: (url: string, options?: ParseOptions) => ParsedUrl;
  • Extract the URL and the query string as an object.

    If the parseFragmentIdentifier option is true, the object will also contain a fragmentIdentifier property.

    Parameter url

    The URL to parse.

    Example 1

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

function pick

pick: {
(
url: string,
keys: readonly string[],
options?: ParseOptions & StringifyOptions
): string;
(
url: string,
filter: (key: string, value: string | number | boolean) => boolean,
options?: { parseBooleans: true; parseNumbers: true } & ParseOptions &
StringifyOptions
): string;
(
url: string,
filter: (key: string, value: string | boolean) => boolean,
options?: { parseBooleans: true } & ParseOptions & StringifyOptions
): string;
(
url: string,
filter: (key: string, value: string | number) => boolean,
options?: { parseNumbers: true } & ParseOptions & StringifyOptions
): string;
};
  • Pick query parameters from a URL.

    Parameter url

    The URL containing the query parameters to pick.

    Parameter keys

    The names of the query parameters to keep. All other query parameters will be removed from the URL.

    Parameter filter

    A filter predicate that will be provided the name of each query parameter and its value. The parseNumbers and parseBooleans options also affect value.

    Returns

    The URL with the picked query parameters.

    Example 1

    queryString.pick('https://foo.bar?foo=1&bar=2#hello', ['foo']);
    //=> 'https://foo.bar?foo=1#hello'
    queryString.pick('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true});
    //=> 'https://foo.bar?bar=2#hello'

function stringify

stringify: (object: Record<string, any>, options?: StringifyOptions) => string;
  • Stringify an object into a query string and sort the keys.

function stringifyUrl

stringifyUrl: (object: UrlObject, options?: StringifyOptions) => string;
  • Stringify an object into a URL with a query string and sorting the keys. The inverse of [.parseUrl()](https://github.com/sindresorhus/query-string#parseurlstring-options)

    Query items in the query property overrides queries in the url property.

    The fragmentIdentifier property overrides the fragment identifier in the url property.

    Example 1

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

Interfaces

interface ParsedQuery

interface ParsedQuery<T = string> {}

    index signature

    [key: string]: T | T[] | null;

      interface ParsedUrl

      interface ParsedUrl {}

        property fragmentIdentifier

        readonly fragmentIdentifier?: string;
        • The fragment identifier of the URL.

          Present when the parseFragmentIdentifier option is true.

        property query

        readonly query: ParsedQuery;

          property url

          readonly url: string;

            interface ParseOptions

            interface ParseOptions {}

              property arrayFormat

              readonly arrayFormat?:
              | 'bracket'
              | 'index'
              | 'comma'
              | 'separator'
              | 'bracket-separator'
              | 'colon-list-separator'
              | 'none';
              • 'none'

                - bracket: Parse arrays with bracket representation:

                ``` import queryString = require('query-string');

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

                - index: Parse arrays with index representation:

                ``` import queryString = require('query-string');

                queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'}); //=> {foo: ['1', '2', '3']} ```

                - comma: Parse arrays with elements separated by comma:

                ``` import queryString = require('query-string');

                queryString.parse('foo=1,2,3', {arrayFormat: 'comma'}); //=> {foo: ['1', '2', '3']} ```

                - separator: Parse arrays with elements separated by a custom character:

                ``` import queryString = require('query-string');

                queryString.parse('foo=1|2|3', {arrayFormat: 'separator', arrayFormatSeparator: '|'}); //=> {foo: ['1', '2', '3']} ```

                - bracket-separator: Parse arrays (that are explicitly marked with brackets) with elements separated by a custom character:

                ``` import queryString = require('query-string');

                queryString.parse('foo[]', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); //=> {foo: []}

                queryString.parse('foo[]=', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); //=> {foo: ['']}

                queryString.parse('foo[]=1', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); //=> {foo: ['1']}

                queryString.parse('foo[]=1|2|3', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); //=> {foo: ['1', '2', '3']}

                queryString.parse('foo[]=1||3|||6', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); //=> {foo: ['1', '', 3, '', '', '6']}

                queryString.parse('foo[]=1|2|3&bar=fluffy&baz[]=4', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); //=> {foo: ['1', '2', '3'], bar: 'fluffy', baz:['4']} ```

                - colon-list-separator: Parse arrays with parameter names that are explicitly marked with :list:

                ``` import queryString = require('query-string');

                queryString.parse('foo:list=one&foo:list=two', {arrayFormat: 'colon-list-separator'}); //=> {foo: ['one', 'two']} ```

                - none: Parse arrays with elements using duplicate keys:

                ``` import queryString = require('query-string');

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

              property arrayFormatSeparator

              readonly arrayFormatSeparator?: string;
              • The character used to separate array elements when using {arrayFormat: 'separator'}.

                ,

              property decode

              readonly decode?: boolean;
              • Decode the keys and values. URI components are decoded with [decode-uri-component](https://github.com/SamVerschueren/decode-uri-component).

                true

              property parseBooleans

              readonly parseBooleans?: boolean;
              • Parse the value as a boolean type instead of string type if it's a boolean.

                false

                Example 1

                ``` import queryString = require('query-string');

                queryString.parse('foo=true', {parseBooleans: true}); //=> {foo: true} ```

              property parseFragmentIdentifier

              readonly parseFragmentIdentifier?: boolean;
              • Parse the fragment identifier from the URL and add it to result object.

                false

                Example 1

                ``` import queryString = require('query-string');

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

              property parseNumbers

              readonly parseNumbers?: boolean;
              • Parse the value as a number type instead of string type if it's a number.

                false

                Example 1

                ``` import queryString = require('query-string');

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

              property sort

              readonly sort?: ((itemLeft: string, itemRight: string) => number) | false;
              • Supports both Function as a custom sorting function or false to disable sorting.

                If omitted, keys are sorted using Array#sort, which means, converting them to strings and comparing strings in Unicode code point order.

                true

                Example 1

                ``` import queryString = require('query-string');

                const order = ['c', 'a', 'b'];

                queryString.parse('?a=one&b=two&c=three', { sort: (itemLeft, itemRight) => order.indexOf(itemLeft) - order.indexOf(itemRight) }); //=> {c: 'three', a: 'one', b: 'two'} ```

                Example 2

                ``` import queryString = require('query-string');

                queryString.parse('?a=one&c=three&b=two', {sort: false}); //=> {a: 'one', c: 'three', b: 'two'} ```

              interface StringifyOptions

              interface StringifyOptions {}

                property arrayFormat

                readonly arrayFormat?:
                | 'bracket'
                | 'index'
                | 'comma'
                | 'separator'
                | 'bracket-separator'
                | 'colon-list-separator'
                | 'none';
                • 'none'

                  - bracket: Serialize arrays using bracket representation:

                  ``` import queryString = require('query-string');

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

                  - index: Serialize arrays using index representation:

                  ``` import queryString = require('query-string');

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

                  - comma: Serialize arrays by separating elements with comma:

                  ``` import queryString = require('query-string');

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

                  queryString.stringify({foo: [1, null, '']}, {arrayFormat: 'comma'}); //=> 'foo=1,,' // Note that typing information for null values is lost // and .parse('foo=1,,') would return {foo: [1, '', '']}. ```

                  - separator: Serialize arrays by separating elements with character:

                  ``` import queryString = require('query-string');

                  queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'separator', arrayFormatSeparator: '|'}); //=> 'foo=1|2|3' ```

                  - bracket-separator: Serialize arrays by explicitly post-fixing array names with brackets and separating elements with a custom character:

                  ``` import queryString = require('query-string');

                  queryString.stringify({foo: []}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); //=> 'foo[]'

                  queryString.stringify({foo: ['']}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); //=> 'foo[]='

                  queryString.stringify({foo: [1]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); //=> 'foo[]=1'

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

                  queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); //=> 'foo[]=1||3|||6'

                  queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|', skipNull: true}); //=> 'foo[]=1||3|6'

                  queryString.stringify({foo: [1, 2, 3], bar: 'fluffy', baz: [4]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); //=> 'foo[]=1|2|3&bar=fluffy&baz[]=4' ```

                  - colon-list-separator: Serialize arrays with parameter names that are explicitly marked with :list:

                  ```js import queryString = require('query-string');

                  queryString.stringify({foo: ['one', 'two']}, {arrayFormat: 'colon-list-separator'}); //=> 'foo:list=one&foo:list=two' ```

                  - none: Serialize arrays by using duplicate keys:

                  ``` import queryString = require('query-string');

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

                property arrayFormatSeparator

                readonly arrayFormatSeparator?: string;
                • The character used to separate array elements when using {arrayFormat: 'separator'}.

                  ,

                property encode

                readonly encode?: boolean;
                • [URL encode](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) the keys and values.

                  true

                property skipEmptyString

                readonly skipEmptyString?: boolean;
                • Skip keys with an empty string as the value.

                  false

                  Example 1

                  ``` import queryString = require('query-string');

                  queryString.stringify({a: 1, b: '', c: '', d: 4}, { skipEmptyString: true }); //=> 'a=1&d=4' ```

                  Example 2

                  ``` import queryString = require('query-string');

                  queryString.stringify({a: '', b: ''}, { skipEmptyString: true }); //=> '' ```

                property skipNull

                readonly skipNull?: boolean;
                • Skip keys with null as the value.

                  Note that keys with undefined as the value are always skipped.

                  false

                  Example 1

                  ``` import queryString = require('query-string');

                  queryString.stringify({a: 1, b: undefined, c: null, d: 4}, { skipNull: true }); //=> 'a=1&d=4'

                  queryString.stringify({a: undefined, b: null}, { skipNull: true }); //=> '' ```

                property sort

                readonly sort?: ((itemLeft: string, itemRight: string) => number) | false;
                • Supports both Function as a custom sorting function or false to disable sorting.

                  If omitted, keys are sorted using Array#sort, which means, converting them to strings and comparing strings in Unicode code point order.

                  true

                  Example 1

                  ``` import queryString = require('query-string');

                  const order = ['c', 'a', 'b'];

                  queryString.stringify({a: 1, b: 2, c: 3}, { sort: (itemLeft, itemRight) => order.indexOf(itemLeft) - order.indexOf(itemRight) }); //=> 'c=3&a=1&b=2' ```

                  Example 2

                  ``` import queryString = require('query-string');

                  queryString.stringify({b: 1, c: 2, a: 3}, {sort: false}); //=> 'b=1&c=2&a=3' ```

                property strict

                readonly strict?: boolean;
                • Strictly encode URI components with [strict-uri-encode](https://github.com/kevva/strict-uri-encode). It uses [encodeURIComponent](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) if set to false. You probably [don't care](https://github.com/sindresorhus/query-string/issues/42) about this option.

                  true

                interface UrlObject

                interface UrlObject {}

                  property fragmentIdentifier

                  readonly fragmentIdentifier?: string;
                  • Overrides the fragment identifier in the url property.

                  property query

                  readonly query?: StringifiableRecord;
                  • Overrides queries in the url property.

                  property url

                  readonly url: string;

                    Type Aliases

                    type Stringifiable

                    type Stringifiable = string | boolean | number | null | undefined;

                      type StringifiableRecord

                      type StringifiableRecord = Record<string, Stringifiable | readonly Stringifiable[]>;

                        Package Files (1)

                        Dependencies (4)

                        Dev Dependencies (6)

                        Peer Dependencies (0)

                        No peer dependencies.

                        Badge

                        To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                        You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/query-string.

                        • Markdown
                          [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/query-string)
                        • HTML
                          <a href="https://www.jsdocs.io/package/query-string"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>