@nlozgachev/pipelined 0.46.0 → 0.48.0

package/dist/{Validation-BMsvixWH.d.ts → Validation-1OgJJdeA.d.ts}

@@ -1,5 +1,6 @@
-import { h as WithKind, o as WithValue, e as WithError, T as Thenable, D as Deferred, a as NonEmptyArr, f as WithErrors } from './InternalTypes-Mssktd7z.js';
-import { Duration } from './types.js';
+import { h as WithKind, o as WithValue, e as WithError, a as NonEmptyArr, T as Thenable, D as Deferred, f as WithErrors } from './InternalTypes-LdhLQx3N.js';
+import { D as Duration } from './Duration-B8joKzro.js';
+import { RetryPolicy } from './types.js';
 
 /**
  * A function that checks whether two values of type `A` are equal.
@@ -86,6 +87,28 @@ declare namespace Equality {
      * ```
      */
     const and: <A>(eq2: Equality<A>) => (eq1: Equality<A>) => Equality<A>;
+    /**
+     * Derives deep equality for a record from field-level `Equality` checkers.
+     *
+     * @example
+     * ```ts
+     * const userEq = Equality.struct({
+     *   id: Equality.string,
+     *   age: Equality.number,
+     * });
+     * ```
+     */
+    const struct: <R extends Record<string, unknown>>(fields: { [K in keyof R]: Equality<R[K]>; }) => Equality<R>;
+    /**
+     * Derives element-wise equality for a tuple from positional `Equality` checkers.
+     *
+     * @example
+     * ```ts
+     * const pairEq = Equality.tuple(Equality.string, Equality.number);
+     * pairEq(["a", 1], ["a", 1]); // true
+     * ```
+     */
+    const tuple: <T extends readonly unknown[]>(...equalities: { [K in keyof T]: Equality<T[K]>; }) => Equality<T>;
 }
 
 type Some<A> = WithKind<"Some"> & WithValue<A>;
