retuple 1.0.0-next.3 → 1.0.0-next.30

package/dist/index.js

@@ -9,7 +9,9 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _ResultAsync_inner;
+var _ResultAsync_inner, _a, _ResultRetry_f, _ResultRetry_promise, _ResultRetry_times, _ResultRetry_attempt, _ResultRetry_aborted, _ResultRetry_abort, _ResultRetry_getDelay, _ResultRetry_handler;
+import { ResultLikeSymbol, } from "retuple-symbols";
+const RetupleStackSymbol = Symbol("RetupleStackSymbol");
 /**
  * ## Retuple Unwrap Failed
  *
@@ -35,7 +37,7 @@ export class RetupleUnwrapErrFailed 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 class RetupleExpectFailed extends Error {
@@ -44,6 +46,43 @@ export class RetupleExpectFailed extends Error {
         this.value = value;
     }
 }
+/**
+ * ## Retuple Assert Failed
+ *
+ * This error is used as the error type of a `Result` when using $assert,
+ * when no map error function is provided.
+ */
+export class RetupleAssertFailed extends Error {
+    constructor(value) {
+        super("Assert failed");
+        this.value = value;
+    }
+}
+/**
+ * ## Retuple Filter Failed
+ *
+ * This error is used as the error type of a `Result` when using $filter,
+ * when no map error function is provided.
+ */
+export class RetupleFilterFailed extends Error {
+    constructor(value) {
+        super("Filter failed");
+        this.value = value;
+    }
+}
+/**
+ * ## Retuple Index Failed
+ *
+ * This error is used as the error type of a `Result` when using $atIndex or
+ * $firstIndex, when no map error function is provided.
+ */
+export class RetupleIndexFailed extends Error {
+    constructor(index, value) {
+        super("Index failed");
+        this.index = index;
+        this.value = value;
+    }
+}
 /**
  * ## Retuple Thrown Value Error
  *
@@ -51,22 +90,24 @@ export class RetupleExpectFailed extends Error {
  * thrown error or rejected value is not an instance of `Error`, and when no
  * map error function is provided.
  */
