Functional switch statement.

Features

• Deep equality testing
• Advanced testing and manipulation
• Add your own domain-specific conditions and transforms
• Strictly typed

Examples

Basic usage

import switchFunctional from 'switch-functional'

const getUserType = (user) =>
  switchFunctional(user.type)
    .case('dev', 'developer')
    .case(['admin', 'owner'], 'administrator')
    .default('unknown')

This is equivalent to:

const getUserType = (user) => {
  switch (user.type) {
    case 'dev': {
      return 'developer'
    }

    case 'admin':

    case 'owner': {
      return 'administrator'
    }

    default: {
      return 'unknown'
    }
  }
}

Testing input

const getUserType = (user) =>
  switchFunctional(user)
    .case(isDeveloper, 'developer')
    .case([isAdmin, isOwner], 'admin')
    .default('unknown')

This is equivalent to:

const getUserType = (user) => {
  if (isDeveloper(user)) {
    return 'developer'
  }

  if (isAdmin(user) || isOwner(user)) {
    return 'admin'
  }

  return 'unknown'
}

Testing properties

const getUserType = (user) =>
  switchFunctional(user)
    // Checks `user.hasDevProjects === true`
    .case({ hasDevProjects: true }, 'developer')
    // Checks for deep properties
    .case({ devProjectsCount: 0, permissions: { admin: true } }, 'admin')
    .default('unknown')

Returning dynamic values

const getUserType = (user) =>
  switchFunctional(user)
    .case(isDeveloper, (user) => user.developerType)
    .case(isAdmin, (user) => user.adminType)
    .default((user) => user.genericType)

Custom conditions

import { Admin, Developer } from './user-classes.js'

// Augment the `.case()` syntax to support domain-specific conditions.
// In this example, this allows conditions to be user classes.
const mapCondition = (condition) =>
  USER_CLASSES.has(condition) ? (user) => user instanceof condition : condition

const USER_CLASSES = new Set([Admin, Developer])

export const customSwitch = (user) => switchFunctional(user, { mapCondition })

import { customSwitch } from './custom-switch.js'
import { Admin, Developer } from './user-classes.js'

const getUserType = (user) =>
  customSwitch(user)
    .case(Developer, 'developer')
    .case(Admin, 'admin')
    .default('unknown')

Custom transforms

// Augment the `.case()` and `.default()` syntax to support domain-specific
// logic applied on the return values.
// In this example, the return value is kept as is. However, it is logged.
const mapReturnValues = (returnValue) => {
  console.log(returnValue)
  return returnValue
}

export const customSwitch = (user) =>
  switchFunctional(user, { mapReturnValues })

import { customSwitch } from './custom-switch.js'

// 'developer', 'admin' or 'unknown' will be logged
const getUserType = (user) =>
  customSwitch(user)
    .case(isDeveloper, 'developer')
    .case(isAdmin, 'admin')
    .default('unknown')

Install

npm install switch-functional

This package works in both Node.js >=18.18.0 and browsers.

This is an ES module. It must be loaded using an import or import() statement, not require(). If TypeScript is used, it must be configured to output ES modules, not CommonJS.

API

switchFunctional(input, options?)

input: unknown
options?: Options
Return value: Switch

Functional switch statement. This must be chained with .case() statements and end with .default().

Switch.case(conditions, caseReturnValue)

conditions: Condition | Condition[]
caseReturnValue: unknown | (input) => unknown
Return value: Switch

If the input matches the conditions, the final return value will be caseReturnValue.

caseReturnValue can optionally be a function taking the input as argument.

Switch.default(defaultReturnValue)

defaultReturnValue: unknown | (input) => unknown
Return value: unknown

If one of the .case() statements matched, returns its caseReturnValue. Else, returns defaultReturnValue.

defaultReturnValue can optionally be a function taking the input as argument.

Conditions

The conditions can be:

• Any value, checked for equality with Object.is()
• An object containing of subset of properties
• A filtering function taking the input as argument and returning a boolean
• A boolean
• An array of the above types, checking if any condition in the array matches

Options

Type: object

mapCondition

Type: (unknown) => Condition

Function mapping each value passed to .case(value) or .case(value[]).

Can return any value condition, including a function taking the input as argument. Cannot return an array of conditions.

This allows augmenting the syntax of .case() to support domain-specific custom conditions.

mapReturnValues

Type: (...unknown[]) => unknown | (input) => unknown

Function mapping each return value passed to .case(..., caseReturnValue) or .default(defaultReturnValue).

Can return any value, including a function taking the input as argument.

Can have multiple parameters: this allows calling .case() and .default() with multiple arguments.

This allows augmenting the syntax of .case() and .default() to support domain-specific custom transforms.

Related projects

• modern-errors-switch: Execute class-specific logic

Support

For any question, don't hesitate to submit an issue on GitHub.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!