Module ior

Functionality for "inclusive-or" relationships.

Remarks

Ior<A, B> is a type that represents one or both of two values. It is represented by three variants: Left<A>, Right<B>, and Both<A, B>.

• A Left<A> contains a left-hand value of type A.
• A Right<B> contains a right-hand value of type B.
• A Both<A, B> contains a left-hand value of type A and a right-hand value of type B.

The companion Ior:namespace namespace provides utilities for working with the Ior<A, B> type.

Ior is often used to represent states of failure or success similar to either!Either:type and validation!Validation:type. However, Ior is capable of also representing a unique state using the Both variant. Both can represent a success that contains additional information, or a state of "partial failure".

When composed, the behavior of Ior is a combination of the short-circuiting behavior of Either and the failure-accumulating behavior of Validation:

• Left short-circuits a computation completely and combines its left-hand value with any existing left-hand value.
• Right supplies its right-hand value to the next computation.
• Both supplies its right-hand value to the next computation, and combines its left-hand value with any existing left-hand value.

Combinators with this behavior require a Semigroup implementation from the accumulating left-hand value.

Using Ior with promises

AsyncIor<A, B> is an alias for Promise<Ior<A, B>>. The companion AsyncIor:namespace namespace provides utilities for working with the AsyncIor<A, B> type.

To accommodate promise-like values, this module also provides the AsyncIorLike<A, B> type as an alias for PromiseLike<Ior<A, B>>.

Importing from this module

The types and namespaces from this module can be imported under the same aliases:

import { AsyncIor, Ior } from "@neotype/prelude/ior.js";
Copy

Or, the types and namespaces can be imported and aliased separately:

import {
    type AsyncIor,
    type Ior,
    AsyncIor as AI,
    Ior as I
} from "@neotype/prelude/ior.js";
Copy