# search-params

> A module to manipulate search part of URLs (querystring)

Latest version **4.0.1** (published 2021-04-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install search-params
pnpm add search-params
yarn add search-params
bun add search-params
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.1 |
| Published | 2021-04-26 |
| First published | 2016-02-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 60.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 14 |
| Author | Thomas Roch |
| Maintainers | troch |
| Keywords | querystring, query, query params, search params, search, location, url |

## Links

- npm: https://www.npmjs.com/package/search-params
- Repository: https://github.com/troch/search-params
- Homepage: https://github.com/troch/search-params#readme
- Issues: https://github.com/troch/search-params/issues
- npm.io page: https://npm.io/package/search-params

## Alternatives

- [gamedig](https://npm.io/package/gamedig.md) — 29.3K weekly downloads
- [join-monster](https://npm.io/package/join-monster.md) — 12.8K weekly downloads
- [masked](https://npm.io/package/masked.md) — 5.5K weekly downloads
- [@comunica/actor-query-process-explain-logical](https://npm.io/package/@comunica/actor-query-process-explain-logical.md) — 4.7K weekly downloads
- [@veracity/vui](https://npm.io/package/@veracity/vui.md) — 4.6K weekly downloads

## Recent versions

- 4.0.1 (latest) — 2021-04-26
- 4.0.0 — 2021-02-25
- 3.0.0 — 2019-12-30
- 2.1.3 — 2018-06-05
- 2.1.2 — 2018-03-27
- 2.1.1 — 2018-03-25
- 2.1.0 — 2018-03-25
- 2.0.0 — 2018-03-19
- 1.3.0 — 2016-09-09
- 1.2.0 — 2016-03-29
- 1.1.0 — 2016-02-22
- 1.0.0 — 2016-02-20

## README

# search-params

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

## API

#### parse: <T>(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: <T>(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.

```js
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'
// }
```

---
_Source: https://npm.io/package/search-params · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._