optional.md

exceptnomore › Optional

Class: Optional <T>

The Optional class is meant to be an alternative to the more common 'return null'/'return undefined' statements. An Optional can be either Present or Empty. The former wraps the value returned by a function. The latter can be used instead of null/undefined.

By using the Optional type, the caller of a function can explicitly see that it may not return any meaningful value and can handle both the present and empty conditions with the fluent API provided by this class.

Type parameters

▪ T

Hierarchy

• Optional

Index

Accessors

• isEmpty
• isPresent

Methods

• else
• filter
• filterAsync
• flatMap
• flatMapAsync
• if
• ifAsync
• ifEmpty
• ifEmptyAsync
• ifPresent
• ifPresentAsync
• map
• mapAsync
• toResult
• unwrap
• unwrapNullable
• empty
• fromPromise
• fromResult
• fromThrower
• fromThrowerAsync
• of
• ofNullable

Accessors

isEmpty

• get isEmpty(): boolean

Returns true if the Optional is Empty, false otherwise

Returns: boolean

---

isPresent

• get isPresent(): boolean

Returns true if the Optional is Present, false otherwise

Returns: boolean

Methods

else

▸ else(value: T): T

Returns the Present value of an Optional, otherwise returns the passed value

Parameters:

Name	Type	Description
value	T	the fallback value

Returns: T

---

filter

▸ filter(predicate: function): Optional‹T›

If the Optional is Empty or the provided function returns false given the value of the Present Optional, an Empty Optional is returned. Otherwise the original Present Optional is returned.

Parameters:

▪ predicate: function

a function that returns a boolean based on the value of the Optional

▸ (value: T): boolean

Parameters:

Name	Type
value	T

Returns: Optional‹T›

---

filterAsync

▸ filterAsync(predicate: function): Promise‹Optional‹T››

If the Optional is Empty or the provided async function returns false given the value of the Present Optional, an Empty Optional is returned. Otherwise the original Present Optional is returned.

Parameters:

▪ predicate: function

a function that returns a boolean based on the value of the Optional

▸ (value: T): Promise‹boolean›

Parameters:

Name	Type
value	T

Returns: Promise‹Optional‹T››

---

flatMap

▸ flatMap<O>(f: function): Optional‹O›

If the Optional is Present, its value is passed to the provided function and the return value is returned. Otherwise, an Empty Optional is returned and the function is not executed

Type parameters:

▪ O

Parameters:

▪ f: function

the mapping function from T to O

▸ (value: T): Optional‹O›

Parameters:

Name	Type
value	T

Returns: Optional‹O›

---

flatMapAsync

▸ flatMapAsync<O>(f: function): Promise‹Optional‹O››

If the Optional is Present, its value is passed to the provided async function and the return value is returned. Otherwise, an Empty Optional is returned and the function is not executed

Type parameters:

▪ O

Parameters:

▪ f: function

the mapping function from T to O

▸ (value: T): Promise‹Optional‹O››

Parameters:

Name	Type
value	T

Returns: Promise‹Optional‹O››

---

if

▸ if(fPresent: function, fEmpty?: undefined | function): Optional‹T›

Executes one of the provided functions based on the type of the Optional

Parameters:

▪ fPresent: function

a function that takes the value of the Optional

▸ (value: T): any

Parameters:

Name	Type
value	T

▪Optional fEmpty: undefined | function

a function that does not have parameters

Returns: Optional‹T›

---

ifAsync

▸ ifAsync(fOk: function, fErr?: undefined | function): Promise‹Optional‹T››

Executes one of the provided async functions based on the type of the Optional

Parameters:

▪ fOk: function

▸ (value: T): Promise‹any›

Parameters:

Name	Type
value	T

▪Optional fErr: undefined | function

Returns: Promise‹Optional‹T››

---

ifEmpty

▸ ifEmpty(f: function): Optional‹T›

If the Optional is Empty, the provided function is executed

Parameters:

▪ f: function

a function

▸ (): any

Returns: Optional‹T›

---

ifEmptyAsync

▸ ifEmptyAsync(f: function): Promise‹Optional‹T››

If the Optional is Empty, the provided async function is executed

Parameters:

▪ f: function

a function

▸ (): Promise‹any›

Returns: Promise‹Optional‹T››

---

ifPresent

▸ ifPresent(f: function): Optional‹T›

If the Optional is Present, the provided function is executed

Parameters:

▪ f: function

a function that takes the value of the Optional

