retuple 1.0.0-next.5 → 1.0.0-next.8

package/dist/index.d.cts

@@ -1,10 +1,10 @@
+export type Ok = typeof Ok;
+export type Err = typeof Err;
 export type nonNullable = typeof nonNullable;
 export type truthy = typeof truthy;
 export type safe = typeof safe;
 export type safeAsync = typeof safeAsync;
 export type safePromise = typeof safePromise;
-export type Ok<T> = OkTuple<T> & Retuple<T, never>;
-export type Err<E> = ErrTuple<E> & Retuple<never, E>;
 export type Result<T, E> = (OkTuple<T> | ErrTuple<E>) & Retuple<T, E>;
 export { type ResultAsync };
 /**
@@ -28,13 +28,23 @@ export declare class RetupleUnwrapErrFailed<const T = unknown> extends Error {
 /**
  * ## Retuple Expect Failed
  *
- * An error which occurs when calling `$expect` on `Err`, and when the value
+ * 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);
 }
+/**
+ * ## Retuple Expect Failed
+ *
+ * An error which occurs when calling `$flatten` on `Ok`, when the value
+ * contained in the `Ok` is not an `Ok` or `Err`.
+ */
+export declare class RetupleFlattenFailed<const T = unknown> extends Error {
+    value: T;
+    constructor(value: T);
+}
 /**
  * ## Retuple Thrown Value Error
  *
@@ -49,456 +59,1897 @@ export declare class RetupleThrownValueError extends Error {
 /**
  * ## Retuple Invalid Result Error
  *
- * An error thrown when attempting to construct a `Result` from a native tuple,
- * when neither index 0 or 1 are null or undefined. In this case, it is impossible
- * to determine whether the result should be `Ok` or `Err`.
+ * This error is thrown when attempting to construct a `Result` from a tuple,
+ * when neither index 0 or 1 are null or undefined. In this case, it is
+ * impossible to determine whether the result should be `Ok` or `Err`.
  */
 export declare class RetupleInvalidResultError extends Error {
     value: unknown[];
     constructor(value: unknown[]);
 }
+/**
+ * ## Retuple Array Method Unavailable Error
+ *
+ * This error is thrown when calling a built-in array method from a `Result`.
+ */
+export declare class RetupleArrayMethodUnavailableError extends Error {
+    value: unknown[];
+    constructor(value: unknown[], method: Exclude<keyof any[] & string, "length">);
+}
 /**
  * ## Result
  *
  * @TODO
  */
-export declare function Result<R extends [err: null | undefined, value: unknown] | [err: unknown, value: null | undefined]>(resultLike: R): (R extends [null | undefined, infer T] ? Ok<T> : R extends [infer E, null | undefined] ? Err<E> : never) extends Ok<infer T> | Err<infer E> ? Result<T, NonNullable<E>> : never;
+export declare function Result<R extends [err: null | undefined, value: unknown] | [err: unknown, value: null | undefined]>(resultLike: R): (R extends [null | undefined, infer T] ? ThisOk<T> : R extends [infer E, null | undefined] ? ThisErr<E> : never) extends ThisOk<infer T> | ThisErr<infer E> ? Result<T, NonNullable<E>> : never;
 export declare namespace Result {
     var Ok: typeof import(".").Ok;
     var Err: typeof import(".").Err;
-    var nonNullable: typeof import(".").nonNullable;
-    var truthy: typeof import(".").truthy;
-    var safe: typeof import(".").safe;
-    var safeAsync: typeof import(".").safeAsync;
-    var safePromise: typeof import(".").safePromise;
+    var $nonNullable: typeof nonNullable;
+    var $truthy: typeof truthy;
+    var $safe: typeof safe;
+    var $safeAsync: typeof safeAsync;
+    var $safePromise: typeof safePromise;
 }
 /**
- * ## Ok
+ * Create a new {@link Result} with the `Ok` variant. When called without
+ * arguments the `T` type is `void`.
  *
- * @TODO
+ * @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 Ok(): Ok<void>;
-export declare function Ok<const T>(val: T): Ok<T>;
+export declare function Ok(): Result<void, never>;
+export declare function Ok<const T>(val: T): Result<T, never>;
 /**
- * ## Err
+ * Create a new {@link Result} with the `Err` variant. When called without
+ * arguments the `E` type is `void`.
  *
- * @TODO
+ * @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 Err(): Err<void>;
-export declare function Err<const E>(err: E): Err<E>;
+export declare function Err(): Result<never, void>;
+export declare function Err<const E>(err: E): Result<never, E>;
 /**
  * Construct a {@link Result} from a value. If the value is neither null or
  * undefined, the result is `Ok`.
+ *
+ * Otherwise, the result is `Err` containing:
+
+ * - the returned value from the error function when provided;
+ * - or `true` otherwise.
+ *
+ * @example
+ *
+ * ```ts
+ * const result: Result<User, Error> = Result.$nonNullable(
+ *    users.find((user) => user.id === currentUserId),
+ *    () => new Error("User not found"),
+ * );
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = Result.$nonNullable("test");
+ *
+ * assert.equal(err, undefined);
+ * assert.equal(value, "test");
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = Result.$nonNullable(null);
+ *
+ * assert.equal(err, true);
+ * assert.equal(value, undefined);
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = Result.$nonNullable(null, () => "error");
+ *
+ * assert.equal(err, "error");
+ * assert.equal(value, undefined);
+ * ```
  */
 export declare function nonNullable<const T>(value: T): Result<NonNullable<T>, true>;
