retuple 1.0.0-next.23 → 1.0.0-next.24

package/dist/index.cjs

@@ -12,7 +12,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 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.RetupleInvalidUnionError = exports.RetupleCaughtValueError = exports.RetupleExpectFailed = exports.RetupleUnwrapErrFailed = exports.RetupleUnwrapFailed = void 0;
+exports.RetupleCheckFailedError = exports.RetupleInvalidUnionError = exports.RetupleCaughtValueError = exports.RetupleExpectFailed = exports.RetupleUnwrapErrFailed = exports.RetupleUnwrapFailed = void 0;
 exports.Result = Result;
 exports.Ok = Ok;
 exports.Err = Err;
@@ -84,6 +84,19 @@ class RetupleInvalidUnionError extends Error {
     }
 }
 exports.RetupleInvalidUnionError = RetupleInvalidUnionError;
+/**
+ * ## Retuple Check Failed Error
+ *
+ * This error is used as the error type of a `Result` when using $andAssert
+ * or $andCheck, when no custom error handler is provided.
+ */
+class RetupleCheckFailedError extends Error {
+    constructor(value) {
+        super("Check failed");
+        this.value = value;
+    }
+}
+exports.RetupleCheckFailedError = RetupleCheckFailedError;
 /**
  * ## Result
  *
@@ -532,11 +545,15 @@ class ResultOk extends Array {
     $mapOrElse(_def, f) {
         return Ok(f(this[1]));
     }
-    $andAssertOr(def, condition = isTruthy) {
-        return condition(this[1]) ? this : asResult(def);
+    $andAssert(mapError = mapCheckError) {
+        return this[1] ? this : Err(mapError(this[1]));
     }
-    $andAssertOrElse(def, condition = isTruthy) {
-        return condition(this[1]) ? this : asResult(def(this[1]));
+    $andCheck(check, mapError = mapCheckError) {
+        return check(this[1]) ? this : Err(mapError(this[1]));
+    }
+    $andFirst(mapError = mapCheckError) {
+        const first = this[1][0];
+        return first ? Ok(first) : Err(mapError(this[1]));
     }
     $or() {
         return this;
@@ -675,10 +692,13 @@ class ResultErr extends Array {
     $mapOrElse(def) {
         return Ok(def(this[0]));
     }
-    $andAssertOr() {
+    $andAssert() {
         return this;
     }
-    $andAssertOrElse() {
+    $andCheck() {
+        return this;
+    }
+    $andFirst() {
         return this;
     }
     $or(or) {
@@ -849,20 +869,31 @@ class ResultAsync {
                 : new ResultOk(def(res[0]));
         }));
     }
-    $andAssertOr(def, condition = isTruthy) {
+    $andAssert(mapError = mapCheckError) {
         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 asResult(await def);
+            return res[1]
+                ? res
+                : Err(mapError(res[1]));
         }));
     }
-    $andAssertOrElse(def, condition = isTruthy) {
+    $andCheck(check, mapError = mapCheckError) {
         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 check(res[1]) ? res : Err(mapError(res[1]));
+        }));
+    }
+    $andFirst(mapError = mapCheckError) {
+        return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then((res) => {
+            if (res instanceof ResultErr) {
                 return res;
             }
-            return asResult(await def(res[1]));
+            const first = res[1][0];
+            return first ? Ok(first) : Err(mapError(res[1]));
         }));
     }
     $or(or) {
@@ -1163,6 +1194,6 @@ function ensureError(err) {
 function mapTrue() {
     return true;
 }
-function isTruthy(val) {
-    return !!val;
+function mapCheckError(value) {
+    return new RetupleCheckFailedError(value);
 }

package/dist/index.d.cts

@@ -59,6 +59,16 @@ export declare class RetupleInvalidUnionError extends Error {
     value: unknown;
     constructor(value: unknown);
 }
+/**
+ * ## Retuple Check Failed Error
+ *
+ * This error is used as the error type of a `Result` when using $andAssert
+ * or $andCheck, when no custom error handler is provided.
+ */
+export declare class RetupleCheckFailedError<const T = unknown> extends Error {
+    value: T;
+    constructor(value: T);
+}
 /**
  * ## Result
  *
@@ -198,23 +208,33 @@ declare class ResultAsync<T, E> {
      */
     $mapOrElse<U, V = U>(this: ResultAsync<T, E>, def: (err: E) => U, f: (val: T) => V): ResultAsync<U | V, never>;
     /**
-     * The same as {@link Retuple.$andAssertOr|$andAssertOr}, except it:
+     * The same as {@link Retuple.$andCheck|$andAssert}, except it:
      *
      * - can also accept a `PromiseLike` default value;
      * - returns {@link ResultAsync}.
      */