-export class RetupleThrownValueError extends Error {
+export class RetupleCaughtValueError extends Error {
     constructor(value) {
         super("Caught value was not an instance of Error");
         this.value = value;
     }
 }
 /**
- * ## Retuple Invalid Result Error
+ * ## Retuple Invalid Union 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.
+ * 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 class RetupleInvalidResultError extends Error {
+export class RetupleInvalidUnionError extends Error {
     constructor(value) {
-        super("Constructing a Result from tuple failed, at least one of the values at index 0 or 1 should be undefined");
+        super("Constructing a Result from discriminated union failed, the success " +
+            "property must be boolean");
         this.value = value;
     }
 }
@@ -76,22 +117,28 @@ export class RetupleInvalidResultError extends Error {
  * @TODO
  */
 export function Result(resultLike) {
-    const [err, ok] = resultLike;
-    if (err === null || err === undefined) {
-        return new ResultOk(ok);
-    }
-    if (ok === null || ok === undefined) {
-        return new ResultErr(err);
-    }
-    throw new RetupleInvalidResultError(resultLike);
+    return asResult(resultLike);
 }
 Result.Ok = Ok;
 Result.Err = Err;
-Result.nonNullable = nonNullable;
-Result.truthy = truthy;
-Result.safe = safe;
-Result.safeAsync = safeAsync;
-Result.safePromise = safePromise;
+Result.$from = $from;
+Result.$resolve = $resolve;
+Result.$nonNullable = $nonNullable;
+Result.$truthy = $truthy;
+Result.$fromUnion = $fromUnion;
+Result.$safe = $safe;
+Result.$safeAsync = $safeAsync;
+Result.$safePromise = $safePromise;
+Result.$retry = $retry;
+Result.$safeRetry = $safeRetry;
+Result.$all = $all;
+Result.$allPromised = $allPromised;
+Result.$any = $any;
+Result.$anyPromised = $anyPromised;
+Result.$collect = $collect;
+Result.$collectPromised = $collectPromised;
+Result.$pipe = $pipe;
+Result.$pipeAsync = $pipeAsync;
 Object.freeze(Result);
 export function Ok(val) {
     return new ResultOk(val);
@@ -99,43 +146,401 @@ export function Ok(val) {
 export function Err(err) {
     return new ResultErr(err);
 }
-export function nonNullable(value, error = mapTrue) {
+/**
+ * Construct a {@link Result} from a {@link ResultLike}.
+ *
+ * @example
+ *
+ * ```ts
+ * const value: Result<T, E> | ResultLike<T, E> = someResultFn();
+ * const result: Result<T, E> = Result.$from(result);
+ * ```
+ */
+function $from(result) {
+    if (result instanceof ResultOk || result instanceof ResultErr) {
+        return result;
+    }
+    return asResult(result);
+}
+/**
+ * Construct a {@link ResultAsync} from a {@link ResultLikeAwaitable}.
+ *
+ * @example
+ *
+ * ```ts
+ * const value:
+ *    | Result<T, E>
+ *    | ResultLike<T, E>
+ *    | ResultAsync<T, E>
+ *    | Promise<Result<T, E>>
+ *    | Promise<ResultLike<T, E>>
+ *    | PromiseLike<Result<T, E>>
+ *    | PromiseLike<ResultLike<T, E>> = someResultFn();
+ *
+ * const result: ResultAsync<T, E> = Result.$resolve(result);
+ * ```
+ */
+function $resolve(result) {
+    switch (true) {
+        case result instanceof ResultAsync:
+            return result;
+        case result instanceof ResultOk:
+        case result instanceof ResultErr:
+            return new ResultAsync(Promise.resolve(result));
+        default:
+            return new ResultAsync(Promise.resolve(result).then((asResult)));
+    }
+}
+function $nonNullable(value, error = mapTrue) {
     if (value !== null && value !== undefined) {
-        return new ResultOk(value);
+        return Ok(value);
     }
-    return new ResultErr(error());
+    return Err(error());
 }
-export function truthy(value, error = mapTrue) {
+function $truthy(value, error = mapTrue) {
     if (value) {
-        return new ResultOk(value);
+        return Ok(value);
     }
-    return new ResultErr(error());
+    return Err(error());
 }
-export function safe(f, mapError = ensureError) {
+/**
+ * Construct a {@link Result} from a common discriminated union shape. If the
+ * union is 'success' then 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);
+ * ```
+ */
+function $fromUnion(union) {
+    if (union.success === true) {
+        return Ok(union.data);
+    }
+    if (union.success === false) {
+        return Err(union.error);
+    }
+    throw new RetupleInvalidUnionError(union);
+}
+function $safe(f, mapError = ensureError) {
     try {
-        return new ResultOk(f());
+        return Ok(f());
     }
     catch (err) {
-        return new ResultErr(mapError(err));
+        return Err(mapError(err));
     }
 }
-export function safeAsync(f, mapError = ensureError) {
+function $safeAsync(f, mapError = ensureError) {
     return new ResultAsync((async () => {
         try {
-            return new ResultOk(await f());
+            return Ok(await f());
         }
         catch (err) {
-            return new ResultErr(await mapError(err));
+            return Err(await mapError(err));
         }
     })());
 }
-export function safePromise(promise, mapError = ensureError) {
+function $safePromise(promise, mapError = ensureError) {
     return new ResultAsync(promise.then((Ok), async (err) => Err(await mapError(err))));
 }
 /**
- * ## Ok
+ * Construct a {@link ResultRetry} from a function which returns a
+ * {@link Result}. The function will be retried based on provided retry
+ * settings and eventually return a `Result`. No attempt is made to catch
+ * thrown errors or promise rejections.
  *
- * @TODO
+ * To retry a potentially unsafe function, use {@link Result.$safeRetry}.
+ *
+ * @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);
+ * ```
+ */
+function $retry(f) {
+    return new ResultRetry(f);
+}
+function $safeRetry(f, mapError = ensureError) {
+    return new ResultRetry(async () => {
+        try {
+            return Ok(await f());
+        }
+        catch (err) {
+            return Err(mapError(err));
+        }
+    });
+}
+/**
+ * Construct a {@link Result} from an array of results. If all are Ok,
+ * then the result is `Ok` containing a tuple of values. Otherwise,
+ * the result is `Err` containing the first error encountered.
+ *
+ * @example
+ *
+ * ```ts
+ * const result: Result<[string, number], Error | string> = Result.$all([
+ *   Result.$truthy(stringValue, () => new Error("Invalid string")),
+ *   Result.$truthy(numberValue, () => "Invalid number"),
+ * ]);
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const tuple: [1, 2, 3] = Result.$all([
+ *   Ok(1),
+ *   Ok(2),
+ *   Ok(3),
+ * ]).$unwrap();
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const error: "error" = Result.$all([
+ *   Ok(1),
+ *   Err("error"),
+ *   Ok(3),
+ * ]).$unwrapErr();
+ * ```
+ */
+function $all(results) {
+    const oks = [];
+    for (const result of results) {
+        const { ok, value } = result[ResultLikeSymbol]();
+        if (ok) {
+            oks.push(value);
+        }
+        else {
+            return Err(value);
+        }
+    }
+    return Ok(oks);
+}
+/**
+ * The same as {@link Result.$all|$all} except it accepts result-like
+ * promises and returns {@link ResultAsync}.
+ */
+function $allPromised(results) {
+    return new ResultAsync(new Promise((resolve, reject) => {
+        void Promise.all(results.map((result) => Promise.resolve(result).then((result) => {
+            const { ok, value } = result[ResultLikeSymbol]();
+            return ok ? value : Promise.reject(value);
+        }, (err) => {
+            reject(err);
+            // Because reject has been called, we can safely return an
+            // empty rejection to ensure we don't end up with undefined
+            // in the Ok path. The subsequent call to resolve will not
+            // change the state of the Promise.
+            return Promise.reject();
+        }))).then((values) => resolve(Ok(values)), (err) => resolve(Err(err)));
+    }));
+}
+/**
+ * Construct a {@link Result} from an array of results. If any are Ok,
+ * then the result is `Ok` containing the first value encountered.
+ * Otherwise, the result is `Err` containing a tuple of errors.
+ *
+ * @example
+ *
+ * ```ts
+ * const result: Result<string | number, [Error, string]> = Result.$any([
+ *   Result.$truthy(stringValue, () => new Error("Invalid string")),
+ *   Result.$truthy(numberValue, () => "Invalid number"),
+ * ]);
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const tuple: 2 = Result.$any([
+ *   Err("error1"),
+ *   Ok(2),
+ *   Err("error3"),
+ * ]).$unwrap();
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const error: ["error1", "error2", "error3"] = Result.$any([
+ *   Err("error1"),
+ *   Err("error2"),
+ *   Err("error3"),
+ * ]).$unwrapErr();
+ * ```
+ */
+function $any(results) {
+    const errs = [];
+    for (const result of results) {
+        const { ok, value } = result[ResultLikeSymbol]();
+        if (ok) {
+            return Ok(value);
+        }
+        else {
+            errs.push(value);
+        }
+    }
+    return Err(errs);
+}
+/**
+ * The same as {@link Result.$any|$any} except it accepts result-like
+ * promises and returns {@link ResultAsync}.
+ */
+function $anyPromised(results) {
+    return new ResultAsync(new Promise((resolve, reject) => {
+        let rejected = false;
+        void Promise.any(results.map((result) => Promise.resolve(result).then((result) => {
+            const { ok, value } = result[ResultLikeSymbol]();
+            return ok ? value : Promise.reject(value);
+        }, (err) => {
+            rejected = true;
+            return Promise.reject(err);
+        }))).then((value) => resolve(Ok(value)), (err) => err instanceof AggregateError && rejected === false
+            ? resolve(Err(err.errors))
+            : reject(err));
+    }));
+}
+/**
+ * Construct a {@link Result} from an object of results. If all are Ok,
+ * then the result is `Ok` containing an object of the values. Otherwise,
+ * the result is `Err` containing the first error encountered.
+ *
+ * @example
+ *
+ * ```ts
+ * const result: Result<
+ *   { test1: string, test2: number},
+ *   string | Error,
+ * > = Result.$collect({
+ *   test1: Result.$truthy(stringValue, () => new Error("Invalid string")),
+ *   test2: Result.$truthy(numberValue, () => "Invalid number"),
+ * ]);
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const object: { a: 1, b: 2 } = Result.$collect({
+ *   a: Ok(1),
+ *   b: Ok(2),
+ * }).$unwrap();
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const error: "error" = Result.$collect({
+ *   a: Ok(1),
+ *   b: Err("error"),
+ * }).$unwrapErr();
+ * ```
+ */
+function $collect(results) {
+    const oks = {};
+    for (const [key, result] of Object.entries(results)) {
+        const { ok, value } = result[ResultLikeSymbol]();
+        if (ok) {
+            oks[key] = value;
+        }
+        else {
+            return Err(value);
+        }
+    }
+    return Ok(oks);
+}
+/**
+ * The same as {@link Result.$collect|$collect} except it accepts result-like
+ * promises and returns {@link ResultAsync}.
+ */
+function $collectPromised(results) {
+    return new ResultAsync(new Promise((resolve, reject) => {
+        void Promise.all(Object.entries(results).map(([key, result]) => Promise.resolve(result).then((result) => {
+            const { ok, value } = result[ResultLikeSymbol]();
+            return ok ? [key, value] : Promise.reject(value);
+        }, (err) => {
+            reject(err);
+            // Because reject has been called, we can safely return an
+            // empty rejection to ensure we don't end up with undefined
+            // in the Ok path. The subsequent call to resolve will not
+            // change the state of the Promise.
+            return Promise.reject();
+        }))).then((values) => resolve(Ok(Object.fromEntries(values))), (err) => resolve(Err(err)));
+    }));
+}
+function $pipe(f0, ...fnx) {
+    const first = asResult(f0());
+    if (first instanceof ResultErr) {
+        return first;
+    }
+    let current = first[1];
+    for (const fn of fnx) {
+        const result = asResult(fn(current));
+        if (result instanceof ResultErr) {
+            return result;
+        }
+        current = result[1];
+    }
+    return Ok(current);
+}
+function $pipeAsync(f0, ...fnx) {
+    return new ResultAsync((async () => {
+        const first = asResult(await f0());
+        if (first instanceof ResultErr) {
+            return first;
+        }
+        let current = first[1];
+        for (const fn of fnx) {
+            const result = asResult(await fn(current));
+            if (result instanceof ResultErr) {
+                return result;
+            }
+            current = result[1];
+        }
+        return Ok(current);
+    })());
+}
+/**
+ * ## ResultOk
+ *
+ * This is the `Ok` variant of a `Result`, used internally and not exported.
  */
 class ResultOk extends Array {
     constructor(value) {
@@ -143,13 +548,10 @@ class ResultOk extends Array {
         this[0] = undefined;
         this[1] = value;
     }
-    toJSON() {
-        return this[1];
-    }
-    $toNativeTuple() {
-        return [undefined, this[1]];
+    [ResultLikeSymbol]() {
+        return { ok: true, value: this[1] };
     }
-    $value() {
+    toJSON() {
         return this[1];
     }
     $isOk() {
@@ -180,50 +582,120 @@ class ResultOk extends Array {
         return this[1];
     }
     $map(f) {
-        return new ResultOk(f(this[1]));
+        return Ok(f(this[1]));
     }
     $mapErr() {
         return this;
     }
     $mapOr(_def, f) {
-        return new ResultOk(f(this[1]));
+        return Ok(f(this[1]));
     }
     $mapOrElse(_def, f) {
-        return new ResultOk(f(this[1]));
-    }
-    $assertOr(def, condition = isTruthy) {
-        return condition(this[1]) ? this : def;
-    }
-    $assertOrElse(def, condition = isTruthy) {
-        return condition(this[1]) ? this : def();
+        return Ok(f(this[1]));
+    }
+    $assert(mapError) {
+        return this[1]
+            ? this
+            : Err(mapError
+                ? mapError(this[1])
+                : new RetupleAssertFailed(this[1]));
+    }
+    $filter(filter, mapError) {
+        return filter(this[1])
+            ? this
+            : Err(mapError ? mapError(this[1]) : new RetupleFilterFailed(this[1]));
+    }
+    $atIndex(index, mapError) {
+        const element = this[1][index];
+        return element
+            ? Ok(element)
+            : Err(mapError
+                ? mapError(this[1])
+                : new RetupleIndexFailed(index, this[1]));
+    }
+    $firstIndex(mapError) {
+        const first = this[1][0];
+        return first
+            ? Ok(first)
+            : Err(mapError
+                ? mapError(this[1])
+                : new RetupleIndexFailed(0, this[1]));
     }
     $or() {
         return this;
     }
+    $orAsync() {
+        return this.$async();
+    }
     $orElse() {
         return this;
     }
+    $orElseAsync() {
+        return this.$async();
+    }
     $orSafe() {
         return this;
     }
+    $orSafeAsync() {
+        return this.$async();
+    }
+    $orSafePromise() {
+        return this.$async();
+    }
     $and(and) {
-        return and;
+        return asResult(and);
+    }
+    $andAsync(and) {
+        return this.$async().$and(and);
     }
     $andThen(f) {
-        return f(this[1]);
+        return asResult(f(this[1]));
+    }
+    $andStack(f) {
+        const res = asResult(f(this[1]));
+        if (res instanceof ResultErr) {
+            return res;
+        }
+        if (this[1] instanceof RetupleStack) {
+            return Ok(new RetupleStack(...this[1], res[1]));
+        }
+        else {
+            return Ok(new RetupleStack(this[1], res[1]));
+        }
+    }
+    $andThenAsync(f) {
+        return this.$async().$andThen(f);
+    }
+    $andStackAsync(f) {
+        return this.$async().$andStack(f);
     }
     $andThrough(f) {
-        const res = f(this[1]);
+        const res = asResult(f(this[1]));
         return res instanceof ResultErr ? res : this;
     }
+    $andThroughAsync(f) {
+        return this.$async().$andThrough(f);
+    }
     $andSafe(f, mapError = ensureError) {
         try {
-            return new ResultOk(f(this[1]));
+            return Ok(f(this[1]));
         }
         catch (err) {
-            return new ResultErr(mapError(err));
+            return Err(mapError(err));
         }
     }
+    $andSafeAsync(f, mapError = ensureError) {
+        return this.$async().$andSafe(f, mapError);
+    }
+    $andSafePromise(promise, mapError = ensureError) {
+        return this.$async().$andSafePromise(promise, mapError);
+    }
+    $andPipe(f0, ...fx) {
+        return Result.$pipe(() => f0(this[1]), ...fx);
+    }
+    $andPipeAsync(f0, ...fx) {
+        return Result.$pipeAsync(() => f0(this[1]), ...fx);
+    }
     $peek(f) {
         f(this);
         return this;
@@ -244,11 +716,14 @@ class ResultOk extends Array {
     $promise() {
         return Promise.resolve(this);
     }
+    *$iter() {
+        yield* this[1];
+    }
 }
 /**
- * ## Err
+ * ## ResultErr
  *
- * @TODO
+ * This is the `Err` variant of a `Result`, used internally and not exported.
  */
 class ResultErr extends Array {
     constructor(err) {
@@ -256,15 +731,12 @@ class ResultErr extends Array {
         this[0] = err;
         this[1] = undefined;
     }
+    [ResultLikeSymbol]() {
+        return { ok: false, value: this[0] };
+    }
     toJSON() {
         return null;
     }
-    $toNativeTuple() {
-        return [this[0], undefined];
-    }
-    $value() {
-        return this[0];
-    }
     $isOk() {
         return false;
     }
@@ -299,46 +771,91 @@ class ResultErr extends Array {
         return this;
     }
     $mapErr(f) {
-        return new ResultErr(f(this[0]));
+        return Err(f(this[0]));
     }
     $mapOr(def) {
-        return new ResultOk(def);
+        return Ok(def);
     }
     $mapOrElse(def) {
-        return new ResultOk(def(this[0]));
+        return Ok(def(this[0]));
     }
-    $assertOr() {
+    $assert() {
         return this;
     }
-    $assertOrElse() {
+    $filter() {
+        return this;
+    }
+    $atIndex() {
+        return this;
+    }
+    $firstIndex() {
         return this;
     }
     $or(or) {
-        return or;
+        return asResult(or);
+    }
+    $orAsync(or) {
+        return this.$async().$or(or);
     }
     $orElse(f) {
-        return f(this[0]);
+        return asResult(f(this[0]));
+    }
+    $orElseAsync(f) {
+        return this.$async().$orElse(f);
     }
     $orSafe(f, mapError = ensureError) {
         try {
-            return new ResultOk(f(this[0]));
+            return Ok(f(this[0]));
         }
         catch (err) {
-            return new ResultErr(mapError(err));
+            return Err(mapError(err));
         }
     }
+    $orSafeAsync(f, mapError = ensureError) {
+        return this.$async().$orSafe(f, mapError);
+    }
+    $orSafePromise(promise, mapError = ensureError) {
+        return this.$async().$orSafePromise(promise, mapError);
+    }
     $and() {
         return this;
     }
+    $andAsync() {
+        return this.$async();
+    }
     $andThen() {
         return this;
     }
+    $andStack() {
+        return this;
+    }
+    $andThenAsync() {
+        return this.$async();
+    }
+    $andStackAsync() {
+        return this.$async();
+    }
     $andThrough() {
         return this;
     }
+    $andThroughAsync() {
+        return this.$async();
+    }
     $andSafe() {
         return this;
     }
+    $andSafeAsync() {
+        return this.$async();
+    }
+    $andSafePromise() {
+        return this.$async();
+    }
+    $andPipe() {
+        return this;
+    }
+    $andPipeAsync() {
+        return this.$async();
+    }
     $peek(f) {
         f(this);
         return this;
@@ -359,6 +876,9 @@ class ResultErr extends Array {
     $promise() {
         return Promise.resolve(this);
     }
+    *$iter() {
+        return;
+    }
 }
 /**
  * ## ResultAsync
@@ -374,44 +894,79 @@ class ResultAsync {
         return __classPrivateFieldGet(this, _ResultAsync_inner, "f").then(onfulfilled, onrejected);
     }
     /**
-     * @TODO
-     */
-    async $value() {
-        return (await __classPrivateFieldGet(this, _ResultAsync_inner, "f")).$value();
-    }
-    /**
-     * @TODO
+     * The same as {@link Retuple.$expect|$expect}, except it returns a `Promise`.
      */
     async $expect() {
         return (await __classPrivateFieldGet(this, _ResultAsync_inner, "f")).$expect();
     }
     /**
-     * @TODO
+     * The same as {@link Retuple.$unwrap|$unwrap}, except it returns a `Promise`.
      */
     async $unwrap(msg) {
         return (await __classPrivateFieldGet(this, _ResultAsync_inner, "f")).$unwrap(msg);
     }
     /**
-     * @TODO
+     * Resolves this `ResultAsync` using the provided resolver. The resolver
+     * receives a promise which resolves when the result is `Ok` and rejects if
+     * the result is `Err`.
+     *
+     * 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, the promise rejects with `RetupleExpectFailed`.
+     *
+     * @example
+     *
+     * ```ts
+     * async function resolver(promise: Promise<URL>): string {
+     *   try {
+     *     const url = await promise;
+     *
+     *     return url.toString();
+     *   } catch (cause) {
+     *     throw new Error("Not a valid URL", { cause });
+     *   }
+     * }
+     *
+     * const urlString = await Result.$safeAsync(() => getDataAsync())
+     *   .$andSafe((data) => new URL(data.url))
+     *   .$resolve(resolver);
+     * ```
+     */
+    async $resolve(resolver) {
+        return __classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (result) => {
+            if (result instanceof ResultOk) {
+                return await resolver(Promise.resolve(result[1]));
+            }
+            return await resolver(Promise.reject(result[0] instanceof Error
+                ? result[0]
+                : new RetupleExpectFailed(result[0])));
+        });
+    }
+    /**
+     * The same as {@link Retuple.$unwrapErr|$unwrapErr}, except it returns
+     * a `Promise`.
      */
     async $unwrapErr(msg) {
         return (await __classPrivateFieldGet(this, _ResultAsync_inner, "f")).$unwrapErr(msg);
     }
     /**
-     * @TODO
+     * The same as {@link Retuple.$unwrapOr|$unwrapOr}, except it returns
+     * a `Promise`.
      */
     async $unwrapOr(def) {
         return (await __classPrivateFieldGet(this, _ResultAsync_inner, "f")).$unwrapOr(def);
     }
     /**
-     * @TODO
+     * The same as {@link Retuple.$unwrapOrElse|$unwrapOrElse}, except it returns
+     * a `Promise`.
      */
     async $unwrapOrElse(f) {
         const res = await __classPrivateFieldGet(this, _ResultAsync_inner, "f");
         return res instanceof ResultOk ? res[1] : f();
     }
     /**
-     * @TODO
+     * The same as {@link Retuple.$map|$map}, except it returns
+     * {@link ResultAsync}.
      */
     $map(f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
@@ -421,7 +976,8 @@ class ResultAsync {
         }));
     }
     /**
-     * @TODO
+     * The same as {@link Retuple.$mapErr|$mapErr}, except it returns
+     * {@link ResultAsync}.
      */
     $mapErr(f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
@@ -431,7 +987,8 @@ class ResultAsync {
         }));
     }
     /**
-     * @TODO
+     * The same as {@link Retuple.$mapOr|$mapOr}, except it returns
+     * {@link ResultAsync}.
      */
     $mapOr(def, f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
@@ -441,7 +998,8 @@ class ResultAsync {
         }));
     }
     /**
-     * @TODO
+     * The same as {@link Retuple.$mapOrElse|$mapOrElse}, except it returns
+     * {@link ResultAsync}.
      */
     $mapOrElse(def, f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
@@ -450,36 +1008,68 @@ class ResultAsync {
                 : new ResultOk(def(res[0]));
         }));
     }
-    $assertOr(def, condition = isTruthy) {
+    $assert(mapError) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
-            if (res instanceof ResultErr || condition(res[1])) {
+            if (res instanceof ResultErr) {
                 return res;
             }
-            return await def;
+            return res[1]
+                ? res
+                : Err(mapError
+                    ? mapError(res[1])
+                    : new RetupleAssertFailed(res[1]));
         }));
     }
-    $assertOrElse(def, condition = isTruthy) {
+    $filter(check, mapError) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
-            if (res instanceof ResultErr || condition(res[1])) {
+            if (res instanceof ResultErr) {
                 return res;
             }
-            return await def();
+            return check(res[1])
+                ? res
+                : Err(mapError
+                    ? mapError(res[1])
+                    : new RetupleFilterFailed(res[1]));
+        }));
+    }
+    $atIndex(index, mapError) {
+        return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then((res) => {
+            if (res instanceof ResultErr) {
+                return res;
+            }
+            const element = res[1][index];
+            return element
+                ? Ok(element)
+                : Err(mapError
+                    ? mapError(res[1])
+                    : new RetupleIndexFailed(index, res[1]));
+        }));
+    }
+    $firstIndex(mapError) {
+        return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then((res) => {
+            if (res instanceof ResultErr) {
+                return res;
+            }
+            const first = res[1][0];
+            return first
+                ? Ok(first)
+                : Err(mapError
+                    ? mapError(res[1])
+                    : new RetupleIndexFailed(0, res[1]));
         }));
     }
-    /**
-     * @TODO
-     */
     $or(or) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
-            return res instanceof ResultErr ? await or : res;
+            return res instanceof ResultErr
+                ? asResult(await or)
+                : res;
         }));
     }
