retuple 1.0.0-next.2 → 1.0.0-next.21

package/dist/index.d.cts

@@ -1,75 +1,144 @@
-export type Ok<T> = OkTuple<T> & Retuple<T, never>;
-export type Err<E> = ErrTuple<E> & Retuple<never, E>;
+import { type ResultLike } from "retuple-symbols";
+export type Ok = typeof Ok;
+export type Err = typeof Err;
 export type Result<T, E> = (OkTuple<T> | ErrTuple<E>) & Retuple<T, E>;
-export { type ResultAsync };
-export declare class RetupleUnwrapFailed<E = unknown> extends Error {
+export { type ResultAsync, type ResultRetry };
+export interface ResultRetryController<E> {
+    error: E;
+    attempt: number;
+    abort: () => void;
+}
+/**
+ * ## Retuple Unwrap Failed
+ *
+ * An error which occurs when calling `$unwrap` on `Err`.
+ */
+export declare class RetupleUnwrapFailed<const E = unknown> extends Error {
     value: E;
     constructor(value: E, msg?: string);
 }
-export declare class RetupleUnwrapErrFailed<T = unknown> extends Error {
+/**
+ * ## Retuple Unwrap Err Failed
+ *
+ * An error which occurs when calling `$unwrapErr` on `Ok`.
+ */
+export declare class RetupleUnwrapErrFailed<const T = unknown> extends Error {
     value: T;
     constructor(value: T, msg?: string);
 }
-export declare class RetupleExpectFailed<E = unknown> extends Error {
+/**
+ * ## Retuple Expect Failed
+ *
+ * An error which occurs when calling `$expect` on `Err`, when the value
+ * contained in the `Err` is not an instance of `Error`.
+ */
+export declare class RetupleExpectFailed<const E = unknown> extends Error {
     value: E;
     constructor(value: E);
 }
-export declare class RetupleThrownValueError extends Error {
+/**
+ * ## Retuple Thrown Value Error
+ *
+ * An error constructed when a safe function call throws or rejects, when the
+ * thrown error or rejected value is not an instance of `Error`, and when no
+ * map error function is provided.
+ */
+export declare class RetupleCaughtValueError extends Error {
     value: unknown;
     constructor(value: unknown);
 }
 /**
- * ## Result
+ * ## Retuple Invalid Union Error
  *
- * @TODO
+ * This error is thrown when attempting to construct a `Result` from a
+ * discriminated union, when the 'success' property is not boolean. In this
+ * case, it is impossible to determine whether the result should be `Ok` or
+ * `Err`.
  */
-export declare const Result: {
-    Ok: typeof Ok;
-    Err: typeof Err;
-    from: typeof from;
-    safe: typeof safe;
-    safeAsync: typeof safeAsync;
-    safePromise: typeof safePromise;
-};
-export default Result;
+export declare class RetupleInvalidUnionError extends Error {
+    value: unknown;
+    constructor(value: unknown);
+}
 /**
- * ## Ok
+ * ## Result
  *
  * @TODO
  */
-export declare function Ok(): Ok<void>;
-export declare function Ok<T>(val: T): Ok<T>;
+export declare function Result<T, E>(resultLike: ResultLike<T, E>): Result<T, E>;
+export declare namespace Result {
+    var Ok: typeof import(".").Ok;
+    var Err: typeof import(".").Err;
+    var $from: <T, E>(result: ResultLike<T, E>) => Result<T, E>;
+    var $resolve: <T, E>(result: ResultLikeAwaitable<T, E>) => ResultAsync<T, E>;
+    var $nonNullable: {
+        <const T>(value: T): Result<NonNullable<T>, true>;
+        <const T, E>(value: T, error: () => E): Result<NonNullable<T>, E>;
+    };
+    var $truthy: {
+        <const T>(value: T): Result<Truthy<T>, true>;
+        <const T, E>(value: T, error: () => E): Result<Truthy<T>, E>;
+    };
+    var $fromUnion: <U extends ObjectUnionOk<any> | ObjectUnionErr<any>>(union: U) => Result<U extends ObjectUnionOk<infer T> ? T : never, U extends ObjectUnionErr<infer E> ? E : never>;
+    var $safe: {
+        <T>(f: () => Awaited<T>): Result<T, Error>;
+        <T, E>(f: () => Awaited<T>, mapError: (err: unknown) => E): Result<T, E>;
+    };
+    var $safeAsync: {
+        <T>(f: () => T | PromiseLike<T>): ResultAsync<T, Error>;
+        <T, E>(f: () => T | PromiseLike<T>, mapError: (err: unknown) => E): ResultAsync<T, E>;
+    };
+    var $safePromise: {
+        <T>(promise: PromiseLike<T>): ResultAsync<T, Error>;
+        <T, E>(promise: PromiseLike<T>, mapError: (err: unknown) => E): ResultAsync<T, E>;
+    };
+    var $retry: <T, E>(f: () => ResultLike<T, E> | PromiseLike<ResultLike<T, E>>) => ResultRetry<T, E>;
+    var $safeRetry: {
+        <T>(f: () => T | PromiseLike<T>): ResultRetry<T, Error>;
+        <T, E>(f: () => T | PromiseLike<T>, mapError: (err: unknown) => E): ResultRetry<T, E>;
+    };
+}
 /**
- * ## Err
+ * Create a new {@link Result} with the `Ok` variant. When called without
+ * arguments the `T` type is `void`.
  *
- * @TODO
- */
-export declare function Err(): Err<void>;
-export declare function Err<E>(err: E): Err<E>;
-/**
- * Construct a {@link Result} from a value. If the value is truthy, the result
- * is `Ok`.
- */
-export declare function from<T>(value: T): Result<Truthy<T>, true>;
-export declare function from<T, E>(value: T, error: () => E): Result<Truthy<T>, E>;
-/**
- * Construct a {@link Result} from a synchronous function call. If the function
- * returns without throwing, the result is `Ok`.
- */
-export declare function safe<T>(f: () => Awaited<T>): Result<T, Error>;
-export declare function safe<T, E>(f: () => Awaited<T>, mapError: (err: unknown) => E): Result<T, E>;
-/**
- * Construct a {@link ResultAsync} from a function call. If the function returns
- * without throwing, and any promise returned resolves, the result is `Ok`.
+ * @example
+ *
+ * ```ts
+ * const [err, value] = Ok("test");
+ *
+ * assert.equal(err, undefined);
+ * assert.equal(value, "test");
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const result: Result<void, never> = Ok();
+ * ```
  */
-export declare function safeAsync<T>(f: () => T | PromiseLike<T>): ResultAsync<T, Error>;
-export declare function safeAsync<T, E>(f: () => T | PromiseLike<T>, mapError: (err: unknown) => E): ResultAsync<T, E>;
+export declare function Ok(): Result<void, never>;
+export declare function Ok<const T>(val: T): Result<T, never>;
 /**
- * Construct a {@link Result} from a promise. If the promise resolves, the
- * result is `Ok`.
+ * Create a new {@link Result} with the `Err` variant. When called without
+ * arguments the `E` type is `void`.
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = Err("test");
+ *
+ * assert.equal(err, "test");
+ * assert.equal(value, undefined);
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const result: Result<never, void> = Err();
+ * ```
  */
-export declare function safePromise<T>(promise: PromiseLike<T>): ResultAsync<T, Error>;
-export declare function safePromise<T, E>(promise: PromiseLike<T>, mapError: (err: unknown) => E): ResultAsync<T, E>;
+export declare function Err(): Result<never, void>;
+export declare function Err<const E>(err: E): Result<never, E>;
 /**
  * ## ResultAsync
  *
@@ -78,340 +147,1317 @@ export declare function safePromise<T, E>(promise: PromiseLike<T>, mapError: (er
 declare class ResultAsync<T, E> {
     #private;
     constructor(inner: PromiseLike<Result<T, E>>);
-    then<TResult1 = Result<T, E>, TResult2 = never>(onfulfilled?: ((result: Result<T, E>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: (reason: any) => TResult2 | PromiseLike<TResult2>): PromiseLike<TResult1 | TResult2>;
-    /**
-     * @TODO
-     */
-    $value(this: ResultAsync<T, E>): Promise<T | E>;
+    then<U = Result<T, E>, F = never>(onfulfilled?: ((value: Result<T, E>) => U | PromiseLike<U>) | null | undefined, onrejected?: ((reason: any) => F | PromiseLike<F>) | null | undefined): PromiseLike<U | F>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$expect|$expect}, except it returns a `Promise`.
      */
     $expect(this: ResultAsync<T, Error>): Promise<T>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$unwrap|$unwrap}, except it returns a `Promise`.
      */
     $unwrap(this: ResultAsync<T, E>, msg?: string): Promise<T>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$unwrapErr|$unwrapErr}, except it returns
+     * a `Promise`.
      */
     $unwrapErr(this: ResultAsync<T, E>, msg?: string): Promise<E>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$unwrapOr|$unwrapOr}, except it returns
