https://github.com/jill64/typed-qparam
🔍 Type-safe query parameter manipulation
https://github.com/jill64/typed-qparam
library querystring typesafe
Last synced: 5 months ago
JSON representation
🔍 Type-safe query parameter manipulation
- Host: GitHub
- URL: https://github.com/jill64/typed-qparam
- Owner: jill64
- License: mit
- Created: 2023-09-28T16:00:08.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-21T11:47:13.000Z (9 months ago)
- Last Synced: 2025-04-21T12:41:03.132Z (9 months ago)
- Topics: library, querystring, typesafe
- Language: TypeScript
- Homepage: https://npmjs.com/package/typed-qparam
- Size: 402 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# typed-qparam
🔍 Type-safe query parameter manipulation
> [!NOTE]
> See [here](./docs/v1.md) for documentation on <=v1 features.
## Installation
```sh
npm i typed-qparam
```
## Simple Usage
Passing a query parameter key to the `qparam` function returns the accessor for that value.
```js
import { extract } from 'typed-qparam'
const qparam = extract(new URL('https://example.com/?foo=bar'))
const foo = qparam('foo')
// output: 'bar'
console.log(foo.get())
// .set() only returns a new URL instance.
// The original URL instance is not changed.
// No navigation of any kind will occur.
// url: new URL('https://example.com/?foo=baz')
const url = foo.set('baz')
// output: 'https://example.com/?foo=baz'
console.log(url.href)
```
## Typed Param
By passing a conversion function as the second argument, you can obtain a value converted to any type.
See [ts-serde](https://github.com/jill64/ts-serde#readme) for more information on type guard.
```js
import { extract } from 'typed-qparam'
import { number } from 'typed-qparam/serde'
const qparam = extract(new URL('https://example.com/?num=123'))
const num = qparam('num', {
stringify: (value) => value.toString(),
parse: (str) => parseInt(str)
})
// output 123
console.log(num.get())
// https://example.com/?key=456
const dist = num.set(456)
```
### Prepared Converter
You can also use the prepared converters in `typed-qparam/serde`.
See [ts-serde](https://github.com/jill64/ts-serde#readme) for more information on type guard
```js
import { extract } from 'typed-qparam'
import { number, boolean, enums } from 'typed-qparam/serde'
const qparam = extract(
new URL('https://example.com/?num=123&bool=true&enumerate=b')
)
const num = qparam('num', number)
const bool = qparam('bool', boolean)
const enumerate = qparam(
'enumerate',
enums(
['a', 'b', 'c'],
'a' // fallback default value
)
)
```
## Array Param
Sometimes you need to handle query parameters with multiple values in the same key, such as `?str=hello&str=world`.
With `typed-qparam`, you can treat this as an array.
```js
import { extract, array } from 'svelte-qparam'
import { string, number } from 'svelte-qparam/serde'
const qparam = extract(new URL('https://example.com/?str=hello&str=world'))
const str = qparam('str', array())
// is equivalent to
// const str = qparam('str', array(string))
// if require other typed value
const num = qparam('num', array(number))
// output ['hello', 'world']
console.log(str.get())
// https://example.com/?str=foo&str=bar&str=baz
str.set(['foo', 'bar', 'baz'])
```
## License
[MIT](LICENSE)