@@ -110,30 +133,68 @@ declare namespace Maybe {
     namespace make {
         /**
          * Creates a Some containing the given value.
+         *
+         * @example
+         * ```ts
+         * Maybe.make.some(42); // Some(42)
+         * ```
          */
         const some: <A>(value: A) => Some<A>;
         /**
          * Creates a None (empty Maybe).
+         *
+         * @example
+         * ```ts
+         * Maybe.make.none(); // None
+         * ```
          */
         const none: () => None;
     }
     namespace is {
         /**
          * Type guard that checks if a Maybe is Some.
+         *
+         * @example
+         * ```ts
+         * const value = Maybe.make.some(42);
+         * if (Maybe.is.some(value)) {
+         *   console.log(value.value); // 42
+         * }
+         * ```
          */
         const some: <A>(data: Maybe<A>) => data is Some<A>;
         /**
          * Type guard that checks if a Maybe is None.
+         *
+         * @example
+         * ```ts
+         * const value = Maybe.make.none();
+         * if (Maybe.is.none(value)) {
+         *   console.log("No value present");
+         * }
+         * ```
          */
         const none: <A>(data: Maybe<A>) => data is None;
     }
     namespace to {
         /**
          * Extracts the value from a Maybe, returning null if None.
+         *
+         * @example
+         * ```ts
+         * Maybe.to.nullable(Maybe.make.some(42)); // 42
+         * Maybe.to.nullable(Maybe.make.none());   // null
+         * ```
          */
         const nullable: <A>(data: Maybe<A>) => A | null;
         /**
          * Extracts the value from a Maybe, returning undefined if None.
+         *
+         * @example
+         * ```ts
+         * Maybe.to.undefined(Maybe.make.some(42)); // 42
+         * Maybe.to.undefined(Maybe.make.none());   // undefined
+         * ```
          */
         const undefined: <A>(data: Maybe<A>) => A | undefined;
         /**
@@ -293,6 +354,12 @@ declare namespace Maybe {
     /**
      * Recovers from a None by providing a fallback Maybe.
      * The fallback can produce a different type, widening the result to `Maybe<A | B>`.
+     *
+     * @example
+     * ```ts
+     * pipe(Maybe.make.none(), Maybe.recover(() => Maybe.make.some(42))); // Some(42)
+     * pipe(Maybe.make.some(10), Maybe.recover(() => Maybe.make.some(42))); // Some(10)
+     * ```
      */
     const recover: <A, B>(fallback: () => Maybe<B>) => (data: Maybe<A>) => Maybe<A | B>;
     /**
@@ -344,6 +411,18 @@ declare namespace Maybe {
      * ```
      */
     const struct: <R extends Record<string, any>>(fields: { [K in keyof R]: Maybe<R[K]>; }) => Maybe<R>;
+    /**
+     * Swaps the outer `Maybe` and inner `Result` context.
+     * `Some(Ok(a))` becomes `Ok(Some(a))`, `Some(Err(e))` becomes `Err(e)`, and `None` becomes `Ok(None)`.
+     *
+     * @example
+     * ```ts
+     * Maybe.transposeResult(Maybe.make.some(Result.make.ok(42)));  // Ok(Some(42))
+     * Maybe.transposeResult(Maybe.make.some(Result.make.err("e"))); // Err("e")
+     * Maybe.transposeResult(Maybe.make.none());                     // Ok(None)
+     * ```
+     */
+    const transposeResult: <E, A>(data: Maybe<Result<E, A>>) => Result<E, Maybe<A>>;
 }
 
 /**
@@ -422,6 +501,28 @@ declare namespace Ordering {
      * ```
      */
     const by: <A, B>(f: (b: B) => A) => (ord: Ordering<A>) => Ordering<B>;
+    /**
+     * Combines a list of orderings into a single composite comparator.
+     * Evaluates each ordering in sequence until a non-zero comparison result is found.
+     *
+     * @example
+     * ```ts
+     * const byName = pipe(Ordering.string, Ordering.by((u: User) => u.name));
+     * const byAge  = pipe(Ordering.number, Ordering.by((u: User) => u.age));
+     * const sortUsers = Ordering.byFields([byName, byAge]);
+     * ```
+     */
+    const byFields: <A>(orderings: ReadonlyArray<Ordering<A>>) => Ordering<A>;
+    /**
+     * Derives a lexicographical tuple ordering from positional `Ordering` comparators.
+     *
+     * @example
+     * ```ts
+     * const pairOrd = Ordering.tuple(Ordering.string, Ordering.number);
+     * pairOrd(["a", 1], ["a", 2]); // negative
+     * ```
+     */
+    const tuple: <T extends readonly unknown[]>(...orderings: { [K in keyof T]: Ordering<T[K]>; }) => Ordering<T>;
 }
 
 type Ok<A> = WithKind<"Ok"> & WithValue<A>;
