IResult | /mod.ts | eitherway@0.10.0

interface IResult

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

Base interface implemented by Ok<T> and Err<E>

Type Parameters

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 [.toString()]this#toString method is a useful short-hand in these scenarios

See the reference

Methods

isOk(): this is Ok<T>

Type predicate - use this to narrow Result<T, E> to Ok<T>

isErr(): this is Err<E>

Type predicate - use this to narrow Result<T, E> to Err<E>

id(): Result<T, E>

Use this to return the Result itself.

Canonical identity function. Mainly useful for flattening instances of Result<Result<T, E>, E> in combination with .andThen()

clone(): Result<T, E>

Use this to obtain a deep clone of Result<T, E>

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<T2>(mapFn: (value: T) => T2): Result<T2, E>

Use this to map the encapsulated value <T>' to `.

In case of Err<E> this method short-circuits. See IResult#mapErr for the opposite case.

mapOr<T2>(mapFn: (value: T) => T2, orValue: T2): Ok<T2>

Same as .map() but in case of Err<E>, a new instance of Ok, wrapping the provided orValue` will be returned.

mapOrElse<T2>(mapFn: (value: T) => T2, elseFn: (err: E) => T2): Ok<T2>

Same as .map() but in case of Err<E>, a new instance of Ok, wrapping the return value of the provided elseFn` will be returned.

Use this if the fallback value is expensive to produce.

mapErr<E2>(mapFn: (err: E) => E2): Result<T, E2>

Use this to map the encapsulated value <E> to <E2>. In case of Ok<T>, this method short-circuits. See IResult#map for the opposite case.

andThen<T2, E2>(thenFn: (value: T) => Result<T2, E2>): Err<E> | Result<T2, E2>

Use this to produce a new instance of Result<T2, E2> from the encapsulated value <T>. Can be used to flatten an instance of Result<Result<T2, E2>, E> to Result<T2, E | E2>.

In case of Err<E>, this method short-circuits.

See IResult#orElse for the opposite case.

Canonical .flatMap() or .chain() method.

orElse<T2, E2>(elseFn: (err: E) => Result<T2, E2>): Ok<T> | Result<T2, E2>

Use this to produce a new instance of Result<T2, E2> from the encapsulated value <E>. Can be used to flatten an instance of Result<T, Result<T2, E2>> to Result<T | T2, E2>.

In case of Ok<T>, this method short-circuits.

See IResult#andThen for the opposite case.

andEnsure<T2, E2>(ensureFn: (value: T) => Result<T2, E2>): Result<T, E> | Err<E2>

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

In case of Err<E>, this method short-circuits.

In case of Ok<T>, the supplied ensureFn is called with the encapsulated value <T> and if the return value is:

Ok<T2>: it is discarded and the original Ok<T> is returned
Err<E2>: Err<E2> is returned

See IResult#orEnsure for the opposite case.

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

LHS andEnsure RHS	RHS: Ok	RHS: Err
LHS: Ok	Ok	Err
LHS: Err	Err	Err

deprecated

trip<T2, E2>(tripFn: (value: T) => Result<T2, E2>): Result<T, E> | Err<E2>

orEnsure<T2, E2>(ensureFn: (err: E) => Result<T2, E2>): Result<T, E> | Ok<T2>

Use this to conditionally pass-through the encapsulated value <E> based upon the outcome of the supplied ensureFn.

In case of Ok<T>, this method short-circuits.

In case of Err<E>, the supplied ensureFn is called with the encapsulated value <E> and if the return value is:

Ok<T2>: it is returned
Err<T2>: it is discarded and the original Err<E> is returned

See IResult#andEnsure for the opposite case.

This is equivalent to chaining: original.orElse(ensureFn).or(original)

LHS orEnsure RHS	RHS: Ok	RHS: Err
LHS: Ok	Ok	Ok
LHS: Err	Ok	Err

deprecated

rise<T2, E2>(riseFn: (err: E) => Result<T2, E2>): Result<T, E> | Ok<T2>

and<T2, E2>(rhs: Result<T2, E2>): Err<E> | Result<T2, E2>

Logical AND (&&) Returns RHS if LHS is Ok, otherwise returns LHS

LHS AND RHS	RHS: Ok	RHS: Err
LHS: Ok	Ok	Err
LHS: Err	Err	Err

or<T2, E2>(rhs: Result<T2, E2>): Ok<T> | Result<T2, E2>

Logical OR (||) Returns RHS if LHS is Err, otherwise returns LHS

|LHS || RHS |RHS: Ok|RHS: Err| |:------------: |:-------------:|:--------------:| |LHS: Ok | Ok | Ok | |LHS: Err| Ok | Err |

zip<T2, E2>(rhs: Result<T2, E2>): Ok<[T, T2]> | Err<E> | Err<E2>

Use this to zip the encapsulated values of two Ok instances into a new Ok instance wrapping a tuple of them.

In case any of the two Result instances is Err, the respective Err instance is returned in left-to-right evaluation order.

LHS zip RHS	RHS: Ok	RHS: Err
LHS: Ok	Ok<[T, T2]>	Err
LHS: Err	Err	Err

This is not only useful to produce tuples, but also to collect arguments to be passed to a function down the line.

unwrap(): T | E

Use this to get the wrapped value out of an Result<T, E> instance

Returns the wrapped value of type <T> in case of Ok<T> OR <E> in case of Err<E>.

It is necessary to narrow the instance to Ok<T> or Err<E> in order to narrow the return value.

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

unwrapOr<T2>(orValue: T2): T | T2

Same as .unwrap() but returns a default value in case of Err<E>

unwrapOrElse<T2>(elseFn: (err: E) => T2): T | T2

Same as .unwrap() but returns a the result of the provided elseFn in case of Err<E>

Use this if the fallback value is expensive to produce

asResult(): Result<T, E>

Use this to cast an instance of Ok<T> or Err<E> to it's Result representation. This is a safe, inherent type cast. Does not alter the runtime behaviour.

Mostly useful in the context of early returns or combination methods, where an already narrowed instance would result in one of the variants being inferred as unknown otherwise.

toTuple(): [T, never] | [never, E] | [never, never]

Use this to obtain a tuple representation of Result<T, E>

ok(): Option<T>

Use this to transform an instance of Result<T, E> into an Option<T>.

See IResult#err for the opposite case.

err(): Option<E>

Use this to transform an instance of Result<T, E> into an Option<E>.

See IResult#ok for the opposite case.

into<T2>(intoFn: (res: Result<T, E>) => T2): T2

Use this to transform an instance of Result<T, E> into a type of your choosing.

This is mostly useful to push the instance into an async context.

iter(): IterableIterator<T>

Use this to obtain an iterator over the wrapped value <T> in case of Ok

In case of Err, an empty iterator is returned

tap(tapFn: (res: Result<T, E>) => void): Result<T, E>

Use this to perform side-effects transparently.

The tapFn receives a deep clone of Result<T, E> IResult#clone

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

See the reference

inspect(inspectFn: (value: T) => void): Result<T, E>

Use this to inspect the the encapsulated value <T> transparently.

Mainly used for debugging and logging purposes.

In case of Err<E>, this method short-cuits and returns the Err<E> instance. See IResult#inspectErr for the opposite case;

inspectErr(inspectFn: (err: E) => void): Result<T, E>

Use this to inspect the the encapsulated value <E> transparently.

Mainly used for debugging and logging purposes.

In case of Ok<T>, this method short-cuits and returns the Ok<T> instance. See IResult#inspect for the opposite case;

toString(): string

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

See the reference

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

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

See the reference