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

4.0.1 • Public • Published

search-params

A module to manipulate search part of URLs (querystring). Created to externalise some code shared by path-parser and route-node.

API

parse: (path: string, opts?: IOptions) => T

Parse a querystring and returns an object of parameters. See options below for available options. Optional generic type can be provided.

build: (params: T, opts?: IOptions) => string

Build a querystring from a list of parameters. Optional generic type can be provided.

omit: (path: string, paramsToOmit: string[], opts?: IOptions) => IOmitResponse

Remove a list of parameters (names) from a querystring, and returns an object containing removedParams and querystring.

keep: (path: string, paramsToKeep: string[], opts?: IOptions) => IKeepResponse

Keep a list of parameters (names) from a querystring, and returns an object containing keptParams and querystring.

Options

All options are optional.

  • arrayFormat: Specifies how arrays should be stringified
    • 'none' (default): no brackets or indexes are added to query parameter names ('role=member&role=admin')
    • 'brackets: brackets are added to query parameter names ('role[]=member&role[]=admin')
    • 'index': brackets and indexes are added to query parameter names ('role[0]=member&role[1]=admin')
  • booleanFormat: specifies how boolean values are stringified and parsed
    • 'none' (default): booleans are stringified to strings ('istrue=true&isfalse=false')
    • 'empty-true': same as 'none' except true values are stringified without value ('istrue&isfalse=false'). If you choose this boolean format, make sure to change the value of 'nullFormat'.
    • 'string': same as 'none' but 'true' and 'false' are parsed as booleans
    • 'unicode': true and false are displayed with unicode characters, and parsed as booleans ('istrue=✓&isfalse=✗')
  • nullFormat: specifies how null values are stringified and parsed
    • 'default' (default): null values are stringified without equal sign and value ('isnull')
    • 'string': null values are stringified to 'null' ('isnull=null') and parsed as null values
    • 'hidden': null values are not stringified

Example

For more examples, look at the tests.

import { parse, build, omit, keep } from 'search-params'

parse('country=scotland&town=glasgow')
// {
//     country: 'scotland',
//     town: 'glasgow'
// }

build({
  country: 'scotland',
  town: 'glasgow'
})
// 'country=scotland&town=glasgow'

omit('country=scotland&town=glasgow', ['country '])
// {
//     removedParams: {
//         country: 'scotland'
//     },
//     querystring: 'town=glasgow'
// }

keep('country=scotland&town=glasgow', ['country '])
// {
//     keptParams: {
//         country: 'scotland'
//     },
//     querystring: 'country=scotland'
// }

Package Sidebar

Install

npm i search-params

Weekly Downloads

75,076

Version

4.0.1

License

MIT

Unpacked Size

61.9 kB

Total Files

15

Last publish

Collaborators

  • troch