true-myth

variable IsMaybe

const IsMaybe: Symbol;

variable just

const just: {
    <F extends (...args: any) => {}>(value: F): Maybe<F>;
    <T extends {}, F extends (...args: any) => T>(value: F): never;
    <F extends (...args: any) => null>(value: F): never;
    <T extends {}>(value: T): Maybe<T>;
};

• Create a instance which is a .

  null and undefined are allowed by the type signature so that the function may throw on those rather than constructing a type like Maybe<undefined>.

  T The type of the item contained in the Maybe.

  Parameter value

  The value to wrap in a Maybe.Just.

  Returns

  An instance of Maybe.Just<T>.

  Throws

  If you pass null or undefined.

variable Maybe

const Maybe: MaybeConstructor;

• Maybe represents a value which may () or may not () be present.

variable nothing

const nothing: <T>(_?: null) => Nothing<T>;

• Create a instance which is a .

  If you want to create an instance with a specific type, e.g. for use in a function which expects a Maybe<T> where the <T> is known but you have no value to give it, you can use a type parameter:

  ```ts const notString = Maybe.nothing(); ```

  T The type of the item contained in the Maybe.

  Returns

  An instance of Maybe.Nothing<T>.

variable of

const of: {
    <F extends (...args: any) => {}>(value: F): Maybe<F>;
    <T extends {}, F extends (...args: any) => T>(value: F): never;
    <F extends (...args: any) => null>(value: F): never;
    <T extends {}>(value: T): Maybe<T>;
    <T>(value: T): Maybe<NonNullable<T>>;
};

• Create a from any value.

  To specify that the result should be interpreted as a specific type, you may invoke Maybe.of with an explicit type parameter:

  ```ts import * as maybe from 'true-myth/maybe'; const foo = maybe.of(null); ```

  This is usually only important in two cases:

  1. If you are intentionally constructing a Nothing from a known null or undefined value *which is untyped*. 2. If you are specifying that the type is more general than the value passed (since TypeScript can define types as literals).

  T The type of the item contained in the Maybe.

  Parameter value

  The value to wrap in a Maybe. If it is undefined or null, the result will be Nothing; otherwise it will be the type of the value passed.

variable ReadonlyArray

const ReadonlyArray: any;

variable T

const T: any;

variable Variant

const Variant: { readonly Just: 'Just'; readonly Nothing: 'Nothing' };

• Discriminant for the and type instances.

  You can use the discriminant via the variant property of instances if you need to match explicitly on it.

function and

and: {
    <T, U>(andMaybe: Maybe<U>, maybe: Maybe<T>): Maybe<U>;
    <T, U>(andMaybe: Maybe<U>): (maybe: Maybe<T>) => Maybe<U>;
};

