retuple 1.0.0-next.13 → 1.0.0-next.15

package/dist/index.js

@@ -9,7 +9,42 @@ 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, _a, _ResultRetry_f, _ResultRetry_promise, _ResultRetry_times, _ResultRetry_attempt, _ResultRetry_aborted, _ResultRetry_abort, _ResultRetry_getDelay, _ResultRetry_errorHandler;
+var _ResultAsync_inner, _a, _ResultRetry_f, _ResultRetry_promise, _ResultRetry_times, _ResultRetry_attempt, _ResultRetry_aborted, _ResultRetry_abort, _ResultRetry_getDelay, _ResultRetry_handler;
+/**
+ * ## Result Like Symbol
+ *
+ * Implement a custom result-like by implementing the `ResultLike` interface
+ * on a class or object. An object with this implementation can be converted
+ * to a `Result` and can be used in most places where a `Result` is required.
+ *
+ * ```ts
+ * import { ResultLikeSymbol } from "retuple/symbol";
+ * import { Result, Ok, Err, type ResultLike } from "retuple";
+ *
+ * class CustomResult<T> implements ResultLike<T, CustomError> {
+ *   value: T;
+ *
+ *   constructor(value: T) {
+ *     this.value = value;
+ *   }
+ *
+ *   [ResultLikeSymbol](): Result<T, CustomError> {
+ *     return this.value === "test"
+ *       ? Ok(this.value)
+ *       : Err(new CustomError("Value was not test"));
+ *   }
+ * }
+ *
+ * const custom = new CustomResult("test");
+ * const result: Result<string, Error> = Result(custom);
+ *
+ * const chain = Ok()
+ *  .$map(() => "value")
+ *  .$andThen((value) => new CustomResult(value))
+ *  .$or(myresult);
+ * ```
+ */
+export const ResultLikeSymbol = Symbol("retuple/result");
 /**
  * ## Retuple Unwrap Failed
  *
@@ -44,18 +79,6 @@ export class RetupleExpectFailed extends Error {
         this.value = value;
     }
 }
-/**
- * ## 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 class RetupleFlattenFailed extends Error {
-    constructor(value) {
-        super("Flatten Result failed, the contained value was not a Result");
-        this.value = value;
-    }
-}
 /**
  * ## Retuple Thrown Value Error
  *
@@ -63,26 +86,12 @@ export class RetupleFlattenFailed 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
- *
- * 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 class RetupleInvalidResultError extends Error {
-    constructor(value) {
-        super("Constructing a Result from native tuple failed, at least one of the " +
-            "values at index 0 or 1 should be null or undefined");
-        this.value = value;
-    }
-}
 /**
  * ## Retuple Invalid Union Error
  *
@@ -116,26 +125,20 @@ export class RetupleArrayMethodUnavailableError 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.$resolve = resolve;
-Result.$nonNullable = nonNullable;
-Result.$truthy = truthy;
-Result.$union = union;
-Result.$safe = safe;
-Result.$safeAsync = safeAsync;
-Result.$safePromise = safePromise;
-Result.$retry = retry;
-Result.$safeRetry = safeRetry;
+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;
 Object.freeze(Result);
 export function Ok(val) {
     return new ResultOk(val);
@@ -144,35 +147,110 @@ export function Err(err) {
     return new ResultErr(err);
 }
 /**
- * @TODO
+ * 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 resolve(result) {
-    if (result instanceof ResultAsync) {
+function $from(result) {
+    if (result instanceof ResultOk || result instanceof ResultErr) {
         return result;
     }
-    else if (result instanceof ResultOk || result instanceof ResultErr) {
-        return result.$async();
-    }
-    else {
-        return new ResultAsync(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 ResultRetry:
+            return new ResultAsync(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) {
+function $nonNullable(value, error = mapTrue) {
     if (value !== null && value !== undefined) {
         return Ok(value);
     }
     return Err(error());
 }
-function truthy(value, error = mapTrue) {
+function $truthy(value, error = mapTrue) {
     if (value) {
         return Ok(value);
     }
     return Err(error());
 }
 /**
- * @TODO
+ * 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 union(union) {
+function $fromUnion(union) {
     if (union.success === true) {
         return Ok(union.data);
     }
@@ -181,7 +259,7 @@ function union(union) {
     }
     throw new RetupleInvalidUnionError(union);
 }
-function safe(f, mapError = ensureError) {
+function $safe(f, mapError = ensureError) {
     try {
         return Ok(f());
     }
@@ -189,7 +267,7 @@ function safe(f, mapError = ensureError) {
         return Err(mapError(err));
     }
 }
-function safeAsync(f, mapError = ensureError) {
+function $safeAsync(f, mapError = ensureError) {
     return new ResultAsync((async () => {
         try {
             return Ok(await f());
@@ -199,16 +277,29 @@ function safeAsync(f, mapError = ensureError) {
         }
     })());
 }
-function safePromise(promise, mapError = ensureError) {
+function $safePromise(promise, mapError = ensureError) {
     return new ResultAsync(promise.then((Ok), async (err) => Err(await mapError(err))));
 }
 /**
- * @TODO
+ * 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.
+ *
+ * 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) {
+function $retry(f) {
     return new ResultRetry(f);
 }
-function safeRetry(f, mapError = ensureError) {
+function $safeRetry(f, mapError = ensureError) {
     return new ResultRetry(async () => {
         try {
             return Ok(await f());
@@ -228,8 +319,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -239,8 +329,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -250,8 +339,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -261,8 +349,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -272,8 +359,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -283,8 +369,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -294,8 +379,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -305,8 +389,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -316,8 +399,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -327,8 +409,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -338,8 +419,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -349,8 +429,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -360,8 +439,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -371,8 +449,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -382,8 +459,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -393,8 +469,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -404,8 +479,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -415,8 +489,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -426,8 +499,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -437,8 +509,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -448,8 +519,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -459,8 +529,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -470,8 +539,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -481,8 +549,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -492,8 +559,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -503,8 +569,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -514,8 +579,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -525,8 +589,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -536,8 +599,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -547,8 +609,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -558,8 +619,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -569,8 +629,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -580,8 +639,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -591,8 +649,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -602,8 +659,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -613,8 +669,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -624,8 +679,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -635,8 +689,7 @@ class RetupleArray extends Array {
     /**
      * ## Method not available
      *
-     * Built-in array methods not available on `Result` types, convert the result
-     * to a tuple using `$tuple()` first.
+     * Built-in array methods not available on {@link Result} types.
      *
      * @deprecated
      */
