retuple 1.0.0-next.13 → 1.0.0-next.14

package/dist/index.cjs

@@ -10,12 +10,13 @@ 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;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RetupleArrayMethodUnavailableError = exports.RetupleInvalidUnionError = exports.RetupleInvalidResultError = exports.RetupleThrownValueError = exports.RetupleFlattenFailed = exports.RetupleExpectFailed = exports.RetupleUnwrapErrFailed = exports.RetupleUnwrapFailed = void 0;
+exports.RetupleArrayMethodUnavailableError = exports.RetupleInvalidUnionError = exports.RetupleCaughtValueError = exports.RetupleExpectFailed = exports.RetupleUnwrapErrFailed = exports.RetupleUnwrapFailed = void 0;
 exports.Result = Result;
 exports.Ok = Ok;
 exports.Err = Err;
+const symbol_js_1 = require("./symbol.cjs");
 /**
  * ## Retuple Unwrap Failed
  *
@@ -53,19 +54,6 @@ class RetupleExpectFailed extends Error {
     }
 }
 exports.RetupleExpectFailed = RetupleExpectFailed;
-/**
- * ## 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`.
- */
-class RetupleFlattenFailed extends Error {
-    constructor(value) {
-        super("Flatten Result failed, the contained value was not a Result");
-        this.value = value;
-    }
-}
-exports.RetupleFlattenFailed = RetupleFlattenFailed;
 /**
  * ## Retuple Thrown Value Error
  *
@@ -73,28 +61,13 @@ exports.RetupleFlattenFailed = RetupleFlattenFailed;
  * thrown error or rejected value is not an instance of `Error`, and when no
  * map error function is provided.
  */
-class RetupleThrownValueError extends Error {
+class RetupleCaughtValueError extends Error {
     constructor(value) {
         super("Caught value was not an instance of Error");
         this.value = value;
     }
 }
-exports.RetupleThrownValueError = RetupleThrownValueError;
-/**
- * ## 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`.
- */
-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;
-    }
-}
-exports.RetupleInvalidResultError = RetupleInvalidResultError;
+exports.RetupleCaughtValueError = RetupleCaughtValueError;
 /**
  * ## Retuple Invalid Union Error
  *
@@ -130,26 +103,20 @@ exports.RetupleArrayMethodUnavailableError = RetupleArrayMethodUnavailableError;
  * @TODO
  */
 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);
 function Ok(val) {
     return new ResultOk(val);
@@ -158,35 +125,110 @@ 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);
     }
@@ -195,7 +237,7 @@ function union(union) {
     }
     throw new RetupleInvalidUnionError(union);
 }
-function safe(f, mapError = ensureError) {
+function $safe(f, mapError = ensureError) {
     try {
         return Ok(f());
     }
@@ -203,7 +245,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());
@@ -213,16 +255,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());
@@ -242,8 +297,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
      */
@@ -253,8 +307,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
      */
@@ -264,8 +317,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
      */
@@ -275,8 +327,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
      */
@@ -286,8 +337,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
      */
@@ -297,8 +347,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
      */
@@ -308,8 +357,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
      */
@@ -319,8 +367,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
      */
@@ -330,8 +377,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
      */
@@ -341,8 +387,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
      */
@@ -352,8 +397,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
      */
@@ -363,8 +407,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
      */
@@ -374,8 +417,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
      */
@@ -385,8 +427,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
      */
@@ -396,8 +437,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
      */
@@ -407,8 +447,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
      */
@@ -418,8 +457,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
      */
@@ -429,8 +467,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
      */
@@ -440,8 +477,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
      */
@@ -451,8 +487,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
      */
@@ -462,8 +497,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
      */
@@ -473,8 +507,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
      */
@@ -484,8 +517,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
      */
@@ -495,8 +527,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
      */
@@ -506,8 +537,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
      */
@@ -517,8 +547,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
      */
@@ -528,8 +557,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
      */
@@ -539,8 +567,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
      */
@@ -550,8 +577,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
      */
@@ -561,8 +587,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
      */
@@ -572,8 +597,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
      */
@@ -583,8 +607,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
      */
@@ -594,8 +617,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
      */
@@ -605,8 +627,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
      */
@@ -616,8 +637,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
      */
@@ -627,8 +647,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
      */
@@ -638,8 +657,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
      */
@@ -649,8 +667,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
      */
@@ -669,6 +686,9 @@ class ResultOk extends RetupleArray {
         this[0] = undefined;
         this[1] = value;
     }
+    [symbol_js_1.ResultLikeSymbol]() {
+        return this;
+    }
     toJSON() {
         return this[1];
     }
@@ -712,10 +732,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;
@@ -727,13 +747,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) {
@@ -756,11 +776,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));
@@ -768,9 +784,6 @@ class ResultOk extends RetupleArray {
     $promise() {
         return Promise.resolve(this);
     }
-    $tuple() {
-        return [undefined, this[1]];
-    }
     *$iter() {
         yield* this[1];
     }
@@ -786,6 +799,9 @@ class ResultErr extends RetupleArray {
         this[0] = err;
         this[1] = undefined;
     }
+    [symbol_js_1.ResultLikeSymbol]() {
+        return this;
+    }
     toJSON() {
         return null;
     }
@@ -838,10 +854,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 {
@@ -883,9 +899,6 @@ class ResultErr extends RetupleArray {
     $promise() {
         return Promise.resolve(this);
     }
-    $tuple() {
-        return [this[0], undefined];
-    }
     *$iter() {
         return;
     }
@@ -938,37 +951,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) {
@@ -976,7 +999,7 @@ class ResultAsync {
             if (res instanceof ResultErr || condition(res[1])) {
                 return res;
             }
-            return await def;
+            return asResult(await def);
         }));
     }
     $andAssertOrElse(def, condition = isTruthy) {
@@ -984,18 +1007,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;
         }));
     }
@@ -1005,10 +1030,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));
             }
         }));
     }
@@ -1018,27 +1043,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;
                 }
@@ -1076,7 +1105,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) => {
@@ -1088,7 +1117,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) => {
@@ -1102,7 +1131,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) => {
@@ -1119,13 +1148,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();
@@ -1133,7 +1156,7 @@ class ResultAsync {
 }
 _ResultAsync_inner = new WeakMap();
 /**
- * @TODO
+ * ## ResultRetry
  */
 class ResultRetry {
     static zero() {
@@ -1156,7 +1179,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");
     }
@@ -1164,7 +1187,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");
@@ -1182,34 +1225,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")));
@@ -1217,16 +1310,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[symbol_js_1.ResultLikeSymbol]();
+}
 function ensureError(err) {
     if (err instanceof Error) {
         return err;
     }
-    return new RetupleThrownValueError(err);
+    return new RetupleCaughtValueError(err);
 }
 function mapTrue() {
     return true;