-export declare function nonNullable<const T, const E>(value: T, error: () => E): Result<NonNullable<T>, E>;
+export declare function nonNullable<const T, E>(value: T, error: () => E): Result<NonNullable<T>, E>;
 /**
  * Construct a {@link Result} from a value. If the value is truthy, the result
  * is `Ok`.
+ *
+ * Otherwise, the result is `Err` containing:
+ *
+ * - the returned value from the error function when provided;
+ * - or `true` otherwise.
+ *
+ * @example
+ *
+ * ```ts
+ * const result: Result<string, Error> = Result.$truthy(
+ *    username.trim(),
+ *    () => new Error("Username is empty"),
+ * );
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = Result.$truthy("test");
+ *
+ * assert.equal(err, undefined);
+ * assert.equal(value, "test");
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = Result.$truthy("");
+ *
+ * assert.equal(err, true);
+ * assert.equal(value, undefined);
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = Result.$truthy(0, () => "error");
+ *
+ * assert.equal(err, "error");
+ * assert.equal(value, undefined);
+ * ```
  */
 export declare function truthy<const T>(value: T): Result<Truthy<T>, true>;
-export declare function truthy<const T, const E>(value: T, error: () => E): Result<Truthy<T>, E>;
+export declare function truthy<const 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`.
+ *
+ * Otherwise, the result is `Err` containing (in priority order):
+ *
+ * - the returned value from the map error function when provided;
+ * - the thrown error when it is an instance of `Error`;
+ * - `RetupleThrownValueError` when a non `Error` instance is thrown.
+ *
+ * @example
+ *
+ * ```ts
+ * const result: Result<URL, Error> = Result.$safe(
+ *    () => new URL(user.url),
+ *    () => new Error("Invalid URL"),
+ * );
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = Result.$safe(() => "test");
+ *
+ * assert.equal(err, undefined);
+ * assert.equal(value, "test");
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = Result.$safe(
+ *    () => {
+ *       throw new Error("throws");
+ *    },
+ *    () => "error",
+ * );
+ *
+ * assert.equal(err, "error");
+ * assert.equal(value, undefined);
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = Result.$safe(
+ *    () => {
+ *       throw new Error("throws")
+ *    },
+ * );
+ *
+ * assert(err instanceof Error && err.message === "throws");
+ * assert.equal(value, undefined);
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = Result.$safe(() => {
+ *    throw "non error";
+ * });
+ *
+ * assert(err instanceof RetupleThrownValueError && err.value === "non error");
+ * assert.equal(value, undefined);
  */
 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`.
+ *
+ * Otherwise, the result is `Err` containing (in priority order):
+ *
+ * - the returned value from the map error function when provided;
+ * - the thrown/rejected error when it is an instance of `Error`;
+ * - `RetupleThrownValueError` when throwing/rejecting with a non `Error`.
+ *
+ * @example
+ *
+ * ```ts
+ * const result: Result<Response, Error> = await Result.$safeAsync(
+ *    () => fetch("http://example.com/api"),
+ *    () => new Error("Fetch failed"),
+ * );
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = await Result.$safeAsync(async () => "test");
+ *
+ * assert.equal(err, undefined);
+ * assert.equal(value, "test");
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = await Result.$safeAsync(
+ *    async () => {
+ *       throw new Error("throws");
+ *    },
+ *    () => "error",
+ * );
+ *
+ * assert.equal(err, "error");
+ * assert.equal(value, undefined);
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = await Result.$safeAsync(
+ *    async () => {
+ *       throw new Error("throws")
+ *    },
+ * );
+ *
+ * assert(err instanceof Error && err.message === "throws");
+ * assert.equal(value, undefined);
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = await Result.$safeAsync(async () => {
+ *    throw "non error";
+ * });
+ *
+ * assert(err instanceof RetupleThrownValueError && err.value === "non error");
+ * assert.equal(value, undefined);
  */
 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>;
 /**
  * Construct a {@link Result} from a promise. If the promise resolves, the
  * result is `Ok`.
+ *
+ * Otherwise, the result is `Err` containing (in priority order):
+ *
+ * - the returned value from the map error function when provided;
+ * - the rejected error when it is an instance of `Error`;
+ * - `RetupleThrownValueError` when rejecting with a non `Error`.
+ *
+ * @example
+ *
+ * ```ts
+ * const result: Result<Response, Error> = await Result.$safePromise(
+ *    fetch("http://example.com/api"),
+ *    () => new Error("Fetch failed"),
+ * );
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = await Result.$safePromise(Promise.resolve("test"));
+ *
+ * assert.equal(err, undefined);
+ * assert.equal(value, "test");
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = await Result.$safePromise(
+ *    Promise.reject(new Error("rejects")),
+ *    () => "error",
+ * );
+ *
+ * assert.equal(err, "error");
+ * assert.equal(value, undefined);
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = await Result.$safePromise(
+ *    Promise.reject(new Error("rejects")),
+ * );
+ *
+ * assert(err instanceof Error && err.message === "rejects");
+ * assert.equal(value, undefined);
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const [err, value] = await Result.$safeAsync(
+ *    Promise.reject("non error"),
+ * );
+ *
+ * assert(err instanceof RetupleThrownValueError && err.value === "non error");
+ * assert.equal(value, undefined);
  */
 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>;
 /**
- * ## ResultAsync
+ * ## RetupleArray
  *
- * @TODO
+ * Using built-in array methods on a `Result` is probably a mistake. This class
+ * makes the built-in methods throw `RetupleArrayMethodUnavailableError`.
  */