@@ -655,6 +708,9 @@ class ResultOk extends RetupleArray {
         this[0] = undefined;
         this[1] = value;
     }
+    [ResultLikeSymbol]() {
+        return this;
+    }
     toJSON() {
         return this[1];
     }
@@ -698,10 +754,10 @@ class ResultOk extends RetupleArray {
         return Ok(f(this[1]));
     }
     $andAssertOr(def, condition = isTruthy) {
-        return condition(this[1]) ? this : def;
+        return condition(this[1]) ? this : asResult(def);
     }
     $andAssertOrElse(def, condition = isTruthy) {
-        return condition(this[1]) ? this : def(this[1]);
+        return condition(this[1]) ? this : asResult(def(this[1]));
     }
     $or() {
         return this;
@@ -713,13 +769,13 @@ class ResultOk extends RetupleArray {
         return this;
     }
     $and(and) {
-        return and;
+        return asResult(and);
     }
     $andThen(f) {
-        return f(this[1]);
+        return asResult(f(this[1]));
     }
     $andThrough(f) {
-        const res = f(this[1]);
+        const res = asResult(f(this[1]));
         return res instanceof ResultErr ? res : this;
     }
     $andSafe(f, mapError = ensureError) {
@@ -742,11 +798,7 @@ class ResultOk extends RetupleArray {
         return this;
     }
     $flatten() {
-        const inner = this[1];
-        if (inner instanceof ResultOk || inner instanceof ResultErr) {
-            return inner;
-        }
-        throw new RetupleFlattenFailed(this[1]);
+        return this[1];
     }
     $async() {
         return new ResultAsync(Promise.resolve(this));
@@ -754,9 +806,6 @@ class ResultOk extends RetupleArray {
     $promise() {
         return Promise.resolve(this);
     }
-    $tuple() {
-        return [undefined, this[1]];
-    }
     *$iter() {
         yield* this[1];
     }
@@ -772,6 +821,9 @@ class ResultErr extends RetupleArray {
         this[0] = err;
         this[1] = undefined;
     }
+    [ResultLikeSymbol]() {
+        return this;
+    }
     toJSON() {
         return null;
     }
@@ -824,10 +876,10 @@ class ResultErr extends RetupleArray {
         return this;
     }
     $or(or) {
-        return or;
+        return asResult(or);
     }
     $orElse(f) {
-        return f(this[0]);
+        return asResult(f(this[0]));
     }
     $orSafe(f, mapError = ensureError) {
         try {
@@ -869,9 +921,6 @@ class ResultErr extends RetupleArray {
     $promise() {
         return Promise.resolve(this);
     }
-    $tuple() {
-        return [this[0], undefined];
-    }
     *$iter() {
         return;
     }
@@ -924,37 +973,47 @@ class ResultAsync {
         return res instanceof ResultOk ? res[1] : f();
     }
     /**
-     * The same as {@link Retuple.$map|$map}, except it returns `ResultAsync`.
+     * 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) => {
-            return res instanceof ResultOk ? Ok(f(res[1])) : res;
+            return res instanceof ResultOk
+                ? new ResultOk(f(res[1]))
+                : res;
         }));
     }
     /**
      * The same as {@link Retuple.$mapErr|$mapErr}, except it returns
-     * `ResultAsync`.
+     * {@link ResultAsync}.
      */
     $mapErr(f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
-            return res instanceof ResultErr ? Err(f(res[0])) : res;
+            return res instanceof ResultErr
+                ? new ResultErr(f(res[0]))
+                : res;
         }));
     }
     /**
-     * The same as {@link Retuple.$mapOr|$mapOr}, except it returns `ResultAsync`.
+     * 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) => {
-            return res instanceof ResultOk ? Ok(f(res[1])) : Ok(def);
+            return res instanceof ResultOk
+                ? new ResultOk(f(res[1]))
+                : new ResultOk(def);
         }));
     }
     /**
      * The same as {@link Retuple.$mapOrElse|$mapOrElse}, except it returns
-     * `ResultAsync`.
+     * {@link ResultAsync}.
      */
     $mapOrElse(def, f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
-            return res instanceof ResultOk ? Ok(f(res[1])) : Ok(def(res[0]));
+            return res instanceof ResultOk
+                ? new ResultOk(f(res[1]))
+                : new ResultOk(def(res[0]));
         }));
     }
     $andAssertOr(def, condition = isTruthy) {
@@ -962,7 +1021,7 @@ class ResultAsync {
             if (res instanceof ResultErr || condition(res[1])) {
                 return res;
             }
-            return await def;
+            return asResult(await def);
         }));
     }
     $andAssertOrElse(def, condition = isTruthy) {
@@ -970,18 +1029,20 @@ class ResultAsync {
             if (res instanceof ResultErr || condition(res[1])) {
                 return res;
             }
-            return await def(res[1]);
+            return asResult(await def(res[1]));
         }));
     }
     $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;
         }));
     }
     $orElse(f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
             return res instanceof ResultErr
-                ? await f(res[0])
+                ? asResult(await f(res[0]))
                 : res;
         }));
     }