+     * a `Promise`.
      */
-    $unwrapOr<U>(this: ResultAsync<T, E>, def: U): Promise<T | U>;
+    $unwrapOr<const U = T>(this: ResultAsync<T, E>, def: U): Promise<T | U>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$unwrapOrElse|$unwrapOrElse}, except it returns
+     * a `Promise`.
      */
     $unwrapOrElse<U = T>(this: ResultAsync<T, E>, f: () => U): Promise<T | U>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$map|$map}, except it returns
+     * {@link ResultAsync}.
      */
     $map<U>(this: ResultAsync<T, E>, f: (val: T) => U): ResultAsync<U, E>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$mapErr|$mapErr}, except it returns
+     * {@link ResultAsync}.
      */
-    $mapErr<F>(this: ResultAsync<T, E>, f: (err: E) => F): ResultAsync<T, F>;
+    $mapErr<F = E>(this: ResultAsync<T, E>, f: (err: E) => F): ResultAsync<T, F>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$mapOr|$mapOr}, except it returns
+     * {@link ResultAsync}.
      */
-    $mapOr<U>(this: ResultAsync<T, E>, def: U, f: (val: T) => U): ResultAsync<U, E>;
+    $mapOr<U, V = U>(this: ResultAsync<T, E>, def: U, f: (val: T) => V): ResultAsync<U | V, never>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$mapOrElse|$mapOrElse}, except it returns
+     * {@link ResultAsync}.
      */
-    $mapOrElse<U>(this: ResultAsync<T, E>, def: (err: E) => U, f: (val: T) => U): ResultAsync<U, E>;
+    $mapOrElse<U, V = U>(this: ResultAsync<T, E>, def: (err: E) => U, f: (val: T) => V): ResultAsync<U | V, never>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$andAssertOr|$andAssertOr}, except it:
+     *
+     * - can also accept a `PromiseLike` default value;
+     * - returns {@link ResultAsync}.
      */
-    $or<U = T, F = E>(this: ResultAsync<T, E>, or: Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<T | U, E | F>;
+    $andAssertOr<U = T, F = E>(this: ResultAsync<T, E>, def: ResultLikeAwaitable<U, F>): ResultAsync<Truthy<T> | U, E | F>;
+    $andAssertOr<U = T, F = E, A extends T = T>(this: ResultAsync<T, E>, def: ResultLikeAwaitable<U, F>, predicate: (val: T) => val is A): ResultAsync<U | A, E | F>;
+    $andAssertOr<U = T, F = E>(this: ResultAsync<T, E>, def: ResultLikeAwaitable<U, F>, condition: (val: T) => unknown): ResultAsync<T | U, E | F>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$andAssertOrElse|$andAssertOrElse}, except it:
+     *
+     * - can also accept an `async` default function;
+     * - returns {@link ResultAsync}.
      */
-    $orElse<U = T, F = E>(this: ResultAsync<T, E>, f: (err: E) => Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<T | U, E | F>;
+    $andAssertOrElse<U = T, F = E>(this: ResultAsync<T, E>, def: (val: T) => ResultLikeAwaitable<U, F>): ResultAsync<Truthy<T> | U, E | F>;
+    $andAssertOrElse<U = T, F = E, A extends T = T>(this: ResultAsync<T, E>, def: (val: T) => ResultLikeAwaitable<U, F>, predicate: (val: T) => val is A): ResultAsync<U | A, E | F>;
+    $andAssertOrElse<U = T, F = E>(this: ResultAsync<T, E>, def: (val: T) => ResultLikeAwaitable<U, F>, condition: (val: T) => unknown): ResultAsync<T | U, E | F>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$or|$or}, except it:
+     *
+     * - can also accept a `PromiseLike` or value;
+     * - returns {@link ResultAsync}.
      */
-    $orSafe<U = T, F = Error>(this: ResultAsync<T, E>, f: (err: E) => U | PromiseLike<U>, mapError?: (err: unknown) => F): ResultAsync<T | U, E | F>;
+    $or<U = T, F = E>(this: ResultAsync<T, E>, or: ResultLikeAwaitable<U, F>): ResultAsync<T | U, F>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$orElse|$orElse}, except it:
+     *
+     * - can also accept an `async` or function;
+     * - returns {@link ResultAsync}.
      */
-    $and<U = T, F = E>(this: ResultAsync<T, E>, and: Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<U, E | F>;
+    $orElse<U = T, F = E>(this: ResultAsync<T, E>, f: (err: E) => ResultLikeAwaitable<U, F>): ResultAsync<T | U, F>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$orSafe|$orSafe}, except it:
+     *
+     * - can also accept an `async` safe function;
+     * - returns {@link ResultAsync}.
      */
