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 extends {}>(_?: 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>;
    (value: unknown): Maybe<{}>;
};

• 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 extends {}, U extends {}>(andMaybe: Maybe<U>, maybe: Maybe<T>): Maybe<U>;
    <T extends {}, U extends {}>(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.

  ```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 extends {}, U extends {}>(
        thenFn: (t: T) => Maybe<U>,
        maybe: Maybe<T>
    ): Maybe<U>;
    <T extends {}, R extends AnyMaybe>(thenFn: (t: T) => R, maybe: Maybe<T>): Maybe<
        ValueFor<R>
    >;
    <T extends {}, U extends {}>(thenFn: (t: T) => Maybe<U>): (
        maybe: Maybe<T>
    ) => Maybe<U>;
    <T extends {}, 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 extends {}, U extends {}>(
        maybeFn: Maybe<(t: T) => U>,
        maybe: Maybe<T>
    ): Maybe<T | U>;
    <T extends {}, 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 extends {}>(mb: Maybe<T>, ma: Maybe<T>): boolean;
    <T extends {}>(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 extends {}, U extends T>(
        predicate: NarrowingPredicate<T, U>,
        array: AnyArray<T>
    ): Maybe<U>;
    <T extends {}, U extends T>(predicate: NarrowingPredicate<T, U>): (
        array: AnyArray<T>
    ) => Maybe<U>;
    <T extends {}>(predicate: Predicate<T>, array: AnyArray<T>): Maybe<T>;
    <T extends {}>(predicate: Predicate<T>): (array: AnyArray<T>) => Maybe<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) ```

  > [!NOTE] > 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 flatten

flatten: <T extends {}>(nested: Maybe<Maybe<T>>) => Maybe<T>;

• Given a nested Maybe, remove one layer of nesting.

  For example, given a Maybe<Maybe<string>>, the resulting type after using this function will be Maybe<string>.

  ## Note

  This function only works when the value wrapped in Maybe is another Maybe. If you have a Maybe<string> or Maybe<number>, this function won't work. If you have a Maybe<Maybe<string>>, then you can call maybe.flatten(theMaybe) to get back a Maybe<string>.

  ## Examples

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

  const nested = maybe.just(maybe.just('hello')); const flattened = maybe.flatten(nested); // Maybe console.log(flattened); // Just('hello')

  const nestedNothing = maybe.just(maybe.nothing()); const flattenedNothing = maybe.flatten(nestedNothing); // Maybe console.log(flattenedNothing); // Nothing

  const nothingNested = maybe.nothing<Maybe>(); const flattenedOuter = maybe.flatten(nothingNested); // Maybe console.log(flattenedOuter); // Nothing ```

function fromJSON

fromJSON: <T extends {}>(json: MaybeJSON<T>) => Maybe<T>;

• Given a object, convert it into a .

  Note that this is not designed for parsing data off the wire, but requires you to have *already* parsed it into the format.

  Parameter json

  The value to convert to JSON

  Returns

  The JSON representation of the Maybe

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 inspect

inspect: {
    <T extends {}>(fn: (value: T) => void, maybe: Maybe<T>): Maybe<T>;
    <T extends {}>(fn: (value: T) => void): (maybe: Maybe<T>) => Maybe<T>;
};

• Run a side effect with the wrapped value without modifying the .

  This is useful for performing actions like logging, debugging, or other “side effects” external to the wrapped value. (**Note:** You should *never* mutate the value in the callback. Doing so will be extremely surprising to callers.) The function is only called if the Maybe is a , and the original Maybe is returned unchanged for further operations.

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

  const log = (value: unknown) => console.log(value); const double = (value: number) => value * 2;

  // Logs 42 then 84, and returns Just(84). const aJust = maybe.just(42); maybe.inspect( maybe.map( double, maybe.inspect( log, aJust ) ) );

  // Does not log anything, and returns Nothing. const aNothing = maybe.nothing(); maybe.inspect( maybe.map( double, maybe.inspect( log, aNothing ) ) ); ```

  T The type of the wrapped value

  Parameter fn

  The function to call with the wrapped value (only called for Just)

  Parameter maybe

  The Maybe to inspect

  Returns

  The original Maybe, unchanged

function isInstance

isInstance: {
    <T extends {}>(item: Maybe<T>): item is Maybe<T>;
    (item: unknown): item is Maybe<{}>;
};

• Determine whether an item is an instance of .

  Parameter item

  The item to check.

function isJust

isJust: <T extends {}>(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 extends {}>(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) ```

  > [!NOTE] > 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 extends {}, U extends {}>(mapFn: (t: T) => U): (maybe: Maybe<T>) => Maybe<U>;
    <T extends {}, 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.)

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

  ```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 extends {}, U extends {}>(orU: U, mapFn: (t: T) => U, maybe: Maybe<T>): U;
    <T extends {}, U extends {}>(orU: U, mapFn: (t: T) => U): (maybe: Maybe<T>) => U;
    <T extends {}, U extends {}>(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 .

  ```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 extends {}, U extends {}>(
        orElseFn: () => U,
        mapFn: (t: T) => U,
        maybe: Maybe<T>
    ): U;
    <T extends {}, U extends {}>(orElseFn: () => U, mapFn: (t: T) => U): (
        maybe: Maybe<T>
    ) => U;
    <T extends {}, U extends {}>(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 .

  ```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 extends {}, A>(matcher: Matcher<T, A>, maybe: Maybe<T>): A;
    <T extends {}, 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 hairier 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 extends {}>(defaultMaybe: Maybe<T>, maybe: Maybe<T>): Maybe<T>;
    <T extends {}>(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 extends {}, R extends AnyMaybe>(elseFn: () => R, maybe: Maybe<T>): Maybe<
        ValueFor<R>
    >;
    <T extends {}, 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 extends {}>(maybe: Maybe<T>) => Serialized<T>;

• 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 extends {}>(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 extends {}, U>(defaultValue: U, maybe: Maybe<T>): T | U;
    <T extends {}, 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 extends {}, U>(orElseFn: () => U, maybe: Maybe<T>): T | U;
    <T extends {}, 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 extends {}> = Just<T> | Nothing<T>;

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

type MaybeJSON

type MaybeJSON<T extends {}> = JustJSON<T> | NothingJSON<T>;

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 Serialized

type Serialized<M extends {}> = M extends Maybe<infer U>
    ? MaybeJSON<Serialized<U>>
    : MaybeJSON<M>;

type TransposedArray

type TransposedArray<T extends ReadonlyArray<Maybe<{}>>> = 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> ? Unwrapped<U> : T;

type Variant

type Variant = keyof typeof Variant;

variable []

const []: any;

variable []

const []: any;

variable []

const []: any;

variable A

const A: any;

variable A

const A: any;

variable A

const A: any;

variable AnyResult

const AnyResult: any;

variable AnyResult

const AnyResult: any;

variable AnyResult

const AnyResult: any;

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 readonly

const readonly: any;

variable readonly

const readonly: any;

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 all

all: (results: readonly []) => Result<[], never>;

• Given an array of results, return a new result if all results are or a new result if some result is .

  ## Examples

  If all results are , return a new result containing an array of all given values:

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

  let result = all([ Result.ok(10), Result.ok(100), Result.ok(1000) ]);

  console.log(result.toString()); // Ok(10,100,1000) ```

  If any result is , return a new result containing the first encountered:

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

  let result = all([ Result.ok(10), Result.ok("something went wrong"), Result.err("something else went wrong") ]);

  console.log(result.toString()); // Err(something went wrong) ```

  Parameter results

  The list of results. A new containing an array of all values if all results are , or a new result containing the first encountered.

  A The type of the array or tuple of results.

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.

  ```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

  ```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 flatten

flatten: <T, E1, E2>(nested: Result<Result<T, E2>, E1>) => Result<T, E1 | E2>;

• Given a nested Result, remove one layer of nesting.

  For example, given a Result<Result<string, E2>, E1>, the resulting type after using this function will be Result<string, E1 | E2>.

  ## Note

  This function only works when the value wrapped in Result is another Result. If you have a Result<string, E> or Result<number, E>, this function won't work. If you have a Result<Result<string, E2>, E1>, then you can call result.flatten(theResult) to get back a Result<string, E1 | E2>.

  ## Examples

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

  const nested = result.ok(result.ok('hello')); const flattened = result.flatten(nested); // Result<string, never> console.log(flattened); // Ok('hello')

  const nestedError = result.ok(result.err('inner error')); const flattenedError = result.flatten(nestedError); // Result<never, string> console.log(flattenedError); // Err('inner error')

  const errorNested = result.err<Result<string, string>, string>('outer error'); const flattenedOuter = result.flatten(errorNested); // Result<string, string> console.log(flattenedOuter); // Err('outer error') ```

function fromJSON

fromJSON: <T, E>(json: ResultJSON<T, E>) => Result<T, E>;

• Given a object, convert it into a .

  Note that this is not designed for parsing data off the wire, but requires you to have *already* parsed it into the format.

  Parameter json

  The value to convert from a JSON object.

  Returns

  {Result<T,E>} The converted Result type.

function inspect

inspect: {
    <T, E>(fn: (value: T) => void, result: Result<T, E>): Result<T, E>;
    <T, E>(fn: (value: T) => void): (result: Result<T, E>) => Result<T, E>;
};