-    $andAssertOr<U = T, F = E>(this: ResultAsync<T, E>, def: ResultLikeAwaitable<U, F>): ResultAsync<Truthy<T> | U, E | F>;
-    $andAssertOr<U = T, F = E, A extends T = T>(this: ResultAsync<T, E>, def: ResultLikeAwaitable<U, F>, predicate: (val: T) => val is A): ResultAsync<U | A, E | F>;
-    $andAssertOr<U = T, F = E>(this: ResultAsync<T, E>, def: ResultLikeAwaitable<U, F>, condition: (val: T) => unknown): ResultAsync<T | U, E | F>;
+    $andAssert(this: ResultAsync<T, E>): ResultAsync<Truthy<T>, E | RetupleCheckFailedError<T>>;
+    $andAssert<F = E>(this: ResultAsync<T, E>, mapError: (val: T) => F): ResultAsync<Truthy<T>, E | F>;
+    /**
+     * The same as {@link Retuple.$andCheck|$andCheck}, except it:
+     *
+     * - can also accept an `async` default function;
+     * - returns {@link ResultAsync}.
+     */
+    $andCheck<U extends T = T>(this: ResultAsync<T, E>, predicate: (val: T) => val is U): ResultAsync<U, E | RetupleCheckFailedError<T>>;
+    $andCheck(this: ResultAsync<T, E>, check: (val: T) => unknown): ResultAsync<T, E | RetupleCheckFailedError<T>>;
+    $andCheck<U extends T = T, F = E>(this: ResultAsync<T, E>, predicate: (val: T) => val is U, mapError: (val: T) => F): ResultAsync<U, E | F>;
+    $andCheck<F = E>(this: ResultAsync<T, E>, check: (val: T) => unknown, mapError: (val: T) => F): ResultAsync<T, E | F>;
     /**
-     * The same as {@link Retuple.$andAssertOrElse|$andAssertOrElse}, except it:
+     * The same as {@link Retuple.$andCheck|$andCheck}, except it:
      *
      * - can also accept an `async` default function;
      * - returns {@link ResultAsync}.
      */
-    $andAssertOrElse<U = T, F = E>(this: ResultAsync<T, E>, def: (val: T) => ResultLikeAwaitable<U, F>): ResultAsync<Truthy<T> | U, E | F>;
-    $andAssertOrElse<U = T, F = E, A extends T = T>(this: ResultAsync<T, E>, def: (val: T) => ResultLikeAwaitable<U, F>, predicate: (val: T) => val is A): ResultAsync<U | A, E | F>;
-    $andAssertOrElse<U = T, F = E>(this: ResultAsync<T, E>, def: (val: T) => ResultLikeAwaitable<U, F>, condition: (val: T) => unknown): ResultAsync<T | U, E | F>;
+    $andFirst<U>(this: ResultAsync<readonly [U?, ...any[]], E>): ResultAsync<U, E | RetupleCheckFailedError<T>>;
+    $andFirst(this: ResultAsync<readonly [], E>): ResultAsync<never, E | RetupleCheckFailedError<T>>;
+    $andFirst<U, F = E>(this: ResultAsync<readonly [U?, ...any[]], E>, mapError: (val: T) => F): ResultAsync<U, E | F>;
+    $andFirst<F = E>(this: ResultAsync<readonly [], E>, mapError: (val: T) => F): ResultAsync<T, E | F>;
     /**
      * The same as {@link Retuple.$or|$or}, except it:
      *
@@ -727,164 +747,118 @@ interface Retuple<T, E> extends ResultLike<T, E> {
     /**
      * Performs an assertion when this result is `Ok`:
      *
-     * - returning `Ok` containing the current ok value when it is truthy, and
-     *   when no predicate/condition function is provided. Narrows the `T` type
-     *   to include only truthy values;
-     * - returning `Ok` containing the current ok value when a
-     *   predicate/condition function  is provided and it returns a truthy value.
-     *   Narrows the `T` type to the predicate type (if any);
-     * - returning the default result when no predicate/condition function is
-     *   provided and the current ok value is falsey;
-     * - returning the default result when a predicate/condition function is
-     *   provided and it returns a falsey value.
+     * - returning `Ok` containing the current ok value when it is truthy.
+     *   Narrows the `T` type to include only truthy values;
+     * - returning `Err` containing the return value of the map error function
+     *   when the ok value is falsey;
+     * - returning `Err` containing {@link RetupleCheckFailedError} when the
+     *   ok value is falsey, and when no map error function is provided.
      *
      * Otherwise returns `Err` containing the current error value.
      *
      * @example
      *
      * ```ts
-     * const result: Result<string | null, string> = Ok("test");
-     * const asserted = result.$andAssertOr(Ok("ok-default"));
+     * const result: Result<string | null, never> = Ok("test");
+     * const asserted = result.$andAssert();
      *
-     * asserted satisfies Result<string, string>;
+     * asserted satisfies Result<string, RetupleCheckFailedError<string | null>>;
      * assert.equal(asserted.$unwrap(), "test");
      * ```
      *
      * @example
      *
      * ```ts
-     * const result: Result<string | null, string> = Ok("test");
-     * const asserted = result.$andAssertOr(
-     *    Err("err-default"),
-     *    (val): val is "test" => val === "test",
+     * const result: Result<string | null | undefined, never> = Ok(null);
+     * const asserted = result.$andAssert(
+     *   (val) => val === null ? "value was null" : "value was undefined"
      * );
      *
-     * asserted satisfies Result<"test", string>;
-     * assert.equal(asserted.$unwrap(), "test");
-     * ```
-     *
-     * @example
-     *
-     * ```ts
-     * const result: Result<string | null, string> = Ok(null);
-     * const asserted = result.$andAssertOr(Ok("ok-default"));
-     *
      * asserted satisfies Result<string, string>;
-     * assert.equal(asserted.$unwrap(), "ok-default");
-     * ```
-     *
-     * @example
-     *
-     * ```ts
-     * const result: Result<string | null, string> = Ok("value");
-     * const asserted = result.$andAssertOr(
-     *    Err("err-default"),
-     *    (val): val is "test" => val === "test",
-     * );
-     *
-     * asserted satisfies Result<"test", string>;
-     * assert.equal(asserted.$unwrapErr(), "err-default");
-     * ```
-     *
-     * @example
-     *
-     * ```ts
-     * const result: Result<string | null, string> = Err("test");
-     * const asserted = result.$andAssertOr(
-     *    Err("err-default"),
-     *    (val): val is "test" => val === "test",
-     * );
-     *
-     * asserted satisfies Result<"test", string>;
-     * assert.equal(asserted.$unwrapErr(), "test");
+     * assert.equal(asserted.$unwrapErr(), "value was null");
      * ```
      */
