IOption | /mod.ts | eitherway@0.10.0

interface IOption

import { type IOption } from "https://deno.land/x/eitherway@0.10.0/mod.ts";

The base interface implemented by Some and None

Properties

[[Symbol.toStringTag]]: string

This well-known symbol is called by Object.prototype.toString to obtain a string representation of a value's type

This maybe useful for debugging or certain logs

The [.toTag()]this#toTag method is a useful short-hand in these scenarios

See the reference

Methods

isSome(): this is Some<T>

Type predicate - use this to narrow an Option<T> to Some<T>

isNone(): this is None

Type predicate - use this to narrow an Option<T> to None

id(): Option<T>

Use this to return the Option itself

Canonical identity function

Mainly useful for flattening types of Option<Option<T>> togehter with .andThen(),

clone(): Option<T>

Use this to obtain a deep clone of Option<T>

Under the hood, this uses the structuredClone algorithm exposed via the global function of the same name

May incur performance penalties, depending on the platform, size and type of the data to be cloned

Can be handy if user-defined operations on reference types mutate the passed value and the original value should be retained

CAUTION: Mutations in a chained series of operations are strongly discouraged

See the reference

map(mapFn: (arg: Readonly<T>) => NonNullish): Option<NonNullish>

Use this to transform Some<T> to Some by applying the supplied mapFn to the wrapped value of type <T>

Produces a new instance of Some

In case of None, this method short-circuits and returns None

mapOr(mapFn: (arg: Readonly<T>) => NonNullish, orValue: NonNullish): Some<NonNullish>

Same as .map(), but in case of None, a new instance of Some wrapping the provided orValue of type  will be returned

mapOrElse(mapFn: (arg: Readonly<T>) => NonNullish, elseFn: () => NonNullish): Some<NonNullish>

Same as .map(), but in case of None, a new instance of Some wrapping the return value of the provided elseFn will be returned

Use this if the fallback value is expensive to produce

filter(predicate: (arg: Readonly<T>) => arg is U): Option

Use this to refine a wrapped value <T> to  or cheaply convert an instance of Some<T> to None in case the wrapped fails the supplied predicate function

In case of None, this method short-circuits and returns None

filter(predicate: (arg: Readonly<T>) => boolean): Option<T>

andThen(thenFn: (arg: Readonly<T>) => Option): Option

Use this to produce a new Option instance from the wrapped value or flatten a nested Option

Given Some<T>, applies the supplied thenFn to the wrapped value of type <T>, which produces a new Option

In case of None, this method short-circuits and returns None

This is equivalent to the canonical .flatMap() method in traditional functional idioms, thus it can be used to flatten instances of Option<Option<T>> to Option<T>

orElse(elseFn: () => Option): Some<T> | Option

Use this if you want to recover from None or lazily initialize a fallback Option in case of None

unwrap(): T | undefined

Use this to get the wrapped value out of an Option instance

Returns the wrapped value of type <T> in case of Some<T> OR undefined in case of None

It is necessary, to narrow an instance of Option<T> to Some<T> in order to narrow the return value of .unwrap()

In contrast to other implementations, this method NEVER throws an exception

unwrapOr(orValue: NonNullish): T | NonNullish

Same as .unwrap(), but with a fallback value

Returns the wrapped value of type <T> or returns a fallback value of type  in case of None

unwrapOrElse(elseFn: () => NonNullish): T | NonNullish

Same as .unwrap(), but with a fallback function

Returns the value of type <T> or lazily produces a value of type  in case of None

Use this if the fallback value is expensive to produce

okOr<E>(err: E): Result<T, E>

Use this to transform an Option<T> into a Result<T, E> by providing a possible Error value in case of None

okOrElse<E>(err: () => E): Result<T, E>

Use this to transform an Option<T> into a Result<T, E> by providing a function to lazily produce a possible Error value in case of None

This is mostly useful if the Error value is expensive to produce

into(intoFn: (arg: Option<T>) => U): U

Use this to transform an Option<T> into a type of your choosing

This is mostly useful for shoving an Option<T> into an async context.