@@ -447,20 +548,46 @@ declare namespace Result {
     namespace make {
         /**
          * Creates a successful Result with the given value.
+         *
+         * @example
+         * ```ts
+         * Result.make.ok(42); // Ok(42)
+         * ```
          */
         const ok: <A>(value: A) => Ok<A>;
         /**
          * Creates a failed Result with the given error.
+         *
+         * @example
+         * ```ts
+         * Result.make.err("Error message"); // Err("Error message")
+         * ```
          */
         const err: <E>(e: E) => Err<E>;
     }
     namespace is {
         /**
          * Type guard that checks if a Result is Ok.
+         *
+         * @example
+         * ```ts
+         * const res = Result.make.ok(42);
+         * if (Result.is.ok(res)) {
+         *   console.log(res.value); // 42
+         * }
+         * ```
          */
         const ok: <E, A>(data: Result<E, A>) => data is Ok<A>;
         /**
          * Type guard that checks if a Result is Err.
+         *
+         * @example
+         * ```ts
+         * const res = Result.make.err("failed");
+         * if (Result.is.err(res)) {
+         *   console.log(res.error); // "failed"
+         * }
+         * ```
          */
         const err: <E, A>(data: Result<E, A>) => data is Err<E>;
     }
@@ -473,11 +600,13 @@ declare namespace Result {
      * const parseJson = (s: string): Result<string, unknown> =>
      *   Result.tryCatch(
      *     () => JSON.parse(s),
-     *     (e) => `Parse error: ${e}`
+     *     { onError: (e) => `Parse error: ${e}` }
      *   );
      * ```
      */
-    const tryCatch: <E, A>(f: () => A, onError: (e: unknown) => E) => Result<E, A>;
+    const tryCatch: <E, A>(f: () => A, options: {
+        onError: (e: unknown) => E;
+    }) => Result<E, A>;
     /**
      * Transforms the success value inside a Result.
      *
@@ -510,7 +639,7 @@ declare namespace Result {
      * pipe(Result.make.ok(-1), Result.chain(validatePositive)); // Err("Must be positive")
      * ```
      */
-    const chain: <E, A, B>(f: (a: A) => Result<E, B>) => (data: Result<E, A>) => Result<E, B>;
+    const chain: <E1, E2, A, B>(f: (a: A) => Result<E2, B>) => (data: Result<E1, A>) => Result<E1 | E2, B>;
     /**
      * Extracts the value from a Result by providing handlers for both cases.
      *
@@ -628,14 +757,26 @@ declare namespace Result {
          * ```ts
          * const safeParse = Result.from.throwable(
          *   (s: string) => JSON.parse(s),
-         *   (e) => new Error(`Parse error: ${e}`)
+         *   { onError: (e) => new Error(`Parse error: ${e}`) }
          * );
          *
          * safeParse('{"a":1}'); // Ok({ a: 1 })
          * safeParse('invalid');  // Err(Error)
          * ```
          */
-        const throwable: <Args extends readonly unknown[], A, E>(f: (...args: Args) => A, onError: (e: unknown) => E) => (...args: Args) => Result<E, A>;
+        const throwable: <Args extends readonly unknown[], A, E>(f: (...args: Args) => A, options: {
+            onError: (e: unknown) => E;
+        }) => (...args: Args) => Result<E, A>;
+        /**
+         * Converts a `Validation` to a `Result`, combining accumulated errors using `combineErrors`.
+         * `Passed(a)` becomes `Ok(a)`; `Failed(errors)` becomes `Err(combineErrors(errors))`.
+         *
+         * @example
+         * ```ts
+         * Result.from.Validation((errors) => errors.join(", "))(Validation.make.failed("error1")); // Err("error1")
+         * ```
+         */
+        const Validation: <E1, E2, A>(combineErrors: (errors: NonEmptyArr<E1>) => E2) => (val: Validation<E1, A>) => Result<E2, A>;
     }
     /**
      * Recovers from an error by providing a fallback Result.
@@ -667,7 +808,29 @@ declare namespace Result {
          * ```
          */
         const Maybe: <E, A>(data: Result<E, A>) => Maybe<A>;
+        /**
+         * Converts a `Result` to a `Validation`. `Ok(a)` becomes `Passed(a)`; `Err(e)` becomes `Failed([e])`.
+         *
+         * @example
+         * ```ts
+         * Result.to.Validation(Result.make.ok(42));     // Passed(42)
+         * Result.to.Validation(Result.make.err("bad")); // Failed(["bad"])
+         * ```
+         */
+        const Validation: <E, A>(data: Result<E, A>) => Validation<E, A>;
     }
+    /**
+     * Swaps the outer `Result` and inner `Maybe` context.
+     * `Ok(Some(a))` becomes `Some(Ok(a))`, `Ok(None)` becomes `None`, and `Err(e)` becomes `Some(Err(e))`.
+     *
+     * @example
+     * ```ts
+     * Result.transposeMaybe(Result.make.ok(Maybe.make.some(42))); // Some(Ok(42))
+     * Result.transposeMaybe(Result.make.ok(Maybe.make.none()));   // None
+     * Result.transposeMaybe(Result.make.err("error"));           // Some(Err("error"))
+     * ```
+     */
+    const transposeMaybe: <E, A>(data: Result<E, Maybe<A>>) => Maybe<Result<E, A>>;
     /**
      * Applies a function wrapped in a Result to a value wrapped in a Result.
      *
@@ -717,6 +880,34 @@ declare namespace Result {
      * ```
      */
     const struct: <E, R extends Record<string, any>>(fields: { [K in keyof R]: Result<E, R[K]>; }) => Result<E, R>;