-    $andAssertOr<U = T, F = E>(this: Result<T, E>, def: ResultLike<U, F>): Result<Truthy<T> | U, E | F>;
-    $andAssertOr<U = T, F = E, A extends T = T>(this: Result<T, E>, def: ResultLike<U, F>, predicate: (val: T) => val is A): Result<U | A, E | F>;
-    $andAssertOr<U = T, F = E>(this: Result<T, E>, def: ResultLike<U, F>, condition: (val: T) => unknown): Result<T | U, E | F>;
+    $andAssert(this: Result<T, E>): Result<Truthy<T>, E | RetupleCheckFailedError<T>>;
+    $andAssert<F = E>(this: Result<T, E>, mapError: (val: T) => F): Result<Truthy<T>, E | F>;
     /**
-     * Performs an assertion when this result is `Ok`:
+     * Performs a check when this result is `Ok`:
      *
-     * - returning `Ok` containing the current ok value when it is truthy, and
-     *   when no predicate/condition function is provided. Narrows the `T` type
-     *   to include only truthy values;
-     * - returning `Ok` containing the current ok value when a
-     *   predicate/condition function  is provided and it returns a truthy value.
-     *   Narrows the `T` type to the predicate type (if any);
-     * - returning the result returned by the default function when no
-     *   predicate/condition function is provided and the current ok value is
-     *   falsey;
-     * - returning the result returned by the default function when a
-     *   predicate/condition function is  provided and it returns a falsey value.
+     * - returning `Ok` containing the current ok value when the predicate/check
+     *   function returns true. Narrows the `T` type based on the check function;
+     * - returning `Err` containing the return value of the map error function
+     *   when the ok value fails the check;
+     * - returning `Err` containing {@link RetupleCheckFailedError} when the
+     *   ok value fails the check, and when no map error function is provided.
      *
      * Otherwise returns `Err` containing the current error value.
      *
      * @example
      *
      * ```ts
-     * const result: Result<string | null, string> = Ok("test");
-     * const asserted = result.$andAssertOrElse(
-     *    (val) => Ok(`ok-default:${val}`),
-     * );
+     * const result: Result<string, never> = Ok("test");
+     * const asserted = result.$andCheck((val) => val === "test");
      *
-     * asserted satisfies Result<string, string>;
+     * asserted satisfies Result<string, RetupleCheckFailedError<string>>;
      * assert.equal(asserted.$unwrap(), "test");
      * ```
      *
      * @example
      *
      * ```ts
-     * const result: Result<string | null, string> = Ok("test");
-     * const asserted = result.$andAssertOrElse(
-     *    (val) => Err(`err-default:${val}`),
-     *    (val): val is "test" => val === "test",
+     * const result: Result<string, never> = Ok("test");
+     * const checked = result.$andCheck(
+     *   (val) => val === "value",
+     *   (val) => `value was ${val}`,
      * );
      *
-     * asserted satisfies Result<"test", string>;
-     * assert.equal(asserted.$unwrap(), "test");
+     * checked satisfies Result<"value", string>;
+     * assert.equal(checked.$unwrapErr(), "value was test");
      * ```
+     */
+    $andCheck<U extends T = T>(this: Result<T, E>, predicate: (val: T) => val is U): Result<U, E | RetupleCheckFailedError<T>>;
+    $andCheck(this: Result<T, E>, check: (val: T) => unknown): Result<T, E | RetupleCheckFailedError<T>>;
+    $andCheck<U extends T = T, F = E>(this: Result<T, E>, predicate: (val: T) => val is U, mapError: (val: T) => F): Result<U, E | F>;
+    $andCheck<F = E>(this: Result<T, E>, check: (val: T) => unknown, mapError: (val: T) => F): Result<T, E | F>;
+    /**
+     * Checks the first element of the contained array when when this result
+     * is `Ok`:
      *
-     * @example
-     *
-     * ```ts
-     * const result: Result<string | null, string> = Ok(null);
-     * const asserted = result.$andAssertOrElse(
-     *    (val) => Ok(`ok-default:${val}`),
-     * );
+     * - returning `Ok` containing the first array element when it is truthy.
+     *   Narrows the type to include only truthy values;
+     * - returning `Err` containing the return value of the map error function
+     *   when the first array element fails the check;
+     * - returning `Err` containing {@link RetupleCheckFailedError} when the
+     *   first array elemnt fails the check, and when no map error function is
+     *   provided.
      *
-     * asserted satisfies Result<string, string>;
-     * assert.equal(asserted.$unwrap(), "ok-default:null");
-     * ```
+     * Otherwise returns `Err` containing the current error value.
      *
      * @example
      *
      * ```ts
-     * const result: Result<string | null, string> = Ok("value");
-     * const asserted = result.$andAssertOrElse(
-     *    (val) => Err(`err-default:${val}`),
-     *    (val): val is "test" => val === "test",
-     * );
+     * const result: Result<(string | null)[], never> = Ok(["test", null]);
+     * const first = result.$andFirst();
      *
-     * asserted satisfies Result<"test", string>;
-     * assert.equal(asserted.$unwrapErr(), "err-default:value");
+     * first satisfies Result<string, RetupleCheckFailedError<string | null>>;
+     * assert.equal(first.$unwrap(), "test");
      * ```
      *
      * @example
      *
      * ```ts
-     * const result: Result<string | null, string> = Err("test");
-     * const asserted = result.$andAssertOrElse(
-     *    (val) => Err(`err-default:${val}`),
-     *    (val): val is "test" => val === "test",
+     * const result: Result<(string | null | undefined)[], never> = Ok([null, "test"]);
+     * const first = result.$andFirst(
+     *   (val) => val === null ? "value was null" : "value was undefined",
      * );
      *
-     * asserted satisfies Result<"test", string>;
-     * assert.equal(asserted.$unwrapErr(), "test");
+     * first satisfies Result<string, string>;
+     * assert.equal(first.$unwrapErr(), "value was null");
      * ```
      */