▸ (value: T): any

Parameters:

Name	Type
value	T

Returns: Optional‹T›

---

ifPresentAsync

▸ ifPresentAsync(f: function): Promise‹Optional‹T››

If the Optional is Present, the provided async function is executed

Parameters:

▪ f: function

a function that takes the value of the Optional

▸ (value: T): Promise‹any›

Parameters:

Name	Type
value	T

Returns: Promise‹Optional‹T››

---

map

▸ map<O>(f: function): Optional‹O›

If the Optional is Present, its value is passed to the provided function and the return value of the latter is wrapped in a new Optional. Otherwise, an Empty Optional is returned and the function is not executed

Type parameters:

▪ O

Parameters:

▪ f: function

the mapping function from T to O

▸ (value: T): O

Parameters:

Name	Type
value	T

Returns: Optional‹O›

---

mapAsync

▸ mapAsync<O>(f: function): Promise‹Optional‹O››

If the Optional is Present, its value is passed to the provided async function and the return value of the latter is wrapped in a new Optional. Otherwise, an Empty Optional is returned and the function is not executed

Type parameters:

▪ O

Parameters:

▪ f: function

the mapping function from T to O

▸ (value: T): Promise‹O›

Parameters:

Name	Type
value	T

Returns: Promise‹Optional‹O››

---

toResult

▸ toResult<TErr>(errIfEmpty: TErr): Result‹T, TErr›

Generates a Result from an Optional. If the Optional has a value, the latter will be wrapped as an Ok Result, otherwise an Error Result will be created with the specified error.

Type parameters:

▪ TErr

Parameters:

Name	Type	Description
errIfEmpty	TErr	the Error value of the Result in case the Optional is empty

Returns: Result‹T, TErr›

---

unwrap

▸ unwrap(): T

Unwrap the Present value of the Optional

throws {Error} if the Optional is of type Empty

Returns: T

---

unwrapNullable

▸ unwrapNullable(): T | null

Unwrap the value (if the Optional is Present) or returns null (if the Optional is Empty)

Returns: T | null

---

Static empty

▸ empty<O>(): Optional‹O›

Generates an Empty Optional

Type parameters:

▪ O

Returns: Optional‹O›

---

Static fromPromise

▸ fromPromise<O>(promise: Promise‹O›): Promise‹Optional‹O››

Generates an Optional from a Promise. If it was resolved its value is wrapped in a Present Optional, otherwise an Empty Optional is returned

Type parameters:

▪ O

Parameters:

Name	Type	Description
promise	Promise‹O›

Returns: Promise‹Optional‹O››

---

Static fromResult

▸ fromResult<O, TErr>(value: Result‹O, TErr›): Optional‹O›

Generates an Optional from a Result. If the Result is of type Ok, its value is wrapped in the Optional, otherwise an Empty Optional is returned

Type parameters:

▪ O

▪ TErr

Parameters:

Name	Type	Description
value	Result‹O, TErr›	the value

Returns: Optional‹O›

---

Static fromThrower

▸ fromThrower<O>(callback: function): Optional‹O›

Generates an Optional executing a function that may or may not throw an exception. On successful completion, the returned value is wrapped in a Present Optional, otherwise an Empty Optional is returned

Type parameters:

▪ O

Parameters:

▪ callback: function

a function that may or may not throw an exception

▸ (): O

Returns: Optional‹O›

---

Static fromThrowerAsync

▸ fromThrowerAsync<O>(callback: function): Promise‹Optional‹O››

Generates an Optional executing an async function that may or may not throw an exception. On successful completion, the returned value is wrapped in a Present Optional, otherwise an Empty Optional is returned

Type parameters:

▪ O

Parameters:

▪ callback: function

a function that may or may not throw an exception

▸ (): Promise‹O›

Returns: Promise‹Optional‹O››

---

Static of

▸ of<O>(value: O): Optional‹O›

Generates an Optional that wraps the provided value

Type parameters:

▪ O

Parameters:

Name	Type	Description
value	O	the value

Returns: Optional‹O›

---

Static ofNullable

▸ ofNullable<O>(value: O | null | undefined): Optional‹O›

Generates an Optional of a value. If the value is null or undefined, an Empty Optional is returned, otherwise the value is wrapped in a Present Optional.

Type parameters:

▪ O

Parameters:

Name	Type	Description
value	O | null | undefined	the nullable/undefinable value to be wrapped

Returns: Optional‹O›