zwitch

[![Build][build-badge]][build] [![Coverage][coverage-badge]][coverage] [![Downloads][downloads-badge]][downloads] [![Size][size-badge]][size]

Handle values based on a field.

* What is this? * When should I use this? * Install * Use * API * zwitch(key[, options]) * one(value[, rest…]) * function handler(value[, rest…]) * Types * Compatibility * Related * Contribute * Security * 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][]:

npm install zwitch

In Deno with [esm.sh][esmsh]:

import {zwitch} from 'https://esm.sh/zwitch@2'

In browsers with [esm.sh][esmsh]:

Use

import {zwitch} from 'zwitch'
const handle = zwitch('type', {invalid, unknown, handlers: {alpha: handleAlpha}})
handle({type: 'alpha'})function handleAlpha() { / … / }

Or, with a switch statement:

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, 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).

###### 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.

* mapz — functional map

Contribute

Yes please! See [How to Contribute to Open Source][contribute].

Security

This package is safe.

License

[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

📄 readme.md