-    /**
-     * @TODO
-     */
     $orElse(f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
-            return res instanceof ResultErr ? await f(res[0]) : res;
+            return res instanceof ResultErr
+                ? asResult(await f(res[0]))
+                : res;
         }));
     }
     $orSafe(f, mapError = ensureError) {
@@ -495,29 +1085,52 @@ class ResultAsync {
             }
         }));
     }
-    /**
-     * @TODO
-     */
+    $orSafePromise(promise, mapError = ensureError) {
+        return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
+            if (res instanceof ResultOk) {
+                return res;
+            }
+            try {
+                return new ResultOk(await promise);
+            }
+            catch (err) {
+                return new ResultErr(mapError(err));
+            }
+        }));
+    }
     $and(and) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
-            return res instanceof ResultOk ? await and : res;
+            return res instanceof ResultOk
+                ? asResult(await and)
+                : res;
         }));
     }
-    /**
-     * @TODO
-     */
     $andThen(f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
-            return res instanceof ResultOk ? await f(res[1]) : res;
+            return res instanceof ResultOk
+                ? asResult(await f(res[1]))
+                : res;
+        }));
+    }
+    $andStack(f) {
+        return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
+            if (res instanceof ResultErr) {
+                return res;
+            }
+            const resThen = asResult(await f(res[1]));
+            if (resThen instanceof ResultErr) {
+                return resThen;
+            }
+            if (res[1] instanceof RetupleStack) {
+                return Ok(new RetupleStack(...res[1], resThen[1]));
+            }
+            return Ok(new RetupleStack(res[1], resThen[1]));
         }));
     }