• You can think of this like a short-circuiting logical "and" operation on a type. If maybe is , then the result is the andMaybe. If maybe is , the result is Nothing.

  This is useful when you have another Maybe value you want to provide if and only if* you have a Just – that is, when you need to make sure that if you Nothing, whatever else you're handing a Maybe to *also* gets a Nothing.

  Notice that, unlike in [map](#map) or its variants, the original maybe is not involved in constructing the new Maybe.

  #### Examples

  ```ts import Maybe from 'true-myth/maybe';

  const justA = Maybe.just('A'); const justB = Maybe.just('B'); const nothing: Maybe = nothing();

  console.log(Maybe.and(justB, justA).toString()); // Just(B) console.log(Maybe.and(justB, nothing).toString()); // Nothing console.log(Maybe.and(nothing, justA).toString()); // Nothing console.log(Maybe.and(nothing, nothing).toString()); // Nothing ```

  T The type of the initial wrapped value. U The type of the wrapped value of the returned Maybe.

  Parameter andMaybe

  The Maybe instance to return if maybe is Just

  Parameter maybe

  The Maybe instance to check. Nothing if the original maybe is Nothing, or andMaybe if the original maybe is Just.

function andThen

andThen: {
    <T, U>(thenFn: (t: T) => Maybe<U>, maybe: Maybe<T>): Maybe<U>;
    <T, R extends AnyMaybe>(thenFn: (t: T) => R, maybe: Maybe<T>): Maybe<
        ValueFor<R>
    >;
    <T, U>(thenFn: (t: T) => Maybe<U>): (maybe: Maybe<T>) => Maybe<U>;
    <T, R extends AnyMaybe>(thenFn: (t: T) => R): (
        maybe: Maybe<T>
    ) => Maybe<ValueFor<R>>;
};

• Apply a function to the wrapped value if and return a new Just containing the resulting value; or return if Nothing.

  This differs from in that thenFn returns another Maybe. You can use andThen to combine two functions which *both* create a Maybe from an unwrapped type.

  You may find the .then method on an ES6 Promise helpful for comparison: if you have a Promise, you can pass its then method a callback which returns another Promise, and the result will not be a *nested* promise, but a single Promise. The difference is that Promise#then unwraps *all* layers to only ever return a single Promise value, whereas Maybe.andThen will not unwrap nested Maybes.

  > [!NOTE] This is sometimes also known as bind, but *not* aliased as such > because [bind already means something in JavaScript][bind].

  [bind]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind

  #### Example

  (This is a somewhat contrived example, but it serves to show the way the function behaves.)

  ```ts import Maybe, { andThen, toString } from 'true-myth/maybe';

  // string -> Maybe const toMaybeLength = (s: string) => Maybe.of(s.length);

  // Maybe const aMaybeString = Maybe.of('Hello, there!');

  // Maybe const resultingLength = andThen(toMaybeLength, aMaybeString); console.log(toString(resultingLength)); // 13 ```

  Note that the result is not Just(Just(13)), but Just(13)!

  T The type of the wrapped value. U The type of the wrapped value in the resulting Maybe.

  Parameter thenFn

  The function to apply to the wrapped T if maybe is Just.

  Parameter maybe

  The Maybe to evaluate and possibly apply a function to the contents of.

  Returns

  The result of the thenFn (a new Maybe) if maybe is a Just, otherwise Nothing if maybe is a Nothing.

function ap

ap: {
    <T, U extends {}>(maybeFn: Maybe<(t: T) => U>, maybe: Maybe<T>): Maybe<T | U>;
    <T, U extends {}>(maybeFn: Maybe<(t: T) => U>): (
        maybe: Maybe<T>
    ) => Maybe<T | U>;
};

• Allows you to *apply* (thus ap) a value to a function without having to take either out of the context of their s. This does mean that the transforming function is itself within a Maybe, which can be hard to grok at first but lets you do some very elegant things. For example, ap allows you to this:

  ```ts import { just, nothing } from 'true-myth/maybe';

  const one = just(1); const five = just(5); const none = nothing();

  const add = (a: number) => (b: number) => a + b; const maybeAdd = just(add);

  maybeAdd.ap(one).ap(five); // Just(6) maybeAdd.ap(one).ap(none); // Nothing maybeAdd.ap(none).ap(five) // Nothing ```

  Without ap, you'd need to do something like a nested match:

  ```ts import { just, nothing } from 'true-myth/maybe';

  const one = just(1); const five = just(5); const none = nothing();

  one.match({ Just: n => five.match({ Just: o => just(n + o), Nothing: () => nothing(), }), Nothing: () => nothing(), }); // Just(6)

  one.match({ Just: n => none.match({ Just: o => just(n + o), Nothing: () => nothing(), }), Nothing: () => nothing(), }); // Nothing

  none.match({ Just: n => five.match({ Just: o => just(n + o), Nothing: () => nothing(), }), Nothing: () => nothing(), }); // Nothing ```

  And this kind of thing comes up quite often once you're using Maybe to handle optionality throughout your application.

  For another example, imagine you need to compare the equality of two ImmutableJS data structures, where a === comparison won't work. With ap, that's as simple as this:

  ```ts import Maybe from 'true-myth/maybe'; import { is as immutableIs, Set } from 'immutable';

  const is = (first: unknown) => (second: unknown) => immutableIs(first, second);

  const x = Maybe.of(Set.of(1, 2, 3)); const y = Maybe.of(Set.of(2, 3, 4));

  Maybe.of(is).ap(x).ap(y); // Just(false) ```

  Without ap, we're back to that gnarly nested match:

  ```ts import Maybe, { just, nothing } from 'true-myth/maybe'; import { is, Set } from 'immutable';

  const x = Maybe.of(Set.of(1, 2, 3)); const y = Maybe.of(Set.of(2, 3, 4));

  x.match({ Just: iX => y.match({ Just: iY => Maybe.just(is(iX, iY)), Nothing: () => Maybe.nothing(), }) Nothing: () => Maybe.nothing(), }); // Just(false) ```

  In summary: anywhere you have two Maybe instances and need to perform an operation that uses both of them, ap is your friend.

  Two things to note, both regarding *currying*:

  1. All functions passed to ap must be curried. That is, they must be of the form (for add) (a: number) => (b: number) => a + b, *not* the more usual (a: number, b: number) => a + b you see in JavaScript more generally.

  (Unfortunately, these do not currently work with lodash or Ramda's curry helper functions. A future update to the type definitions may make that work, but the intermediate types produced by those helpers and the more general function types expected by this function do not currently align.)

  2. You will need to call ap as many times as there are arguments to the function you're dealing with. So in the case of this add3 function, which has the "arity" (function argument count) of 3 (a and b), you'll need to call ap twice: once for a, and once for b. To see why, let's look at what the result in each phase is:

  ```ts const add3 = (a: number) => (b: number) => (c: number) => a + b + c;

  const maybeAdd = just(add3); // Just((a: number) => (b: number) => (c: number) => a + b + c) const maybeAdd1 = maybeAdd.ap(just(1)); // Just((b: number) => (c: number) => 1 + b + c) const maybeAdd1And2 = maybeAdd1.ap(just(2)) // Just((c: number) => 1 + 2 + c) const final = maybeAdd1.ap(just(3)); // Just(4) ```

  So for toString, which just takes a single argument, you would only need to call ap once.

  ```ts const toStr = (v: { toString(): string }) => v.toString(); just(toStr).ap(12); // Just("12") ```

  One other scenario which doesn't come up *quite* as often but is conceivable is where you have something that may or may not actually construct a function for handling a specific Maybe scenario. In that case, you can wrap the possibly-present in ap and then wrap the values to apply to the function to in Maybe themselves.

  __Aside:__ ap is not named apply because of the overlap with JavaScript's existing [apply] function – and although strictly speaking, there isn't any direct overlap (Maybe.apply and Function.prototype.apply don't intersect at all) it's useful to have a different name to avoid implying that they're the same.

  [apply]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/apply

  Parameter maybeFn

  maybe a function from T to U

  Parameter maybe

  maybe a T to apply to fn

function equals

equals: {
    <T>(mb: Maybe<T>, ma: Maybe<T>): boolean;
    <T>(mb: Maybe<T>): (ma: Maybe<T>) => boolean;
};

• Allows quick triple-equal equality check between the values inside two instances without having to unwrap them first.

  ```ts const a = Maybe.of(3); const b = Maybe.of(3); const c = Maybe.of(null); const d = Maybe.nothing();

  Maybe.equals(a, b); // true Maybe.equals(a, c); // false Maybe.equals(c, d); // true ```

  Parameter mb

  A maybe to compare to.

  Parameter ma

  A maybe instance to check.

function find

find: {
    <T, U extends T>(predicate: NarrowingPredicate<T, U>, array: AnyArray<T>): Maybe<
        NonNullable<U>
    >;
    <T, U extends T>(predicate: NarrowingPredicate<T, U>): (
        array: AnyArray<T>
    ) => Maybe<NonNullable<U>>;
    <T>(predicate: Predicate<T>, array: AnyArray<T>): Maybe<NonNullable<T>>;
    <T>(predicate: Predicate<T>): (array: AnyArray<T>) => Maybe<NonNullable<T>>;
};

• Safely search for an element in an array.

  This function behaves like Array.prototype.find, but returns Maybe<T> instead of T | undefined.

  ## Examples

  The basic form is:

  ```ts import Maybe from 'true-myth/maybe';

  let array = [1, 2, 3]; Maybe.find(v => v > 1, array); // Just(2) Maybe.find(v => v < 1, array); // Nothing ```

  The function is curried so you can use it in a functional chain. For example (leaving aside error handling on a bad response for simplicity), suppose the url https://arrays.example.com returned a JSON payload with the type Array<{ count: number, name: string }>, and we wanted to get the first of these where count was at least 100. We could write this:

  ```ts import Maybe from 'true-myth/maybe';

  type Item = { count: number; name: string }; type Response = Array;

  // curried variant! const findAtLeast100 = Maybe.find(({ count }: Item) => count > 100);

  fetch('https://arrays.example.com') .then(response => response.json() as Response) .then(findAtLeast100) .then(found => { if (found.isJust) { console.log(The matching value is ${found.value.name}!); } }); ```

  Parameter predicate

  A function to execute on each value in the array, returning true when the item in the array matches the condition. The signature for predicate is identical to the signature for the first argument to Array.prototype.find. The function is called once for each element of the array, in ascending order, until it finds one where predicate returns true. If such an element is found, find immediately returns that element value wrapped in Just. Otherwise, Maybe.find returns Nothing.

  Parameter array

  The array to search using the predicate.

function first

first: {
    <T extends {}>(array: AnyArray<T>): Maybe<Just<T>>;
    (array: AnyArray<null>): Maybe<Nothing<{}>>;
    <T extends {}>(array: AnyArray<T>): Maybe<Maybe<T>>;
};

• Safely get the first item from a list, returning the first item if the array has at least one item in it, or if it is empty.

  This produces a Maybe<Maybe<T>> rather than Maybe<T> to distinguish between arrays that include null or undefined and empty arrays.

  ## Examples

  ```ts import { first } from 'true-myth/maybe';

  let empty = []; first(empty); // => Nothing

  let full = [1, 2, 3]; first(full); // => Just(Just(1))

  let mixed = [undefined, 1]; first(mixed); // => Just(Nothing) ```

  Unfortunately, it is not possible to distinguish between these statically in a single call signature in a reasonable way: we do not want to change the types and runtime result produced by calling this function simply because the input array had *its* type changed (to include, or not include, null or undefined). Although the types and runtime could be guaranteed to align, correctly doing so would require every item in the array to check whether *any* items are null or undefined, making the performance linear on the size of the array ($O(n)$) instead of constant time ($O(1)$). This is _quite_ undesirable!

  Parameter array

  The array to get the first item from.

function get

get: {
    <T extends { [key: string]: unknown }, K extends keyof T>(
        key: K,
        maybeObj: Maybe<T>
    ): Maybe<NonNullable<T[K]>>;
    <T extends { [key: string]: unknown }, K extends keyof T>(key: K): (
        maybeObj: Maybe<T>
    ) => Maybe<NonNullable<T[K]>>;
};

• Safely extract a key from a of an object, returning if the key has a value on the object and if it does not. (Like but operating on a Maybe<T> rather than directly on a T.)

  The check is type-safe: you won't even be able to compile if you try to look up a property that TypeScript *knows* doesn't exist on the object.

  ```ts import { get, just, nothing } from 'true-myth/maybe';

  type Person = { name?: string };

  const me: Maybe = just({ name: 'Chris' }); console.log(get('name', me)); // Just('Chris')

  const nobody = nothing(); console.log(get('name', nobody)); // Nothing ```

  However, it also works correctly with dictionary types:

  ```ts import { get, just } from 'true-myth/maybe';

  type Dict = { [key: string]: T };

  const score: Maybe<Dict> = just({ player1: 0, player2: 1 });

  console.log(get('player1', score)); // Just(0) console.log(get('player2', score)); // Just(1) console.log(get('player3', score)); // Nothing ```

  The order of keys is so that it can be partially applied:

  ```ts import { get, just } from 'true-myth/maybe';

  type Person = { name?: string };

  const lookupName = get('name');

  const me: Person = { name: 'Chris' }; console.log(lookupName(me)); // Just('Chris')

  const nobody: Person = {}; console.log(lookupName(nobody)); // Nothing ```

  Parameter key

  The key to pull out of the object.

  Parameter maybeObj

  The object to look up the key from.

function isInstance

isInstance: <T>(item: unknown) => item is Maybe<T>;

• Determine whether an item is an instance of .

  Parameter item

  The item to check.

function isJust

isJust: <T>(maybe: Maybe<T>) => maybe is Just<T>;

• Is the a ?

  T The type of the item contained in the Maybe.

  Parameter maybe

  The Maybe to check.

  Returns

  A type guarded Just.

function isNothing

isNothing: <T>(maybe: Maybe<T>) => maybe is Nothing<T>;

• Is the a ?

  T The type of the item contained in the Maybe.

  Parameter maybe

  The Maybe to check.

  Returns

  A type guarded Nothing.

function last

last: {
    <T extends {}>(array: AnyArray<T>): Maybe<Just<T>>;
    (array: AnyArray<null>): Maybe<Nothing<never>>;
    <T extends {}>(array: AnyArray<T>): Maybe<Maybe<T>>;
};

• Safely get the last item from a list, returning the last item if the array has at least one item in it, or if it is empty.

  This produces a Maybe<Maybe<T>> rather than Maybe<T> to distinguish between arrays that include null or undefined and empty arrays.

  ## Examples

  ```ts import { last } from 'true-myth/maybe';

  let empty = []; last(empty); // => Nothing

  let full = [1, 2, 3]; last(full); // => Just(Just(3))

  let mixed = [1, null, 2, null]; last(mixed); // Just(Nothing) ```

  Unfortunately, it is not possible to distinguish between these statically in a single call signature in a reasonable way: we do not want to change the types and runtime result produced by calling this function simply because the input array had *its* type changed (to include, or not include, null or undefined). Although the types and runtime could be guaranteed to align, correctly doing so would require every item in the array to check whether *any* items are null or undefined, making the performance linear on the size of the array ($O(n)$) instead of constant time ($O(1)$). This is _quite_ undesirable!

  Parameter array

  The array to get the first item from.

function map

map: {
    <T, U extends {}>(mapFn: (t: T) => U): (maybe: Maybe<T>) => Maybe<U>;
    <T, U extends {}>(mapFn: (t: T) => U, maybe: Maybe<T>): Maybe<U>;
};

• Map over a instance: apply the function to the wrapped value if the instance is , and return if the instance is Nothing.

  map works a lot like Array.prototype.map: Maybe and Array are both containers* for other things. If you have no items in an array of numbers named foo and call foo.map(x => x + 1), you'll still just have an array with nothing in it. But if you have any items in the array ([2, 3]), and you call foo.map(x => x + 1) on it, you'll get a new array with each of those items inside the array "container" transformed ([3, 4]).

  That's exactly what's happening with map. If the container is *empty* – the Nothing variant – you just get back an empty container. If the container has something in it – the Just variant – you get back a container with the item inside transformed.

  (So... why not just use an array? The biggest reason is that an array can be any length. With a Maybe, we're capturing the idea of "something or nothing" rather than "0 to n" items. And this lets us implement a whole set of *other* interfaces, like those in this module.)

  #### Examples

  ```ts const length = (s: string) => s.length;

  const justAString = Maybe.just('string'); const justTheStringLength = map(length, justAString); console.log(justTheStringLength.toString()); // Just(6)

  const notAString = Maybe.nothing(); const notAStringLength = map(length, notAString); console.log(notAStringLength.toString()); // "Nothing" ```

  T The type of the wrapped value. U The type of the wrapped value of the returned Maybe.

  Parameter mapFn

  The function to apply the value to if Maybe is Just.

  Returns

  A function accepting a Maybe<T>, which will produce Maybe<U> after applying mapFn.

• Map over a instance: apply the function to the wrapped value if the instance is , and return if the instance is Nothing.

  map works a lot like Array.prototype.map: Maybe and Array are both containers* for other things. If you have no items in an array of numbers named foo and call foo.map(x => x + 1), you'll still just have an array with nothing in it. But if you have any items in the array ([2, 3]), and you call foo.map(x => x + 1) on it, you'll get a new array with each of those items inside the array "container" transformed ([3, 4]).

  That's exactly what's happening with map. If the container is *empty* – the Nothing variant – you just get back an empty container. If the container has something in it – the Just variant – you get back a container with the item inside transformed.

  (So... why not just use an array? The biggest reason is that an array can be any length. With a Maybe, we're capturing the idea of "something or nothing" rather than "0 to n" items. And this lets us implement a whole set of *other* interfaces, like those in this module.)

  #### Examples

  ```ts const length = (s: string) => s.length;

  const justAString = Maybe.just('string'); const justTheStringLength = map(length, justAString); console.log(justTheStringLength.toString()); // Just(6)

  const notAString = Maybe.nothing(); const notAStringLength = map(length, notAString); console.log(notAStringLength.toString()); // "Nothing" ```

  T The type of the wrapped value. U The type of the wrapped value of the returned Maybe.

  Parameter mapFn

  The function to apply the value to if Maybe is Just.

  Parameter maybe

  The Maybe instance to map over.

  Returns

  A new Maybe with the result of applying mapFn to the value in a Just, or Nothing if maybe is Nothing.

function mapOr

mapOr: {
    <T, U>(orU: U, mapFn: (t: T) => U, maybe: Maybe<T>): U;
    <T, U>(orU: U, mapFn: (t: T) => U): (maybe: Maybe<T>) => U;
    <T, U>(orU: U): (mapFn: (t: T) => U) => (maybe: Maybe<T>) => U;
};

• Map over a instance and get out the value if maybe is a , or return a default value if maybe is a .

  #### Examples

  ```ts const length = (s: string) => s.length;

  const justAString = Maybe.just('string'); const theStringLength = mapOr(0, length, justAString); console.log(theStringLength); // 6

  const notAString = Maybe.nothing(); const notAStringLength = mapOr(0, length, notAString) console.log(notAStringLength); // 0 ```

  T The type of the wrapped value. U The type of the wrapped value of the returned Maybe.

  Parameter orU

  The default value to use if maybe is Nothing

  Parameter mapFn

  The function to apply the value to if Maybe is Just

  Parameter maybe

  The Maybe instance to map over.

function mapOrElse

mapOrElse: {
    <T, U>(orElseFn: () => U, mapFn: (t: T) => U, maybe: Maybe<T>): U;
    <T, U>(orElseFn: () => U, mapFn: (t: T) => U): (maybe: Maybe<T>) => U;
    <T, U>(orElseFn: () => U): (mapFn: (t: T) => U) => (maybe: Maybe<T>) => U;
};

• Map over a instance and get out the value if maybe is a , or use a function to construct a default value if maybe is .

  #### Examples

  ```ts const length = (s: string) => s.length; const getDefault = () => 0;

  const justAString = Maybe.just('string'); const theStringLength = mapOrElse(getDefault, length, justAString); console.log(theStringLength); // 6

  const notAString = Maybe.nothing(); const notAStringLength = mapOrElse(getDefault, length, notAString) console.log(notAStringLength); // 0 ```

  T The type of the wrapped value. U The type of the wrapped value of the returned Maybe.

  Parameter orElseFn

  The function to apply if maybe is Nothing.

  Parameter mapFn

  The function to apply to the wrapped value if maybe is Just

  Parameter maybe

  The Maybe instance to map over.

function match

match: {
    <T, A>(matcher: Matcher<T, A>, maybe: Maybe<T>): A;
    <T, A>(matcher: Matcher<T, A>): (m: Maybe<T>) => A;
};

• Performs the same basic functionality as , but instead of simply unwrapping the value if it is and applying a value to generate the same default type if it is , lets you supply functions which may transform the wrapped type if it is Just or get a default value for Nothing.

  This is kind of like a poor man's version of pattern matching, which JavaScript currently lacks.

  Instead of code like this:

  ```ts import Maybe from 'true-myth/maybe';

  const logValue = (mightBeANumber: Maybe) => { const valueToLog = Maybe.mightBeANumber.isJust ? mightBeANumber.value.toString() : 'Nothing to log.';

  console.log(valueToLog); }; ```

  ...we can write code like this:

  ```ts import { match } from 'true-myth/maybe';

  const logValue = (mightBeANumber: Maybe) => { const value = match( { Just: n => n.toString(), Nothing: () => 'Nothing to log.', }, mightBeANumber );

  console.log(value); }; ```

  This is slightly longer to write, but clearer: the more complex the resulting expression, the hairer it is to understand the ternary. Thus, this is especially convenient for times when there is a complex result, e.g. when rendering part of a React component inline in JSX/TSX.

  Parameter matcher

  A lightweight object defining what to do in the case of each variant.

  Parameter maybe

  The maybe instance to check.

function or

or: {
    <T>(defaultMaybe: Maybe<T>, maybe: Maybe<T>): Maybe<T>;
    <T>(defaultMaybe: Maybe<T>): (maybe: Maybe<T>) => Maybe<T>;
};

• Provide a fallback for a given . Behaves like a logical or: if the maybe value is a , returns that maybe; otherwise, returns the defaultMaybe value.

  This is useful when you want to make sure that something which takes a Maybe always ends up getting a Just variant, by supplying a default value for the case that you currently have a nothing.

  ```ts import Maybe from 'true-utils/maybe';

  const justA = Maybe.just("a"); const justB = Maybe.just("b"); const aNothing: Maybe = nothing();

  console.log(Maybe.or(justB, justA).toString()); // Just(A) console.log(Maybe.or(aNothing, justA).toString()); // Just(A) console.log(Maybe.or(justB, aNothing).toString()); // Just(B) console.log(Maybe.or(aNothing, aNothing).toString()); // Nothing ```

  T The type of the wrapped value.

  Parameter defaultMaybe

  The Maybe to use if maybe is a Nothing.

  Parameter maybe

  The Maybe instance to evaluate.

  Returns

  maybe if it is a Just, otherwise defaultMaybe.

function orElse

orElse: {
    <T, R extends AnyMaybe>(elseFn: () => R, maybe: Maybe<T>): Maybe<ValueFor<R>>;
    <T, R extends AnyMaybe>(elseFn: () => R): (
        maybe: Maybe<T>
    ) => Maybe<ValueFor<R>>;
};

• Like , but using a function to construct the alternative .

  Sometimes you need to perform an operation using other data in the environment to construct the fallback value. In these situations, you can pass a function (which may be a closure) as the elseFn to generate the fallback Maybe<T>.

  Useful for transforming empty scenarios based on values in context.

  T The type of the wrapped value.

  Parameter elseFn

  The function to apply if maybe is Nothing

  Parameter maybe

  The maybe to use if it is Just.

  Returns

  The maybe if it is Just, or the Maybe returned by elseFn if the maybe is Nothing.

function property

property: {
    <T, K extends keyof T>(key: K, obj: T): Maybe<NonNullable<T[K]>>;
    <T, K extends keyof T>(key: K): (obj: T) => Maybe<NonNullable<T[K]>>;
};

• Safely extract a key from an object, returning if the key has a value on the object and if it does not.

  The check is type-safe: you won't even be able to compile if you try to look up a property that TypeScript *knows* doesn't exist on the object.

  ```ts type Person = { name?: string };

  const me: Person = { name: 'Chris' }; console.log(Maybe.property('name', me)); // Just('Chris')

  const nobody: Person = {}; console.log(Maybe.property('name', nobody)); // Nothing ```

  However, it also works correctly with dictionary types:

  ```ts import * as maybe from 'true-myth/maybe';

  type Dict = { [key: string]: T };

  const score: Dict = { player1: 0, player2: 1 };

  console.log(maybe.property('player1', score)); // Just(0) console.log(maybe.property('player2', score)); // Just(1) console.log(maybe.property('player3', score)); // Nothing ```

  The order of keys is so that it can be partially applied:

  ```ts type Person = { name?: string };

  const lookupName = maybe.property('name');

  const me: Person = { name: 'Chris' }; console.log(lookupName(me)); // Just('Chris')

  const nobody: Person = {}; console.log(lookupName(nobody)); // Nothing ```

  Parameter key

  The key to pull out of the object.

  Parameter obj

  The object to look up the key from.

function safe

safe: <
    F extends AnyFunction,
    P extends Parameters<F>,
    R extends NonNullable<ReturnType<F>>
>(
    fn: F
) => (...params: P) => Maybe<R>;

• Transform a function from a normal JS function which may return null or undefined to a function which returns a instead.

  For example, dealing with the Document#querySelector DOM API involves a lot* of things which can be null:

  ```ts const foo = document.querySelector('#foo'); let width: number; if (foo !== null) { width = foo.getBoundingClientRect().width; } else { width = 0; }

  const getStyle = (el: HTMLElement, rule: string) => el.style[rule]; const bar = document.querySelector('.bar'); let color: string; if (bar != null) { let possibleColor = getStyle(bar, 'color'); if (possibleColor !== null) { color = possibleColor; } else { color = 'black'; } } ```

  (Imagine in this example that there were more than two options: the simplifying workarounds you commonly use to make this terser in JS, like the ternary operator or the short-circuiting || or ?? operators, eventually become very confusing with more complicated flows.)

  We can work around this with Maybe, always wrapping each layer in invocations, and this is *somewhat* better:

  ```ts import Maybe from 'true-myth/maybe';

  const aWidth = Maybe.of(document.querySelector('#foo')) .map(el => el.getBoundingClientRect().width) .unwrapOr(0);

  const aColor = Maybe.of(document.querySelector('.bar')) .andThen(el => Maybe.of(getStyle(el, 'color')) .unwrapOr('black'); ```

  With safe, though, you can create a transformed version of a function once* and then be able to use it freely throughout your codebase, *always* getting back a Maybe:

  ```ts import { safe } from 'true-myth/maybe';

  const querySelector = safe(document.querySelector.bind(document)); const safelyGetStyle = safe(getStyle);

  const aWidth = querySelector('#foo') .map(el => el.getBoundingClientRect().width) .unwrapOr(0);

  const aColor = querySelector('.bar') .andThen(el => safelyGetStyle(el, 'color')) .unwrapOr('black'); ```

  Parameter fn

  The function to transform; the resulting function will have the exact same signature except for its return type.

function toJSON

toJSON: <T>(maybe: Maybe<T>) => MaybeJSON<unknown>;

• Create an Object representation of a instance.

  Useful for serialization. JSON.stringify() uses it.

  Parameter maybe

  The value to convert to JSON

  Returns

  The JSON representation of the Maybe

function toString

toString: <T>(maybe: Maybe<T>) => string;

• Create a String representation of a instance.

  A instance will be Just(<representation of the value>), where the representation of the value is simply the value's own toString representation. For example:

  | call | output | |----------------------------------------|-------------------------| | toString(Maybe.of(42)) | Just(42) | | toString(Maybe.of([1, 2, 3])) | Just(1,2,3) | | toString(Maybe.of({ an: 'object' })) | Just([object Object]) | | toString(Maybe.nothing()) | Nothing |

  T The type of the wrapped value; its own .toString will be used to print the interior contents of the Just variant.

  Parameter maybe

  The value to convert to a string.

  Returns

  The string representation of the Maybe.

function transposeArray

transposeArray: () => any;

• Given an array or tuple of s, return a Maybe of the array or tuple values.

  - Given an array of type Array<Maybe<A> | Maybe<B>>, the resulting type is Maybe<Array<A | B>>. - Given a tuple of type [Maybe<A>, Maybe<B>], the resulting type is Maybe<[A, B]>.

  If any of the items in the array or tuple are , the whole result is Nothing. If all items in the array or tuple are , the whole result is Just.

  ## Examples

  Given an array with a mix of Maybe types in it, both allJust and mixed here will have the type Maybe<Array<string | number>>, but will be Just and Nothing respectively.

  ```ts import Maybe, { transposeArray } from 'true-myth/maybe';

  let valid = [Maybe.just(2), Maybe.just('three')]; let allJust = transposeArray(valid); // => Just([2, 'three']);

  let invalid = [Maybe.just(2), Maybe.nothing()]; let mixed = transposeArray(invalid); // => Nothing ```

  When working with a tuple type, the structure of the tuple is preserved. Here, for example, result has the type Maybe<[string, number]> and will be Nothing:

  ```ts import Maybe, { transposeArray } from 'true-myth/maybe';

  type Tuple = [Maybe, Maybe];

  let invalid: Tuple = [Maybe.just('wat'), Maybe.nothing()]; let result = transposeArray(invalid); // => Nothing ```

  If all of the items in the tuple are Just, the result is Just wrapping the tuple of the values of the items. Here, for example, result again has the type Maybe<[string, number]> and will be Just(['hey', 12]:

  ```ts import Maybe, { transposeArray } from 'true-myth/maybe';

  type Tuple = [Maybe, Maybe];

  let valid: Tuple = [Maybe.just('hey'), Maybe.just(12)]; let result = transposeArray(valid); // => Just(['hey', 12]) ```

  Parameter maybes

  The Maybes to resolve to a single Maybe.

function unwrapOr

unwrapOr: {
    <T, U>(defaultValue: U, maybe: Maybe<T>): T | U;
    <T, U>(defaultValue: U): (maybe: Maybe<T>) => T | U;
};

• Safely get the value out of a .

  Returns the content of a or defaultValue if . This is the recommended way to get a value out of a Maybe most of the time.

  ```ts import Maybe from 'true-myth/maybe';

  const notAString = Maybe.nothing(); const isAString = Maybe.just('look ma! some characters!');

  console.log(Maybe.unwrapOr('', notAString)); // "" console.log(Maybe.unwrapOr('', isAString)); // "look ma! some characters!" ```

  T The type of the wrapped value.

  Parameter defaultValue

  The value to return if maybe is a Nothing.

  Parameter maybe

  The Maybe instance to unwrap if it is a Just.

  Returns

  The content of maybe if it is a Just, otherwise defaultValue.

function unwrapOrElse

unwrapOrElse: {
    <T, U>(orElseFn: () => U, maybe: Maybe<T>): T | U;
    <T, U>(orElseFn: () => U): (maybe: Maybe<T>) => T | U;
};

• Safely get the value out of a by returning the wrapped value if it is , or by applying orElseFn if it is .

  This is useful when you need to *generate* a value (e.g. by using current values in the environment – whether preloaded or by local closure) instead of having a single default value available (as in ).

  ```ts import Maybe from 'true-myth/maybe';

  // You can imagine that someOtherValue might be dynamic. const someOtherValue = 99; const handleNothing = () => someOtherValue;

  const aJust = Maybe.just(42); console.log(Maybe.unwrapOrElse(handleNothing, aJust)); // 42

  const aNothing = nothing(); console.log(Maybe.unwrapOrElse(handleNothing, aNothing)); // 99 ```

  T The wrapped value.

  Parameter orElseFn

  A function used to generate a valid value if maybe is a Nothing.

  Parameter maybe

  The Maybe instance to unwrap if it is a Just

  Returns

  Either the content of maybe or the value returned from orElseFn.

type AnyArray

type AnyArray<T> = Array<T> | ReadonlyArray<T>;

• An array or a readonly array.

type AnyMaybe

type AnyMaybe = Maybe<{}>;

• A convenient way to name Maybe<{}>.

type Matcher

type Matcher<T, A> = {
    Just: (value: T) => A;
    Nothing: () => A;
};

• A lightweight object defining how to handle each variant of a .

type Maybe

type Maybe<T> = Just<T> | Nothing<T>;

• Maybe represents a value which may () or may not () be present.

type MaybeJSON

type MaybeJSON<T> = JustJSON<T> | NothingJSON;

type NarrowingPredicate

type NarrowingPredicate<T, U extends T> = (
    element: T,
    index: number,
    array: AnyArray<T>
) => element is U;

type Predicate

type Predicate<T> = (element: T, index: number, array: AnyArray<T>) => boolean;

type TransposedArray

type TransposedArray<T extends ReadonlyArray<Maybe<unknown>>> =
    Array<unknown> extends T
        ? Maybe<{
              -readonly [K in keyof T]: Unwrapped<T[K]>;
          }>
        : Maybe<{
              [K in keyof T]: Unwrapped<T[K]>;
          }>;

type Unwrapped

type Unwrapped<T> = T extends Maybe<infer U> ? U : T;

type Variant

type Variant = keyof typeof Variant;

variable err

const err: {
    <T = never, E = unknown>(): Result<T, Unit>;
    <T = never, E = unknown>(error: E): Result<T, E>;
};

• Create an instance of .

  If you need to create an instance with a specific type (as you do whenever you are not constructing immediately for a function return or as an argument to a function), you can use a type parameter:

  ```ts const notString = Result.err<number, string>('something went wrong'); ```

  Note: passing nothing, or passing null or undefined explicitly, will produce a Result<T, Unit>, rather than producing the nonsensical and in practice quite annoying Result<null, string> etc. See for more.

  ```ts const normalResult = Result.err<number, string>('oh no'); const explicitUnit = Result.err<number, Unit>(Unit); const implicitUnit = Result.err<number, Unit>(); ```

  In the context of an immediate function return, or an arrow function with a single expression value, you do not have to specify the types, so this can be quite convenient.

  ```ts type SomeData = { //... };

  const isValid = (data: SomeData): boolean => { // true or false... }

  const arrowValidate = (data: SomeData): Result<number, Unit> => isValid(data) ? Result.ok(42) : Result.err();

  function fnValidate(data: someData): Result<number, Unit> { return isValid(data) ? Result.ok(42) : Result.err(); } ```

  T The type of the item contained in the Result.

  Parameter E

  The error value to wrap in a Result.Err.

variable IsResult

const IsResult: Symbol;

variable ok

const ok: { (): Result<Unit, never>; <T, E = never>(value: T): Result<T, E> };

• Create an instance of .

  If you need to create an instance with a specific type (as you do whenever you are not constructing immediately for a function return or as an argument to a function), you can use a type parameter:

  ```ts const yayNumber = Result.ok<number, string>(12); ```

  Note: passing nothing, or passing null or undefined explicitly, will produce a Result<Unit, E>, rather than producing the nonsensical and in practice quite annoying Result<null, string> etc. See for more.

  ```ts const normalResult = Result.ok<number, string>(42); const explicitUnit = Result.ok<Unit, string>(Unit); const implicitUnit = Result.ok<Unit, string>(); ```

  In the context of an immediate function return, or an arrow function with a single expression value, you do not have to specify the types, so this can be quite convenient.

  ```ts type SomeData = { //... };

  const isValid = (data: SomeData): boolean => { // true or false... }

  const arrowValidate = (data: SomeData): Result<Unit, string> => isValid(data) ? Result.ok() : Result.err('something was wrong!');

  function fnValidate(data: someData): Result<Unit, string> { return isValid(data) ? Result.ok() : Result.err('something was wrong'); } ```

  T The type of the item contained in the Result.

  Parameter value

  The value to wrap in a Result.Ok.

variable Result

const Result: ResultConstructor;

• A Result represents success () or failure ().

  The behavior of this type is checked by TypeScript at compile time, and bears no runtime overhead other than the very small cost of the container object.

variable Variant

const Variant: { readonly Ok: 'Ok'; readonly Err: 'Err' };

• Discriminant for and variants of the type.

  You can use the discriminant via the variant property of Result instances if you need to match explicitly on it.

function and

and: {
    <T, U, E>(andResult: Result<U, E>, result: Result<T, E>): Result<U, E>;
    <T, U, E>(andResult: Result<U, E>): (result: Result<T, E>) => Result<U, E>;
};

• You can think of this like a short-circuiting logical "and" operation on a type. If result is , then the result is the andResult. If result is , the result is the Err.

  This is useful when you have another Result value you want to provide if and only if* you have an Ok – that is, when you need to make sure that if you Err, whatever else you're handing a Result to *also* gets that Err.

  Notice that, unlike in [map](#map) or its variants, the original result is not involved in constructing the new Result.

  #### Examples

  ```ts import { and, ok, err, toString } from 'true-myth/result';

  const okA = ok('A'); const okB = ok('B'); const anErr = err({ so: 'bad' });

  console.log(toString(and(okB, okA))); // Ok(B) console.log(toString(and(okB, anErr))); // Err([object Object]) console.log(toString(and(anErr, okA))); // Err([object Object]) console.log(toString(and(anErr, anErr))); // Err([object Object]) ```

  T The type of the value wrapped in the Ok of the Result. U The type of the value wrapped in the Ok of the andResult, i.e. the success type of the Result present if the checked Result is Ok. E The type of the value wrapped in the Err of the Result.

  Parameter andResult

  The Result instance to return if result is Err.

  Parameter result

  The Result instance to check.

function andThen

andThen: {
    <T, E, R extends AnyResult>(thenFn: (t: T) => R, result: Result<T, E>): Result<
        OkFor<R>,
        E | ErrFor<R>
    >;
    <T, E, R extends AnyResult>(thenFn: (t: T) => R): (
        result: Result<T, E>
    ) => Result<OkFor<R>, E | ErrFor<R>>;
};

• Apply a function to the wrapped value if and return a new Ok containing the resulting value; or if it is return it unmodified.

  This differs from map in that thenFn returns another . You can use andThen to combine two functions which *both* create a Result from an unwrapped type.

  You may find the .then method on an ES6 Promise helpful for comparison: if you have a Promise, you can pass its then method a callback which returns another Promise, and the result will not be a *nested* promise, but a single Promise. The difference is that Promise#then unwraps *all* layers to only ever return a single Promise value, whereas Result.andThen will not unwrap nested Results.

  > [!NOTE] This is is sometimes also known as bind, but *not* aliased as such > because [bind already means something in JavaScript][bind].

  [bind]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind

  #### Examples

  ```ts import { ok, err, andThen, toString } from 'true-myth/result';

  const toLengthAsResult = (s: string) => ok(s.length);

  const anOk = ok('just a string'); const lengthAsResult = andThen(toLengthAsResult, anOk); console.log(toString(lengthAsResult)); // Ok(13)

  const anErr = err(['srsly', 'whatever']); const notLengthAsResult = andThen(toLengthAsResult, anErr); console.log(toString(notLengthAsResult)); // Err(srsly,whatever) ```

  T The type of the value wrapped in the Ok of the Result. U The type of the value wrapped in the Ok of the Result returned by the thenFn. E The type of the value wrapped in the Err of the Result.

  Parameter thenFn

  The function to apply to the wrapped T if maybe is Just.

  Parameter result

  The Maybe to evaluate and possibly apply a function to.

function ap

ap: {
    <A, B, E>(resultFn: Result<(a: A) => B, E>, result: Result<A, E>): Result<B, E>;
    <A, B, E>(resultFn: Result<(a: A) => B, E>): (
        result: Result<A, E>
    ) => Result<B, E>;
};

• Allows you to *apply* (thus ap) a value to a function without having to take either out of the context of their s. This does mean that the transforming function is itself within a Result, which can be hard to grok at first but lets you do some very elegant things. For example, ap allows you to do this (using the method form, since nesting ap calls is awkward):

  ```ts import { ap, ok, err } from 'true-myth/result';

  const one = ok<number, string>(1); const five = ok<number, string>(5); const whoops = err<number, string>('oh no');

  const add = (a: number) => (b: number) => a + b; const resultAdd = ok<typeof add, string>(add);

  resultAdd.ap(one).ap(five); // Ok(6) resultAdd.ap(one).ap(whoops); // Err('oh no') resultAdd.ap(whoops).ap(five) // Err('oh no') ```

  Without ap, you'd need to do something like a nested match:

  ```ts import { ok, err } from 'true-myth/result';

  const one = ok<number, string>(1); const five = ok<number, string>(5); const whoops = err<number, string>('oh no');

  one.match({ Ok: n => five.match({ Ok: o => ok<number, string>(n + o), Err: e => err<number, string>(e), }), Err: e => err<number, string>(e), }); // Ok(6)

  one.match({ Ok: n => whoops.match({ Ok: o => ok<number, string>(n + o), Err: e => err<number, string>(e), }), Err: e => err<number, string>(e), }); // Err('oh no')

  whoops.match({ Ok: n => five.match({ Ok: o => ok(n + o), Err: e => err(e), }), Err: e => err(e), }); // Err('oh no') ```

  And this kind of thing comes up quite often once you're using Result to handle errors throughout your application.

  For another example, imagine you need to compare the equality of two ImmutableJS data structures, where a === comparison won't work. With ap, that's as simple as this:

  ```ts import { ok } from 'true-myth/result'; import { is as immutableIs, Set } from 'immutable';

  const is = (first: unknown) => (second: unknown) => immutableIs(first, second);

  const x = ok(Set.of(1, 2, 3)); const y = ok(Set.of(2, 3, 4));

  ok(is).ap(x).ap(y); // Ok(false) ```

  Without ap, we're back to that gnarly nested match:

  ```ts import Result, { ok, err } from 'true-myth/result'; import { is, Set } from 'immutable';

  const x = ok(Set.of(1, 2, 3)); const y = ok(Set.of(2, 3, 4));

  x.match({ Ok: iX => y.match({ Ok: iY => Result.of(is(iX, iY)), Err: (e) => ok(false), }) Err: (e) => ok(false), }); // Ok(false) ```

  In summary: anywhere you have two Result instances and need to perform an operation that uses both of them, ap is your friend.

  Two things to note, both regarding *currying*:

  1. All functions passed to ap must be curried. That is, they must be of the form (for add) (a: number) => (b: number) => a + b, *not* the more usual (a: number, b: number) => a + b you see in JavaScript more generally.

  (Unfortunately, these do not currently work with lodash or Ramda's curry helper functions. A future update to the type definitions may make that work, but the intermediate types produced by those helpers and the more general function types expected by this function do not currently align.)

  2. You will need to call ap as many times as there are arguments to the function you're dealing with. So in the case of this add3 function, which has the "arity" (function argument count) of 3 (a and b), you'll need to call ap twice: once for a, and once for b. To see why, let's look at what the result in each phase is:

  ```ts const add3 = (a: number) => (b: number) => (c: number) => a + b + c;

  const resultAdd = ok(add); // Ok((a: number) => (b: number) => (c: number) => a + b + c) const resultAdd1 = resultAdd.ap(ok(1)); // Ok((b: number) => (c: number) => 1 + b + c) const resultAdd1And2 = resultAdd1.ap(ok(2)) // Ok((c: number) => 1 + 2 + c) const final = maybeAdd1.ap(ok(3)); // Ok(4) ```

  So for toString, which just takes a single argument, you would only need to call ap once.

  ```ts const toStr = (v: { toString(): string }) => v.toString(); ok(toStr).ap(12); // Ok("12") ```

  One other scenario which doesn't come up *quite* as often but is conceivable is where you have something that may or may not actually construct a function for handling a specific Result scenario. In that case, you can wrap the possibly-present in ap and then wrap the values to apply to the function to in Result themselves.

  Because Result often requires you to type out the full type parameterization on a regular basis, it's convenient to use TypeScript's typeof operator to write out the type of a curried function. For example, if you had a function that simply merged three strings, you might write it like this:

  ```ts import Result from 'true-myth/result'; import { curry } from 'lodash';

  const merge3Strs = (a: string, b: string, c: string) => string; const curriedMerge = curry(merge3Strs);

  const fn = Result.ok<typeof curriedMerge, string>(curriedMerge); ```

  The alternative is writing out the full signature long-form:

  ```ts const fn = Result.ok<(a: string) => (b: string) => (c: string) => string, string>(curriedMerge); ```

  *Aside:** ap is not named apply because of the overlap with JavaScript's existing [apply] function – and although strictly speaking, there isn't any direct overlap (Result.apply and Function.prototype.apply don't intersect at all) it's useful to have a different name to avoid implying that they're the same.

  [apply]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/apply

  Parameter resultFn

  result of a function from T to U

  Parameter result

  result of a T to apply to fn

function equals

equals: {
    <T, E>(resultB: Result<T, E>, resultA: Result<T, E>): boolean;
    <T, E>(resultB: Result<T, E>): (resultA: Result<T, E>) => boolean;
};

• Allows quick triple-equal equality check between the values inside two s without having to unwrap them first.

  ```ts const a = Result.of(3) const b = Result.of(3) const c = Result.of(null) const d = Result.nothing()

  Result.equals(a, b) // true Result.equals(a, c) // false Result.equals(c, d) // true ```

  Parameter resultB

  A maybe to compare to.

  Parameter resultA

  A maybe instance to check.

function isErr

isErr: <T, E>(result: Result<T, E>) => result is Err<T, E>;

• Is the an ?

  T The type of the item contained in the Result.

  Parameter result

  The Result to check.

  Returns

  A type guarded Err.

function isInstance

isInstance: <T, E>(item: unknown) => item is Result<T, E>;

• Determine whether an item is an instance of .

  Parameter item

  The item to check.

function isOk

isOk: <T, E>(result: Result<T, E>) => result is Ok<T, E>;

• Is the an ?

  T The type of the item contained in the Result.

  Parameter result

  The Result to check.

  Returns

  A type guarded Ok.

function map

map: {
    <T, U, E>(mapFn: (t: T) => U, result: Result<T, E>): Result<U, E>;
    <T, U, E>(mapFn: (t: T) => U): (result: Result<T, E>) => Result<U, E>;
};

• Map over a instance: apply the function to the wrapped value if the instance is , and return the wrapped error value wrapped as a new of the correct type (Result<U, E>) if the instance is Err.

  map works a lot like Array.prototype.map, but with one important difference. Both Result and Array are containers for other kinds of items, but where Array.prototype.map has 0 to _n_ items, a Result always has exactly one item, which is *either* a success or an error instance.

  Where Array.prototype.map will apply the mapping function to every item in the array (if there are any), Result.map will only apply the mapping function to the (single) element if an Ok instance, if there is one.

  If you have no items in an array of numbers named foo and call `foo.map(x => x + 1)`, you'll still some have an array with nothing in it. But if you have any items in the array ([2, 3]), and you call foo.map(x => x + 1) on it, you'll get a new array with each of those items inside the array "container" transformed ([3, 4]).

  With this map, the Err variant is treated *by the map function* kind of the same way as the empty array case: it's just ignored, and you get back a new Result that is still just the same Err instance. But if you have an Ok variant, the map function is applied to it, and you get back a new Result with the value transformed, and still wrapped in an Ok.

  #### Examples

  ```ts import { ok, err, map, toString } from 'true-myth/result'; const double = n => n * 2;

  const anOk = ok(12); const mappedOk = map(double, anOk); console.log(toString(mappedOk)); // Ok(24)

  const anErr = err("nothing here!"); const mappedErr = map(double, anErr); console.log(toString(mappedErr)); // Err(nothing here!) ```

  T The type of the value wrapped in an Ok instance, and taken as the argument to the mapFn. U The type of the value wrapped in the new Ok instance after applying mapFn, that is, the type returned by mapFn. E The type of the value wrapped in an Err instance.

  Parameter mapFn

  The function to apply the value to if result is Ok.

  Parameter result

  The Result instance to map over.

  Returns

  A new Result with the result of applying mapFn to the value in an Ok, or else the original Err value wrapped in the new instance.

function mapErr

mapErr: {
    <T, E, F>(mapErrFn: (e: E) => F, result: Result<T, E>): Result<T, F>;
    <T, E, F>(mapErrFn: (e: E) => F): (result: Result<T, E>) => Result<T, F>;
};

• Map over a , exactly as in , but operating on the value wrapped in an instead of the value wrapped in the . This is handy for when you need to line up a bunch of different types of errors, or if you need an error of one shape to be in a different shape to use somewhere else in your codebase.

  #### Examples

  ```ts import { ok, err, mapErr, toString } from 'true-myth/result';

  const reason = (err: { code: number, reason: string }) => err.reason;

  const anOk = ok(12); const mappedOk = mapErr(reason, anOk); console.log(toString(mappedOk)); // Ok(12)

  const anErr = err({ code: 101, reason: 'bad file' }); const mappedErr = mapErr(reason, anErr); console.log(toString(mappedErr)); // Err(bad file) ```

  T The type of the value wrapped in the Ok of the Result. E The type of the value wrapped in the Err of the Result. F The type of the value wrapped in the Err of a new Result, returned by the mapErrFn.

  Parameter mapErrFn

  The function to apply to the value wrapped in Err if result is an Err.

  Parameter result

  The Result instance to map over an error case for.

function mapOr

mapOr: {
    <T, U, E>(orU: U, mapFn: (t: T) => U, result: Result<T, E>): U;
    <T, U, E>(orU: U, mapFn: (t: T) => U): (result: Result<T, E>) => U;
    <T, U, E>(orU: U): (mapFn: (t: T) => U) => (result: Result<T, E>) => U;
};

• Map over a instance as in [map](#map) and get out the value if result is an , or return a default value if result is an .

  #### Examples

  ```ts import { ok, err, mapOr } from 'true-myth/result';

  const length = (s: string) => s.length;

  const anOkString = ok('a string'); const theStringLength = mapOr(0, length, anOkString); console.log(theStringLength); // 8

  const anErr = err('uh oh'); const anErrMapped = mapOr(0, length, anErr); console.log(anErrMapped); // 0 ```

  Parameter orU

  The default value to use if result is an Err.

  Parameter mapFn

  The function to apply the value to if result is an Ok.

  Parameter result

  The Result instance to map over.

function mapOrElse

mapOrElse: {
    <T, U, E>(orElseFn: (err: E) => U, mapFn: (t: T) => U, result: Result<T, E>): U;
    <T, U, E>(orElseFn: (err: E) => U, mapFn: (t: T) => U): (
        result: Result<T, E>
    ) => U;
    <T, U, E>(orElseFn: (err: E) => U): (
        mapFn: (t: T) => U
    ) => (result: Result<T, E>) => U;
};

• Map over a instance as in and get out the value if result is , or apply a function (orElseFn) to the value wrapped in the to get a default value.

  Like but using a function to transform the error into a usable value instead of simply using a default value.

  #### Examples

  ```ts import { ok, err, mapOrElse } from 'true-myth/result';

  const summarize = (s: string) => The response was: '${s}'; const getReason = (err: { code: number, reason: string }) => err.reason;

  const okResponse = ok("Things are grand here."); const mappedOkAndUnwrapped = mapOrElse(getReason, summarize, okResponse); console.log(mappedOkAndUnwrapped); // The response was: 'Things are grand here.'

  const errResponse = err({ code: 500, reason: 'Nothing at this endpoint!' }); const mappedErrAndUnwrapped = mapOrElse(getReason, summarize, errResponse); console.log(mappedErrAndUnwrapped); // Nothing at this endpoint! ```

  T The type of the wrapped Ok value. U The type of the resulting value from applying mapFn to the Ok value or orElseFn to the Err value. E The type of the wrapped Err value.

  Parameter orElseFn

  The function to apply to the wrapped Err value to get a usable value if result is an Err.

  Parameter mapFn

  The function to apply to the wrapped Ok value if result is an Ok.

  Parameter result

  The Result instance to map over.

function match

match: {
    <T, E, A>(matcher: Matcher<T, E, A>, result: Result<T, E>): A;
    <T, E, A>(matcher: Matcher<T, E, A>): (result: Result<T, E>) => A;
};

• Performs the same basic functionality as , but instead of simply unwrapping the value if it is and applying a value to generate the same default type if it is , lets you supply functions which may transform the wrapped type if it is Ok or get a default value for Err.

  This is kind of like a poor man's version of pattern matching, which JavaScript currently lacks.

  Instead of code like this:

  ```ts import Result, { isOk, match } from 'true-myth/result';

  const logValue = (mightBeANumber: Result<number, string>) => { console.log( mightBeANumber.isOk ? mightBeANumber.value.toString() : There was an error: ${unsafelyGetErr(mightBeANumber)} ); }; ```

  ...we can write code like this:

  ```ts import Result, { match } from 'true-myth/result';

  const logValue = (mightBeANumber: Result<number, string>) => { const value = match( { Ok: n => n.toString(), Err: e => There was an error: ${e}, }, mightBeANumber ); console.log(value); }; ```

  This is slightly longer to write, but clearer: the more complex the resulting expression, the hairer it is to understand the ternary. Thus, this is especially convenient for times when there is a complex result, e.g. when rendering part of a React component inline in JSX/TSX.

  Parameter matcher

  A lightweight object defining what to do in the case of each variant.

  Parameter result

  The result instance to check.

• Performs the same basic functionality as , but instead of simply unwrapping the value if it is and applying a value to generate the same default type if it is , lets you supply functions which may transform the wrapped type if it is Ok or get a default value for Err.

  This is kind of like a poor man's version of pattern matching, which JavaScript currently lacks.

  Instead of code like this:

  ```ts import Result, { isOk, match } from 'true-myth/result';

  const logValue = (mightBeANumber: Result<number, string>) => { console.log( mightBeANumber.isOk ? mightBeANumber.value.toString() : There was an error: ${unsafelyGetErr(mightBeANumber)} ); }; ```

  ...we can write code like this:

  ```ts import Result, { match } from 'true-myth/result';

  const logValue = (mightBeANumber: Result<number, string>) => { const value = match( { Ok: n => n.toString(), Err: e => There was an error: ${e}, }, mightBeANumber ); console.log(value); }; ```

  This is slightly longer to write, but clearer: the more complex the resulting expression, the hairer it is to understand the ternary. Thus, this is especially convenient for times when there is a complex result, e.g. when rendering part of a React component inline in JSX/TSX.

  Parameter matcher

  A lightweight object defining what to do in the case of each variant.

function or

or: {
    <T, E, F>(defaultResult: Result<T, F>, result: Result<T, E>): Result<T, F>;
    <T, E, F>(defaultResult: Result<T, F>): (result: Result<T, E>) => Result<T, F>;
};

• Provide a fallback for a given . Behaves like a logical or: if the result value is an , returns that result; otherwise, returns the defaultResult value.

  This is useful when you want to make sure that something which takes a Result always ends up getting an Ok variant, by supplying a default value for the case that you currently have an .

  ```ts import { ok, err, Result, or } from 'true-utils/result';

  const okA = ok<string, string>('a'); const okB = ok<string, string>('b'); const anErr = err<string, string>(':wat:'); const anotherErr = err<string, string>(':headdesk:');

  console.log(or(okB, okA).toString()); // Ok(A) console.log(or(anErr, okA).toString()); // Ok(A) console.log(or(okB, anErr).toString()); // Ok(B) console.log(or(anotherErr, anErr).toString()); // Err(:headdesk:) ```

  T The type wrapped in the Ok case of result. E The type wrapped in the Err case of result. F The type wrapped in the Err case of defaultResult.

  Parameter defaultResult

  The Result to use if result is an Err.

  Parameter result

  The Result instance to check.

  Returns

  result if it is an Ok, otherwise defaultResult.