-    $andThen<U = T, F = E>(this: ResultAsync<T, E>, f: (val: T) => Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<U, E | F>;
+    $orSafe<U = T>(this: ResultAsync<T, E>, f: (err: E) => U | PromiseLike<U>): ResultAsync<T | U, Error>;
+    $orSafe<U = T, F = E>(this: ResultAsync<T, E>, f: (err: E) => U | PromiseLike<U>, mapError: (err: unknown) => F): ResultAsync<T | U, F>;
     /**
-     * @TODO
+     * Returns {@link ResultAsync} based on the outcome of the promise when this
+     * result is `Err`.
+     *
+     * Otherwise, returns `Ok` containing the current contained value.
+     *
+     * Uses the same strategy as {@link Result.$safePromise}, equivalent to
+     * calling:
+     *
+     * ```ts
+     * resultAsync.$orElse(() => Result.$safePromise(...))
+     * ```
      */
-    $andThrough<F = E>(this: ResultAsync<T, E>, f: (val: T) => Result<any, F> | PromiseLike<Result<any, F>>): ResultAsync<T, E | F>;
+    $orSafePromise<U = T>(this: ResultAsync<T, E>, promise: PromiseLike<U>): ResultAsync<T | U, Error>;
+    $orSafePromise<U = T, F = E>(this: ResultAsync<T, E>, promise: PromiseLike<U>, mapError: (err: unknown) => F): ResultAsync<T | U, F>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$and|$and}, except it:
+     *
+     * - can also accept a `PromiseLike` and value;
+     * - returns {@link ResultAsync}.
      */
-    $andSafe<U = T, F = Error>(this: ResultAsync<T, E>, f: (val: T) => U | PromiseLike<U>, mapError?: (err: unknown) => F): ResultAsync<U, E | F>;
+    $and<U = T, F = E>(this: ResultAsync<T, E>, and: ResultLikeAwaitable<U, F>): ResultAsync<U, E | F>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$andThen|$andThen}, except it:
+     *
+     * - can also accept an `async` and function;
+     * - returns {@link ResultAsync}.
      */
-    $peek(this: ResultAsync<T, E>, f: (res: Result<T, E>) => any): ResultAsync<T, E>;
+    $andThen<U = T, F = E>(this: ResultAsync<T, E>, f: (val: T) => ResultLikeAwaitable<U, F>): ResultAsync<U, E | F>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$andThrough|$andThrough}, except it:
+     *
+     * - can also accept an `async` through function;
+     * - returns {@link ResultAsync}.
      */
-    $tap(this: ResultAsync<T, E>, f: (val: T) => any): ResultAsync<T, E>;
+    $andThrough<F = E>(this: ResultAsync<T, E>, f: (val: T) => ResultLikeAwaitable<any, F>): ResultAsync<T, E | F>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$andSafe|$andSafe}, except it:
+     *
+     * - can also accept an `async` safe function;
+     * - returns {@link ResultAsync}.
      */
-    $tapErr(this: ResultAsync<T, E>, f: (err: E) => any): ResultAsync<T, E>;
+    $andSafe<U = T>(this: ResultAsync<T, E>, f: (val: T) => U | PromiseLike<U>): ResultAsync<U, E | Error>;
+    $andSafe<U = T, F = E>(this: ResultAsync<T, E>, f: (val: T) => U | PromiseLike<U>, mapError: (err: unknown) => F): ResultAsync<U, E | F>;
     /**
-     * @TODO
+     * Returns {@link ResultAsync} based on the outcome of the promise when this
+     * result is `Ok`.
+     *
+     * Otherwise, returns `Err` containing the current error value.
+     *
+     * Uses the same strategy as {@link Result.$safePromise}, equivalent to
+     * calling:
+     *
+     * ```ts
+     * resultAsync.$andThen(() => Result.$safePromise(...))
+     * ```
+     */
+    $andSafePromise<U = T>(this: ResultAsync<T, E>, promise: PromiseLike<U>): ResultAsync<U, E | Error>;
+    $andSafePromise<U = T, F = E>(this: ResultAsync<T, E>, promise: PromiseLike<U>, mapError: (err: unknown) => F): ResultAsync<U, E | F>;
+    /**
+     * The same as {@link Retuple.$peek|$peek}, except it:
+     *
+     * - awaits the peek function;
+     * - returns {@link ResultAsync}.
      */
-    $promise(this: ResultAsync<T, E>): Promise<Result<T, E>>;
-}
-type OkTuple<T> = [err: undefined, value: T];
-type ErrTuple<E> = [err: E, value: undefined];
-type Truthy<T> = Exclude<T, false | null | undefined | 0 | 0n | "">;
-/**
- * @TODO - Result.all / Result.any
- */
-interface Retuple<T, E> {
-    /**
-     * @TODO
-     */
-    $isOk(this: Result<T, E>): this is Ok<T>;
+    $peek(this: ResultAsync<T, E>, f: (res: Result<T, E>) => any): ResultAsync<T, E>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$tap|$tap}, except it:
+     *
+     * - awaits the tap function;
+     * - returns {@link ResultAsync}.
      */
-    $isOkAnd<U extends T = T>(this: Result<T, E>, f: ((val: T) => val is U) | ((val: T) => boolean)): this is Ok<U>;
+    $tap(this: ResultAsync<T, E>, f: (val: T) => any): ResultAsync<T, E>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$tapErr|$tapErr}, except it:
+     *
+     * - awaits the tap error function;
+     * - returns {@link ResultAsync}.
      */
-    $isErr(this: Result<T, E>): this is Err<E>;
+    $tapErr(this: ResultAsync<T, E>, f: (err: E) => any): ResultAsync<T, E>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$promise|$promise}.
      */
-    $isErrAnd<F extends E = E>(this: Result<T, E>, f: ((err: E) => err is F) | ((err: E) => boolean)): this is Err<F>;
+    $promise(this: ResultAsync<T, E>): Promise<Result<T, E>>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$iter|$iter}, except it returns a `Promise`.
      */
