@golemcloud/golem-ts/out/result.d.ts

A library that help writing Golem programs by providing higher level wrappers for Golem's runtime APIs, including functions for defining and performing operations transactionally.

declare const prototype: {
    /**
     * Returns `true` if the result is successful, `false` otherwise
     * @example.
     * Result.ok(123).isOk() // true
     * @example
     * Result.err('error').isOk() // false
     */
    readonly isOk: typeof isOk;
    /**
     * Returns `true` if the result is an error, `false` otherwise
     * @example
     * Result.err('error').isOk() // false
     * @example.
     * Result.ok(123).isOk() // true
     */
    readonly isErr: typeof isErr;
    /**
     * Returns the successful value of the result or throws the error value.
     * This should be used when returning from a component function that expects to receive a result.
     * See https://bytecodealliance.github.io/jco/wit-type-representations.html#results-in-context-function-return-values for more details.
     * @example Returns the payload of a successful result.
     * Result.ok(123).unwrapForWit() // 123
     * @example Throws the payload of a failed result.
     * Result.err('error').unwrapForWit() // throws 'error'
     */
    readonly unwrapForWit: typeof unwrapForWit;
    /**
     * Returns `this.value` if `this` is a successful result, otherwise throws a TypeError.
     * @example Returns the payload of a successful result.
     * Result.ok(123).unwrap() // 123
     * @example Throws a TypeError for a failed result.
     * Result.err('error').unwrap() // throws TypeError
     */
    readonly unwrap: typeof unwrap;
    /**
     *
     * Returns `this.error` if `this` is a failed result, otherwise throws a TypeError.
     * @example Throw a TypeError for a successful result.
     * Result.ok(123).unwrapErr() // throws TypeError
     * @example Returns the payload of a failed result
     * Result.err('error').unwrap() // 'error'
     */
    readonly unwrapErr: typeof unwrapErr;
    /**
     * Returns the payload of the result.
     * @example Returns the payload of a successful result.
     * Result.ok(123).toUnion() // 123
     * @example Returns the payload of a failed result.
     * Result.err('error').toUnion() // 'error'
     */
    readonly toUnion: typeof toUnion;
    /**
     * Return the result of applying one of the given functions to the payload.
     * @example
     * Result.ok(123).match((x) => x * 2, (x: string) => x + '!') // 246
     * Result.err('error').match((x: number) => x * 2, (x) => x + '!') // 'error!'
     */
    readonly match: typeof match;
    /**
     * Creates a Result value by modifying the payload of the successful result using the given function.
     * @example
     * Result.ok(123).map((x) => x * 2) // Result.ok(246)
     * Result.err('error').map((x: number) => x * 2) // Result.err('error')
     */
    readonly map: typeof map;
    /**
     * Creates a Result value by modifying the payload of the failed result using the given function.
     * @example
     * Result.ok(123).mapError((x: string) => x + '!') // Result.ok(123)
     * Result.err('error').mapError((x) => x + '!') // Result.err('error!')
     */
    readonly mapError: typeof mapError;
    /**
     * Calls the given function with the payload of the result and returns the result unchanged.
     */
    readonly tap: typeof tap;
    /**
     * Maps the payload of the successful result and flattens the nested Result type.
     * @example
     * Result.ok(123).flatMap((x) => Result.ok(x * 2)) // Result.ok(246)
     * Result.ok(123).flatMap((x) => Result.err('error')) // Result.err('error')
     * Result.err('error').flatMap((x: number) => Result.ok(x * 2)) // Result.err('error')
     * Result.err('error').flatMap((x) => Result.err('failure')) // Result.err('error')
     */
    readonly flatMap: typeof flatMap;
    /**
     * Flattens the nested Result type.
     * @example
     * Result.ok(Result.ok(123)).flatten() // Result.ok(123)
     * Result.ok(Result.err('error')).flatten() // Result.err('error')
     * Result.err('error').flatten() // Result.err('error')
     */
    readonly flatten: typeof flatten;
    /**
     * Perform a safe cast of the error type to the given class. If the payload of the failed result is not instance of constructor, throws TypeError.
     * @example
     * const result: Result<number, Error> = Result.tryCatch(() => {
     *   if (Math.random() >= 0) {
     *     throw new Error('error')
     *   } else {
     *     return 123
     *   }
     * }).assertErrorInstanceOf(Error)
     */
    readonly assertErrorInstanceOf: typeof assertErrorInstanceOf;
};
/** Type representing success or failure. */
export type Result<T, E = unknown> = Result.Ok<T> | Result.Err<E>;
export declare namespace Result {
    /**
     * The type of a successful result.
     * @example
     * const success: Result.ok<number> = Result.ok(123)
     */
    type Ok<T> = typeof prototype & {
        readonly tag: "ok";
        readonly val: T;
    };
    /**
     * A failed result.
     * @example
     * const failure: Result.err<string> = Result.err('error')
     */
    type Err<E> = typeof prototype & {
        readonly tag: "err";
        readonly val: E;
    };
    /**
     * Create a successful result.
     */
    function ok<T>(value: T): Result.Ok<T>;
    /**
     * Create an error result.
     */
    function err<E>(error: E): Err<E>;
    /**
     * Create a result from a function that may throw an error.
     */
    function tryCatch<T>(f: () => T): Result<T, unknown>;
    function fromNullish(value: null): Result.Err<null>;
    function fromNullish(value: undefined): Result.Err<undefined>;
    function fromNullish(value: null | undefined): Result.Err<null | undefined>;
    function fromNullish<T extends {}>(value: T): Result.Ok<T>;
    function fromNullish<T>(value: T | null): Result<T, null>;
    function fromNullish<T>(value: T | undefined): Result<T, undefined>;
    function fromNullish<T>(value: T | null | undefined): Result<T, null | undefined>;
    function all<T>(results: readonly Result.Ok<T>[]): Result.Ok<T[]>;
    function all<T, E>(results: readonly Result<T, E>[]): Result<T[], E>;
}
declare function isOk<T, E>(this: Result<T, E>): this is Result.Ok<T>;
declare function isErr<T, E>(this: Result<T, E>): this is Result.Err<E>;
declare function unwrapForWit<T>(this: Result.Ok<T>): T;
declare function unwrapForWit<E>(this: Result.Err<E>): never;
declare function unwrapForWit<T, E>(this: Result<T, E>): T;
declare function unwrap<T>(this: Result.Ok<T>): T;
declare function unwrap<E>(this: Result.Err<E>): never;
declare function unwrap<T, E>(this: Result<T, E>): T;
declare function unwrapErr<T>(this: Result.Ok<T>): never;
declare function unwrapErr<E>(this: Result.Err<E>): E;
declare function unwrapErr<T, E>(this: Result<T, E>): E;
declare function toUnion<T>(this: Result.Ok<T>): T;
declare function toUnion<E>(this: Result.Err<E>): E;
declare function toUnion<T, E>(this: Result<T, E>): T | E;
declare function match<T, E, T2, E2>(this: Result.Ok<T>, f: (value: T) => T2, g: (error: E) => E2): T2;
declare function match<T, E, T2, E2>(this: Result.Err<E>, f: (value: T) => T2, g: (error: E) => E2): E2;
declare function match<T, E, T2, E2>(this: Result<T, E>, f: (value: T) => T2, g: (error: E) => E2): T2 | E2;
declare function map<T, T2>(this: Result.Ok<T>, f: (value: T) => T2): Result.Ok<T2>;
declare function map<T, E, T2>(this: Result.Err<E>, f: (value: T) => T2): Result.Err<E>;
declare function map<T, E, T2>(this: Result<T, E>, f: (value: T) => T2): Result<T2, E>;
declare function mapError<T, E, E2>(this: Result.Ok<T>, f: (error: E) => E2): Result.Ok<T>;
declare function mapError<E, E2>(this: Result.Err<E>, f: (error: E) => E2): Result.Err<E2>;
declare function mapError<T, E, E2>(this: Result<T, E>, f: (error: E) => E2): Result<T, E2>;
declare function tap<E>(this: Result.Err<E>, f: (error: E) => void): Result.Err<E>;
declare function tap<T>(this: Result.Ok<T>, f: (value: T) => void): Result.Ok<T>;
declare function tap<T, E>(this: Result<T, E>, f: (value: T) => void): Result<T, E>;
declare function flatMap<T, T2>(this: Result.Ok<T>, f: (value: T) => Result.Ok<T2>): Result.Ok<T2>;
declare function flatMap<T, E2>(this: Result.Ok<T>, f: (value: T) => Result.Err<E2>): Result.Err<E2>;
declare function flatMap<T, T2, E2>(this: Result.Ok<T>, f: (value: T) => Result<T2, E2>): Result<T2, E2>;
declare function flatMap<T, E, T2, E2>(this: Result.Err<E>, f: (value: T) => Result<T2, E2>): Result.Err<E>;
declare function flatMap<T, E, T2>(this: Result<T, E>, f: (value: T) => Result.Ok<T2>): Result<T2, E>;
declare function flatMap<T, E, T2, E2>(this: Result<T, E>, f: (value: T) => Result.Err<E2>): Result.Err<E | E2>;
declare function flatMap<T, E, T2, E2>(this: Result<T, E>, f: (value: T) => Result<T2, E2>): Result<T2, E | E2>;
declare function flatten<E>(this: Result.Err<E>): Result.Err<E>;
declare function flatten<E>(this: Result.Ok<Result.Err<E>>): Result.Err<E>;
declare function flatten<T>(this: Result.Ok<Result.Ok<T>>): Result.Ok<T>;
declare function flatten<T, E>(this: Result.Ok<Result<T, E>>): Result<T, E>;
declare function flatten<T, E>(this: Result<Result.Ok<T>, E>): Result<T, E>;
declare function flatten<E, E2>(this: Result<Result.Err<E>, E2>): Result.Err<E | E2>;
declare function flatten<T, E, E2>(this: Result<Result<T, E>, E2>): Result<T, E | E2>;
declare function assertErrorInstanceOf<T, C extends abstract new (..._: any) => any>(this: Result.Ok<T>, constructor: C): Result.Ok<T>;
declare function assertErrorInstanceOf<E, C extends abstract new (..._: any) => any>(this: Result.Err<E>, constructor: C): Result.Err<E & InstanceType<C>>;
declare function assertErrorInstanceOf<T, E, C extends abstract new (..._: any) => any>(this: Result<T, E>, constructor: C): Result<T, E & InstanceType<C>>;
export {};