+    /**
+     * Narrows an `Ok` value with a predicate, converting to `Err(onFail(a))` if the predicate returns false.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Result.make.ok(15),
+     *   Result.ensure((n) => n >= 18, (n) => `Age ${n} is below 18`)
+     * ); // Err("Age 15 is below 18")
+     * ```
+     */
+    const ensure: <A, E2>(predicate: (a: A) => boolean, onFail: (a: A) => E2) => <E1>(data: Result<E1, A>) => Result<E1 | E2, A>;
+    /**
+     * Transforms both branches of a Result simultaneously.
+     * Applies `onErr` to `Err` values and `onOk` to `Ok` values.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Result.make.ok(5),
+     *   Result.bimap(
+     *     (e) => `Error: ${e}`,
+     *     (n) => n * 2
+     *   )
+     * ); // Ok(10)
+     * ```
+     */
+    const bimap: <E1, E2, A, B>(onErr: (e: E1) => E2, onOk: (a: A) => B) => (data: Result<E1, A>) => Result<E2, B>;
 }
 
 /**
@@ -737,29 +928,76 @@ type TaskMaybe<A> = Task<Maybe<A>>;
 declare namespace TaskMaybe {
     /**
      * Wraps a value in a Some inside a Task.
+     *
+     * @example
+     * ```ts
+     * const task = Task.Maybe.some(42);
+     * const res = await task(); // Some(42)
+     * ```
      */
+    namespace make {
+        /**
+         * Creates a Task.Maybe that resolves to Some(value).
+         *
+         * @example
+         * ```ts
+         * const task = Task.Maybe.make.some(42);
+         * const res = await task(); // Some(42)
+         * ```
+         */
+        const some: <A>(value: A) => TaskMaybe<A>;
+        /**
+         * Creates a Task.Maybe that resolves to None.
+         *
+         * @example
+         * ```ts
+         * const task = Task.Maybe.make.none();
+         * const res = await task(); // None
+         * ```
+         */
+        const none: <A = never>() => TaskMaybe<A>;
+    }
     const some: <A>(value: A) => TaskMaybe<A>;
-    /**
-     * Creates a Task.Maybe that resolves to None.
-     */
     const none: <A = never>() => TaskMaybe<A>;
     namespace from {
         /**
-         * Lifts an Option into a Task.Maybe.
+         * Lifts a Maybe into a Task.Maybe.
+         *
+         * @example
+         * ```ts
+         * Task.Maybe.from.Maybe(Maybe.make.some(42));
+         * ```
          */
         const Maybe: <A>(option: Maybe<A>) => TaskMaybe<A>;
         /**
          * Creates a Task.Maybe from a nullable value.
          * Returns Some if the value is not null or undefined, None otherwise.
+         *
+         * @example
+         * ```ts
+         * Task.Maybe.from.nullable(42);   // resolves to Some(42)
+         * Task.Maybe.from.nullable(null); // resolves to None
+         * ```
          */
         const nullable: <A>(value: A | null | undefined) => TaskMaybe<A>;
         /**
          * Creates a Task.Maybe from a Result.
          * Ok becomes Some, Error becomes None (the error value is discarded).
+         *
+         * @example
+         * ```ts
+         * Task.Maybe.from.Result(Result.make.ok(42)); // resolves to Some(42)
+         * Task.Maybe.from.Result(Result.make.err("e")); // resolves to None
+         * ```
          */
         const Result: <E, A>(result: Result<E, A>) => TaskMaybe<A>;
         /**
          * Lifts a Task into a Task.Maybe by wrapping its result in Some.
+         *
+         * @example
+         * ```ts
+         * Task.Maybe.from.Task(Task.resolve(42)); // resolves to Some(42)
+         * ```
          */
         const Task: <A>(task: Task<A>) => TaskMaybe<A>;
     }