-    /**
-     * @TODO
-     */
     $andThrough(f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
             if (res instanceof ResultOk) {
-                const through = await f(res[1]);
+                const through = asResult(await f(res[1]));
                 if (through instanceof ResultErr) {
                     return through;
                 }
@@ -531,15 +1144,47 @@ class ResultAsync {
                 return res;
             }
             try {
-                return new ResultOk(await f(res[1]));
+                return Ok(await f(res[1]));
             }
             catch (err) {
-                return new ResultErr(mapError(err));
+                return Err(mapError(err));
+            }
+        }));
+    }
+    $andSafePromise(promise, mapError = ensureError) {
+        return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
+            if (res instanceof ResultErr) {
+                return res;
+            }
+            try {
+                return Ok(await promise);
+            }
+            catch (err) {
+                return Err(mapError(err));
+            }
+        }));
+    }
+    $andPipe(...fx) {
+        return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
+            if (res instanceof ResultErr) {
+                return res;
             }
+            let current = res[1];
+            for (const f of fx) {
+                const result = asResult(await f(current));
+                if (result instanceof ResultErr) {
+                    return result;
+                }
+                current = result[1];
+            }
+            return Ok(current);
         }));
     }
     /**
-     * @TODO
+     * The same as {@link Retuple.$peek|$peek}, except it:
+     *
+     * - awaits the peek function;
+     * - returns {@link ResultAsync}.
      */
     $peek(f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
@@ -548,7 +1193,10 @@ class ResultAsync {
         }));
     }
     /**
-     * @TODO
+     * The same as {@link Retuple.$tap|$tap}, except it:
+     *
+     * - awaits the tap function;
+     * - returns {@link ResultAsync}.
      */
     $tap(f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
@@ -559,7 +1207,10 @@ class ResultAsync {
         }));
     }
     /**
-     * @TODO
+     * The same as {@link Retuple.$tapErr|$tapErr}, except it:
+     *
+     * - awaits the tap error function;
+     * - returns {@link ResultAsync}.
      */
     $tapErr(f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
@@ -570,22 +1221,171 @@ class ResultAsync {
         }));
     }
     /**
-     * @TODO
+     * The same as {@link Retuple.$flatten|$flatten} except it returns
+     * {@link ResultAsync}.
+     */
+    $flatten() {
+        return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then((res) => res.$flatten()));
+    }
+    /**
+     * The same as {@link Retuple.$promise|$promise}.
      */
     $promise() {
         return Promise.resolve(this);
     }