-    $value(this: Result<T, E>): T | E;
-    /**
-     * @TODO
+    $iter<U>(this: ResultAsync<Iterable<U>, E>): Promise<IterableIterator<U, undefined, unknown>>;
+}
+/**
+ * ## ResultRetry
+ */
+declare class ResultRetry<T, E> extends ResultAsync<T, E> implements PromiseLike<Result<T, E>> {
+    #private;
+    private static MAX_TIMEOUT;
+    private static MAX_RETRY;
+    private static zero;
+    private static delay;
+    private static integer;
+    constructor(f: () => ResultLikeAwaitable<T, E>);
+    then<U = Result<T, E>, F = never>(this: ResultRetry<T, E>, onfulfilled?: ((value: Result<T, E>) => U | PromiseLike<U>) | null | undefined, onrejected?: ((reason: any) => F | PromiseLike<F>) | null | undefined): PromiseLike<U | F>;
+    /**
+     * Sets the maximum number of times the retry function can be executed,
+     * mutating this `ResultRetry` instance.
+     *
+     * **The default value is 1 - meaning that unless set, no retries will be
+     * attempted.**
+     *
+     * The retry function can be called up to the maximum number of times until
+     * it returns `Ok`. If it never returns `Ok`, the  most recent `Err` is
+     * returned.
+     *
+     * This function accepts a positive integer between 1 and 100:
+     *
+     * - Integers outside of this range are clamped to the nearest valid value;
+     * - Any other value (NaN, Infinity, fractions, strings) are treated as 1.
+     *
+     * @example
+     *
+     * ```ts
+     * // Retry someResultFn up to 3 times until Ok is returned:
+     * const result = await Result.$retry(someResultFn).$times(3);
+     * ```
+     */
+    $times<N extends number>(this: ResultRetry<T, E>, times: NonZero<N> & NonNegativeOrDecimal<N>): ResultRetry<T, E>;
+    /**
+     * Sets the delay between each retry attempt, mutating this `ResultRetry`
+     * instance.
+     *
+     * - Provide a number of milliseconds to introduce a static delay between
+     *   attempts;
+     * - Provide a function to compute the delay dynamically for each attempt;
+     * - If the maximum number of retries is 1, this setting as no effect.
+     *
+     * **The default value is 0 - meaning that unless set, there will be no delay
+     * between attempts.**
+     *
+     * This function accepts an integer between 0 and 3600000:
+     *
+     * - Integers outside of this range are clamped to the nearest valid value;
+     * - Any other value (NaN, Infinity, fractions, strings) are treated as 0.
+     *
+     * @example
+     *
+     * ```ts
+     * // Retry someResultFn up to 3 times until Ok is returned,
+     * // with a 1 second delay between each invocation:
+     * const result = await Result.$retry(someResultFn).$times(3).$delay(1000);
+     * ```
+     */
+    $delay<N extends number>(this: ResultRetry<T, E>, f: (attempt: number) => NonNegativeOrDecimal<N>): ResultRetry<T, E>;
+    $delay<N extends number>(this: ResultRetry<T, E>, ms: NonNegativeOrDecimal<N>): ResultRetry<T, E>;
+    /**
+     * Sets a handler to be called when an attempt returns `Err`, mutating this
+     * `ResultRetry` instance. The handler can be used to capture information
+     * about each failure, and to abort early and prevent further retries.
+     *
+     * The handler function is called with `ResultRetryHandleState`, containing:
+     *
+     * - **error** - The error value from the last failed attempt;
+     * - **attempt** - The attempt number;
+     * - **abort** - A function which when called, prevents further retries.
+     *
+     * @example
+     *
+     * ```ts
+     * // Retry someResultFn up to 3 times until Ok is returned, logging each
+     * // attempt and aborting early if the error code is "UNAUTHORIZED".
+     * const result = await Result.$retry(someResultFn)
+     *    .$times(3)
+     *    .$handle(({ error, attempt, abort }) => {
+     *       console.info(`Attempt ${attempt} failed: ${error}`);
+     *       if (error === "UNAUTHORIZED") {
+     *          abort();
+     *       }
+     *    });
+     * ```
+     */
+    $handle(f: (controller: ResultRetryController<E>) => void): ResultRetry<T, E>;
+    private drain;
+}
+interface Retuple<T, E> extends ResultLike<T, E> {
+    /**
+     * Returns true when this result is `Ok`. Acts as a type guard.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(result.$isOk(), true);
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(result.$isOk(), false);
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, Error> = someResultFn();
+     *
+     * if (result.$isOk()) {
+     *    result satisfies Result<string, never>;
+     * }
+     * ```
+     */
+    $isOk(this: Result<T, E>): this is Result<T, never>;
+    /**
+     * Returns true when this result is `Ok`, and when the predicate/condition
+     * function returns true. Acts as a type guard.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(result.$isOkAnd((val) => val === "test"), true);
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok<string>("test");
+     * assert.equal(result.$isOkAnd((val) => val !== "test"), false);
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(result.$isOkAnd((err) => err === "test"), false);
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string | number, Error> = someResultFn();
+     *
+     * if (result.$isOkAnd((val): val is number => typeof val === "number")) {
+     *    result satisfies Result<number, never>;
+     * }
+     * ```
+     */
+    $isOkAnd<U extends T = T>(this: Result<T, E>, predicate: (val: T) => val is U): this is Result<U, never>;
+    $isOkAnd(this: Result<T, E>, predicate: (val: T) => unknown): this is Result<T, never>;
+    /**
+     * Returns true when this result is `Err`. Acts as a type guard.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(result.$isErr(), true);
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(result.$isErr(), false);
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, Error> = someResultFn();
+     *
+     * if (result.$isErr()) {
+     *    result satisfies Result<never, Error>;
+     * }
+     * ```
+     */
+    $isErr(this: Result<T, E>): this is Result<never, E>;
+    /**
+     * Returns true when this result is `Err`, and when the predicate/condition
+     * function returns true. Acts as a type guard.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(result.$isErrAnd((err) => err === "test"), true);
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err<string>("test");
+     * assert.equal(result.$isErrAnd((err) => err !== "test"), false);
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(result.$isErrAnd((val) => val === "test"), false);
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, Error | number> = someResultFn();
+     *
+     * if (result.$isErrAnd((err): err is number => typeof err === "number")) {
+     *    result satisfies Result<never, number>;
+     * }
+     * ```
+     */
+    $isErrAnd<F extends E = E>(this: Result<T, E>, prediacte: (val: E) => val is F): this is Result<never, F>;
+    $isErrAnd(this: Result<T, E>, predicate: (val: E) => unknown): this is Result<never, E>;
+    /**
+     * Returns the ok value when this result is `Ok`.
+     *
+     * Otherwise, the error value is thrown.
+     *
+     * This method should only be called when the `E` type extends `Error`. This
+     * is enforced with a type constraint. If the error value is not an instance
+     * of Error, `RetupleExpectFailed` is thrown. Use
+     * {@link Retuple.$unwrap|$unwrap} When the `E` type does not extend Error.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(result.$expect(), "test");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const error = new Error("test");
+     * const result = Err(error);
+     *
+     * try {
+     *   const value = result.$expect(); // throws
+     * } catch (e) {
+     *   assert.equal(e, error);
+     * }
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     *
+     * try {
+     *   // This is a type error - the E type does not extend Error
+     *   const value = result.$expect(); // throws
+     * } catch (e) {
+     *   assert(e instanceof RetupleExpectFailed && e.value === "test");
+     * }
+     * ```
      */
     $expect(this: Result<T, Error>): T;
     /**
-     * @TODO
+     * Returns the ok value when this result is `Ok`.
+     *
+     * Otherwise, `RetupleUnwrapFailed` is thrown. A custom error message can be
+     * provided.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(result.$unwrap(), "test");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     *
+     * try {
+     *   const value = result.$unwrap(); // throws
+     * } catch (e) {
+     *   assert(e instanceof RetupleUnwrapFailed && e.value === "test");
+     * }
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const error = new Error("test");
+     * const result = Err(error);
+     *
+     * try {
+     *   const value = result.$unwrap("error-message"); // throws
+     * } catch (e) {
+     *   assert(
+     *      e instanceof RetupleUnwrapFailed &&
+     *      e.message === "error-message" &&
+     *      e.value === error &&
+     *      e.cause === error, // set when error value was an instance of `Error`
+     *   );
+     * }
+     * ```
      */
     $unwrap(this: Result<T, E>, msg?: string): T;
     /**
-     * @TODO
+     * Returns the error value when this result is `Err`.
+     *
+     * Otherwise, `RetupleUnwrapErrFailed` is thrown. A custom error message can
+     * be provided.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(result.$unwrapErr(), "test");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     *
+     * try {
+     *   const value = result.$unwrapErr(); // throws
+     * } catch (e) {
+     *   assert(e instanceof RetupleUnwrapErrFailed && e.value === "test");
+     * }
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     *
+     * try {
+     *   const value = result.$unwrapErr("error-message"); // throws
+     * } catch (e) {
+     *   assert(
+     *      e instanceof RetupleUnwrapErrFailed &&
+     *      e.message === "error-message" &&
+     *      e.value === "test",
+     *   );
+     * }
+     * ```
      */
     $unwrapErr(this: Result<T, E>, msg?: string): E;
     /**
-     * @TODO
-     */
-    $unwrapOr<U = T>(this: Result<T, E>, def: U): T | U;
-    /**
-     * @TODO
+     * Returns the ok value when this result is `Ok`.
+     *
+     * Otherwise, returns the default value.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(result.$unwrapOr("default"), "test");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(result.$unwrapOr("default"), "default");
+     * ```
+     */
+    $unwrapOr<const U = T>(this: Result<T, E>, def: U): T | U;
+    /**
+     * Returns the ok value when this result is `Ok`.
+     *
+     * Otherwise, returns the value returned by the default function.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(result.$unwrapOrElse(() => "default"), "test");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(result.$unwrapOrElse(() => "default"), "default");
+     * ```
      */
     $unwrapOrElse<U = T>(this: Result<T, E>, f: () => U): T | U;
     /**
-     * @TODO
+     * Performs an assertion when this result is `Ok`:
+     *
+     * - returning `Ok` containing the current ok value when it is truthy, and
+     *   when no predicate/condition function is provided. Narrows the `T` type
+     *   to include only truthy values;
+     * - returning `Ok` containing the current ok value when a
+     *   predicate/condition function  is provided and it returns a truthy value.
+     *   Narrows the `T` type to the predicate type (if any);
+     * - returning the default result when no predicate/condition function is
+     *   provided and the current ok value is falsey;
+     * - returning the default result when a predicate/condition function is
+     *   provided and it returns a falsey value.
+     *
+     * Otherwise returns `Err` containing the current error value.
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string | null, string> = Ok("test");
+     * const asserted = result.$andAssertOr(Ok("ok-default"));
+     *
+     * asserted satisfies Result<string, string>;
+     * assert.equal(asserted.$unwrap(), "test");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string | null, string> = Ok("test");
+     * const asserted = result.$andAssertOr(
+     *    Err("err-default"),
+     *    (val): val is "test" => val === "test",
+     * );
+     *
+     * asserted satisfies Result<"test", string>;
+     * assert.equal(asserted.$unwrap(), "test");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string | null, string> = Ok(null);
+     * const asserted = result.$andAssertOr(Ok("ok-default"));
+     *
+     * asserted satisfies Result<string, string>;
+     * assert.equal(asserted.$unwrap(), "ok-default");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string | null, string> = Ok("value");
+     * const asserted = result.$andAssertOr(
+     *    Err("err-default"),
+     *    (val): val is "test" => val === "test",
+     * );
+     *
+     * asserted satisfies Result<"test", string>;
+     * assert.equal(asserted.$unwrapErr(), "err-default");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string | null, string> = Err("test");
+     * const asserted = result.$andAssertOr(
+     *    Err("err-default"),
+     *    (val): val is "test" => val === "test",
+     * );
+     *
+     * asserted satisfies Result<"test", string>;
+     * assert.equal(asserted.$unwrapErr(), "test");
+     * ```
+     */
+    $andAssertOr<U = T, F = E>(this: Result<T, E>, def: ResultLike<U, F>): Result<Truthy<T> | U, E | F>;
+    $andAssertOr<U = T, F = E, A extends T = T>(this: Result<T, E>, def: ResultLike<U, F>, predicate: (val: T) => val is A): Result<U | A, E | F>;
+    $andAssertOr<U = T, F = E>(this: Result<T, E>, def: ResultLike<U, F>, condition: (val: T) => unknown): Result<T | U, E | F>;
+    /**
+     * Performs an assertion when this result is `Ok`:
+     *
+     * - returning `Ok` containing the current ok value when it is truthy, and
+     *   when no predicate/condition function is provided. Narrows the `T` type
+     *   to include only truthy values;
+     * - returning `Ok` containing the current ok value when a
+     *   predicate/condition function  is provided and it returns a truthy value.
+     *   Narrows the `T` type to the predicate type (if any);
+     * - returning the result returned by the default function when no
+     *   predicate/condition function is provided and the current ok value is
+     *   falsey;
+     * - returning the result returned by the default function when a
+     *   predicate/condition function is  provided and it returns a falsey value.
+     *
+     * Otherwise returns `Err` containing the current error value.
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string | null, string> = Ok("test");
+     * const asserted = result.$andAssertOrElse(
+     *    (val) => Ok(`ok-default:${val}`),
+     * );
+     *
+     * asserted satisfies Result<string, string>;
+     * assert.equal(asserted.$unwrap(), "test");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string | null, string> = Ok("test");
+     * const asserted = result.$andAssertOrElse(
+     *    (val) => Err(`err-default:${val}`),
+     *    (val): val is "test" => val === "test",
+     * );
+     *
+     * asserted satisfies Result<"test", string>;
+     * assert.equal(asserted.$unwrap(), "test");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string | null, string> = Ok(null);
+     * const asserted = result.$andAssertOrElse(
+     *    (val) => Ok(`ok-default:${val}`),
+     * );
+     *
+     * asserted satisfies Result<string, string>;
+     * assert.equal(asserted.$unwrap(), "ok-default:null");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string | null, string> = Ok("value");
+     * const asserted = result.$andAssertOrElse(
+     *    (val) => Err(`err-default:${val}`),
+     *    (val): val is "test" => val === "test",
+     * );
+     *
+     * asserted satisfies Result<"test", string>;
+     * assert.equal(asserted.$unwrapErr(), "err-default:value");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string | null, string> = Err("test");
+     * const asserted = result.$andAssertOrElse(
+     *    (val) => Err(`err-default:${val}`),
+     *    (val): val is "test" => val === "test",
+     * );
+     *
+     * asserted satisfies Result<"test", string>;
+     * assert.equal(asserted.$unwrapErr(), "test");
+     * ```
+     */
+    $andAssertOrElse<U = T, F = E>(this: Result<T, E>, def: (val: T) => ResultLike<U, F>): Result<Truthy<T> | U, E | F>;
+    $andAssertOrElse<U = T, F = E, A extends T = T>(this: Result<T, E>, def: (val: T) => ResultLike<U, F>, predicate: (val: T) => val is A): Result<U | A, E | F>;
+    $andAssertOrElse<U = T, F = E>(this: Result<T, E>, def: (val: T) => ResultLike<U, F>, condition: (val: T) => unknown): Result<T | U, E | F>;
+    /**
+     * Returns `Ok` containing the return value of the map function when this
+     * result is `Ok`.
+     *
+     * Otherwise, returns `Err` containing the current error value.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(
+     *    result.$map((val) => `map:${val}`).$unwrap(),
+     *    "map:test",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, string> = Err("test");
+     * assert.equal(
+     *    result.$map((val) => `map:${val}`).$unwrapErr(),
+     *    "test",
+     * );
+     * ```
      */
     $map<U>(this: Result<T, E>, f: (value: T) => U): Result<U, E>;
     /**
-     * @TODO
-     */
-    $mapErr<F>(this: Result<T, E>, f: (err: E) => F): Result<T, F>;
-    /**
-     * @TODO
-     */
-    $mapOr<U>(this: Result<T, E>, def: U, f: (val: T) => U): Result<U, E>;
-    /**
-     * @TODO
-     */
-    $mapOrElse<U>(this: Result<T, E>, def: (err: E) => U, f: (val: T) => U): Result<U, E>;
-    /**
-     * @TODO
-     */
-    $or<U = T, F = E>(this: Result<T, E>, or: Result<U, F>): Result<T | U, E | F>;
-    /**
-     * @TODO
-     */
-    $orElse<U = never, F = never>(this: Result<T, E>, f: (err: E) => Result<U, F>): Result<T | U, E | F>;
-    /**
-     * @TODO
-     */
-    $orSafe<U = T>(this: Result<T, E>, f: (err: E) => U): Result<T | U, E | Error>;
-    $orSafe<U = T, F = E>(this: Result<T, E>, f: (err: E) => U, mapError: (err: unknown) => F): Result<T | U, E | F>;
-    $orSafe<U = T, F = Error>(this: Result<T, E>, f: (err: E) => U, mapError: (err: unknown) => F): Result<T | U, E | F>;
-    /**
-     * @TODO
-     */
-    $and<U = T, F = E>(this: Result<T, E>, and: Result<U, F>): Result<U, E | F>;
-    /**
-     * @TODO
-     */
-    $andThen<U = never, F = never>(this: Result<T, E>, f: (val: T) => Result<U, F>): Result<U, E | F>;
-    /**
-     * @TODO
-     */
-    $andThrough<F = never>(this: Result<T, E>, f: (val: T) => Result<any, F>): Result<T, E | F>;
-    /**
-     * @TODO
-     */
-    $andSafe<U = T>(this: Result<T, E>, f: (val: T) => U): Result<T | U, E | Error>;
-    $andSafe<U = T, F = E>(this: Result<T, E>, f: (val: T) => U, mapError: (err: unknown) => F): Result<T | U, E | F>;
-    $andSafe<U, F = Error>(this: Result<T, E>, f: (val: T) => U, mapError: (err: unknown) => F): Result<T | U, E | F>;
-    /**
-     * @TODO
+     * Returns `Err` containing the return value of the map function when this
+     * result is `Err`.
+     *
+     * Otherwise, returns `Ok` containing the current ok value.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(
+     *    result.$mapErr((err) => `map-err:${err}`).$unwrapErr(),
+     *    "map-err:test",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, string> = Ok("test");
+     * assert.equal(
+     *    result.$mapErr((err) => `map-err:${err}`).$unwrap(),
+     *    "test",
+     * );
+     * ```
+     */
+    $mapErr<F = E>(this: Result<T, E>, f: (err: E) => F): Result<T, F>;
+    /**
+     * Returns `Ok` containing the return value of the map function when this
+     * result is `Ok`.
+     *
+     * Otherwise, returns `Ok` containing the default value.
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, string> = Ok("test");
+     * assert.equal(
+     *    result.$mapOr("default", (val) => `map:${val}`).$unwrap(),
+     *    "map:test",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, string> = Err("test");
+     * assert.equal(
+     *    result.$mapOr("default", (val) => `map:${val}`).$unwrap(),
+     *    "default",
+     * );
+     * ```
+     */
+    $mapOr<U, V = U>(this: Result<T, E>, def: U, f: (val: T) => V): Result<U | V, never>;
+    /**
+     * Returns `Ok` containing the return value of the map function when this
+     * result is `Ok`.
+     *
+     * Otherwise, returns `Ok` containing the return value of the default
+     * function.
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, string> = Ok("test");
+     * assert.equal(
+     *    result.$mapOrElse(
+     *       (err) => `default:${err}`,
+     *       (val) => `map:${val}`,
+     *    ).$unwrap(),
+     *    "map:test",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, string> = Err("test");
+     * assert.equal(
+     *    result.$mapOrElse(
+     *       (err) => `default:${err}`,
+     *       (val) => `map:${val}`,
+     *    ).$unwrap(),
+     *    "default:test",
+     * );
+     * ```
+     */
+    $mapOrElse<U, V = U>(this: Result<T, E>, def: (err: E) => U, f: (val: T) => V): Result<U | V, never>;
+    /**
+     * Returns the or result, when this result is `Err`.
+     *
+     * Otherwise, returns `Ok` containing the current ok value.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(
+     *    result.$or(Ok("or-ok")).$unwrap(),
+     *    "or-ok",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(
+     *    result.$or(Err("or-err")).$unwrapErr(),
+     *    "or-err",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(
+     *    result.$or(Ok("or-ok")).$unwrap(),
+     *    "test",
+     * );
+     * ```
+     */
+    $or<U = T, F = E>(this: Result<T, E>, or: ResultLike<U, F>): Result<T | U, F>;
+    /**
+     * Shorthand for `result.$async().$or(...)`
+     */
+    $orAsync<U = T, F = E>(this: Result<T, E>, or: ResultLikeAwaitable<U, F>): ResultAsync<T | U, F>;
+    /**
+     * Returns the result returned by the or function, when this result is `Err`.
+     *
+     * Otherwise, returns `Ok` containing the current ok value.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(
+     *    result.$orElse((err) => Ok(`or-ok:${err}`)).$unwrap(),
+     *    "or-ok:test",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(
+     *    result.$orElse((err) => Err(`or-err:${err}`)).$unwrapErr(),
+     *    "or-err:test",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, string> = Ok("test");
+     * assert.equal(
+     *    result.$orElse((err) => Ok(`or-ok:${err}`)).$unwrap(),
+     *    "test",
+     * );
+     * ```
+     */
+    $orElse<U = T, F = E>(this: Result<T, E>, f: (err: E) => ResultLike<U, F>): Result<T | U, F>;
+    /**
+     * Shorthand for `result.$async().$orElse(...)`
+     */
+    $orElseAsync<U = T, F = E>(this: Result<T, E>, f: (err: E) => ResultLikeAwaitable<U, F>): ResultAsync<T | U, F>;
+    /**
+     * Returns a {@link Result} based on the outcome of the safe function when
+     * this result is `Err`.
+     *
+     * Otherwise, returns `Ok` containing the current ok value.
+     *
+     * Uses the same strategy as {@link Result.$safe}, equivalent to calling
+     * `result.$or(Result.$safe(...))`.
+     */
+    $orSafe<U = T>(this: Result<T, E>, f: (err: E) => U): Result<T | U, Error>;
+    $orSafe<U = T, F = E>(this: Result<T, E>, f: (err: E) => U, mapError: (err: unknown) => F): Result<T | U, F>;
+    /**
+     * Shorthand for `result.$async().$orSafe(...)`
+     */
+    $orSafeAsync<U = T>(this: Result<T, E>, f: (err: E) => U | PromiseLike<U>): ResultAsync<T | U, Error>;
+    $orSafeAsync<U = T, F = E>(this: Result<T, E>, f: (err: E) => U | PromiseLike<U>, mapError: (err: unknown) => F): ResultAsync<T | U, F>;
+    /**
+     * Shorthand for `result.$async().$orSafePromise(...)`
+     */
+    $orSafePromise<U = T>(this: Result<T, E>, promise: PromiseLike<U>): ResultAsync<T | U, Error>;
+    $orSafePromise<U = T, F = E>(this: Result<T, E>, promise: PromiseLike<U>, mapError: (err: unknown) => F): ResultAsync<T | U, F>;
+    /**
+     * Returns the and result, when this result is `Ok`.
+     *
+     * Otherwise, returns `Err` containing the current error value.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(
+     *    result.$and(Ok("and-ok")).$unwrap(),
+     *    "and-ok",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(
+     *    result.$and(Err("and-err")).$unwrapErr(),
+     *    "and-err",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(
+     *    result.$and(Ok("and-ok")).$unwrapErr(),
+     *    "test",
+     * );
+     * ```
+     */
+    $and<U = T, F = E>(this: Result<T, E>, and: ResultLike<U, F>): Result<U, E | F>;
+    /**
+     * Shorthand for `result.$async().$and(...)`
+     */
+    $andAsync<U = T, F = E>(this: Result<T, E>, and: ResultLikeAwaitable<U, F>): ResultAsync<U, E | F>;
+    /**
+     * Returns the and result, when this result is `Ok`.
+     *
+     * Otherwise, returns `Err` containing the current error value.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(
+     *    result.$and((val) => Ok(`and-ok:${val}`)).$unwrap(),
+     *    "and-ok:test",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(
+     *    result.$and((val) => Err(`and-err:${val}`)).$unwrapErr(),
+     *    "and-err:test",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, string> = Err("test");
+     * assert.equal(
+     *    result.$and((val) => Ok(`and-ok:${val}`)).$unwrapErr(),
+     *    "test",
+     * );
+     * ```
+     */
+    $andThen<U = T, F = E>(this: Result<T, E>, f: (val: T) => ResultLike<U, F>): Result<U, E | F>;
+    /**
+     * Shorthand for `result.$async().$andThen(...)`
+     */
+    $andThenAsync<U = T, F = E>(this: Result<T, E>, f: (val: T) => ResultLikeAwaitable<U, F>): ResultAsync<U, E | F>;
+    /**
+     * Calls the through function when this result is `Ok` and returns:
+     *
+     * - `Ok` containing the original ok value when the through function
+     *   returns `Ok`;
+     * - the `Err` returned by the through function when it returns `Err`.
+     *
+     * Otherwise, returns `Err` containing the current error value.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(
+     *    result.$andThrough((val) => Ok(`ok-through:${val}`)).$unwrap(),
+     *    "test",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(
+     *    result.$andThrough((val) => Err(`err-through:${val}`)).$unwrapErr(),
+     *    "err-through:test",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, string> = Err("test");
+     * assert.equal(
+     *    result.$andThrough((val) => Ok(`ok-through:${val}`)).$unwrapErr(),
+     *    "test",
+     * );
+     * ```
+     */
+    $andThrough<F = E>(this: Result<T, E>, f: (val: T) => ResultLike<any, F>): Result<T, E | F>;
+    /**
+     * Shorthand for `result.$async().$andThrough(...)`
+     */
+    $andThroughAsync<F = E>(this: Result<T, E>, f: (val: T) => ResultLikeAwaitable<any, F>): ResultAsync<T, E | F>;
+    /**
+     * Returns a result based on the outcome of the safe function when this
+     * result is `Ok`.
+     *
+     * Otherwise, returns `Err` containing the current error value.
+     *
+     * Uses the same strategy as {@link Result.$safe}, equivalent to calling:
+     *
+     * ```ts
+     * result.$andThen(() => Result.$safe(...))
+     * ```
+     */
+    $andSafe<U = T>(this: Result<T, E>, f: (val: T) => U): Result<U, E | Error>;
+    $andSafe<U = T, F = E>(this: Result<T, E>, f: (val: T) => U, mapError: (err: unknown) => F): Result<U, E | F>;
+    /**
+     * Shorthand for `result.$async().$andSafe(...)`
+     */
+    $andSafeAsync<U = T>(this: Result<T, E>, f: (val: T) => U | PromiseLike<U>): ResultAsync<U, E | Error>;
+    $andSafeAsync<U = T, F = E>(this: Result<T, E>, f: (val: T) => U | PromiseLike<U>, mapError: (err: unknown) => F): ResultAsync<U, E | F>;
+    /**
+     * Shorthand for `result.$async().$andSafePromise(...)`
+     */
+    $andSafePromise<U = T>(this: Result<T, E>, promise: PromiseLike<U>): ResultAsync<U, E | Error>;
+    $andSafePromise<U = T, F = E>(this: Result<T, E>, promise: PromiseLike<U>, mapError: (err: unknown) => F): ResultAsync<U, E | F>;
+    /**
+     * Calls the peek function and returns {@link Result} equivalent to this
+     * result.
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, string> = Ok("test");
+     * assert.equal(
+     *    result
+     *       .$peek((res) => {
+     *          const [err, value] = res;
+     *
+     *          console.log("Err:", err); // Err: undefined
+     *          console.log("Value:", value); // Value: test
+     *       })
+     *       .$unwrap(),
+     *    "test",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, string> = Err("test");
+     * assert.equal(
+     *    result
+     *       .$peek((res) => {
+     *          const [err, value] = res;
+     *
+     *          console.log("Err:", err); // Err: test
+     *          console.log("Value:", value); // Value: undefined
+     *       })
+     *       .$unwrapErr(),
+     *    "test",
+     * );
+     * ```
      */
     $peek(this: Result<T, E>, f: (res: Result<T, E>) => void): Result<T, E>;
     /**
-     * @TODO
+     * Calls the tap function when this result is `Ok`, and returns `Ok`
+     * containing the current ok value.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.equal(
+     *    result
+     *       .$tap((val) => console.log("Value:", val)) // Value: test
+     *       .$unwrap(),
+     *    "test",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Record<string, string> = Err("test");
+     * assert.equal(
+     *    result
+     *       .$tap((val) => console.log("Value:", val)) // not executed
+     *       .$unwrapErr(),
+     *    "test",
+     * );
+     * ```
      */
     $tap(this: Result<T, E>, f: (val: T) => any): Result<T, E>;
     /**
-     * @TODO
+     * Calls the tap error function when this result is `Err`, and returns `Err`
+     * containing the current error value.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(
+     *    result
+     *       .$tapErr((err) => console.log("Err:", err)) // Err: test
+     *       .$unwrapErr(),
+     *    "test",
+     * );
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Record<string, string> = Ok("test");
+     * assert.equal(
+     *    result
+     *       .$tapErr((err) => console.log("Err:", err)) // not executed
+     *       .$unwrap(),
+     *    "test",
+     * );
+     * ```
      */
     $tapErr(this: Result<T, E>, f: (err: E) => void): Result<T, E>;
     /**
-     * @TODO
+     * Returns the contained {@link Result} when this result is `Ok`.
+     *
+     * Otherwise returns `Err` containing the current error value.
+     *
+     * This method should only be called when the `T` type is `Result`. This
+     * is enforced with a type constraint. If the ok value is not
+     * a result, `RetupleFlattenFailed` is thrown.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok(Ok("test"));
+     * assert.equal(result.$flatten().$unwrap(), "test");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok(Err("test"));
+     * assert.equal(result.$flatten().$unwrapErr(), "test");
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.equal(result.$flatten().$unwrapErr(), "test");
+     * ```
      */
     $flatten<U, F>(this: Result<Result<U, F>, E>): Result<U, E | F>;
     /**
-     * @TODO
+     * Returns an equivalent {@link ResultAsync}.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test").$async();
+     * assert.equal(await result.$unwrap(), "test");
+     * ```
+     * @example
+     *
+     * ```ts
+     * const result = Err("test").$async();
+     * assert.equal(await result.$unwrapErr(), "test");
+     * ```
      */
     $async(this: Result<T, E>): ResultAsync<T, E>;
     /**
-     * @TODO
+     * Returns a `Promise` which resolves to this result.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test").$promise();
+     * assert.equal(await result, result);
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test").$promise();
+     * assert.equal(await result, result);
+     * ```
      */
     $promise(this: Result<T, E>): Promise<Result<T, E>>;
     /**
-     * Mark standard array methods as deprecated, to assist with type hinting.
-     */
-    /**
-     * @deprecated
-     */
-    at(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    concat(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    copyWithin(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    entries(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    every(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    fill(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    filter(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    find(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    findIndex(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    flat(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    flatMap(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    forEach(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    includes(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    indexOf(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    join(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    keys(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    lastIndexOf(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    map(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    pop(...args: unknown[]): any;
-    /**
-     * @deprecated
-     */
-    push(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    reduce(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    reduceRight(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    reverse(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    shift(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    slice(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    some(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    sort(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    splice(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    toString(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    toLocaleString(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    unshift(...args: unknown[]): unknown;
-    /**
-     * @deprecated
-     */
-    values(...args: unknown[]): unknown;
+     * Returns an `IterableIterator` over the contained ok value, when this
+     * result is `Ok`.
+     *
+     * Otherwise, returns an empty `IterableIterator`.
+     *
+     * This method should only be called when the `T` type is `Iterable`. This
+     * is enforced with a type constraint. If the ok value is not iterable,
+     * attempting to iterate over it will throw the built-in error.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok([1, 2, 3]);
+     *
+     * for (const n of result.$iter()) {
+     *    console.log(n); // 1.. 2.. 3
+     * }
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err([1, 2, 3]);
+     *
+     * for (const n of result.$iter()) {
+     *    console.log(n); // not executed, iterator is empty
+     * }
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok<any>(1);
+     *
+     * try {
+     *    for (const n of result.$iter()) {}
+     * } catch (err) {
+     *    // err is 'TypeError: number 1 is not iterable' in V8
+     * }
+     * ```
+     */
+    $iter<U>(this: Result<Iterable<U>, E>): IterableIterator<U, undefined, unknown>;
 }
+type OkTuple<T> = [err: undefined, value: T];
+type ErrTuple<E> = [err: E, value: undefined];
+type ResultLikeAwaitable<T, E> = ResultLike<T, E> | PromiseLike<ResultLike<T, E>>;
+type ObjectUnionOk<T> = {
+    success: true;
+    data: T;
+    error?: never | undefined;
+};
+type ObjectUnionErr<E> = {
+    success: false;
+    data?: never | undefined;
+    error: E;
+};
+type Truthy<T> = Exclude<T, false | null | undefined | 0 | 0n | "">;
+type NonZero<N extends number> = N & (`${N}` extends "0" ? never : N);
+type NonNegativeOrDecimal<N extends number> = N & (`${N}` extends `-${string}` | `${string}.${string}` ? never : N);