-    $andAssertOrElse<U = T, F = E>(this: Result<T, E>, def: (val: T) => ResultLike<U, F>): Result<Truthy<T> | U, E | F>;
-    $andAssertOrElse<U = T, F = E, A extends T = T>(this: Result<T, E>, def: (val: T) => ResultLike<U, F>, predicate: (val: T) => val is A): Result<U | A, E | F>;
-    $andAssertOrElse<U = T, F = E>(this: Result<T, E>, def: (val: T) => ResultLike<U, F>, condition: (val: T) => unknown): Result<T | U, E | F>;
+    $andFirst(this: Result<readonly [], E>): Result<never, E | RetupleCheckFailedError<[]>>;
+    $andFirst<U>(this: Result<readonly [U?, ...any[]], E>): Result<Truthy<U>, E | RetupleCheckFailedError<T>>;
+    $andFirst<F = E>(this: Result<readonly [], E>, mapError: (val: readonly []) => F): Result<never, E | F>;
+    $andFirst<U, F = E>(this: Result<readonly [U?, ...any[]], E>, mapError: (val: T) => F): Result<Truthy<U>, E | F>;
     /**
      * Returns `Ok` containing the return value of the map function when this
      * result is `Ok`.
@@ -911,10 +885,10 @@ interface Retuple<T, E> extends ResultLike<T, E> {
      * );
      * ```
      */
