227 lines
4.8 KiB
Markdown
227 lines
4.8 KiB
Markdown
# zwitch
|
||
|
||
[![Build][build-badge]][build]
|
||
[![Coverage][coverage-badge]][coverage]
|
||
[![Downloads][downloads-badge]][downloads]
|
||
[![Size][size-badge]][size]
|
||
|
||
Handle values based on a field.
|
||
|
||
## Contents
|
||
|
||
* [What is this?](#what-is-this)
|
||
* [When should I use this?](#when-should-i-use-this)
|
||
* [Install](#install)
|
||
* [Use](#use)
|
||
* [API](#api)
|
||
* [`zwitch(key[, options])`](#zwitchkey-options)
|
||
* [`one(value[, rest…])`](#onevalue-rest)
|
||
* [`function handler(value[, rest…])`](#function-handlervalue-rest)
|
||
* [Types](#types)
|
||
* [Compatibility](#compatibility)
|
||
* [Related](#related)
|
||
* [Contribute](#contribute)
|
||
* [Security](#security)
|
||
* [License](#license)
|
||
|
||
## What is this?
|
||
|
||
This is a tiny package that lets you `switch` between some field on objects.
|
||
|
||
## When should I use this?
|
||
|
||
This package is very useful when mapping one AST to another.
|
||
It’s a lot like a `switch` statement on one field, but it’s extensible.
|
||
|
||
## Install
|
||
|
||
This package is [ESM only][esm].
|
||
In Node.js (version 14.14+, 16.0+), install with [npm][]:
|
||
|
||
```sh
|
||
npm install zwitch
|
||
```
|
||
|
||
In Deno with [`esm.sh`][esmsh]:
|
||
|
||
```js
|
||
import {zwitch} from 'https://esm.sh/zwitch@2'
|
||
```
|
||
|
||
In browsers with [`esm.sh`][esmsh]:
|
||
|
||
```html
|
||
<script type="module">
|
||
import {zwitch} from 'https://esm.sh/zwitch@2?bundle'
|
||
</script>
|
||
```
|
||
|
||
## Use
|
||
|
||
```js
|
||
import {zwitch} from 'zwitch'
|
||
|
||
const handle = zwitch('type', {invalid, unknown, handlers: {alpha: handleAlpha}})
|
||
|
||
handle({type: 'alpha'})
|
||
|
||
function handleAlpha() { /* … */ }
|
||
```
|
||
|
||
Or, with a `switch` statement:
|
||
|
||
```js
|
||
const field = 'type'
|
||
|
||
function handle(value) {
|
||
let fn = invalid
|
||
|
||
if (value && typeof value === 'object' && field in value) {
|
||
switch (value[field]) {
|
||
case 'alpha':
|
||
fn = handleAlpha
|
||
break
|
||
default:
|
||
fn = unknown
|
||
break
|
||
}
|
||
}
|
||
|
||
return fn.apply(this, arguments)
|
||
}
|
||
|
||
handle({type: 'alpha'})
|
||
|
||
function handleAlpha() { /* … */ }
|
||
function unknown() { /* … */ }
|
||
function invalid() { /* … */ }
|
||
```
|
||
|
||
## API
|
||
|
||
This package exports the identifier `zwitch`.
|
||
There is no default export.
|
||
|
||
### `zwitch(key[, options])`
|
||
|
||
Create a switch, based on a `key` (`string`).
|
||
|
||
##### `options`
|
||
|
||
Options can be omitted and added later to `one`.
|
||
|
||
###### `options.handlers`
|
||
|
||
Handlers to use, stored on `one.handlers` (`Record<string, Function>`,
|
||
optional).
|
||
|
||
###### `options.unknown`
|
||
|
||
Handler to use for unknown values, stored on `one.unknown` (`Function`,
|
||
optional).
|
||
|
||
###### `options.invalid`
|
||
|
||
Handler to use for invalid values, stored on `one.invalid` (`Function`,
|
||
optional).
|
||
|
||
###### Returns
|
||
|
||
See [`one`][one] (`Function`).
|
||
|
||
### `one(value[, rest…])`
|
||
|
||
Handle one value.
|
||
Based on the bound `key`, a respective handler will be called.
|
||
If `value` is not an object, or doesn’t have a `key` property, the special
|
||
“invalid” handler will be called.
|
||
If `value` has an unknown `key`, the special “unknown” handler will be called.
|
||
|
||
All arguments, and the context object (`this`), are passed through to the
|
||
[handler][], and it’s result is returned.
|
||
|
||
###### `one.handlers`
|
||
|
||
Map of [handler][]s (`Record<string, Function>`).
|
||
|
||
###### `one.invalid`
|
||
|
||
Special [`handler`][handler] called if a value doesn’t have a `key` property.
|
||
If not set, `undefined` is returned for invalid values.
|
||
|
||
###### `one.unknown`
|
||
|
||
Special [`handler`][handler] called if a value does not have a matching
|
||
handler.
|
||
If not set, `undefined` is returned for unknown values.
|
||
|
||
### `function handler(value[, rest…])`
|
||
|
||
Handle one value.
|
||
|
||
## Types
|
||
|
||
This package is fully typed with [TypeScript][].
|
||
It exports the types `Handler`, `UnknownHandler`, `InvalidHandler`, and
|
||
`Options`.
|
||
|
||
## Compatibility
|
||
|
||
This package is at least compatible with all maintained versions of Node.js.
|
||
As of now, that is Node.js 14.14+ and 16.0+.
|
||
It also works in Deno and modern browsers.
|
||
|
||
## Related
|
||
|
||
* [`mapz`](https://github.com/wooorm/mapz)
|
||
— functional map
|
||
|
||
## Contribute
|
||
|
||
Yes please!
|
||
See [How to Contribute to Open Source][contribute].
|
||
|
||
## Security
|
||
|
||
This package is safe.
|
||
|
||
## License
|
||
|
||
[MIT][license] © [Titus Wormer][author]
|
||
|
||
<!-- Definitions -->
|
||
|
||
[build-badge]: https://github.com/wooorm/zwitch/workflows/main/badge.svg
|
||
|
||
[build]: https://github.com/wooorm/zwitch/actions
|
||
|
||
[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/zwitch.svg
|
||
|
||
[coverage]: https://codecov.io/github/wooorm/zwitch
|
||
|
||
[downloads-badge]: https://img.shields.io/npm/dm/zwitch.svg
|
||
|
||
[downloads]: https://www.npmjs.com/package/zwitch
|
||
|
||
[size-badge]: https://img.shields.io/bundlephobia/minzip/zwitch.svg
|
||
|
||
[size]: https://bundlephobia.com/result?p=zwitch
|
||
|
||
[npm]: https://docs.npmjs.com/cli/install
|
||
|
||
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
|
||
|
||
[esmsh]: https://esm.sh
|
||
|
||
[typescript]: https://www.typescriptlang.org
|
||
|
||
[contribute]: https://opensource.guide/how-to-contribute/
|
||
|
||
[license]: license
|
||
|
||
[author]: https://wooorm.com
|
||
|
||
[one]: #onevalue-rest
|
||
|
||
[handler]: #function-handlervalue-rest
|