True Myth

Appearance

True Myth / maybe / Maybe

Class: Maybe<T> ​

Maybe represents a value which may (`Just<T>`) or may not (Nothing) be present.

Type Parameters ​

T ​

T extends object

Constructors ​

Constructor ​

new Maybe(value?): Maybe

Parameters ​

value? ​

T | null

Returns ​

Maybe

Properties ​

isJust ​

isJust: boolean

Is the Maybe a Just?

isNothing ​

isNothing: boolean

Is the Maybe a Nothing?

variant ​

readonly variant: "Just" | "Nothing"

Distinguish between the Just and Nothing variants.

just() ​

static just: {<F>(value): Maybe<F>; <T, F>(value): never; <F>(value): never; <T>(value): Maybe<T>; }

Call Signature ​

<F>(value): Maybe<F>

Create an instance of Maybe.Just.

Type Parameters ​
F ​

F extends (...args) => object

Parameters ​
value ​

F

The value to wrap in a Maybe.Just.

Returns ​

Maybe<F>

An instance of Maybe.Just<T>.

Throws ​

If you pass null or undefined.

Call Signature ​

<T, F>(value): never

Create an instance of Maybe.Just.

Type Parameters ​
T ​

T extends object

The type of the item contained in the Maybe.

F ​

F extends (...args) => T | null | undefined

Parameters ​
value ​

F

The value to wrap in a Maybe.Just.

Returns ​

never

An instance of Maybe.Just<T>.

Throws ​

If you pass null or undefined.

Call Signature ​

<F>(value): never

Create an instance of Maybe.Just.

Type Parameters ​
F ​

F extends (...args) => null | undefined

Parameters ​
value ​

F

The value to wrap in a Maybe.Just.

Returns ​

never

An instance of Maybe.Just<T>.

Throws ​

If you pass null or undefined.

Call Signature ​

<T>(value): Maybe<T>

Create an instance of Maybe.Just.

Type Parameters ​
T ​

T extends object

The type of the item contained in the Maybe.

Parameters ​
value ​

T

The value to wrap in a Maybe.Just.

Returns ​

Maybe<T>

An instance of Maybe.Just<T>.

Throws ​

If you pass null or undefined.

nothing() ​

static nothing: <T>(_?) => Nothing<T>

Create an instance of Maybe.Nothing.

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<string>();

Type Parameters ​

T ​

T extends object

The type of the item contained in the Maybe.

Parameters ​

_? ​

null

Returns ​

Nothing<T>

An instance of Maybe.Nothing<T>.

of() ​

static of: {<F>(value): Maybe<F>; <T, F>(value): never; <F>(value): never; <T>(value): Maybe<T>; (value): Maybe<{ }>; }

Call Signature ​

<F>(value): Maybe<F>

Create a Maybe 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
const foo = Maybe.of<string>(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).
Type Parameters ​
F ​

F extends (...args) => object

Parameters ​
value ​

F

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.

Returns ​

Maybe<F>

Call Signature ​

<T, F>(value): never

Create a Maybe 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
const foo = Maybe.of<string>(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).
Type Parameters ​
T ​

T extends object

The type of the item contained in the Maybe.

F ​

F extends (...args) => T | null | undefined

Parameters ​
value ​

F

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.

Returns ​

never

Call Signature ​

<F>(value): never

Create a Maybe 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
const foo = Maybe.of<string>(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).
Type Parameters ​
F ​

F extends (...args) => null | undefined

Parameters ​
value ​

F

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.

Returns ​

never

Call Signature ​

<T>(value): Maybe<T>

Create a Maybe 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
const foo = Maybe.of<string>(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).
Type Parameters ​
T ​

T extends object

The type of the item contained in the Maybe.

Parameters ​
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.

T | null | undefined

Returns ​

Maybe<T>

Call Signature ​

(value): Maybe<{ }>

Create a Maybe 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
const foo = Maybe.of<string>(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).
Parameters ​
value ​

unknown

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.

Returns ​

Maybe<{ }>

Methods ​

and() ​

and<U>(mAnd): Maybe<U>

Method variant for and

Type Parameters ​

U ​

U extends object

Parameters ​

mAnd ​

Maybe<U>

Returns ​

Maybe<U>

andThen() ​

Call Signature ​

