@nlozgachev/pipelined 0.13.0 → 0.15.0

package/dist/core.d.mts

@@ -1,5 +1,5 @@
-import { O as Option, W as WithValue, a as WithLog, R as Result, b as WithKind, c as WithError, T as Task, d as WithErrors, e as WithFirst, f as WithSecond } from './Task-ChKyH0pF.mjs';
-export { D as Deferred, E as Err, N as None, g as Ok, S as Some } from './Task-ChKyH0pF.mjs';
+import { a as Option, W as WithValue, b as WithLog, R as Result, c as WithKind, d as WithError, T as Task, e as WithErrors, f as WithFirst, g as WithSecond } from './Task-Bd3gXPRQ.mjs';
+export { D as Deferred, E as Err, N as None, O as Ok, S as Some } from './Task-Bd3gXPRQ.mjs';
 import { N as NonEmptyList } from './NonEmptyList-BlGFjor5.mjs';
 
 /** Keys of T for which undefined is assignable (i.e. optional fields). */
@@ -1045,6 +1045,218 @@ declare namespace RemoteData {
     const toResult: <E>(onNotReady: () => E) => <A>(data: RemoteData<E, A>) => Result<E, A>;
 }
 
+/**
+ * A Task that can fail with an error of type E or succeed with a value of type A.
+ * Combines async operations with typed error handling.
+ *
+ * @example
+ * ```ts
+ * const fetchUser = (id: string): TaskResult<Error, User> =>
+ *   TaskResult.tryCatch(
+ *     () => fetch(`/users/${id}`).then(r => r.json()),
+ *     (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 TaskResult.
+     */
+    const ok: <E, A>(value: A) => TaskResult<E, A>;
+    /**
+     * Creates a failed TaskResult with the given error.
+     */
+    const err: <E, A>(error: E) => TaskResult<E, A>;
+    /**
+     * Creates a TaskResult from a function that may throw.
+     * Catches any errors and transforms them using the onError function.
+     *
+     * @example
+     * ```ts
+     * const parseJson = (s: string): TaskResult<string, unknown> =>
+     *   TaskResult.tryCatch(
+     *     async () => JSON.parse(s),
+     *     (e) => `Parse error: ${e}`
+     *   );
+     * ```
+     */
+    const tryCatch: <E, A>(f: () => Promise<A>, onError: (e: unknown) => E) => TaskResult<E, A>;
+    /**
+     * Transforms the success value inside a TaskResult.
+     */
+    const map: <E, A, B>(f: (a: A) => B) => (data: TaskResult<E, A>) => TaskResult<E, B>;
+    /**
+     * Transforms the error value inside a TaskResult.
+     */
+    const mapError: <E, F, A>(f: (e: E) => F) => (data: TaskResult<E, A>) => TaskResult<F, A>;
+    /**
+     * Chains TaskResult 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>;
+    /**
+     * Extracts the value from a TaskResult by providing handlers for both cases.
+     */
+    const fold: <E, A, B>(onErr: (e: E) => B, onOk: (a: A) => B) => (data: TaskResult<E, A>) => Task<B>;
+    /**
+     * Pattern matches on a TaskResult, returning a Task of the result.
+     */
+    const match: <E, A, B>(cases: {
+        err: (e: E) => B;
+        ok: (a: A) => B;
+    }) => (data: TaskResult<E, A>) => Task<B>;
+    /**
+     * Recovers from an error by providing a fallback TaskResult.
+     * The fallback can produce a different success type, widening the result to `TaskResult<E, A | B>`.
+     */
+    const recover: <E, A, B>(fallback: (e: E) => TaskResult<E, B>) => (data: TaskResult<E, A>) => TaskResult<E, A | B>;
+    /**
+     * Returns the success value or a default value if the TaskResult is an error.
+     * The default can be a different type, widening the result to `Task<A | B>`.
+     */
+    const getOrElse: <E, A, B>(defaultValue: () => B) => (data: TaskResult<E, A>) => Task<A | B>;
+    /**
+     * Executes a side effect on the success value without changing the TaskResult.
+     * Useful for logging or debugging.
+     */
+    const tap: <E, A>(f: (a: A) => void) => (data: TaskResult<E, A>) => TaskResult<E, A>;
+    /**
+     * Re-runs a TaskResult on `Err` with configurable attempts, backoff, and retry condition.
+     *
+     * @param options.attempts - Total number of attempts (1 = no retry, 3 = up to 3 tries)
+     * @param options.backoff - Fixed delay in ms, or a function `(attempt) => ms` for computed delay
+     * @param options.when - Only retry when this returns true; defaults to always retry on Err
+     *
+     * @example
+     * ```ts
+     * // Retry up to 3 times with exponential backoff
+     * pipe(
+     *   fetchUser,
+     *   TaskResult.retry({ attempts: 3, backoff: n => n * 1000 })
+     * );
+     *
+     * // Only retry on network errors, not auth errors
+     * pipe(
+     *   fetchUser,
+     *   TaskResult.retry({ attempts: 3, when: e => e instanceof NetworkError })
+     * );
+     * ```
+     */
+    const retry: <E>(options: {
+        attempts: number;
+        backoff?: number | ((attempt: number) => number);
+        when?: (error: E) => boolean;
+    }) => <A>(data: TaskResult<E, A>) => TaskResult<E, A>;
+    /**
+     * Fails a TaskResult with a typed error if it does not resolve within the given time.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   fetchUser,
+     *   TaskResult.timeout(5000, () => new TimeoutError("fetch user timed out"))
+     * );
+     * ```
+     */
+    const timeout: <E>(ms: number, onTimeout: () => E) => <A>(data: TaskResult<E, A>) => TaskResult<E, A>;
+}
+
+/**
+ * A Resource pairs an async acquisition step with a guaranteed cleanup step.
+ *
+ * Use it whenever something must be explicitly closed, released, or torn down
+ * after you are done with it — database connections, file handles, locks,
+ * temporary directories, or any object with a lifecycle.
+ *
+ * The key guarantee: `release` always runs after `Resource.use`, even when
+ * the work function returns an error. If `acquire` itself fails, `release` is
+ * skipped — there is nothing to clean up.
+ *
+ * Build a Resource with `Resource.make` or `Resource.fromTask`, then run it
+ * with `Resource.use`.
+ *
+ * @example
+ * ```ts
+ * const dbResource = Resource.make(
+ *   TaskResult.tryCatch(() => openConnection(config), (e) => new DbError(e)),
+ *   (conn) => Task.from(() => conn.close())
+ * );
+ *
+ * const result = await pipe(
+ *   dbResource,
+ *   Resource.use((conn) => queryUser(conn, userId))
+ * )();
+ * // conn.close() is called whether queryUser succeeds or fails
+ * ```
+ */
+type Resource<E, A> = {
+    readonly acquire: TaskResult<E, A>;
+    readonly release: (a: A) => Task<void>;
+};
+declare namespace Resource {
+    /**
+     * Creates a Resource from an acquire operation that may fail and a release function.
+     *
+     * @example
+     * ```ts
+     * const fileResource = Resource.make(
+     *   TaskResult.tryCatch(() => fs.promises.open("data.csv", "r"), toFileError),
+     *   (handle) => Task.from(() => handle.close())
+     * );
+     * ```
+     */
+    const make: <E, A>(acquire: TaskResult<E, A>, release: (a: A) => Task<void>) => Resource<E, A>;
+    /**
+     * Creates a Resource from an acquire operation that cannot fail.
+     * Use this when opening the resource is guaranteed to succeed, such as
+     * in-memory locks, counters, or timers.
+     *
+     * @example
+     * ```ts
+     * const timerResource = Resource.fromTask<never, Timer>(
+     *   Task.from(() => Promise.resolve(startTimer())),
+     *   (timer) => Task.from(() => Promise.resolve(timer.stop()))
+     * );
+     * ```
+     */
+    const fromTask: <E, A>(acquire: Task<A>, release: (a: A) => Task<void>) => Resource<E, A>;
+    /**
+     * Acquires the resource, runs `f` with it, then releases it.
+     *
+     * Release always runs, even when `f` returns an error.
+     * If acquire fails, `f` and release are both skipped and the error is returned.
+     *
+     * @example
+     * ```ts
+     * const rows = await pipe(
+     *   dbResource,
+     *   Resource.use((conn) => runQuery(conn, "SELECT * FROM users"))
+     * )();
+     * // conn is closed whether the query succeeds or fails
+     * ```
+     */
+    const use: <E, A, B>(f: (a: A) => TaskResult<E, B>) => (resource: Resource<E, A>) => TaskResult<E, B>;
+    /**
+     * Acquires two resources in sequence and presents them as a tuple.
+     * Resources are released in reverse order: the second is released before the first.
+     *
+     * If the second resource fails to acquire, the first is released immediately
+     * before returning the error.
+     *
+     * @example
+     * ```ts
+     * const combined = Resource.combine(dbResource, cacheResource);
+     *
+     * const result = await pipe(
+     *   combined,
+     *   Resource.use(([conn, cache]) => lookupWithFallback(conn, cache, userId))
+     * )();
+     * ```
+     */
+    const combine: <E, A, B>(resourceA: Resource<E, A>, resourceB: Resource<E, B>) => Resource<E, readonly [A, B]>;
+}
+
 /**
  * A synchronous computation that threads a piece of mutable state `S` through
  * a pipeline without exposing mutation at call sites.
@@ -1237,123 +1449,6 @@ declare namespace State {
     const execute: <S>(initialState: S) => <A>(st: State<S, A>) => S;
 }
 
-/**
- * A Task that can fail with an error of type E or succeed with a value of type A.
- * Combines async operations with typed error handling.
- *
- * @example
- * ```ts
- * const fetchUser = (id: string): TaskResult<Error, User> =>
- *   TaskResult.tryCatch(
- *     () => fetch(`/users/${id}`).then(r => r.json()),
- *     (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 TaskResult.
-     */
-    const ok: <E, A>(value: A) => TaskResult<E, A>;
-    /**
-     * Creates a failed TaskResult with the given error.
-     */
-    const err: <E, A>(error: E) => TaskResult<E, A>;
-    /**
-     * Creates a TaskResult from a function that may throw.
-     * Catches any errors and transforms them using the onError function.
-     *
-     * @example
-     * ```ts
-     * const parseJson = (s: string): TaskResult<string, unknown> =>
-     *   TaskResult.tryCatch(
-     *     async () => JSON.parse(s),
-     *     (e) => `Parse error: ${e}`
-     *   );
-     * ```
-     */
-    const tryCatch: <E, A>(f: () => Promise<A>, onError: (e: unknown) => E) => TaskResult<E, A>;
-    /**
-     * Transforms the success value inside a TaskResult.
-     */
-    const map: <E, A, B>(f: (a: A) => B) => (data: TaskResult<E, A>) => TaskResult<E, B>;
-    /**
-     * Transforms the error value inside a TaskResult.
-     */
-    const mapError: <E, F, A>(f: (e: E) => F) => (data: TaskResult<E, A>) => TaskResult<F, A>;
-    /**
-     * Chains TaskResult 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>;
-    /**
-     * Extracts the value from a TaskResult by providing handlers for both cases.
-     */
-    const fold: <E, A, B>(onErr: (e: E) => B, onOk: (a: A) => B) => (data: TaskResult<E, A>) => Task<B>;
-    /**
-     * Pattern matches on a TaskResult, returning a Task of the result.
-     */
-    const match: <E, A, B>(cases: {
-        err: (e: E) => B;
-        ok: (a: A) => B;
-    }) => (data: TaskResult<E, A>) => Task<B>;
-    /**
-     * Recovers from an error by providing a fallback TaskResult.
-     * The fallback can produce a different success type, widening the result to `TaskResult<E, A | B>`.
-     */
-    const recover: <E, A, B>(fallback: (e: E) => TaskResult<E, B>) => (data: TaskResult<E, A>) => TaskResult<E, A | B>;
-    /**
-     * Returns the success value or a default value if the TaskResult is an error.
-     * The default can be a different type, widening the result to `Task<A | B>`.
-     */
-    const getOrElse: <E, A, B>(defaultValue: () => B) => (data: TaskResult<E, A>) => Task<A | B>;
-    /**
-     * Executes a side effect on the success value without changing the TaskResult.
-     * Useful for logging or debugging.
-     */
-    const tap: <E, A>(f: (a: A) => void) => (data: TaskResult<E, A>) => TaskResult<E, A>;
-    /**
-     * Re-runs a TaskResult on `Err` with configurable attempts, backoff, and retry condition.
-     *
-     * @param options.attempts - Total number of attempts (1 = no retry, 3 = up to 3 tries)
-     * @param options.backoff - Fixed delay in ms, or a function `(attempt) => ms` for computed delay
-     * @param options.when - Only retry when this returns true; defaults to always retry on Err
-     *
-     * @example
-     * ```ts
-     * // Retry up to 3 times with exponential backoff
-     * pipe(
-     *   fetchUser,
-     *   TaskResult.retry({ attempts: 3, backoff: n => n * 1000 })
-     * );
-     *
-     * // Only retry on network errors, not auth errors
-     * pipe(
-     *   fetchUser,
-     *   TaskResult.retry({ attempts: 3, when: e => e instanceof NetworkError })
-     * );
-     * ```
-     */
-    const retry: <E>(options: {
-        attempts: number;
-        backoff?: number | ((attempt: number) => number);
-        when?: (error: E) => boolean;
-    }) => <A>(data: TaskResult<E, A>) => TaskResult<E, A>;
-    /**
-     * Fails a TaskResult with a typed error if it does not resolve within the given time.
-     *
-     * @example
-     * ```ts
-     * pipe(
-     *   fetchUser,
-     *   TaskResult.timeout(5000, () => new TimeoutError("fetch user timed out"))
-     * );
-     * ```
-     */
-    const timeout: <E>(ms: number, onTimeout: () => E) => <A>(data: TaskResult<E, A>) => TaskResult<E, A>;
-}
-
 /**
  * A Task that resolves to an optional value.
  * Combines async operations with the Option type for values that may not exist.
@@ -2167,4 +2262,4 @@ declare namespace Tuple {
     const tap: <A, B>(f: (a: A, b: B) => void) => (tuple: Tuple<A, B>) => Tuple<A, B>;
 }
 
-export { type Failure, type Invalid, Lens, type Loading, Logged, type NotAsked, Option, Optional, Predicate, Reader, Refinement, RemoteData, Result, State, type Success, Task, TaskOption, TaskResult, TaskValidation, These, type TheseBoth, type TheseFirst, type TheseSecond, Tuple, type Valid, Validation };
+export { type Failure, type Invalid, Lens, type Loading, Logged, type NotAsked, Option, Optional, Predicate, Reader, Refinement, RemoteData, Resource, Result, State, type Success, Task, TaskOption, TaskResult, TaskValidation, These, type TheseBoth, type TheseFirst, type TheseSecond, Tuple, type Valid, Validation };