zip(rhs: Option): Option<[T, U]>

Use this to produce a tuple from two wrapped values if both are Some, otherwise return None

Apart from creating tuples, this is mostly useful for composing arguments, which should be applied to a function down the line

LHS `x` RHS	RHS: Some	RHS: None
LHS: Some	Some<[T, U]>	None
LHS: None	None	None

andEnsure(ensureFn: (value: T) => Option): Option<T>

Use this to conditionally pass-through the encapsulated value of type <T> based upon the outcome of the supplied ensureFn`

In case of None this method short-circuits and returns None

In case of Some<T>, the provided ensureFn gets called with a value of type <T> and if the return value is:

Some: it is discarded and the original Some<T> is returned
None: None is returned

This is equivalent to chaining: original.andThen(ensureFn).and(original)

LHS `ensure` RHS	RHS: Some	RHS: None
LHS: Some	Some	None
LHS: None	None	None

Can be used to perform synchronous side-effects which can derail the current Option<T>

deprecated

trip(tripFn: (value: T) => Option): Option<T>

and(rhs: Option): Some<T> | Some | None

Logical AND ( && ) Returns RHS if LHS is Some<T>

LHS `&&` RHS	RHS: Some	RHS: None
LHS: Some	Some	None
LHS: None	None	None

or(rhs: Option): Some<T> | Some | None

Logical OR ( || ) Returns LHS if LHS is Some<T>, otherwise returns RHS

| LHS || RHS | RHS: Some | RHS: None | |----------------|--------------|-------------| | LHS: Some | Some | Some | | LHS: None | Some | None |

xor(rhs: Option): Some<T> | Some | None

Logical XOR ( ^ ) Useful when only one of two values should be Some, but not both Returns Some, if only LHS or RHS is Some

LHS `^` RHS	RHS: Some	RHS: None
LHS: Some	None	Some
LHS: None	Some	None

tap(tapFn: (arg: Option<T>) => void): Option<T>

Use this to perform side-effects transparently

The tapFn receives a deep clone of Option<T> IOption#clone

This may have performance implications, dependending on the size of the wrapped value <T>, but ensures that the tapFn can never change or invalidate the state of the Option<T> instance

See the reference

inspect(inspectFn: (value: T) => void): Option<T>

Use this to inspect the value inside an instance of Some<T> in a transparent manner

Short-curcuits in case of `None'

toTag(): string

Use this to get the full string tag Short-hand for Object.prototype.toString.call(option)

toJSON(): JsonRepr<T>

Delegates to the implementation of the wrapped value <T> or returns a deep copy of the value itself, if no implementation is present

Returns undefined in case of None

See the reference

toString(): StringRepr<T>

Delegates to the implementation of the wrapped value <T> or returns the empty string (i.e. "") in case of None

See the reference

valueOf(): ValueRepr<T>

Delegates to the implementation of the wrapped value <T> or returns 0 in case of None

Be aware that there exists an asymmetry between Some<T> and None for all types except <number> if <T> doesn't implement .valueOf() for number coercion.

See the reference

iter(): IterableIterator<T>

Use this to obtain an iterator over the wrapped value <T>

In case of None, an empty iterator is returned

[[Symbol.iterator]](): IterableIterator<T extends Iterable<infer U> ? U : never>

Delegates to the implementation of the wrapped value <T> or exhausts the iterator by returning { done: true, value: undefined } if <T> doesn't implement the iterator protocol

None represents the empty iterator and returns the empty iterator result { done: true, value: undefined }

See the reference

[[Symbol.toPrimitive]](hint?: string):

| string

| number

| boolean

| symbol

Delegates to the implementation of the wrapped value <T> or returns <T> if it already is a primitive value

This method ALWAYS returns a primitive value, as required by the spec In case of keyed/indexed collection types, if no primitive conversion is defined, their string representation will be returned (i.e. collection.toString())

In case of None the spec required hints produce the following values:

"string" -> ""
"number" -> 0
"default"? -> false

See the reference

Type Parameters

Properties

Methods