-    $map<U>(this: Result<T, E>, f: (value: T) => U): Result<U, E>;
+    $map<U>(this: Result<T, E>, f: (val: T) => U): Result<U, E>;
     /**
-     * Returns `Err` containing the return value of the map function when this
-     * result is `Err`.
+     * Returns `Err` containing the return value of the map error function
+     * when this result is `Err`.
      *
      * Otherwise, returns `Ok` containing the current ok value.
      *
@@ -1351,10 +1325,6 @@ interface Retuple<T, E> extends ResultLike<T, E> {
      *
      * Otherwise returns `Err` containing the current error value.
      *
-     * This method should only be called when the `T` type is `Result`. This
-     * is enforced with a type constraint. If the ok value is not
-     * a result, `RetupleFlattenFailed` is thrown.
-     *
      * @example
      *
      * ```ts

package/dist/index.d.ts

@@ -59,6 +59,16 @@ export declare class RetupleInvalidUnionError extends Error {
     value: unknown;
     constructor(value: unknown);
 }
+/**
+ * ## Retuple Check Failed Error
+ *
+ * This error is used as the error type of a `Result` when using $andAssert
+ * or $andCheck, when no custom error handler is provided.
+ */
+export declare class RetupleCheckFailedError<const T = unknown> extends Error {
+    value: T;
+    constructor(value: T);
+}
 /**
  * ## Result
  *
@@ -198,23 +208,33 @@ declare class ResultAsync<T, E> {
      */
     $mapOrElse<U, V = U>(this: ResultAsync<T, E>, def: (err: E) => U, f: (val: T) => V): ResultAsync<U | V, never>;
     /**
-     * The same as {@link Retuple.$andAssertOr|$andAssertOr}, except it:
+     * The same as {@link Retuple.$andCheck|$andAssert}, except it:
      *
      * - can also accept a `PromiseLike` default value;
      * - returns {@link ResultAsync}.
      */
-    $andAssertOr<U = T, F = E>(this: ResultAsync<T, E>, def: ResultLikeAwaitable<U, F>): ResultAsync<Truthy<T> | U, E | F>;
-    $andAssertOr<U = T, F = E, A extends T = T>(this: ResultAsync<T, E>, def: ResultLikeAwaitable<U, F>, predicate: (val: T) => val is A): ResultAsync<U | A, E | F>;
-    $andAssertOr<U = T, F = E>(this: ResultAsync<T, E>, def: ResultLikeAwaitable<U, F>, condition: (val: T) => unknown): ResultAsync<T | U, E | F>;
+    $andAssert(this: ResultAsync<T, E>): ResultAsync<Truthy<T>, E | RetupleCheckFailedError<T>>;
+    $andAssert<F = E>(this: ResultAsync<T, E>, mapError: (val: T) => F): ResultAsync<Truthy<T>, E | F>;
+    /**
+     * The same as {@link Retuple.$andCheck|$andCheck}, except it:
+     *
+     * - can also accept an `async` default function;
+     * - returns {@link ResultAsync}.
+     */
+    $andCheck<U extends T = T>(this: ResultAsync<T, E>, predicate: (val: T) => val is U): ResultAsync<U, E | RetupleCheckFailedError<T>>;
+    $andCheck(this: ResultAsync<T, E>, check: (val: T) => unknown): ResultAsync<T, E | RetupleCheckFailedError<T>>;
+    $andCheck<U extends T = T, F = E>(this: ResultAsync<T, E>, predicate: (val: T) => val is U, mapError: (val: T) => F): ResultAsync<U, E | F>;
+    $andCheck<F = E>(this: ResultAsync<T, E>, check: (val: T) => unknown, mapError: (val: T) => F): ResultAsync<T, E | F>;
     /**
-     * The same as {@link Retuple.$andAssertOrElse|$andAssertOrElse}, except it:
+     * The same as {@link Retuple.$andCheck|$andCheck}, except it:
      *
      * - can also accept an `async` default function;
      * - returns {@link ResultAsync}.
      */