@@ -905,40 +1143,87 @@ declare namespace TaskMaybe {
  * const fetchUser = (id: string): Task.Result<Error, User> =>
  *   Task.Result.tryCatch(
  *     (signal) => fetch(`/users/${id}`, { signal }).then(r => r.json()),
- *     (e) => new Error(`Failed to fetch user: ${e}`)
+ *     { onError: (e) => new Error(`Failed to fetch user: ${e}`) }
  *   );
  * ```
  */
 type TaskResult<E, A> = Task<Result<E, A>>;
 declare namespace TaskResult {
-    /**
-     * Wraps a value in a successful Task.Result.
-     */
+    namespace make {
+        /**
+         * Wraps a value in a successful Task.Result.
+         *
+         * @example
+         * ```ts
+         * const task = Task.Result.make.ok(42);
+         * const res = await task(); // Ok(42)
+         * ```
+         */
+        const ok: <E, A>(value: A) => TaskResult<E, A>;
+        /**
+         * Creates a failed Task.Result with the given error.
+         *
+         * @example
+         * ```ts
+         * const task = Task.Result.make.err("failed");
+         * const res = await task(); // Err("failed")
+         * ```
+         */
+        const err: <E, A>(error: E) => TaskResult<E, A>;
+    }
     const ok: <E, A>(value: A) => TaskResult<E, A>;
-    /**
-     * Creates a failed Task.Result with the given error.
-     */
     const err: <E, A>(error: E) => TaskResult<E, A>;
     namespace from {
         /**
          * Creates a Task.Result from a nullable value.
          * Returns Ok if the value is not null or undefined, err from onNull otherwise.
+         *
+         * @example
+         * ```ts
+         * Task.Result.from.nullable(() => "missing")(42);   // resolves to Ok(42)
+         * Task.Result.from.nullable(() => "missing")(null); // resolves to Err("missing")
+         * ```
          */
         const nullable: <E>(onNull: () => E) => <A>(value: A | null | undefined) => TaskResult<E, A>;
         /**
          * Creates a Task.Result from a Maybe.
          * Some becomes Ok, None becomes err from onNone.
+         *
+         * @example
+         * ```ts
+         * Task.Result.from.Maybe(() => "empty")(Maybe.make.some(42)); // resolves to Ok(42)
+         * Task.Result.from.Maybe(() => "empty")(Maybe.make.none());   // resolves to Err("empty")
+         * ```
          */
         const Maybe: <E>(onNone: () => E) => <A>(maybe: Maybe<A>) => TaskResult<E, A>;
         /**
          * Lifts a Result into a Task.Result.
+         *
+         * @example
+         * ```ts
+         * Task.Result.from.Result(Result.make.ok(42)); // resolves to Ok(42)
+         * ```
          */
         const Result: <E, A>(result: Result<E, A>) => TaskResult<E, A>;
         /**
          * Wraps a Promise-returning function of any arguments, returning a new function
          * that catches rejections and returns a Task.Result.
          */
-        const throwable: <Args extends readonly unknown[], A, E>(f: (...args: Args) => Promise<A>, onError: (e: unknown) => E) => (...args: Args) => TaskResult<E, A>;
+        const throwable: <Args extends readonly unknown[], A, E>(f: (...args: Args) => Promise<A>, options: {
+            onError: (e: unknown) => E;
+        }) => (...args: Args) => TaskResult<E, A>;
+    }
+    namespace to {
+        /**
+         * Converts a Task.Result to a Task.Maybe, dropping the error value on Err.
+         *
+         * @example
+         * ```ts
+         * const taskResult = Task.Result.ok(42);
+         * const taskMaybe = pipe(taskResult, Task.Result.to.Maybe);
+         * ```
+         */
+        const Maybe: <E, A>(data: TaskResult<E, A>) => TaskMaybe<A>;
     }
     /**
      * Creates a Task.Result from a function that may throw.
@@ -950,11 +1235,13 @@ declare namespace TaskResult {
      * const fetchUser = (id: string): Task.Result<string, User> =>
      *   Task.Result.tryCatch(
      *     (signal) => fetch(`/users/${id}`, { signal }).then(r => r.json()),
-     *     String
+     *     { onError: String }
      *   );
      * ```
      */
-    const tryCatch: <E, A>(f: (signal?: AbortSignal) => Thenable<A>, onError: (e: unknown) => E) => TaskResult<E, A>;
+    const tryCatch: <E, A>(f: (signal?: AbortSignal) => Thenable<A>, options: {
+        onError: (e: unknown) => E;
+    }) => TaskResult<E, A>;
     /**
      * Transforms the success value inside a Task.Result.
      */
@@ -967,7 +1254,7 @@ declare namespace TaskResult {
      * Chains Task.Result computations. If the first succeeds, passes the value to f.
      * If the first fails, propagates the error.
      */
-    const chain: <E, A, B>(f: (a: A) => TaskResult<E, B>) => (data: TaskResult<E, A>) => TaskResult<E, B>;
+    const chain: <E1, E2, A, B>(f: (a: A) => TaskResult<E2, B>) => (data: TaskResult<E1, A>) => TaskResult<E1 | E2, B>;
     /**
      * Extracts the value from a Task.Result by providing handlers for both cases.
      */
@@ -1065,6 +1352,55 @@ declare namespace TaskResult {
      * ```
      */
     const struct: <E, R extends Record<string, any>>(fields: { [K in keyof R]: TaskResult<E, R[K]>; }) => TaskResult<E, R>;
+    /**
+     * Retries a fallible Task.Result according to a RetryPolicy.
+     * If the task succeeds, returns Ok immediately.
+     * If the task fails, retries up to policy.attempts times with delays generated by policy.
+     *
+     * @example
+     * ```ts
+     * const policy = RetryPolicy.exponential({ attempts: 3, initial: Duration.milliseconds(100) });
+     * const retryableFetch = pipe(fetchData, Task.Result.retry(policy));
+     * ```
+     */
+    const retry: (policy: RetryPolicy) => <E, A>(task: TaskResult<E, A>) => TaskResult<E, A>;
+    /**
+     * Creates a memoized version of a Task.Result. The task is executed at most once on first call,
+     * and its resolved Result is cached for all subsequent calls.
+     *
+     * @example
+     * ```ts
+     * const loadConfig = Task.Result.memoize(fetchConfigTask);
+     * ```
+     */
+    const memoize: <E, A>(task: TaskResult<E, A>) => TaskResult<E, A>;
+    /**
+     * Times out a fallible task, resolving to `Err(onTimeout())` if the duration elapses
+     * before the task completes.
+     *
+     * @example
+     * ```ts
+     * const fetchWithTimeout = pipe(
+     *   fetchTask,
+     *   Task.Result.timeout({ duration: Duration.seconds(5), onTimeout: () => "Request timed out" })
+     * );
+     * ```
+     */
+    const timeout: <E2>(options: {
+        duration: Duration;
+        onTimeout: () => E2;
+    }) => <E1, A>(task: TaskResult<E1, A>) => TaskResult<E1 | E2, A>;
+    /**
+     * Runs a list of fallible tasks in parallel and collects all outcomes (`Ok` and `Err`)
+     * without short-circuiting on failure.
+     *
+     * @example
+     * ```ts
+     * const results = await Task.Result.allSettled([task1, task2, task3])();
+     * // [Ok(val1), Err(err2), Ok(val3)]
+     * ```
+     */
+    const allSettled: <E, A>(tasks: ReadonlyArray<TaskResult<E, A>>) => Task<ReadonlyArray<Result<E, A>>>;
 }
 
 /**
@@ -1090,37 +1426,83 @@ declare namespace TaskResult {
  */
 type TaskValidation<E, A> = Task<Validation<E, A>>;
 declare namespace TaskValidation {
-    /**
-     * Wraps a value in a passed Task.Validation.
-     */
+    namespace make {
+        /**
+         * Wraps a value in a passed Task.Validation.
+         *
+         * @example
+         * ```ts
+         * const task = Task.Validation.make.passed(42);
+         * const res = await task(); // Passed(42)
+         * ```
+         */
+        const passed: <E, A>(value: A) => TaskValidation<E, A>;
+        /**
+         * Creates a failed Task.Validation with a single error.
+         *
+         * @example
+         * ```ts
+         * const task = Task.Validation.make.failed("invalid");
+         * const res = await task(); // Failed(["invalid"])
+         * ```
+         */
+        const failed: <E, A>(error: E) => TaskValidation<E, A>;
+        /**
+         * Creates a failed Task.Validation from multiple errors.
+         *
+         * @example
+         * ```ts
+         * const task = Task.Validation.make.failedAll(["err1", "err2"]);
+         * const res = await task(); // Failed(["err1", "err2"])
+         * ```
+         */
+        const failedAll: <E, A>(errors: NonEmptyArr<E>) => TaskValidation<E, A>;
+    }
     const passed: <E, A>(value: A) => TaskValidation<E, A>;
-    /**
-     * Creates a failed Task.Validation with a single error.
-     */
     const failed: <E, A>(error: E) => TaskValidation<E, A>;
-    /**
-     * Creates a failed Task.Validation from multiple errors.
-     */
     const failedAll: <E, A>(errors: NonEmptyArr<E>) => TaskValidation<E, A>;
     namespace from {
         /**
          * Lifts a Validation into a Task.Validation.
+         *
+         * @example
+         * ```ts
+         * Task.Validation.from.Validation(Validation.make.passed(42));
+         * ```
          */
         const Validation: <E, A>(validation: Validation<E, A>) => TaskValidation<E, A>;
         /**
          * Creates a Task.Validation from a nullable value.
          * If the value is null or undefined, returns Failed with the error from onNull.
          * Otherwise, returns Passed.
+         *
+         * @example
+         * ```ts
+         * Task.Validation.from.nullable(() => "missing")(42);   // resolves to Passed(42)
+         * Task.Validation.from.nullable(() => "missing")(null); // resolves to Failed(["missing"])
+         * ```
          */
         const nullable: <E>(onNull: () => E) => <A>(value: A | null | undefined) => TaskValidation<E, A>;
         /**
          * Creates a Task.Validation from a Maybe.
          * Some becomes Passed, None becomes Failed with the error from onNone.
+         *
+         * @example
+         * ```ts
+         * Task.Validation.from.Maybe(() => "empty")(Maybe.make.some(42)); // resolves to Passed(42)
+         * Task.Validation.from.Maybe(() => "empty")(Maybe.make.none());   // resolves to Failed(["empty"])
+         * ```
          */
         const Maybe: <E>(onNone: () => E) => <A>(maybe: Maybe<A>) => TaskValidation<E, A>;
         /**
          * Creates a Task.Validation from a Result.
          * Ok becomes Passed, Err(e) becomes Failed([e]).
+         *
+         * @example
+         * ```ts
+         * Task.Validation.from.Result(Result.make.ok(42));     // resolves to Passed(42)
+         * Task.Validation.from.Result(Result.make.err("bad")); // resolves to Failed(["bad"])
+         * ```
          */
         const Result: <E, A>(result: Result<E, A>) => TaskValidation<E, A>;
     }
@@ -1508,12 +1890,15 @@ declare namespace Task {
      * ```ts
      * pipe(
      *   heavyComputation,
-     *   Task.timeout(Duration.seconds(5), () => "timed out"),
+     *   Task.timeout({ duration: Duration.seconds(5), onTimeout: () => "timed out" }),
      *   Task.Result.chain(processResult)
      * );
      * ```
      */
-    const timeout: <E>(duration: Duration, onTimeout: () => E) => <A>(task: Task<A>) => Task<Result<E, A>>;
+    const timeout: <E>(options: {
+        duration: Duration;
+        onTimeout: () => E;
+    }) => <A>(task: Task<A>) => Task<Result<E, A>>;
     /**
      * Creates a Task paired with an `abort` handle. Calling `abort()` cancels the
      * current in-flight call immediately. Unlike a one-shot abort, calling `task()`
@@ -1574,6 +1959,43 @@ declare namespace Task {
      * ```
      */
     const bind: <K extends string, A, B>(key: K, f: (a: A) => Task<B>) => (data: Task<A>) => Task<A & { [P in K]: B; }>;
+    /**
+     * Creates a memoized version of a Task. The task is executed at most once on first call,
+     * and its resolved value is cached for all subsequent calls.
+     *
+     * @example
+     * ```ts
+     * const loadToken = Task.memoize(loadAuthToken);
+     * const token1 = await loadToken(); // loads token
+     * const token2 = await loadToken(); // returns cached token immediately
+     * ```
+     */
+    const memoize: <A>(task: Task<A>) => Task<A>;
+    /**
+     * Monitors progress of a Task by calling `onProgress(0)` before execution and `onProgress(1)` upon completion.
+     *
+     * @example
+     * ```ts
+     * const taskWithProgress = pipe(
+     *   readTask,
+     *   Task.withProgress((ratio) => console.log(`Progress: ${ratio * 100}%`))
+     * );
+     * ```
+     */
+    const withProgress: <A>(onProgress: (ratio: number) => void) => (task: Task<A>) => Task<A>;
+    type LabeledTask<L extends string, A> = Task<A> & {
+        readonly label: L;
+    };
+    /**
+     * Attaches a read-only `.label` property to a Task, preserving the literal string generic type for IDE tooltips.
+     *
+     * @example
+     * ```ts
+     * const labeledTask = pipe(readTask, Task.withLabel("readUser"));
+     * console.log(labeledTask.label); // "readUser"
+     * ```
+     */
+    const withLabel: <L extends string>(label: L) => <A>(task: Task<A>) => LabeledTask<L, A>;
     type Maybe<A> = TaskMaybe<A>;
     const Maybe: typeof TaskMaybe;
     type Result<E, A> = TaskResult<E, A>;
@@ -1643,13 +2065,45 @@ declare namespace Validation {
     namespace is {
         /**
          * Type guard that checks if a Validation is passed.
+         *
+         * @example
+         * ```ts
+         * const v = Validation.make.passed(42);
+         * if (Validation.is.passed(v)) {
+         *   console.log(v.value); // 42
+         * }
+         * ```
          */
         const passed: <E, A>(data: Validation<E, A>) => data is Passed<A>;
         /**
          * Type guard that checks if a Validation is failed.
+         *
+         * @example
+         * ```ts
+         * const v = Validation.make.failed("invalid");
+         * if (Validation.is.failed(v)) {
+         *   console.log(v.errors); // ["invalid"]
+         * }
+         * ```
          */
         const failed: <E, A>(data: Validation<E, A>) => data is Failed<E>;
     }
+    /**
+     * Creates a Validation from a function that may throw.
+     * Catches any errors and transforms them using the onError function into a Failed validation.
+     *
+     * @example
+     * ```ts
+     * const parseJson = (s: string): Validation<string, unknown> =>
+     *   Validation.tryCatch(
+     *     () => JSON.parse(s),
+     *     { onError: (e) => `Parse error: ${e}` }
+     *   );
+     * ```
+     */
+    const tryCatch: <E, A>(f: () => A, options: {
+        onError: (e: unknown) => E;
+    }) => Validation<E, A>;
     namespace from {
         /**
          * Creates a Validation from a predicate applied to a value.
@@ -1739,12 +2193,24 @@ declare namespace Validation {
      *
      * pipe(
      *   Validation.make.passed(add),
-     *   Validation.ap(Validation.make.failed<string, number>("bad a")),
-     *   Validation.ap(Validation.make.failed<string, number>("bad b"))
+     *   Validation.ap(Validation.make.failed<string>("bad a")),
+     *   Validation.ap(Validation.make.failed<string>("bad b"))
      * ); // Failed(["bad a", "bad b"])
      * ```
      */
     const ap: <E, A>(arg: Validation<E, A>) => <B>(data: Validation<E, (a: A) => B>) => Validation<E, B>;
+    /**
+     * Applies a function wrapped in a Validation to a value wrapped in a Validation,
+     * using a custom error concatenator function when both sides fail.
+     *
+     * @example
+     * ```ts
+     * const concat = (e1: NonEmptyArr<string>, e2: NonEmptyArr<string>): NonEmptyArr<string> =>
+     *   [...e1, ...e2];
+     * pipe(fnVal, Validation.apCustom(concat)(argVal));
+     * ```
+     */
+    const apCustom: <E1, E2, E3>(concat: (e1: NonEmptyArr<E1>, e2: NonEmptyArr<E2>) => NonEmptyArr<E3>) => <A>(arg: Validation<E2, A>) => <B>(data: Validation<E1, (a: A) => B>) => Validation<E3, B>;
     /**
      * Extracts the value from a Validation by providing handlers for both cases.
      *
@@ -1839,15 +2305,19 @@ declare namespace Validation {
     namespace to {
         /**
          * Converts a Validation to a Result.
-         * Passed becomes Ok, Failed becomes Err with the accumulated error list.
+         * Passed becomes Ok.
+         * Direct call converts Failed to Err with accumulated error list `NonEmptyArr<E>`.
+         * Curried call converts Failed to Err with combined error `E2` via `combineErrors`.
          *
          * @example
          * ```ts
          * Validation.to.Result(Validation.make.passed(42));        // Ok(42)
          * Validation.to.Result(Validation.make.failed("oops"));  // Err(["oops"])
+         * pipe(Validation.make.failed("oops"), Validation.to.Result(errors => errors.join(", "))); // Err("oops")
          * ```
          */
-        const Result: <E, A>(data: Validation<E, A>) => Result<NonEmptyArr<E>, A>;
+        function Result<E1, E2, A>(combineErrors: (errors: NonEmptyArr<E1>) => E2): (val: Validation<E1, A>) => Result<E2, A>;
+        function Result<E, A>(data: Validation<E, A>): Result<NonEmptyArr<E>, A>;
         /**
          * Converts a Validation to a Maybe. `Passed` becomes `Some`; `Failed` becomes `None`
          * (errors are discarded).