+    /**
+     * The same as {@link Retuple.$iter|$iter}, except it returns a `Promise`.
+     */
+    async $iter() {
+        return (await __classPrivateFieldGet(this, _ResultAsync_inner, "f")).$iter();
+    }
 }
 _ResultAsync_inner = new WeakMap();
+/**
+ * ## ResultRetry
+ */
+class ResultRetry extends ResultAsync {
+    static zero() {
+        return 0;
+    }
+    static delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, Math.min(ms, _a.MAX_TIMEOUT)));
+    }
+    static integer(value) {
+        if (typeof value === "number" && Number.isInteger(value)) {
+            return Math.max(0, value);
+        }
+        return 0;
+    }
+    constructor(f) {
+        super(Promise.resolve().then(() => __classPrivateFieldGet(this, _ResultRetry_promise, "f")));
+        _ResultRetry_f.set(this, void 0);
+        _ResultRetry_promise.set(this, void 0);
+        _ResultRetry_times.set(this, 1);
+        _ResultRetry_attempt.set(this, 0);
+        _ResultRetry_aborted.set(this, false);
+        _ResultRetry_abort.set(this, () => (__classPrivateFieldSet(this, _ResultRetry_aborted, true, "f")));
+        _ResultRetry_getDelay.set(this, _a.zero);
+        _ResultRetry_handler.set(this, void 0);
+        __classPrivateFieldSet(this, _ResultRetry_f, f, "f");
+        __classPrivateFieldSet(this, _ResultRetry_promise, this.drain(), "f");
+    }
+    then(onfulfilled, onrejected) {
+        return super.then(onfulfilled, onrejected);
+    }
+    /**
+     * 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(times) {
+        __classPrivateFieldSet(this, _ResultRetry_times, Math.min(Math.max(1, _a.integer(times)), _a.MAX_RETRY), "f");
+        return this;
+    }
+    $delay(fnOrMs) {
+        if (typeof fnOrMs === "function") {
+            __classPrivateFieldSet(this, _ResultRetry_getDelay, fnOrMs, "f");
+            return this;
+        }
+        const delay = _a.integer(fnOrMs);
+        if (delay > 0) {
+            __classPrivateFieldSet(this, _ResultRetry_getDelay, () => delay, "f");
+        }
+        return this;
+    }
+    /**
+     * 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) {
+        __classPrivateFieldSet(this, _ResultRetry_handler, f, "f");
+        return this;
+    }
+    async drain() {
+        var _b;
+        while (__classPrivateFieldGet(this, _ResultRetry_attempt, "f") < __classPrivateFieldGet(this, _ResultRetry_times, "f")) {
+            const result = asResult(await __classPrivateFieldGet(this, _ResultRetry_f, "f").call(this));
+            __classPrivateFieldSet(this, _ResultRetry_attempt, (_b = __classPrivateFieldGet(this, _ResultRetry_attempt, "f"), _b++, _b), "f");
+            if (result.$isOk()) {
+                return result;
+            }
+            if (__classPrivateFieldGet(this, _ResultRetry_handler, "f")) {
+                await __classPrivateFieldGet(this, _ResultRetry_handler, "f").call(this, {
+                    error: result[0],
+                    attempt: __classPrivateFieldGet(this, _ResultRetry_attempt, "f"),
+                    abort: __classPrivateFieldGet(this, _ResultRetry_abort, "f"),
+                });
+            }
+            if (__classPrivateFieldGet(this, _ResultRetry_aborted, "f") || __classPrivateFieldGet(this, _ResultRetry_attempt, "f") >= __classPrivateFieldGet(this, _ResultRetry_times, "f")) {
+                return result;
+            }
+            const delay = _a.integer(__classPrivateFieldGet(this, _ResultRetry_getDelay, "f").call(this, __classPrivateFieldGet(this, _ResultRetry_attempt, "f")));
+            if (delay > 0) {
+                await _a.delay(delay);
+            }
+        }
+        /* v8 ignore next */
+        throw new Error("Retuple: Unreachable code executed");
+    }
+}
+_a = ResultRetry, _ResultRetry_f = new WeakMap(), _ResultRetry_promise = new WeakMap(), _ResultRetry_times = new WeakMap(), _ResultRetry_attempt = new WeakMap(), _ResultRetry_aborted = new WeakMap(), _ResultRetry_abort = new WeakMap(), _ResultRetry_getDelay = new WeakMap(), _ResultRetry_handler = new WeakMap();
+ResultRetry.MAX_TIMEOUT = 3600000;
+ResultRetry.MAX_RETRY = 100;
+class RetupleStack extends Array {
+}
+function asResult(resultLike) {
+    if (resultLike instanceof ResultOk || resultLike instanceof ResultErr) {
+        return resultLike;
+    }
+    const result = resultLike[ResultLikeSymbol]();
+    return result.ok ? new ResultOk(result.value) : new ResultErr(result.value);
+}
 function ensureError(err) {
     if (err instanceof Error) {
         return err;
     }
-    return new RetupleThrownValueError(err);
+    return new RetupleCaughtValueError(err);
 }
 function mapTrue() {
     return true;
 }
-function isTruthy(val) {
-    return !!val;
-}