-    $andAssertOrElse<U = T, F = E>(this: ResultAsync<T, E>, def: (val: T) => ResultLikeAwaitable<U, F>): ResultAsync<Truthy<T> | U, E | F>;
-    $andAssertOrElse<U = T, F = E, A extends T = T>(this: ResultAsync<T, E>, def: (val: T) => ResultLikeAwaitable<U, F>, predicate: (val: T) => val is A): ResultAsync<U | A, E | F>;
-    $andAssertOrElse<U = T, F = E>(this: ResultAsync<T, E>, def: (val: T) => ResultLikeAwaitable<U, F>, condition: (val: T) => unknown): ResultAsync<T | U, E | F>;
+    $andFirst<U>(this: ResultAsync<readonly [U?, ...any[]], E>): ResultAsync<U, E | RetupleCheckFailedError<T>>;
+    $andFirst(this: ResultAsync<readonly [], E>): ResultAsync<never, E | RetupleCheckFailedError<T>>;
+    $andFirst<U, F = E>(this: ResultAsync<readonly [U?, ...any[]], E>, mapError: (val: T) => F): ResultAsync<U, E | F>;
+    $andFirst<F = E>(this: ResultAsync<readonly [], E>, mapError: (val: T) => F): ResultAsync<T, E | F>;
     /**
      * The same as {@link Retuple.$or|$or}, except it:
      *
@@ -727,164 +747,118 @@ interface Retuple<T, E> extends ResultLike<T, E> {
     /**
      * Performs an assertion when this result is `Ok`:
      *
-     * - returning `Ok` containing the current ok value when it is truthy, and
-     *   when no predicate/condition function is provided. Narrows the `T` type
-     *   to include only truthy values;
-     * - returning `Ok` containing the current ok value when a
-     *   predicate/condition function  is provided and it returns a truthy value.
-     *   Narrows the `T` type to the predicate type (if any);
-     * - returning the default result when no predicate/condition function is
-     *   provided and the current ok value is falsey;
-     * - returning the default result when a predicate/condition function is
-     *   provided and it returns a falsey value.
+     * - returning `Ok` containing the current ok value when it is truthy.
+     *   Narrows the `T` type to include only truthy values;
+     * - returning `Err` containing the return value of the map error function
+     *   when the ok value is falsey;
+     * - returning `Err` containing {@link RetupleCheckFailedError} when the
+     *   ok value is falsey, and when no map error function is provided.
      *
      * Otherwise returns `Err` containing the current error value.
      *
      * @example
      *
      * ```ts
-     * const result: Result<string | null, string> = Ok("test");
-     * const asserted = result.$andAssertOr(Ok("ok-default"));
+     * const result: Result<string | null, never> = Ok("test");
+     * const asserted = result.$andAssert();
      *
-     * asserted satisfies Result<string, string>;
+     * asserted satisfies Result<string, RetupleCheckFailedError<string | null>>;
      * assert.equal(asserted.$unwrap(), "test");
      * ```
      *
      * @example
      *
      * ```ts
-     * const result: Result<string | null, string> = Ok("test");
-     * const asserted = result.$andAssertOr(
-     *    Err("err-default"),
-     *    (val): val is "test" => val === "test",
+     * const result: Result<string | null | undefined, never> = Ok(null);
+     * const asserted = result.$andAssert(
+     *   (val) => val === null ? "value was null" : "value was undefined"
      * );
      *
-     * asserted satisfies Result<"test", string>;
-     * assert.equal(asserted.$unwrap(), "test");
-     * ```
-     *
-     * @example
-     *
-     * ```ts
-     * const result: Result<string | null, string> = Ok(null);
-     * const asserted = result.$andAssertOr(Ok("ok-default"));
-     *
      * asserted satisfies Result<string, string>;
-     * assert.equal(asserted.$unwrap(), "ok-default");
-     * ```
-     *
-     * @example
-     *
-     * ```ts
-     * const result: Result<string | null, string> = Ok("value");
-     * const asserted = result.$andAssertOr(
-     *    Err("err-default"),
-     *    (val): val is "test" => val === "test",
-     * );
-     *
-     * asserted satisfies Result<"test", string>;
-     * assert.equal(asserted.$unwrapErr(), "err-default");
-     * ```
-     *
-     * @example
-     *
-     * ```ts
-     * const result: Result<string | null, string> = Err("test");
-     * const asserted = result.$andAssertOr(
-     *    Err("err-default"),
-     *    (val): val is "test" => val === "test",
-     * );
-     *
-     * asserted satisfies Result<"test", string>;
-     * assert.equal(asserted.$unwrapErr(), "test");
+     * assert.equal(asserted.$unwrapErr(), "value was null");
      * ```
      */