@@ -991,10 +1052,10 @@ class ResultAsync {
                 return res;
             }
             try {
-                return Ok(await f(res[0]));
+                return new ResultOk(await f(res[0]));
             }
             catch (err) {
-                return Err(mapError(err));
+                return new ResultErr(mapError(err));
             }
         }));
     }
@@ -1004,27 +1065,31 @@ class ResultAsync {
                 return res;
             }
             try {
-                return Ok(await promise);
+                return new ResultOk(await promise);
             }
             catch (err) {
-                return Err(mapError(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;
         }));
     }
     $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;
         }));
     }
     $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;
                 }
@@ -1062,7 +1127,7 @@ class ResultAsync {
      * The same as {@link Retuple.$peek|$peek}, except it:
      *
      * - awaits the peek function;
-     * - returns `ResultAsync`.
+     * - returns {@link ResultAsync}.
      */
     $peek(f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
@@ -1074,7 +1139,7 @@ class ResultAsync {
      * The same as {@link Retuple.$tap|$tap}, except it:
      *
      * - awaits the tap function;
-     * - returns `ResultAsync`.
+     * - returns {@link ResultAsync}.
      */
     $tap(f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
@@ -1088,7 +1153,7 @@ class ResultAsync {
      * The same as {@link Retuple.$tapErr|$tapErr}, except it:
      *
      * - awaits the tap error function;
-     * - returns `ResultAsync`.
+     * - returns {@link ResultAsync}.
      */
     $tapErr(f) {
         return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then(async (res) => {
@@ -1105,13 +1170,7 @@ class ResultAsync {
         return Promise.resolve(this);
     }
     /**
-     * The same as {@link Retuple.$tuple|$tuple}, except it returns a `Promise`.
-     */
-    async $tuple() {
-        return (await __classPrivateFieldGet(this, _ResultAsync_inner, "f")).$tuple();
-    }
-    /**
-     * The same as {@link Retuple.$tuple|$iter}, except it returns a `Promise`.
+     * The same as {@link Retuple.$iter|$iter}, except it returns a `Promise`.
      */
     async $iter() {
         return (await __classPrivateFieldGet(this, _ResultAsync_inner, "f")).$iter();
@@ -1119,7 +1178,7 @@ class ResultAsync {
 }
 _ResultAsync_inner = new WeakMap();
 /**
- * @TODO
+ * ## ResultRetry
  */
 class ResultRetry {
     static zero() {
@@ -1142,7 +1201,7 @@ class ResultRetry {
         _ResultRetry_aborted.set(this, false);
         _ResultRetry_abort.set(this, () => (__classPrivateFieldSet(this, _ResultRetry_aborted, true, "f")));
         _ResultRetry_getDelay.set(this, _a.zero);
-        _ResultRetry_errorHandler.set(this, void 0);
+        _ResultRetry_handler.set(this, void 0);
         __classPrivateFieldSet(this, _ResultRetry_f, f, "f");
         __classPrivateFieldSet(this, _ResultRetry_promise, this.drain(), "f");
     }
@@ -1150,7 +1209,27 @@ class ResultRetry {
         return __classPrivateFieldGet(this, _ResultRetry_promise, "f").then(onfulfilled, onrejected);
     }
     /**
-     * @TODO - Capped 100
+     * 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");
@@ -1168,34 +1247,84 @@ class ResultRetry {
         return this;
     }
     /**
-     * @TODO
+     * 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();
+     *       }
+     *    });
+     * ```
      */
-    $monitor(f) {
-        __classPrivateFieldSet(this, _ResultRetry_errorHandler, f, "f");
+    $handle(f) {
+        __classPrivateFieldSet(this, _ResultRetry_handler, f, "f");
         return this;
     }
     /**
-     * @TODO
+     * Returns {@link ResultAsync} which resolves to this retried {@link Result}.
+     *
+     * @example
+     *
+     * ```ts
+     * const result: Result<string, SomeError> = await Result
+     *    .$retry(someResultFn)
+     *    .$times(3)
+     *    .$delay(100)
+     *    .$async()
+     *    .$andThen((message) => `Success: ${message}`)
+     *    .$mapErr((code) => new SomeError({ code }));
+     * ```
      */
     $async() {
         return new ResultAsync(this);
     }
+    /**
+     * Returns a `Promise` which resolves to this retried {@link Result}.
+     *
+     * @example
+     *
+     * ```ts
+     * const promise: Promise<Result<string, Error>> = Result
+     *    .$retry(someResultFn)
+     *    .$times(3)
+     *    .$promise();
+     * ```
+     */
+    $promise() {
+        return Promise.resolve(this);
+    }
     async drain() {
         var _b;
         while (__classPrivateFieldGet(this, _ResultRetry_attempt, "f") < __classPrivateFieldGet(this, _ResultRetry_times, "f")) {
-            const result = await __classPrivateFieldGet(this, _ResultRetry_f, "f").call(this);
+            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_errorHandler, "f")) {
-                await __classPrivateFieldGet(this, _ResultRetry_errorHandler, "f").call(this, {
+            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")) {
+            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")));
@@ -1203,16 +1332,21 @@ class ResultRetry {
                 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_errorHandler = new WeakMap();
+_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;
+function asResult(resultLike) {
+    return resultLike[ResultLikeSymbol]();
+}
 function ensureError(err) {
     if (err instanceof Error) {
         return err;
     }
-    return new RetupleThrownValueError(err);
+    return new RetupleCaughtValueError(err);
 }
 function mapTrue() {
     return true;