tiinvo
Version:
A library of types and utilities for your TypeScript and JavaScript projects
527 lines (526 loc) • 15.4 kB
TypeScript
import type * as Fn from './Fn.js';
import type * as Functors from './Functors.js';
/**
* Represents an error
*/
export type Err = Error;
/**
* Represents the successful result of an operation
*/
export type Ok<A> = A extends Error ? never : A;
/**
* Could represent both an Error `Err` or a successful result of an operation `Ok<a>`
*/
export type T<A> = Ok<A> | Err;
/**
* Returns an `Err`
*
* @example
*
* ```ts
* import { Result } from 'tiinvo';
*
* Result.err(10) instanceof Error // true
* Result.err(new TypeError('aaaa')) instanceof Error // true
* Result.err({}) instanceof Error // true
* Result.err(10n) instanceof Error // true
* Result.err([10, 20, 30]) instanceof Error // true
* ```
*
* @param a
* @returns
* @group Factories
* @since 3.8.0
*/
export declare const err: (a: unknown) => Err;
/**
* Checks if a value is `Err`
*
* @example
*
* ```ts
* import { Result } from 'tiinvo';
*
* Result.isErr(10) // false
* Result.isErr(new TypeError('aaaa')) // true
* ```
*
* @param x the value to check
* @returns true if `x` is `Err`, false otherwise
* @group Guardables
* @since 4.0.0
*/
export declare const isErr: (x: unknown) => x is Error;
/**
* Checks if a value is `Ok`
*
* @example
*
* ```ts
* import { Result } from 'tiinvo';
*
* Result.isOk(10) // true
* Result.isOk(new TypeError('aaaa')) // false
* ```
*
* @param x
* @returns true if `x` is `Ok<A>`, false otherwise
* @group Guardables
* @since 4.0.0
*/
export declare const isOk: <A>(x: T<A>) => x is Ok<A>;
/**
* Checks if a value is `Ok<A>`
*
* ```ts
* import { Num, Result } from 'tiinvo';
*
* const guard = Result.isOkOf(Num.guard);
*
* guard(10) // true
* guard("hello") // false
* guard(new TypeError('aaaa')) // false
* ```
*
* @template A the type
* @param g the type guard
* @returns the Guard
* @group Guardables
* @since 4.0.0
*/
export declare const isOkOf: <A>(g: Functors.Guardable<A>) => (x: T<unknown>) => x is A;
/**
* Compares two results `T<A>` by a given `Comparable<A>`.
*
* If `a` is `Err` and `b` is `Ok` returns -1, else if both are `Err` returns 0, else returns 1
*
* @example
*
* ```ts
* import { Str, Result } from 'tiinvo';
*
* Result.cmp(Str.cmp, "a", "a") // 0
* Result.cmp(Str.cmp, "a", "b") // -1
* Result.cmp(Str.cmp, "b", "a") // 1
* Result.cmp(Str.cmp, new Error(), new Error()) // 0
* Result.cmp(Str.cmp, new Error(), "a") // -1
* Result.cmp(Str.cmp, "a", new Error()) // 1
* ```
*
* @template A the type
* @param cmp the comparer function
* @param a first value
* @param b last value
* @returns
* - -1 if `a` is less than `b`
* - 0 if `a` is same of `b`
* - 1 if `a` is greater than `b`.
* @since 4.0.0
*/
export declare function cmp<A>(cmp: Functors.Comparable<A>, a: T<A>, b: T<A>): Functors.ComparableResult;
/**
* Compares two results `T<A>` by a given `ComparableModule<A>`.
*
* If `a` is `Err` and `b` is `Ok` returns -1, else if both are `Err` returns 0, else returns 1
*
* @example
*
* ```ts
* import { Str, Result } from 'tiinvo';
*
* Result.cmp(Str, "a", "a") // 0
* Result.cmp(Str, "a", "b") // -1
* Result.cmp(Str, "b", "a") // 1
* Result.cmp(Str, new Error(), new Error()) // 0
* Result.cmp(Str, new Error(), "a") // -1
* Result.cmp(Str, "a", new Error()) // 1
* ```
*
* @template A the type
* @param cmp the comparer function
* @param a first value
* @returns
* - -1 if `a` is less than `b`
* - 0 if `a` is same of `b`
* - 1 if `a` is greater than `b`.
* @param b last value
* @since 4.0.0
*/
export declare function cmp<A>(cmp: Functors.ComparableModule<A>, a: T<A>, b: T<A>): Functors.ComparableResult;
/**
* Returns a unary function which compares two results `T<A>` by a given `Comparable<A>`.
*
* If `a` is `Err` and `b` is `Ok` returns -1, else if both are `Err` returns 0, else returns 1
*
* @example
*
* ```ts
* import { Str, Result } from 'tiinvo';
*
* const cmp = Result.cmp(Str.cmp, "a");
*
* cmp("a") // 0
* cmp("b") // -1
* cmp("a") // 1
* cmp(new Error()) // 1
* ```
*
* @template A the type
* @param cmp the comparer function
* @param a first value
* @returns the unary function which returns
* - -1 if `a` is less than `b`
* - 0 if `a` is same of `b`
* - 1 if `a` is greater than `b`.
* @group Comparables
* @since 4.0.0
*/
export declare function cmp<A>(cmp: Functors.Comparable<A>, a: T<A>): Fn.Unary<T<A>, Functors.ComparableResult>;
/**
* Returns a unary function which compares two results `T<A>` by a given `ComparableModule<A>`.
*
* If `a` is `Err` and `b` is `Ok` returns -1, else if both are `Err` returns 0, else returns 1
*
* @example
*
* ```ts
* import { Str, Result } from 'tiinvo';
*
* const cmp = Result.cmp(Str, "a");
*
* cmp("a") // 0
* cmp("b") // -1
* cmp("a") // 1
* cmp(new Error()) // 1
* ```
*
* @template A the type
* @param cmp the comparer module
* @param a first value
* @returns the unary function which returns
* - -1 if `a` is less than `b`
* - 0 if `a` is same of `b`
* - 1 if `a` is greater than `b`.
* @group Comparables
* @since 4.0.0
*/
export declare function cmp<A>(cmp: Functors.ComparableModule<A>, a: T<A>): Fn.Unary<T<A>, Functors.ComparableResult>;
/**
* Returns a binary function which compares two results `T<A>` by a given `Comparable<A>`.
*
* If `a` is `Err` and `b` is `Ok` returns -1, else if both are `Err` returns 0, else returns 1
*
* @example
*
* ```ts
* import { Str, Result } from 'tiinvo';
*
* const cmp = Result.cmp(Str.cmp);
*
* cmp("a", "a") // 0
* cmp("a", "b") // -1
* cmp("b", "a") // 1
* cmp("a", new Error()) // 1
* cmp(new Error(), "a") // -1
* cmp(new Error(), new Error()) // 0
* ```
*
* @template A the type
* @param cmp the comparer function
* @returns the binary function which returns
* - -1 if `a` is less than `b`
* - 0 if `a` is same of `b`
* - 1 if `a` is greater than `b`.
* @group Comparables
* @since 4.0.0
*/
export declare function cmp<A>(cmp: Functors.Comparable<A>): Fn.Binary<T<A>, T<A>, Functors.ComparableResult>;
/**
* Returns a binary function which compares two results `T<A>` by a given `ComparableModule<A>`.
*
* If `a` is `Err` and `b` is `Ok` returns -1, else if both are `Err` returns 0, else returns 1
*
* @example
*
* ```ts
* import { Str, Result } from 'tiinvo';
*
* const cmp = Result.cmp(Str);
*
* cmp("a", "a") // 0
* cmp("a", "b") // -1
* cmp("b", "a") // 1
* cmp("a", new Error()) // 1
* cmp(new Error(), "a") // -1
* cmp(new Error(), new Error()) // 0
* ```
*
* @template A the type
* @param cmp the comparer module
* @returns the binary function which returns
* - -1 if `a` is less than `b`
* - 0 if `a` is same of `b`
* - 1 if `a` is greater than `b`.
* @group Comparables
* @since 4.0.0
*/
export declare function cmp<A>(cmp: Functors.ComparableModule<A>): Fn.Binary<T<A>, T<A>, Functors.ComparableResult>;
/**
* Returns true if two results are equal, false otherwise.
*
* ```ts
* import { Num, Result } from 'tiinvo';
*
* Result.eq(Num.eq, 0, 0) // true
* Result.eq(Num.eq, new Error(), new TypeError()) // true
* Result.eq(Num.eq, new Error(), 0) // false
* Result.eq(Num.eq, 0, new Error()) // false
* Result.eq(Num.eq, 1_000_000, 0) // false
* ```
*
* @template A the value type
* @param eq the Equatable functor
* @param a the left compared value
* @param b the right compared value
* @returns true if `a` equals to `b`
* @group Comparables
* @since 4.0.0
*/
export declare function eq<A>(eq: Functors.Equatable<A>, a: T<A>, b: T<A>): boolean;
/**
* Returns true if two results are equal, false otherwise.
*
* ```ts
* import { Num, Result } from 'tiinvo';
*
* Result.eq(Num, 0, 0) // true
* Result.eq(Num, new Error(), new TypeError()) // true
* Result.eq(Num, new Error(), 0) // false
* Result.eq(Num, 0, new Error()) // false
* Result.eq(Num, 1_000_000, 0) // false
* ```
*
* @template A the value type
* @param eq the Equatable module
* @param a the left compared value
* @param b the right compared value
* @returns true if `a` equals to `b`
* @group Comparables
* @since 4.0.0
*/
export declare function eq<A>(eq: Functors.EquatableModule<A>, a: T<A>, b: T<A>): boolean;
/**
* Returns a unary function which returns true if two results are equal, false otherwise.
*
* ```ts
* import { Num, Result } from 'tiinvo';
*
* const is0 = Result.eq(Num.eq, 0)
*
* Result.eq(0) // true
* Result.eq(new TypeError()) // false
* Result.eq(new Error()) // false
* Result.eq(1_000_000) // false
* ```
*
* @template A the value type
* @param eq the Equatable functor
* @param a the left compared value
* @returns the unary function
* @group Comparables
* @since 4.0.0
*/
export declare function eq<A>(eq: Functors.Equatable<A>, a: T<A>): Fn.Unary<T<A>, boolean>;
/**
* Returns a unary function which returns true if two results are equal, false otherwise.
*
* ```ts
* import { Num, Result } from 'tiinvo';
*
* const is0 = Result.eq(Num, 0)
*
* Result.eq(0) // true
* Result.eq(new TypeError()) // false
* Result.eq(new Error()) // false
* Result.eq(1_000_000) // false
* ```
*
* @template A the value type
* @param eq the Equatable functor
* @param a the left compared value
* @returns the unary function
* @group Comparables
* @since 4.0.0
*/
export declare function eq<A>(eq: Functors.EquatableModule<A>, a: T<A>): Fn.Unary<T<A>, boolean>;
/**
* Returns a binary function which returns true if two results are equal, false otherwise.
*
* ```ts
* import { Num, Result } from 'tiinvo';
*
* const is0 = Result.eq(Num.eq)
*
* Result.eq(0, 0) // true
* Result.eq(new TypeError(), new Error()) // true
* Result.eq(0, new Error()) // false
* Result.eq(1_000, 1_000) // true
* ```
*
* @template A the value type
* @param eq the Equatable functor
* @returns the binary function
* @group Comparables
* @since 4.0.0
*/
export declare function eq<a>(eq: Functors.Equatable<a>): Fn.Binary<T<a>, T<a>, boolean>;
/**
* Returns a binary function which returns true if two results are equal, false otherwise.
*
* ```ts
* import { Num, Result } from 'tiinvo';
*
* const is0 = Result.eq(Num)
*
* Result.eq(0, 0) // true
* Result.eq(new TypeError(), new Error()) // true
* Result.eq(0, new Error()) // false
* Result.eq(1_000, 1_000) // true
* ```
*
* @template A the value type
* @param eq the Equatable module
* @returns the binary function
* @group Comparables
* @since 4.0.0
*/
export declare function eq<a>(eq: Functors.EquatableModule<a>): Fn.Binary<T<a>, T<a>, boolean>;
/**
* Returns `Ok<A>` if the value `a` is `Ok<A>` and the predicate is satisfied, otherwise returns `Err`.
*
* ```typescript
* import { Result, Num } from 'tiinvo';
*
* Result.filter(Num.gt(1), 1) // Error("Value did not pass filter")
* Result.filter(Num.gt(1), 2) // 2
* Result.filter(Num.gt(1), new TypeError()) // Error("Value did not pass filter")
* ```
*
* @template A the value type
* @param f the Filterable functor
* @param a the value to filter
* @returns `T<A>` if the Filterable has been satisfied
* @group Filterables
* @since 4.0.0
*/
export declare function filter<A>(f: Functors.Filterable<A>, a: T<A>): T<A>;
/**
* Returns a unary function which checks if `Result.T<A>` is `Ok<A>` and the predicate is satisfied, otherwise returns `Err`.
*
* ```typescript
* import { Result, Num } from 'tiinvo';
*
* const f = Result.filter(Num.gt(1));
*
* f(1) // Error("Value did not pass filter")
* f(2) // 2
* f(new TypeError()) // Error("Value did not pass filter")
* ```
*
* @template A the value type
* @param f the Filterable functor
* @returns the unary function
* @group Filterables
* @since 4.0.0
*/
export declare function filter<A>(f: Functors.Filterable<A>): Fn.Unary<T<A>, T<A>>;
/**
* Maps `Result.t<a>` to `Result.t<b>` if ok, otherwise returns `err`
*
* ```ts
* import { Num, Result } from 'tiinvo';
*
* const m = Result.map(Num.add(10))
*
* m(10) // 20
* m(new Error('foobar!')) // Error('foobar!')
* ```
*
* @param m the Mappable functor
* @returns
* @since 4.0.0
*/
export declare const map: <A, B>(m: Functors.Mappable<A, B>) => (a: T<A>) => T<B>;
/**
* Maps `Result.t<a>` to `Result.t<b>` if ok, otherwise returns `b`
*
* ```ts
* import { Str, Result } from 'tiinvo';
*
* const map = Result.mapOr(Str.length, 0);
*
* map('hello') // 5
* map(new Error()) // 0
* ```
*
* @param value
* @returns
* @since 4.0.0
*/
export declare const mapOr: <a, b>(m: Functors.Mappable<a, b>, b: b) => (a: T<a>) => b;
/**
* Calls a function `f` with it's arguments and returns a `Promise<Result.t<ReturnType<f>>>`
*
* ```typescript
* import { Result, Num } from 'tiinvo';
*
* const fn = async (arg: number) => {
* if (Num.isEven(arg)) {
* return arg * 2;
* }
*
* throw new Error(`${arg} is not even`);
* }
*
* const safe = Result.tryAsync(fn);
*
* await safe(2) // 4
* await safe(3) // Error("3 is not even")
*
* Result.isOk(await safe(2)) // true
* Result.isErr(await safe(3)) // true
* ```
*
* @param fn
* @returns
* @since 4.0.0
*/
export declare const tryAsync: <f extends Fn.AnyAsyncFn>(f: f) => ((...args: Parameters<f>) => Promise<T<ReturnType<f>>>) extends infer T_1 ? T_1 extends (...args: Parameters<f>) => Promise<T<ReturnType<f>>> ? T_1 extends Fn.AnyAsyncFn ? (...args: Parameters<T_1>) => Promise<Awaited<ReturnType<T_1>>> : (...args: Parameters<T_1>) => ReturnType<T_1> : never : never;
/**
* Calls a function `f` with it's arguments and returns a `Promise<Result.t<ReturnType<f>>>`
*
* ```typescript
* import { Result, Num } from 'tiinvo';
*
* const fn = (arg: number) => {
* if (Num.isEven(arg)) {
* return arg * 2;
* }
*
* throw new Error(`${arg} is not even`);
* }
*
* const safe = Result.trySync(fn);
*
* safe(2) // 4
* safe(3) // Error("3 is not even")
*
* Result.isOk(safe(2)) // true
* Result.isErr(safe(3)) // true
* ```
*
* @param fn
* @returns
* @since 4.0.0
*/
export declare const trySync: <f extends Fn.AnyFn>(f: f) => ((...args: Parameters<f>) => T<ReturnType<f>>) extends infer T_1 ? T_1 extends (...args: Parameters<f>) => T<ReturnType<f>> ? T_1 extends Fn.AnyAsyncFn ? (...args: Parameters<T_1>) => Promise<Awaited<ReturnType<T_1>>> : (...args: Parameters<T_1>) => ReturnType<T_1> : never : never;