-    $andAssertOr<U = T, F = E>(this: Result<T, E>, def: ResultLike<U, F>): Result<Truthy<T> | U, E | F>;
-    $andAssertOr<U = T, F = E, A extends T = T>(this: Result<T, E>, def: ResultLike<U, F>, predicate: (val: T) => val is A): Result<U | A, E | F>;
-    $andAssertOr<U = T, F = E>(this: Result<T, E>, def: ResultLike<U, F>, condition: (val: T) => unknown): Result<T | U, E | F>;
+    $andAssert(this: Result<T, E>): Result<Truthy<T>, E | RetupleCheckFailedError<T>>;
+    $andAssert<F = E>(this: Result<T, E>, mapError: (val: T) => F): Result<Truthy<T>, E | F>;
     /**
-     * Performs an assertion when this result is `Ok`:
+     * Performs a check when this result is `Ok`:
      *
-     * - returning `Ok` containing the current ok value when it is truthy, and
-     *   when no predicate/condition function is provided. Narrows the `T` type
-     *   to include only truthy values;
-     * - returning `Ok` containing the current ok value when a
-     *   predicate/condition function  is provided and it returns a truthy value.
-     *   Narrows the `T` type to the predicate type (if any);
-     * - returning the result returned by the default function when no
-     *   predicate/condition function is provided and the current ok value is
-     *   falsey;
-     * - returning the result returned by the default function when a
-     *   predicate/condition function is  provided and it returns a falsey value.
+     * - returning `Ok` containing the current ok value when the predicate/check
+     *   function returns true. Narrows the `T` type based on the check function;
+     * - returning `Err` containing the return value of the map error function
+     *   when the ok value fails the check;
+     * - returning `Err` containing {@link RetupleCheckFailedError} when the
+     *   ok value fails the check, and when no map error function is provided.
      *
      * Otherwise returns `Err` containing the current error value.
      *
      * @example
      *
      * ```ts
-     * const result: Result<string | null, string> = Ok("test");
-     * const asserted = result.$andAssertOrElse(
-     *    (val) => Ok(`ok-default:${val}`),
-     * );
+     * const result: Result<string, never> = Ok("test");
+     * const asserted = result.$andCheck((val) => val === "test");
      *
-     * asserted satisfies Result<string, string>;
+     * asserted satisfies Result<string, RetupleCheckFailedError<string>>;
      * assert.equal(asserted.$unwrap(), "test");
      * ```
      *
      * @example
      *
      * ```ts
-     * const result: Result<string | null, string> = Ok("test");
-     * const asserted = result.$andAssertOrElse(
-     *    (val) => Err(`err-default:${val}`),
-     *    (val): val is "test" => val === "test",
+     * const result: Result<string, never> = Ok("test");
+     * const checked = result.$andCheck(
+     *   (val) => val === "value",
+     *   (val) => `value was ${val}`,
      * );
      *
-     * asserted satisfies Result<"test", string>;
-     * assert.equal(asserted.$unwrap(), "test");
+     * checked satisfies Result<"value", string>;
+     * assert.equal(checked.$unwrapErr(), "value was test");
      * ```
+     */
+    $andCheck<U extends T = T>(this: Result<T, E>, predicate: (val: T) => val is U): Result<U, E | RetupleCheckFailedError<T>>;
+    $andCheck(this: Result<T, E>, check: (val: T) => unknown): Result<T, E | RetupleCheckFailedError<T>>;
+    $andCheck<U extends T = T, F = E>(this: Result<T, E>, predicate: (val: T) => val is U, mapError: (val: T) => F): Result<U, E | F>;
+    $andCheck<F = E>(this: Result<T, E>, check: (val: T) => unknown, mapError: (val: T) => F): Result<T, E | F>;
+    /**
+     * Checks the first element of the contained array when when this result
+     * is `Ok`:
      *
-     * @example
-     *
-     * ```ts
-     * const result: Result<string | null, string> = Ok(null);
-     * const asserted = result.$andAssertOrElse(
-     *    (val) => Ok(`ok-default:${val}`),
-     * );
+     * - returning `Ok` containing the first array element when it is truthy.
+     *   Narrows the type to include only truthy values;
+     * - returning `Err` containing the return value of the map error function
+     *   when the first array element fails the check;
+     * - returning `Err` containing {@link RetupleCheckFailedError} when the
+     *   first array elemnt fails the check, and when no map error function is
+     *   provided.
      *
-     * asserted satisfies Result<string, string>;
-     * assert.equal(asserted.$unwrap(), "ok-default:null");
-     * ```
+     * Otherwise returns `Err` containing the current error value.
      *
      * @example
      *
      * ```ts
-     * const result: Result<string | null, string> = Ok("value");
-     * const asserted = result.$andAssertOrElse(
-     *    (val) => Err(`err-default:${val}`),
-     *    (val): val is "test" => val === "test",
-     * );
+     * const result: Result<(string | null)[], never> = Ok(["test", null]);
+     * const first = result.$andFirst();
      *
-     * asserted satisfies Result<"test", string>;
-     * assert.equal(asserted.$unwrapErr(), "err-default:value");
+     * first satisfies Result<string, RetupleCheckFailedError<string | null>>;
+     * assert.equal(first.$unwrap(), "test");
      * ```
      *
      * @example
      *
      * ```ts
-     * const result: Result<string | null, string> = Err("test");
-     * const asserted = result.$andAssertOrElse(
-     *    (val) => Err(`err-default:${val}`),
-     *    (val): val is "test" => val === "test",
+     * const result: Result<(string | null | undefined)[], never> = Ok([null, "test"]);
+     * const first = result.$andFirst(
+     *   (val) => val === null ? "value was null" : "value was undefined",
      * );
      *
-     * asserted satisfies Result<"test", string>;
-     * assert.equal(asserted.$unwrapErr(), "test");
+     * first satisfies Result<string, string>;
+     * assert.equal(first.$unwrapErr(), "value was null");
      * ```
      */
