@danielnarey/maybe

[Deprecated] A tiny functional data structure for values that might not exist

Deprecation Warning: This experimental library is no longer in active development and will not be updated in response to Node.js version releases or security vulnerabilities identified in the dependency tree.

Purpose

When you have a reference or function result that might not resolve to a value of the expected type or range, using a maybe simplifies error handling, helping to ensure predictable behavior from your application.

Examples

import maybe from '@danielnarey/maybe';
// OR: const maybe = require('@danielnarey/maybe');

// constructor
const mb = maybe.of('🤷‍♂️');
typeof(mb); //--> 'function'

// accessors
maybe.withDefault(mb, '🙈'); //--> '🤷‍♂️'
maybe.withDefault(maybe.nothing(), '🙈'); //--> '🙈'

// conversion
maybe.toPromise(mb).then(console.log); //--> '🤷‍♂️'
maybe.toPromise(maybe.nothing()).catch(() => console.log('🙈')); //--> '🙈'

// functional transforms
const mb2 = maybe.map(mb, (s) => `🧜‍♀️${s}`);

// immutability
maybe.toString(mb); //--> '(?"🤷‍♂️")'
maybe.toString(mb2); //--> '(?"🧜‍♀️🤷‍♂️")'

API

of(v) => (?v)

Create a maybe of something: perhaps a resolvable value, or perhaps a reference or function result that is undefined, null, an inappropriate type, or out of bounds. Returns a functional interface to the enclosed value (denoted as (?v)).

nothing() => (?nothing)

Returns a maybe that encloses nothing.

map(mb, f, [test]) => (?f(v)|nothing)

Attempt to apply a function to a maybe. If passing the enclosed value v of mb to test returns true, map applies f to v and returns the result as a new maybe. If test returns false, map returns a maybe that encloses nothing. If a test function is not supplied, the default test returns true for any value that is not undefined or null.

withDefault(mb, d, [test]) => v|d

Attempt to resolve a maybe, substituting a default when the enclosed value is missing or invalid. If passing the enclosed value v of mb to test returns true, withDefault returns v. If test returns false, withDefault returns d. If a test function is not supplied, the default test returns true for any value that is not undefined or null.

toPromise(mb, [test, [err]]) => Promise<v|err>

Convert a maybe to a Promise. If passing the enclosed value v of mb to test returns true, toPromise returns a promise that resolves to v. If test returns false, toPromise returns a promise that rejects with err. If a test function is not supplied, the default test returns true for any value that is not undefined or null.

fromPromise(p) => Promise<(?v|nothing)>

Ensure that a promise won't reject by converting its awaited value to a maybe. If p is a promise that resolves to v, awaiting fromPromise(p) returns a maybe that encloses v. If p is a promise that rejects, awaiting fromPromise(p) returns a maybe that encloses nothing.

toString(mb) => '(?v)'

Returns a string representing the contents of a maybe.

Prior Art

• Haskell: Data.Maybe
• Elm/core: Maybe