andThen<U>(andThenFn): Maybe<U>

Method variant for andThen

Type Parameters ​
U ​

U extends object

Parameters ​
andThenFn ​

(t) => Maybe<U>

Returns ​

Maybe<U>

Call Signature ​

andThen<R>(andThenFn): Maybe<ValueFor<R>>

Method variant for andThen

Type Parameters ​
R ​

R extends AnyMaybe

Parameters ​
andThenFn ​

(t) => R

Returns ​

Maybe<ValueFor<R>>

ap() ​

ap<A, B>(this, val): Maybe<B>

Method variant for ap

Type Parameters ​

A ​

A extends object

B ​

B extends object

Parameters ​

this ​

Maybe<(val) => B>

val ​

Maybe<A>

Returns ​

Maybe<B>

equals() ​

equals(comparison): boolean

Method variant for equals

Parameters ​

comparison ​

Maybe<T>

Returns ​

boolean

flatten() ​

flatten<A>(this): Maybe<A>

Given a nested Maybe, remove one layer of nesting.

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

Note ​

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

Examples ​

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

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

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

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

Type Parameters ​

A ​

A extends object

Parameters ​

this ​

Maybe<Maybe<A>>

Returns ​

Maybe<A>

get() ​

get<K>(key): Maybe<NonNullable<T[K]>>

Method variant for get

If you have a Maybe of an object type, you can do thatMaybe.get('a key') to look up the next layer down in the object.

ts
type DeepOptionalType = {
  something?: {
    with?: {
      deeperKeys?: string;
    }
  }
};

const fullySet: DeepType = {
  something: {
    with: {
      deeperKeys: 'like this'
    }
  }
};

const deepJust = Maybe.of(fullySet)
  .get('something')
  .get('with')
  .get('deeperKeys');

console.log(deepJust); // Just('like this');

const partiallyUnset: DeepType = { something: { } };

const deepEmpty = Maybe.of(partiallyUnset)
  .get('something')
  .get('with')
  .get('deeperKeys');

console.log(deepEmpty); // Nothing

Type Parameters ​

K ​

K extends string | number | symbol

Parameters ​

key ​

K

Returns ​

Maybe<NonNullable<T[K]>>

map() ​

map<U>(mapFn): Maybe<U>

Method variant for map

Type Parameters ​

U ​

U extends object

Parameters ​

mapFn ​

(t) => U

Returns ​

Maybe<U>

mapOr() ​

mapOr<U>(orU, mapFn): U

Method variant for `mapOr`

Type Parameters ​

U ​

U

Parameters ​

orU ​

U

mapFn ​

(t) => U

Returns ​

U

mapOrElse() ​

mapOrElse<U>(orElseFn, mapFn): U

Method variant for mapOrElse

Type Parameters ​

U ​

U

Parameters ​

orElseFn ​

() => U

mapFn ​

(t) => U

Returns ​

U

match() ​

match<U>(matcher): U

Method variant for match

Type Parameters ​

U ​

U

Parameters ​

matcher ​

Matcher<T, U>

Returns ​

U

or() ​

or(mOr): Maybe<T>

Method variant for or

Parameters ​

mOr ​

Maybe<T>

Returns ​

Maybe<T>

orElse() ​

Call Signature ​

orElse(orElseFn): Maybe<T>

Method variant for orElse

Parameters ​
orElseFn ​

() => Maybe<T>

Returns ​

Maybe<T>

Call Signature ​

orElse<R>(orElseFn): Maybe<ValueFor<R>>

Method variant for orElse

Type Parameters ​
R ​

R extends AnyMaybe

Parameters ​
orElseFn ​

() => R

Returns ​

Maybe<ValueFor<R>>

toJSON() ​

toJSON(): Serialized<T>

Method variant for toJSON

Returns ​

Serialized<T>

toString() ​

toString(): string

Method variant for toString

Returns ​

string

unwrapOr() ​

unwrapOr<U>(defaultValue): T | U

Method variant for unwrapOr

Type Parameters ​

U ​

U

Parameters ​

defaultValue ​

U

Returns ​

T | U

unwrapOrElse() ​

unwrapOrElse<U>(elseFn): T | U

Method variant for unwrapOrElse

Type Parameters ​

U ​

U

Parameters ​

elseFn ​

() => U

Returns ​

T | U