-    $andAssertOrElse<U = T, F = E>(this: Result<T, E>, def: (val: T) => ResultLike<U, F>): Result<Truthy<T> | U, E | F>;
-    $andAssertOrElse<U = T, F = E, A extends T = T>(this: Result<T, E>, def: (val: T) => ResultLike<U, F>, predicate: (val: T) => val is A): Result<U | A, E | F>;
-    $andAssertOrElse<U = T, F = E>(this: Result<T, E>, def: (val: T) => ResultLike<U, F>, condition: (val: T) => unknown): Result<T | U, E | F>;
+    $andFirst(this: Result<readonly [], E>): Result<never, E | RetupleCheckFailedError<[]>>;
+    $andFirst<U>(this: Result<readonly [U?, ...any[]], E>): Result<Truthy<U>, E | RetupleCheckFailedError<T>>;
+    $andFirst<F = E>(this: Result<readonly [], E>, mapError: (val: readonly []) => F): Result<never, E | F>;
+    $andFirst<U, F = E>(this: Result<readonly [U?, ...any[]], E>, mapError: (val: T) => F): Result<Truthy<U>, E | F>;
     /**
      * Returns `Ok` containing the return value of the map function when this
      * result is `Ok`.
@@ -911,10 +885,10 @@ interface Retuple<T, E> extends ResultLike<T, E> {
      * );
      * ```
      */
-    $map<U>(this: Result<T, E>, f: (value: T) => U): Result<U, E>;
+    $map<U>(this: Result<T, E>, f: (val: T) => U): Result<U, E>;
     /**
-     * Returns `Err` containing the return value of the map function when this
-     * result is `Err`.
+     * Returns `Err` containing the return value of the map error function
+     * when this result is `Err`.
      *
      * Otherwise, returns `Ok` containing the current ok value.
      *
@@ -1351,10 +1325,6 @@ interface Retuple<T, E> extends ResultLike<T, E> {
      *
      * Otherwise returns `Err` containing the current error value.
      *
-     * This method should only be called when the `T` type is `Result`. This
-     * is enforced with a type constraint. If the ok value is not
-     * a result, `RetupleFlattenFailed` is thrown.
-     *
      * @example
      *
      * ```ts

package/dist/index.js

@@ -73,6 +73,18 @@ export class RetupleInvalidUnionError extends Error {
         this.value = value;
     }
 }
+/**
+ * ## Retuple Check Failed Error
+ *
+ * This error is used as the error type of a `Result` when using $andAssert
+ * or $andCheck, when no custom error handler is provided.
+ */
+export class RetupleCheckFailedError extends Error {
+    constructor(value) {
+        super("Check failed");
+        this.value = value;
+    }
+}
 /**
  * ## Result
  *
@@ -521,11 +533,15 @@ class ResultOk extends Array {
     $mapOrElse(_def, f) {
         return Ok(f(this[1]));
     }
-    $andAssertOr(def, condition = isTruthy) {
-        return condition(this[1]) ? this : asResult(def);
+    $andAssert(mapError = mapCheckError) {
+        return this[1] ? this : Err(mapError(this[1]));
     }
-    $andAssertOrElse(def, condition = isTruthy) {
-        return condition(this[1]) ? this : asResult(def(this[1]));
+    $andCheck(check, mapError = mapCheckError) {
+        return check(this[1]) ? this : Err(mapError(this[1]));
+    }
+    $andFirst(mapError = mapCheckError) {
+        const first = this[1][0];
+        return first ? Ok(first) : Err(mapError(this[1]));
     }
     $or() {
         return this;
@@ -664,10 +680,13 @@ class ResultErr extends Array {
     $mapOrElse(def) {
         return Ok(def(this[0]));
     }
-    $andAssertOr() {
+    $andAssert() {
         return this;
     }
-    $andAssertOrElse() {
+    $andCheck() {
+        return this;
+    }
+    $andFirst() {
         return this;
     }
     $or(or) {
@@ -838,20 +857,31 @@ class ResultAsync {
                 : new ResultOk(def(res[0]));
         }));
     }
-    $andAssertOr(def, condition = isTruthy) {
+    $andAssert(mapError = mapCheckError) {
         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 asResult(await def);
+            return res[1]
+                ? res
+                : Err(mapError(res[1]));
         }));
     }
-    $andAssertOrElse(def, condition = isTruthy) {
+    $andCheck(check, mapError = mapCheckError) {
         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 check(res[1]) ? res : Err(mapError(res[1]));
+        }));
+    }
+    $andFirst(mapError = mapCheckError) {
+        return new ResultAsync(__classPrivateFieldGet(this, _ResultAsync_inner, "f").then((res) => {
+            if (res instanceof ResultErr) {
                 return res;
             }
-            return asResult(await def(res[1]));
+            const first = res[1][0];
+            return first ? Ok(first) : Err(mapError(res[1]));
         }));
     }
     $or(or) {
@@ -1152,6 +1182,6 @@ function ensureError(err) {
 function mapTrue() {
     return true;
 }
-function isTruthy(val) {
-    return !!val;
+function mapCheckError(value) {
+    return new RetupleCheckFailedError(value);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retuple",
-  "version": "1.0.0-next.23",
+  "version": "1.0.0-next.24",
   "scripts": {
     "test": "vitest",
     "lint": "eslint . --ext .ts -c eslint.config.mjs --fix",