-declare class ResultAsync<T, E> {
-    #private;
-    constructor(inner: PromiseLike<Result<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>;
+declare class RetupleArray<T> extends Array<T> {
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $toNativeTuple(this: ResultAsync<T, E>): Promise<OkTuple<T> | ErrTuple<E>>;
+    at(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $value(this: ResultAsync<T, E>): Promise<T | E>;
+    concat(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $ok(this: ResultAsync<T, E>): Promise<T | undefined>;
+    copyWithin(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $expect(this: ResultAsync<T, Error>): Promise<T>;
+    entries(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $unwrap(this: ResultAsync<T, E>, msg?: string): Promise<T>;
+    every(): this is never[];
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $unwrapErr(this: ResultAsync<T, E>, msg?: string): Promise<E>;
+    fill(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $unwrapOr<U>(this: ResultAsync<T, E>, def: U): Promise<T | U>;
+    filter(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $unwrapOrElse<U>(this: ResultAsync<T, E>, f: () => U): Promise<T | U>;
+    find(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $map<U>(this: ResultAsync<T, E>, f: (val: T) => U): ResultAsync<U, E>;
+    findIndex(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $mapErr<F>(this: ResultAsync<T, E>, f: (err: E) => F): ResultAsync<T, F>;
+    findLast(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $mapOr<U, V>(this: ResultAsync<T, E>, def: U, f: (val: T) => V): ResultAsync<U | V, E>;
+    findLastIndex(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $mapOrElse<U, V>(this: ResultAsync<T, E>, def: (err: E) => U, f: (val: T) => V): ResultAsync<U | V, E>;
+    flat(): never;
     /**
-     * ## $assertOr
+     * ## Method not available
      *
-     * {@link Retuple.$assertOr|$assertOr}
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $assertOr<U, F>(this: ResultAsync<T, E>, def: Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<Truthy<T>, E | F>;
-    $assertOr<U, F, A extends T>(this: ResultAsync<T, E>, def: Result<U, F> | PromiseLike<Result<U, F>>, predicate: (val: T) => val is A): ResultAsync<U | A, E | F>;
-    $assertOr<U, F>(this: ResultAsync<T, E>, def: Result<U, F> | PromiseLike<Result<U, F>>, condition: (val: T) => unknown): ResultAsync<T | U, E | F>;
-    $assertOrElse<U, F>(this: ResultAsync<T, E>, def: () => Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<Truthy<T>, E | F>;
-    $assertOrElse<U, F, A extends T>(this: ResultAsync<T, E>, def: () => Result<U, F> | PromiseLike<Result<U, F>>, predicate: (val: T) => val is A): ResultAsync<U | A, E | F>;
-    $assertOrElse<U, F>(this: ResultAsync<T, E>, def: () => Result<U, F> | PromiseLike<Result<U, F>>, condition: (val: T) => unknown): ResultAsync<T | U, E | F>;
+    flatMap(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $or<U, F>(this: ResultAsync<T, E>, or: Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<T | U, E | F>;
+    forEach(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $orElse<U, F>(this: ResultAsync<T, E>, f: (err: E) => Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<T | U, E | F>;
+    includes(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $orSafe<U>(this: ResultAsync<T, E>, f: (err: E) => U | PromiseLike<U>): ResultAsync<T | U, E | Error>;
-    $orSafe<U, F>(this: ResultAsync<T, E>, f: (err: E) => U | PromiseLike<U>, mapError: (err: unknown) => F): ResultAsync<T | U, E | F>;
+    indexOf(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $and<U, F>(this: ResultAsync<T, E>, and: Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<U, E | F>;
+    join(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $andThen<U, F>(this: ResultAsync<T, E>, f: (val: T) => Result<U, F> | PromiseLike<Result<U, F>>): ResultAsync<U, E | F>;
+    keys(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $andThrough<F>(this: ResultAsync<T, E>, f: (val: T) => Result<any, F> | PromiseLike<Result<any, F>>): ResultAsync<T, E | F>;
+    lastIndexOf(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $andSafe<U>(this: ResultAsync<T, E>, f: (val: T) => U | PromiseLike<U>): ResultAsync<T | U, E | Error>;
-    $andSafe<U, F>(this: ResultAsync<T, E>, f: (val: T) => U | PromiseLike<U>, mapError: (err: unknown) => F): ResultAsync<T | U, E | F>;
+    map(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $peek(this: ResultAsync<T, E>, f: (res: Result<T, E>) => any): ResultAsync<T, E>;
+    pop(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $tap(this: ResultAsync<T, E>, f: (val: T) => any): ResultAsync<T, E>;
+    push(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $tapErr(this: ResultAsync<T, E>, f: (err: E) => any): ResultAsync<T, E>;
+    reduce(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $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> {
+    reduceRight(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $toNativeTuple(this: Result<T, E>): OkTuple<T> | ErrTuple<E>;
+    reverse(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $value(this: Result<T, E>): T | E;
+    shift(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $ok(this: Result<T, E>): T | undefined;
+    slice(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $isOk(this: Result<T, E>): this is Ok<T>;
+    some(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $isOkAnd<U extends T>(this: Result<T, E>, predicate: (val: T) => val is U): this is Ok<U>;
-    $isOkAnd(this: Result<T, E>, predicate: (val: T) => unknown): this is Ok<T>;
+    sort(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $isErr(this: Result<T, E>): this is Err<E>;
+    splice(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $isErrAnd<F extends E>(this: Result<T, E>, prediacte: (val: E) => val is F): this is Err<F>;
-    $isErrAnd(this: Result<T, E>, predicate: (val: E) => unknown): this is Err<E>;
+    toString(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $expect(this: Result<T, Error>): T;
+    toLocaleString(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $unwrap(this: Result<T, E>, msg?: string): T;
+    toReversed(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $unwrapErr(this: Result<T, E>, msg?: string): E;
+    toSorted(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $unwrapOr<const U>(this: Result<T, E>, def: U): T | U;
+    toSpliced(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $unwrapOrElse<U>(this: Result<T, E>, f: () => U): T | U;
+    unshift(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $map<U>(this: Result<T, E>, f: (value: T) => U): Result<U, E>;
+    values(): never;
     /**
-     * @TODO
+     * ## Method not available
+     *
+     * Built-in array methods not available on `Result` types, convert the result
+     * to a tuple using `$tuple()` first.
+     *
+     * @deprecated
      */
-    $mapErr<F>(this: Result<T, E>, f: (err: E) => F): Result<T, F>;
+    with(): never;
+}
+/**
+ * ## ResultAsync
+ *
+ * @TODO
+ */
+declare class ResultAsync<T, E> {
+    #private;
+    constructor(inner: PromiseLike<Result<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`.
      */
-    $mapOr<U, V = U>(this: Result<T, E>, def: U, f: (val: T) => V): Result<U | V, E>;
+    $expect(this: ResultAsync<T, Error>): Promise<T>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$unwrap|$unwrap}, except it returns a `Promise`.
      */
-    $mapOrElse<U, V = U>(this: Result<T, E>, def: (err: E) => U, f: (val: T) => V): Result<U | V, E>;
+    $unwrap(this: ResultAsync<T, E>, msg?: string): Promise<T>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$unwrapErr|$unwrapErr}, except it returns
+     * a `Promise`.
      */
-    $or<U, F>(this: Result<T, E>, or: Result<U, F>): Result<T | U, E | F>;
+    $unwrapErr(this: ResultAsync<T, E>, msg?: string): Promise<E>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$unwrapOr|$unwrapOr}, except it returns
+     * a `Promise`.
      */
-    $orElse<U, F>(this: Result<T, E>, f: (err: E) => Result<U, F>): Result<T | U, E | F>;
+    $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`.
      */
-    $orSafe<U>(this: Result<T, E>, f: (err: E) => U): Result<T | U, E | Error>;
-    $orSafe<U, F>(this: Result<T, E>, f: (err: E) => U, mapError: (err: unknown) => F): Result<T | U, E | F>;
+    $unwrapOrElse<U = T>(this: ResultAsync<T, E>, f: () => U): Promise<T | U>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$map|$map}, except it returns `ResultAsync`.
      */
-    $and<U, F>(this: Result<T, E>, and: Result<U, F>): Result<U, E | F>;
+    $map<U>(this: ResultAsync<T, E>, f: (val: T) => U): ResultAsync<U, E>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$mapErr|$mapErr}, except it returns
+     * `ResultAsync`.
      */
-    $andThen<U, F>(this: Result<T, E>, f: (val: T) => Result<U, F>): Result<U, E | 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 `ResultAsync`.
      */
-    $andThrough<F>(this: Result<T, E>, f: (val: T) => Result<any, F>): Result<T, E | F>;
+    $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
+     * `ResultAsync`.
      */
-    $andSafe<U>(this: Result<T, E>, f: (val: T) => U): Result<T | U, E | Error>;
-    $andSafe<U, F>(this: Result<T, E>, f: (val: T) => U, mapError: (err: unknown) => F): Result<T | U, E | F>;
+    $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.$assertOr|$assertOr}, except it:
+     *
+     * - can also accept a `PromiseLike` default value;
+     * - returns `ResultAsync`.
      */
-    $assertOr<U, F>(this: Result<T, E>, def: Result<U, F>): Result<Truthy<T>, E | F>;
-    $assertOr<U, F, A extends T>(this: Result<T, E>, def: Result<U, F>, predicate: (val: T) => val is A): Result<U | A, E | F>;
-    $assertOr<U, F>(this: Result<T, E>, def: Result<U, F>, condition: (val: T) => unknown): Result<T | U, E | F>;
+    $assertOr<U = T, F = E>(this: ResultAsync<T, E>, def: RetupleAwaitable<U, F>): ResultAsync<Truthy<T>, E | F>;
+    $assertOr<U = T, F = E, A extends T = T>(this: ResultAsync<T, E>, def: RetupleAwaitable<U, F>, predicate: (val: T) => val is A): ResultAsync<U | A, E | F>;
+    $assertOr<U = T, F = E>(this: ResultAsync<T, E>, def: RetupleAwaitable<U, F>, condition: (val: T) => unknown): ResultAsync<T | U, E | F>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$assertOrElse|$assertOrElse}, except it:
+     *
+     * - can also accept an `async` default function;
+     * - returns `ResultAsync`.
      */
-    $assertOrElse<U, F>(this: Result<T, E>, def: () => Result<U, F>): Result<Truthy<T>, E | F>;
-    $assertOrElse<U, F, A extends T>(this: Result<T, E>, def: () => Result<U, F>, predicate: (val: T) => val is A): Result<U | A, E | F>;
-    $assertOrElse<U, F>(this: Result<T, E>, def: () => Result<U, F>, condition: (val: T) => unknown): Result<T | U, E | F>;
+    $assertOrElse<U = T, F = E>(this: ResultAsync<T, E>, def: (val: T) => RetupleAwaitable<U, F>): ResultAsync<Truthy<T>, E | F>;
+    $assertOrElse<U = T, F = E, A extends T = T>(this: ResultAsync<T, E>, def: (val: T) => RetupleAwaitable<U, F>, predicate: (val: T) => val is A): ResultAsync<U | A, E | F>;
+    $assertOrElse<U = T, F = E>(this: ResultAsync<T, E>, def: (val: T) => RetupleAwaitable<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 `ResultAsync`.
      */
-    $peek(this: Result<T, E>, f: (res: Result<T, E>) => void): Result<T, E>;
+    $or<U = T, F = E>(this: ResultAsync<T, E>, or: Retuple<U, F> | PromiseLike<Retuple<U, F>>): ResultAsync<T | U, F>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$orElse|$orElse}, except it:
+     *
+     * - can also accept an `async` or function;
+     * - returns `ResultAsync`.
      */
-    $tap(this: Result<T, E>, f: (val: T) => any): Result<T, E>;
+    $orElse<U = T, F = E>(this: ResultAsync<T, E>, f: (err: E) => RetupleAwaitable<U, F>): ResultAsync<T | U, F>;
     /**
-     * @TODO
+     * The same as {@link Retuple.$orSafe|$orSafe}, except it:
+     *
+     * - can also accept an `async` safe function;
+     * - returns `ResultAsync`.
      */
-    $tapErr(this: Result<T, E>, f: (err: E) => void): Result<T, E>;
+    $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
      */
-    $flatten<U, F>(this: Result<Result<U, F>, E>): Result<U, 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 `ResultAsync`.
      */
-    $async(this: Result<T, E>): ResultAsync<T, E>;
+    $and<U = T, F = E>(this: ResultAsync<T, E>, and: RetupleAwaitable<U, F>): ResultAsync<U, E | F>;
+    /**
+     * The same as {@link Retuple.$andThen|$andThen}, except it:
+     *
+     * - can also accept an `async` and function;
+     * - returns `ResultAsync`.
+     */
+    $andThen<U = T, F = E>(this: ResultAsync<T, E>, f: (val: T) => RetupleAwaitable<U, F>): ResultAsync<U, E | F>;
+    /**
+     * The same as {@link Retuple.$andThrough|$andThrough}, except it:
+     *
+     * - can also accept an `async` through function;
+     * - returns `ResultAsync`.
+     */
+    $andThrough<F = E>(this: ResultAsync<T, E>, f: (val: T) => RetupleAwaitable<any, F>): ResultAsync<T, E | F>;
+    /**
+     * The same as {@link Retuple.$andSafe|$andSafe}, except it:
+     *
+     * - can also accept an `async` safe function;
+     * - returns `ResultAsync`.
+     */
+    $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
      */
-    $promise(this: Result<T, E>): Promise<Result<T, E>>;
+    $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>;
     /**
-     * Mark standard array methods as deprecated, to assist with type hinting.
+     * The same as {@link Retuple.$peek|$peek}, except it:
+     *
+     * - awaits the peek function;
+     * - returns `ResultAsync`.
      */
+    $peek(this: ResultAsync<T, E>, f: (res: Result<T, E>) => any): ResultAsync<T, E>;
     /**
-     * @deprecated
+     * The same as {@link Retuple.$tap|$tap}, except it:
+     *
+     * - awaits the tap function;
+     * - returns `ResultAsync`.
      */
-    at(...args: unknown[]): unknown;
+    $tap(this: ResultAsync<T, E>, f: (val: T) => any): ResultAsync<T, E>;
     /**
-     * @deprecated
+     * The same as {@link Retuple.$tapErr|$tapErr}, except it:
+     *
+     * - awaits the tap error function;
+     * - returns `ResultAsync`.
      */
-    concat(...args: unknown[]): unknown;
+    $tapErr(this: ResultAsync<T, E>, f: (err: E) => any): ResultAsync<T, E>;
     /**
-     * @deprecated
+     * The same as {@link Retuple.$promise|$promise}.
      */
-    copyWithin(...args: unknown[]): unknown;
+    $promise(this: ResultAsync<T, E>): Promise<Result<T, E>>;
     /**
-     * @deprecated
+     * The same as {@link Retuple.$tuple|$tuple}, except it returns a `Promise`.
      */
-    entries(...args: unknown[]): unknown;
+    $tuple(this: ResultAsync<T, E>): Promise<[err: E | undefined, value: T | undefined]>;
     /**
-     * @deprecated
+     * The same as {@link Retuple.$tuple|$iter}, except it returns a `Promise`.
      */
-    every(...args: unknown[]): unknown;
+    $iter<U>(this: ResultAsync<Iterable<U>, E>): Promise<IterableIterator<U, undefined, unknown>>;
+}
+type Truthy<T> = Exclude<T, false | null | undefined | 0 | 0n | "">;
+type OkTuple<T> = [err: undefined, value: T];
+type ErrTuple<E> = [err: E, value: undefined];
+type ThisOk<T> = OkTuple<T> & Retuple<T, never>;
+type ThisErr<E> = ErrTuple<E> & Retuple<never, E>;
+type RetupleAwaitable<T, E> = Retuple<T, E> | PromiseLike<Retuple<T, E>>;
+interface Retuple<T, E> extends RetupleArray<T | E | undefined> {
     /**
-     * @deprecated
+     * 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>;
+     * }
+     * ```
      */
-    fill(...args: unknown[]): unknown;
+    $isOk(this: Result<T, E>): this is Result<T, never>;
     /**
-     * @deprecated
+     * 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>;
+     * }
+     * ```
      */
-    filter(...args: unknown[]): unknown;
+    $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>;
     /**
-     * @deprecated
+     * 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>;
+     * }
+     * ```
      */
-    find(...args: unknown[]): unknown;
+    $isErr(this: Result<T, E>): this is Result<never, E>;
     /**
-     * @deprecated
+     * 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>;
+     * }
+     * ```
      */
-    findIndex(...args: unknown[]): unknown;
+    $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>;
     /**
-     * @deprecated
+     * 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");
+     * }
+     * ```
      */
-    flat(...args: unknown[]): unknown;
+    $expect(this: Result<T, Error>): T;
     /**
-     * @deprecated
+     * 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`
+     *   );
+     * }
+     * ```
      */
-    flatMap(...args: unknown[]): unknown;
+    $unwrap(this: Result<T, E>, msg?: string): T;
     /**
-     * @deprecated
+     * 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",
+     *   );
+     * }
+     * ```
      */
-    forEach(...args: unknown[]): unknown;
+    $unwrapErr(this: Result<T, E>, msg?: string): E;
     /**
-     * @deprecated
+     * 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");
+     * ```
      */
-    includes(...args: unknown[]): unknown;
+    $unwrapOr<const U = T>(this: Result<T, E>, def: U): T | U;
     /**
-     * @deprecated
+     * 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");
+     * ```
      */
-    indexOf(...args: unknown[]): unknown;
+    $unwrapOrElse<U = T>(this: Result<T, E>, f: () => U): T | U;
     /**
-     * @deprecated
+     * 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.$assertOr(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.$assertOr(
+     *    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.$assertOr(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.$assertOr(
+     *    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.$assertOr(
+     *    Err("err-default"),
+     *    (val): val is "test" => val === "test",
+     * );
+     *
+     * asserted satisfies Result<"test", string>;
+     * assert.equal(asserted.$unwrapErr(), "test");
+     * ```
      */
-    join(...args: unknown[]): unknown;
+    $assertOr<U = T, F = E>(this: Result<T, E>, def: Result<U, F>): Result<Truthy<T> | U, E | F>;
+    $assertOr<U = T, F = E, A extends T = T>(this: Result<T, E>, def: Result<U, F>, predicate: (val: T) => val is A): Result<U | A, E | F>;
+    $assertOr<U = T, F = E>(this: Result<T, E>, def: Result<U, F>, condition: (val: T) => unknown): Result<T | U, E | F>;
     /**
-     * @deprecated
+     * 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.$assertOrElse(
+     *    (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.$assertOrElse(
+     *    (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.$assertOrElse(
+     *    (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.$assertOrElse(
+     *    (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.$assertOrElse(
+     *    (val) => Err(`err-default:${val}`),
+     *    (val): val is "test" => val === "test",
+     * );
+     *
+     * asserted satisfies Result<"test", string>;
+     * assert.equal(asserted.$unwrapErr(), "test");
+     * ```
      */
-    keys(...args: unknown[]): unknown;
+    $assertOrElse<U = T, F = E>(this: Result<T, E>, def: (val: T) => Result<U, F>): Result<Truthy<T> | U, E | F>;
+    $assertOrElse<U = T, F = E, A extends T = T>(this: Result<T, E>, def: (val: T) => Result<U, F>, predicate: (val: T) => val is A): Result<U | A, E | F>;
+    $assertOrElse<U = T, F = E>(this: Result<T, E>, def: (val: T) => Result<U, F>, condition: (val: T) => unknown): Result<T | U, E | F>;
     /**
-     * @deprecated
+     * 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",
+     * );
+     * ```
      */
-    lastIndexOf(...args: unknown[]): unknown;
+    $map<U>(this: Result<T, E>, f: (value: T) => U): Result<U, E>;
     /**
-     * @deprecated
+     * 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",
+     * );
+     * ```
      */
-    map(...args: unknown[]): unknown;
+    $mapOr<U, V = U>(this: Result<T, E>, def: U, f: (val: T) => V): Result<U | V, E>;
     /**
-     * @deprecated
+     * 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",
+     * );
+     * ```
      */
-    pop(...args: unknown[]): any;
+    $mapOrElse<U, V = U>(this: Result<T, E>, def: (err: E) => U, f: (val: T) => V): Result<U | V, E>;
     /**
-     * @deprecated
+     * 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",
+     * );
+     * ```
      */
-    push(...args: unknown[]): unknown;
+    $or<U = T, F = E>(this: Result<T, E>, or: Result<U, F>): Result<T | U, F>;
     /**
-     * @deprecated
+     * 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) => Result<U, F>): Result<T | U, F>;
+    /**
+     * Returns a `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(...))`.
      */
-    reduce(...args: unknown[]): unknown;
+    $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>;
     /**
-     * @deprecated
+     * 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",
+     * );
+     * ```
      */
-    reduceRight(...args: unknown[]): unknown;
+    $and<U = T, F = E>(this: Result<T, E>, and: Result<U, F>): Result<U, E | F>;
     /**
-     * @deprecated
+     * 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",
+     * );
+     * ```
      */
-    reverse(...args: unknown[]): unknown;
+    $andThen<U = T, F = E>(this: Result<T, E>, f: (val: T) => Result<U, F>): Result<U, E | F>;
     /**
-     * @deprecated
+     * 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) => Result<any, F>): Result<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
+     * `result.$and(Result.$safe(...))`.
      */
-    shift(...args: unknown[]): unknown;
+    $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>;
     /**
-     * @deprecated
+     * @TODO
      */
-    slice(...args: unknown[]): unknown;
     /**
-     * @deprecated
+     * Calls the peek function and returns `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",
+     * );
+     * ```
      */
-    some(...args: unknown[]): unknown;
+    $peek(this: Result<T, E>, f: (res: Result<T, E>) => void): Result<T, E>;
     /**
-     * @deprecated
+     * 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",
+     * );
+     * ```
      */
-    sort(...args: unknown[]): unknown;
+    $tap(this: Result<T, E>, f: (val: T) => any): Result<T, E>;
     /**
-     * @deprecated
+     * 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",
+     * );
+     * ```
      */
-    splice(...args: unknown[]): unknown;
+    $tapErr(this: Result<T, E>, f: (err: E) => void): Result<T, E>;
     /**
-     * @deprecated
+     * Returns the contained `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");
+     * ```
      */
-    toString(...args: unknown[]): unknown;
+    $flatten<U, F>(this: Result<Result<U, F>, E>): Result<U, E | F>;
     /**
-     * @deprecated
+     * Returns an equivalent `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");
+     * ```
      */
-    toLocaleString(...args: unknown[]): unknown;
+    $async(this: Result<T, E>): ResultAsync<T, E>;
     /**
-     * @deprecated
+     * 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);
+     * ```
      */
-    unshift(...args: unknown[]): unknown;
+    $promise(this: Result<T, E>): Promise<Result<T, E>>;
     /**
-     * @deprecated
+     * Returns a two-element, standard array tuple equivalent to this result.
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Ok("test");
+     * assert.deepEqual(result.$tuple(), [undefined, "test"]);
+     * ```
+     *
+     * @example
+     *
+     * ```ts
+     * const result = Err("test");
+     * assert.deepEqual(result.$tuple(), ["test", undefined]);
+     * ```
      */
-    values(...args: unknown[]): unknown;
+    $tuple(this: Result<T, E>): [err: E | undefined, value: T | undefined];
+    /**
+     * 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>;
 }