@arrows/multimethod
Advanced tools
Multimethods are functions with superpowers - they can do all that ordinary functions can do, but additionally:
The multimethod library provides a tiny set of higher-order functions to create powerful, immutable multimethods - in a functional way.
The library has built-in type definitions, which provide an excellent IDE support.
Via NPM:
npm i @arrows/multimethod
Via Yarn:
yarn add @arrows/multimethod
Note: You can find all the examples from this section (runnable) in the examples folder.
import { multi, method, fromMulti } from '@arrows/multimethod'
/**
* Save data in a specified format
*
* @param {object} data
* @param {string} format
* @returns {void}
*/
const save = multi(
(data, format) => format, // Custom dispatch function
method('json', (data, format) => {
console.log('Saving as JSON!')
}),
method('html', (data, format) => {
console.log('Saving as HTML!')
}),
method((data, format) => {
console.log('Default - saving as TXT!')
}),
)
const data = { name: 'Alice', score: 100 }
save(data, 'json') // -> "Saving as JSON!"
save(data, 'html') // -> "Saving as HTML!"
save(data, 'csv') // -> "Default - saving as TXT!"
Let's add a new format, without touching the existing code:
const extendedSave = method('csv', (data, format) => {
console.log('Saving as CSV!')
})(save)
extendedSave(data, 'json') // -> "Saving as JSON!"
extendedSave(data, 'html') // -> "Saving as HTML!"
extendedSave(data, 'csv') // -> "Saving as CSV!"
extendedSave(data, 'yaml') // -> "Default - saving as TXT!"
We can also easily extend the original function with multiple methods:
const extendedSave2 = fromMulti(
method('csv', (data, format) => {
console.log('Saving as CSV!')
}),
method('yaml', (data, format) => {
console.log('Saving as YAML!')
}),
)(save)
extendedSave2(data, 'json') // -> "Saving as JSON!"
extendedSave2(data, 'html') // -> "Saving as HTML!"
extendedSave2(data, 'csv') // -> "Saving as CSV!"
extendedSave2(data, 'yaml') // -> "Saving as YAML!"
In both cases, the original save function remains intact.
That's just a simple example, you can do much more!
const myFunction = multi(
optional_dispatch_function,
method(optional_case_value, corresponding_value),
...other_methods,
)
Dispatch function produces values, by which multimethod should be dispatched. The return value of the dispatch function is compared with the case values of registered methods.
The matching algorithm uses deep strict equality to find the match. There are several exceptions to this rule, they are described in the case value section.
Note: The current implementation of the deep strict equal algorithms guarantees the correct results for JSON compatible types, Map, Set, and TypedArray
If you do not provide a dispatch function, the default one will be used. Default dispatch function returns all arguments as an array, or in case of single argument - as a standalone value.
For a collection of useful, ready-to-use dispatch functions, check out the @arrows/dispatch package.
Examples:
/**
* Function with a single argument,
* default dispatch will return that argument as-is.
*
* @param {string} color
* @returns {string} hex color
*/
const colorToHex = multi(
method('red', '#ff0000'),
method('green', '#00ff00'),
method('blue', '#0000ff'),
)
colorToHex('green') // -> "#00ff00"
/**
* Function with multiple arguments,
* default dispatch will return the array of arguments.
*
* Note that the order of the arguments does matter,
* so if you want the example to work for each combination,
* you either have to provide methods for reversed arguments
* or add your custom dispatch function,
* which returns sorted values (better option).
*
* @param {string} colorA
* @param {string} colorB
* @returns {string} the resulting color
*/
const mixLights = multi(
method(['red', 'green'], 'yellow'),
method(['red', 'blue'], 'magenta'),
method(['green', 'blue'], 'cyan'),
)
mixLights('red', 'blue') // -> "magenta"
mixLights('blue', 'red') // -> throws an error
/**
* Function with a custom dispatch.
* More flexible version of the previous example.
*
* @param {string} colorA
* @param {string} colorB
* @returns {string} the resulting color
*/
const mixLights = multi(
(colorA, colorB) => [colorA, colorB].sort(), // custom dispatch
method(['green', 'red'], 'yellow'),
method(['blue', 'red'], 'magenta'),
method(['blue', 'green'], 'cyan'),
)
mixLights('red', 'blue') // -> "magenta"
mixLights('blue', 'red') // -> "magenta"
const store = {
add(text) {
console.log('todo added')
},
remove(id) {
console.log('todo removed')
},
toggle(id) {
console.log('todo toggled')
},
}
/**
* Function with a custom dispatch.
* Dispatch function can produce any arbitrary value.
*
* @param {Object} action
* @param {Object} store
* @returns {void}
*/
const handleAction = multi(
(action, store) => action.type, // custom dispatch
method('ADD_TODO', (action, store) => store.add(action.text)),
method('REMOVE_TODO', (action, store) => store.remove(action.id)),
method('TOGGLE_TODO', (action, store) => store.toggle(action.id)),
)
handleAction({ type: 'ADD_TODO', text: 'Eat banana.' }, store) // -> "todo added"
handleAction({ type: 'TOGGLE_TODO', id: 0 }, store) // -> "todo toggled"
The case value is the first argument of the two-argument method (if you provide only one argument to the method, it will be treated as a default case).
Case value can be anything:
_)You can mix all case value types in one multimethod.
If the case value is neither a predicate function, regular expression, constructor nor a wildcard, it will be matched against the result of the dispatch function using the deep strict equal algorithm.
Examples:
/**
* Function with case values as ordinary values.
* Values can be any arbitrary nested structure, or a primitive.
*
* Matched by the deep strict equal algorithm.
*
* @param {Object} player
* @returns {string} greeting
*/
const greet = multi(
method({ name: 'John', age: '30' }, 'Hello John!'),
method({ name: 'Jane', age: '25' }, 'Hi Jane!'),
method('Howdy stranger!'),
)
greet({ name: 'John', age: '30' }) // -> "Hello John!"
greet({ name: 'Jane', age: '25' }) // -> "Hi Jane!"
greet({ name: 'Jane', age: '40' }) // -> "Howdy stranger!"
If the case value is a constructor, it will be matched against the result of the dispatch function by the strict equality (===) operator,
and if that fails — by the instanceof operator.
Example:
class Email {}
class SMS {}
/**
* Function with case values as constructors.
* Matched by strict equality check, followed by instanceof check.
*
* @param {Object} message
* @returns {string} status
*/
const sendMessage = multi(
method(Email, 'Sending email...'),
method(SMS, 'Sending SMS...'),
)
sendMessage(new Email()) // -> "Sending email..."
sendMessage(new SMS()) // -> "Sending SMS..."
sendMessage(Email) // -> "Sending email..."
sendMessage(SMS) // -> "Sending SMS..."
If the case value is a regular expression it will be matched against the result of the dispatch function by the strict equality (===) operator,
and if that fails — by the RegExp.prototype.test() method.
Example:
/**
* Function with case values as regular expressions.
* Matched by RegExp.prototype.test() method
*
* @param {RegExp} pattern
* @returns {string} type
*/
const productCategory = multi(
method(/wine/, 'wine'),
method(/cheese/, 'cheese'),
method(/bread/, 'bread'),
)
productCategory('blue cheese') // -> "cheese"
productCategory('red wine') // -> "wine"
productCategory('white wine from Germany') // -> "wine"
productCategory('breadcrumbs') // -> "bread"
If the case value is the wildcard (_) it matches any value.
Wildcards (especially paired with the predicate functions) are very useful when you need to check the correctness of the arguments, or shuffle them around (when multimethod has multiple valid signatures).
Wildcard is functionally equivalent to the predicate function that always return true: () => true. It is a bit faster, because it does not execute unnecessary function.
Example:
const { multi, method, _ } = require('@arrows/multimethod')
/**
* Function with case values containing wildcards.
* These values always resolve to true.
*
* @param {any} a
* @param {any} b
* @param {any} c
* @returns {string}
*/
const checkArgs = multi(
(...args) => args.map((arg) => typeof arg),
// Skipping check on the first argument
method([_, 'function', 'function'], () => {
throw new Error('To many functions')
}),
// Skipping check on the second argument
method(['object', _, 'function'], () => {
throw new Error('Wrong combination')
}),
method((a, b, c) => 'ok'),
)
checkArgs(
1,
() => 2,
() => 3,
) // -> Error: To many functions
checkArgs({ id: 1 }, 2, () => 3) // -> Error: Wrong combination
checkArgs(1, { id: 2 }, () => 3) // -> "ok"
If the case value is a function it will be matched against the result of the dispatch function by the strict equality (===) operator,
and if that fails — , and if that fails, the original dispatch function will be ignored,
and the case value function will be executed with all provided arguments.
Case value function should return a boolean value (or at least the output will be treated as such).
If the return value is truthy, then we have a match.
Example:
/**
* Function with case values as ordinary functions.
* Case value functions will be executed ignoring dispatch function values,
* and instead operating on raw arguments.
*
* It's like each method has its own dispatch function.
*
* It is useful when you can't express dispatch in one common function
* when each case has some specific rule.
*
* @param {Object} req
* @returns {string | Object} response value
*/
const router = multi(
method(
(req) => ['GET'].includes(req.method) && req.url === '/',
'Hello world!',
),
method(
(req) => ['GET', 'POST'].includes(req.method) && req.url === '/users',
[{ id: 1, name: 'John' }],
),
method('Oops!'),
)
router({ method: 'GET', url: '/' }) // -> "Hello world!"
router({ method: 'POST', url: '/' }) // -> "Oops!"
router({ method: 'GET', url: '/users' }) // -> [{ id: 1, name: "John" }]
Predicate functions inside an array have slightly different behavior, they receive as an argument the value supplied by the dispatch function at the current position. They do not receive all arguments, and do not override dispatch function.
That way you can fine-tune checks for every argument, going beyond simple equality check.
Example:
const { multi, method, _ } = require('@arrows/multimethod')
/* Custom predicates */
const not = (y) => (x) => x !== y
const notIn = (...args) => (x) => !args.includes(x)
/**
* Function with case value ans an array
* that contains predicate functions.
*
* Very powerful when paired with wildcards.
*
* @param {any} a
* @param {any} b
* @returns {string}
*/
const checkArgs2 = multi(
(a, b) => [typeof a, typeof b],
method([not('number'), _], () => {
throw new Error('First argument should be a number')
}),
method([_, notIn('string', 'number')], () => {
throw new Error('Second argument should be a number or a string')
}),
method((a, b) => 'ok'),
)
checkArgs2('a', 1) // -> Error: First argument should be a number
checkArgs2(1, [2, 3]) // -> Error: Second argument should be a number or a string
checkArgs2(1, 2) // -> "ok"
checkArgs2(5, 'b') // -> "ok"
If the case value is an array that contains any of those:
_)then these values will be matched according to their specific algorithms (but only if they are at the first level of the array).
Everything else will be matched using the deep strict equal algorithm.
This allows you to dispatch multiple arguments using the best fit for every one of them.
Example:
class Article {}
class Recipe {}
class PDF {}
class HTML {}
/**
* Function with case values as constructors wrapped in an array.
*
* It can be very useful, for example as a trivial alternative
* to otherwise complex visitor patter.
*
* @param {Object} document
* @param {Object} template
* @returns {string} embedding description
*/
const embed = multi(
method([Article, PDF], 'Embedding article inside PDF'),
method([Article, HTML], 'Embedding article inside HTML'),
method([Recipe, PDF], 'Embedding recipe inside PDF'),
method([Recipe, HTML], 'Embedding recipe inside HTML'),
)
embed(new Article(), new PDF()) // -> "Embedding article inside PDF"
embed(new Recipe(), new HTML()) // -> "Embedding recipe inside HTML"
You may also noticed that I already used this method in the wildcard and the predicate function examples!
Additional example of case values of different types in one multimethod:
const VIPs = ['john@vip.com', 'alice@vip.com']
/**
* Function with case values of different types.
*
* @param {Object} msg
* @returns {string | Object} response value
*/
const notify = multi(
(msg) => msg.type,
method(
(msg) => msg.type === 'email' && VIPs.includes(msg.email),
'Email from VIP!',
),
method('email', (msg) => `Email from ${msg.email}!`),
method('sms', (msg) => `SMS from ${msg.number}!`),
)
notify({ type: 'email', email: 'alice@vip.com' }) // -> "Email from VIP!"
notify({ type: 'email', email: 'joe@ab.com' }) // -> "Email from joe@ab.com!"
notify({ type: 'sms', number: '123456789' }) // -> "SMS from 123456789!"
The corresponding value is a second argument of the two-argument method (or the first and only argument of the default method).
Corresponding value can be either:
If the corresponding value is a function, it will be executed with passed arguments when its case value is matching.
If the corresponding value is not a function, it will be returned when its case value is matching.
There are many examples already, but here's another one:
/**
* Classic recursive fibonacci.
* Do not use it for big numbers.
*
* As you can see, recursion works just like with ordinary functions.
*
* @param {number} n
* @returns {number} Nth element of fibonacci sequence
*/
const fib = multi(
method(0, 0),
method(1, 1),
method((n) => fib(n - 1) + fib(n - 2)),
)
fib(0) // -> 0
fib(1) // -> 1
fib(9) // -> 34
The multimethod is immutable, so we can't add/override methods, but we can easily create a new multimethod based on the existing one. In fact, every time we execute the method function, we create a new multimethod. This multimethod will have all cases the old one has, plus the new method (you can also "replace" a method by using the same caseValue as an existing one).
You can create a new multimethod with a new method by executing method function and passing a base multimethod as an argument to the second chunk.
Examples:
const baseAdd = multi(
(a, b) => [typeof a, typeof b],
method(['number', 'number'], (a, b) => a + b),
method(['string', 'string'], (a, b) => `${a}${b}`),
)
/**
* Creating a new multimethod with an additional method
*/
const add = method(['bigint', 'bigint'], (a, b) => a + b)(baseAdd)
add(1, 2) // -> 3
add('bat', 'man') // -> "batman"
add(1n, 2n) // -> 3n
const { multi, method } = require('@arrows/multimethod')
/**
* @param {string} language
* @returns ${string} greeting
*/
const baseGreet = multi(
method('ru', 'Привет!'),
method('es', '¡Hola!'),
method('pl', 'Cześć!'),
)
/**
* Creating a new multimethod with added default method
*/
const greet = method('Hello!')(baseGreet)
greet('ru') // -> "Привет!"
greet('es') // -> "¡Hola!"
greet('pl') // -> "Cześć!"
greet('fr') // -> "Hello!"
You can create a new multimethod with multiple new methods either by generic compose function, or by using a built-in fromMulti function that gives you additional type checks and better error handling.
Examples:
const baseHandleHTTPError = multi(
method(400, 'Incorrect request.'),
method(404, 'The path does not exist.'),
)
/**
* Creating a new multimethod with many new methods via generic functional `compose`
*/
const handleHTTPError = compose(
method(403, 'You do not have access to this resource.'),
method(418, 'We are all teapots!'),
)(baseHandleHTTPError)
handleHTTPError(400) // -> "Incorrect request."
handleHTTPError(418) // -> "We are all teapots!"
const baseArea = multi(
(shape) => shape.type,
method('rectangle', (shape) => shape.a * shape.b),
method('square', (shape) => shape.a ** 2),
)
/**
* Creating a new multimethod with many new methods via `fromMulti` function
*/
const area = fromMulti(
method('circle', (shape) => Math.PI * shape.r ** 2),
method('triangle', (shape) => 0.5 * shape.a * shape.h),
)(baseArea)
area({ type: 'square', a: 5 }) // -> 25
area({ type: 'circle', r: 3 }) // -> 28.274333882308138
When you execute the method function, the case will be added to the front of the multimethod. In case of the partially applied method functions passed to the multi and fromMulti functions, they will be added from bottom to top - so they will maintain their order in a final multimethod.
Order of the methods inside a multimethod determines their priority.
Examples:
/** Priorities for methods inside `evenMoreExtended` function */
const base = multi(
method('a', 'priority: 5'),
method('b', 'priority: 6'),
method('c', 'priority: 7'),
)
const extended = method('d', 'priority: 4')(base)
const evenMoreExtended = fromMulti(
method('e', 'priority: 1'),
method('f', 'priority: 2'),
method('g', 'priority: 3'),
)(extended)
/**
* Function where the priority does matter
*
* @param {number} points
* @returns {number} grade
*/
const baseGradeExam = multi(
method((points) => points < 10, 'failed'),
method((points) => points <= 15, 'ok'),
method((points) => points > 15, 'good'),
)
const gradeExam = fromMulti(
method((points) => points === 0, 'terrible'),
method((points) => points > 20, 'excellent'),
)(baseGradeExam)
gradeExam(0) // -> 'terrible'
gradeExam(5) // -> 'failed'
gradeExam(10) // -> 'ok'
gradeExam(15) // -> 'ok'
gradeExam(20) // -> 'good'
gradeExam(25) // -> 'excellent'
Multimethods support automatic currying and manual currying/chunking, based on dispatch function.
Multimethods work with all generic curry functions. Currying is based on the length of the dispatch function, so you should provide an explicit dispatch (default dispatch is a variadic function, so its length is 0).
Example:
import curry from '@arrows/composition/curry'
import { multi, method } from '@arrows/multimethod'
/**
* Currying with a generic `curry` function.
* Explicit dispatch function (length: 2).
*
* Note that you can still use non-functions as corresponding values.
*
* @param {string} type
* @param {string} source
* @returns {string} info
*/
const play = multi(
(type, source) => type,
method('audio', (type, source) => `Playing audio from: ${source}`),
method('video', (type, source) => `Playing video from: ${source}`),
)
const curriedPlay = curry(play)
const playAudio = curriedPlay('audio')
const playVideo = curriedPlay('video')
playAudio('songs.io/123') // -> "Playing audio from: songs.io/123"
playVideo('movies.com/123') // -> "Playing video from: movies.com/123"
If you prefer manual currying, or you already have functions that use manual currying and want to use them as methods, you can easily do that with the multimethod. Just like with automatic currying, execution is based on the dispatch function.
Examples:
const mapArray = (fn) => (arr) => arr.map(fn)
const mapString = (fn) => (str) => [...str].map(fn)
/**
* Manually curried function - each chunk has one argument.
*/
const map = multi(
(fn) => (val) => (Array.isArray(val) ? 'array' : typeof val),
method('array', mapArray),
method('string', mapString),
)
map((char) => char.charCodeAt(0))('Hello') // -> [72, 101, 108, 108, 111]
map((item) => item * 2)([1, 2, 3]) // -> [2, 4, 6]
/**
* Manually chunked function - chunks can have more than one argument,
* they can also have default values.
*
* Note that you can still use non-functions as corresponding values.
*/
const checkGrammar = multi(
(config = {}) => (text, language) => language,
method('en', 'Checking English grammar'),
method('pl', 'Checking Polish grammar'),
)
const checkTypos = checkGrammar({ typos: true })
checkTypos('mistkae', 'en') // -> "Checking English grammar"
checkTypos('błąt', 'pl') // -> "Checking Polish grammar"
Note: To make it possible, the multi function counts chunks (segments) when multimethod is created, by executing dispatch function without arguments until a returned value is not a function or error is thrown. This comes with one limitation - you should not use any argument-based calculations as default values. If you do that, the library won't be able to correctly count segments.
For example, this will not work as intended:
/**
* This won't work, because of the default value calculation
* based on the `a` argument.
*/
const fn = multi(
(a) => (b = a.foo) => a,
method(/* some case */),
method(/* some case */),
)
Note: If you use custom caseValue functions when using manual currying, arguments for these caseValue functions are automatically flattened.
For example:
/**
* Even though we don't use dispatch value, we have to add
* a dispatch function to inform the multimethod of how to handle this.
*
* As you can see, you don't have to curry a caseValue function.
*/
const fn = multi(
a => b => c => null,
method((a, b, c) => /* some check */, a => b => c => /* some return */),
method((a, b, c) => /* some check */, a => b => c => /* some return */),
)
If you use TypeScript, you will probably want to make your multimethods type-safe. While the dynamic nature of the multimethods makes it hard for the compiler to guarantee that multimethod is put together correctly, you can still ensure correct usage of the multimethod by defining its interface.
TypeScript supports function overloading defined via interfaces (or type alias equivalents) and intersections.
Creating a new multimethod from scratch:
import { method, multi, Multi } from '@arrows/multimethod'
/**
* Multimethod type defined using interface.
*
* Extending `Multi` type guarantees that the multimethod will
* be recognized correctly when extended by `fromMulti` function.
*/
interface Add extends Multi {
(x: number, y: number): number
(x: string, y: string): string
}
const add: Add = multi(
<T>(x: T, x: T): T => [x, y],
method([Number, Number], (x: number, y: number): number => x + y),
method([String, String], (x: string, y: string): string => `${x}${y}`),
)
/*
add(3, 3) // -> 6
add('foo', 'bar') // -> "foobar"
add(5, [1, 2]) // compiler error
*/
export { Add }
export default add
Creating a new multimethod from an existing one:
import { fromMulti, method } from '@arrows/multimethod'
import baseAdd, { Add as BaseAdd } from './add'
/**
* Multimethod type defined by extending existing interface.
*/
interface Add extends BaseAdd {
(x: bigint, y: bigint): bigint
}
const add: Add = fromMulti(
method([BigInt, BigInt], (x: bigint, y: bigint) => x + y),
)(baseAdd)
add(3, 3) // -> 6
add('foo', 'bar') // -> "foobar"
add(3n, 5n) // -> 8n
add(3, [1, 2, 3]) // compiler error
Creating a new multimethod from scratch:
import { method, multi, Multi } from '@arrows/multimethod'
/**
* Multimethod type defined using interface.
*
* Using intersection with `Multi` type guarantees that the multimethod
* will be recognized correctly when extended by `fromMulti` function.
*/
type Add = Multi & {
(x: number, y: number): number
(x: string, y: string): string
}
const add: Add = multi(
<T>(x: T, x: T): T => [x, y],
method([Number, Number], (x: number, y: number): number => x + y),
method([String, String], (x: string, y: string): string => `${x}${y}`),
)
/*
add(3, 3) // -> 6
add('foo', 'bar') // -> "foobar"
add(5, [1, 2]) // compiler error
*/
export { Add }
export default add
Creating a new multimethod from an existing one:
import { fromMulti, method } from '@arrows/multimethod'
import baseAdd, { Add as BaseAdd } from './add'
/**
* Multimethod type defined by intersection with existing type.
*/
type Add = BaseAdd & {
(x: bigint, y: bigint): bigint
}
const add: Add = fromMulti(
method([BigInt, BigInt], (x: bigint, y: bigint) => x + y),
)(baseAdd)
add(3, 3) // -> 6
add('foo', 'bar') // -> "foobar"
add(3n, 5n) // -> 8n
add(3, [1, 2, 3]) // compiler error
Usually, the best way to create a multimethod is to define component functions and their type aliases first - that way you can use a multimethod or a raw function - according to what fits best. Doing so you can also reuse type aliases for specific components for multimethod type.
Creating a new multimethod from scratch:
import { method, multi, Multi } from '@arrows/multimethod'
/**
* Component functions with type aliases.
*/
type AddNumbers = (x: number, y: number) => number
const addNumbers: AddNumbers = (x, y) => x + y
type AddStrings = (x: string, y: string) => string
const addStrings: AddStrings = (x, y) => `${x}${y}`
/**
* Multimethod type defined by intersection of existing types.
*
* Using intersection with `Multi` type guarantees that the multimethod
* will be recognized correctly when extended by `fromMulti` function.
*/
type Add = Multi & AddNumbers & AddStrings
const add: Add = multi(
<T>(x: T, y: T): T => [x, y],
method([Number, Number], addNumbers),
method([String, String], addStrings),
)
/*
add(3, 3) // -> 6
add('foo', 'bar') // -> "foobar"
add(3, [1, 2, 3]) // compiler error
*/
export { addNumbers, addStrings, Add }
export default add
Creating a new multimethod from an existing one:
import { fromMulti, method } from '@arrows/multimethod'
import baseAdd, { Add as BaseAdd } from './add'
type AddBigInts = (x: bigint, y: bigint) => bigint
const addBigInts: AddBigInts = (x, y) => x + y
/**
* Multimethod type defined by intersection of existing types.
*/
type Add = BaseAdd & AddBigInts
// prettier-ignore
const add: Add = fromMulti(
method([BigInt, BigInt], addBigInts),
)(baseAdd)
add(3, 3) // -> 6
add('foo', 'bar') // -> "foobar"
add(3n, 5n) // -> 8n
add(3, [1, 2, 3]) // compiler error
Creates multimethod - a function that can dynamically choose proper implementation, based on arbitrary dispatch of its arguments.
first - The first argument can be either a dispatch function or a partially-applied methodmethods - Arbitrary number of partially applied methods (optional)
(dispatch | method, method?, method?, ..., method?) => multimethod
Create a multimethod with a custom dispatch and no methods:
const fn = multi((x) => typeof x)
fn('foo') // -> throws an Error (because of no matching methods), but is useful as a base for extensions
Create a multimethod with the default dispatch and some methods:
const makeSound = multi(
method('cat', () => 'Meow!'),
method('dog', () => 'Woof!'),
method(() => 'Hello!'), // default method (ony one argument provided)
)
makeSound('cat') // -> 'Meow!'
makeSound('dog') // -> 'Woof!'
makeSound('cow') // -> 'Hello!' (that's a rather unusual cow)
Create a multimethod with a custom dispatch and some methods:
const multiply = multi(
(multiplier, x) => [typeof multiplier, typeof x],
method(['number', 'number'], (multiplier, x) => x * multiplier),
method(['number', 'string'], (multiplier, x) => x.repeat(multiplier)),
)
multiply(2, 5) // -> 10
multiply(3, 'Beetlejuice! ') // -> 'Beetlejuice! Beetlejuice! Beetlejuice! ' (do not read it out loud)
multiply(2, [1, 2, 3]) // -> throws an Error (no match and no default method for these arguments)
Adds a method to a multimethod
caseValue - The value to which the result of dispatch function is matched
correspondingValue - The value that function should return on matching case
multimethod - Multimethod on which you want to base the new multimethod
(caseValue?, correspondingValue) => (multimethod) => new_multimethod
Default method as a function:
const sayHello = multi((user) => user.lang)
const sayHelloWithDefault = method((user) => `Hello ${user.name}!`)(sayHello)
sayHelloWithDefault({ name: 'Alejandro', lang: 'es' }) // -> 'Hello Alejandro!'
Default method as other value:
const sayHello = multi((user) => user.lang)
const sayHelloWithDefault = method('Hello!')(sayHello)
sayHelloWithDefault({ name: 'Alejandro', lang: 'es' }) // -> 'Hello!'
Method with caseValue as an ordinary value and correspondingValue as a function:
const add = multi((a, b) => [typeof a, typeof b])
const extendedAdd = method(['number', 'number'], (a, b) => a + b)(add)
extendedAdd(1, 2) // -> 3
Method with caseValue and correspondingValue as ordinary values:
const getHexColor = multi((color) => color)
const extendedGetHexColor = method('red', '#FF0000')(getHexColor)
extendedGetHexColor('red') // -> '#FF0000'
Method with caseValue as a function and correspondingValue as an ordinary value:
class Enemy {}
const is = (prototype) => (value) => value instanceof prototype
const greet = multi((person) => person)
// Matches, when case function executed with initial arguments returns truthy value
const extendedGreet = method(is(Enemy), 'Goodbye!')(greet)
extendedGreet(new Enemy()) // -> 'Goodbye!'
Method with caseValue and correspondingValue as functions:
class Car {
drive() {
return 'driving...'
}
}
class Human {
walk() {
return 'walking...'
}
}
const is = (prototype) => (value) => value instanceof prototype
const go = multi(
method(is(Car), (entity) => entity.drive()), // lets add one case to original multimethod
)
const extendedGo = method(is(Human), (entity) => entity.walk())(go)
extendedGo(new Car()) // -> 'driving...'
extendedGo(new Human()) // -> 'walking...'
Method with caseValue as a constructor:
class Email {}
class SMS {}
const send = multi(
method(Email, 'Sending email...'), // lets add one case to the original multimethod
)
const extendedSend = method(SMS, 'Sending SMS...')(send)
extendedSend(new Email()) // -> 'Sending email...'
extendedSend(new SMS()) // -> 'Sending SMS...'
Creates a new multimethods from the existing ones, convenient for adding multiple methods.
methods - Arbitrary number of partially applied methodsmultimethod - Multimethod on which you want to base a new multimethod(method, method?, ..., method?) => (multimethod) => new_multimethod
Create a new multimethod using an existing one as a base:
const add = multi(
(a, b) => [typeof a, typeof b],
method(['number', 'number'], (a, b) => a + b),
method(['string', 'string'], (a, b) => `${a}${b}`),
)
const extendedAdd = fromMulti(
method(['bigint', 'bigint'], (a, b) => a + b),
method(['number', 'bigint'], (a, b) => BigInt(a) + b),
method(['bigint', 'number'], (a, b) => a + BigInt(b)),
)(add)
extendedAdd(1, 2) // -> 3
extendedAdd('foo', 'bar') // -> 'foobar'
extendedAdd(2n, 3n) // -> 5n
extendedAdd(5, 5n) // -> 10n
extendedAdd(9n, 2) // -> 11n
Retrieves the object with building blocks of the multimethod.
Note: You should not mutate any of its values.
multimethod - Multimethod which you want to inspectdispatch - shows the dispatch functionentries - shows all [caseValue, correspondingValue] entriescases - shows all caseValue itemsvalues - shows all correspondingValue items(multimethod) => inspection_object
const { multi, method, inspect, _ } = require('@arrows/multimethod')
const mixColors = multi(
method(['yellow', 'red'], 'orange'),
method(['black', _], 'black'),
method(['red', 'blue'], 'purple'),
method('no idea'),
)
const inspectionObject = inspect(mixColors)
console.dir(inspectionObject.entries, { depth: null })
/* Result:
[
[ { type: 'data', value: [ 'yellow', 'red' ] }, 'orange' ],
[
{
type: 'mixed',
values: [ { type: 'data', value: 'black' }, { type: 'wildcard' } ]
},
'black'
],
[ { type: 'data', value: [ 'red', 'blue' ] }, 'purple' ],
[ { type: 'default' }, 'no idea' ]
]
*/
console.dir(inspectionObject.dispatch, { depth: null })
/* Result:
[Function: implicitDispatch]
*/
Special placeholder that matches any value.
const { multi, method, _ } = require('@arrows/multimethod')
const hasCallback = multi(
(a, b) => [typeof a, typeof b],
method(['function', __], true),
method([__, 'function'], true),
method(false),
)
hasCallback(() => {}, 'a') // -> true
hasCallback('b', () => {}) // -> true
hasCallback(
() => {},
() => {},
) // -> true
hasCallback(3, 4) // -> false
Project is under open, non-restrictive ISC license.
FAQs
Functional multimethod library
We found that @arrows/multimethod demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.