awaitly 2.0.0 → 3.0.0

package/dist/run.d.cts

@@ -0,0 +1,90 @@
+import { v as DepValueOfReturn } from './index-ICmfQi08.cjs';
+export { B as BackoffStrategy, b as BoundSteps, E as EARLY_EXIT_SYMBOL, c as EarlyExit, w as ErrorsOf, d as RetryOptions, e as RunOptions, f as RunOptionsWithCatch, g as RunOptionsWithoutCatch, a as RunStep, S as STEP_TIMEOUT_MARKER, h as ScopeType, i as StepFailureMeta, j as StepOptions, k as StepTimeoutError, l as StepTimeoutMarkerMeta, T as TimeoutOptions, W as WorkflowEvent, m as createEarlyExit, n as getStepTimeoutMeta, o as isEarlyExit, p as isStepTimeoutError, r as run } from './index-ICmfQi08.cjs';
+import { AsyncResult, ErrorOf } from './result.cjs';
+import { U as UnexpectedError, o as TimeoutError } from './errors-sDSeaZBO.cjs';
+import { D as Duration } from './duration-BjVn3QpB.cjs';
+
+/**
+ * Per-dependency policies: retry, timeout, fallback.
+ *
+ * Policies are value-level function wrappers declared where dependencies
+ * are declared — in the deps object — so call sites stay pristine and the
+ * policy is statically visible in the deps literal (the analyzer reads it
+ * as fact, not inference):
+ *
+ * ```typescript
+ * const result = await run(
+ *   {
+ *     getUser,
+ *     charge: retry(timeout(charge, 5000), { attempts: 3 }),
+ *     sendEmail: fallback(sendEmail, () => ({ queued: true })),
+ *   },
+ *   async (s) => {
+ *     const user = await s.getUser(userId);   // call sites unchanged
+ *     const payment = await s.charge(user.id);
+ *     return s.sendEmail(user.id);
+ *   }
+ * );
+ * ```
+ *
+ * Every policy returns a Result-returning function with exact error-union
+ * math:
+ * - `retry(fn, opts)` — same errors as `fn` (the last failure propagates)
+ * - `timeout(fn, ms)` — errors of `fn` plus `TimeoutError`
+ * - `fallback(fn, fb)` — errors of `fn` are consumed; only `fb`'s errors remain
+ *
+ * Plain (non-Result) functions are valid inputs: their values are
+ * normalized to `ok()`, and their throws keep throwing (so they surface as
+ * `UnexpectedError` at the run/workflow layer, same as unwrapped deps).
+ */
+
+type AnyFunction = (...args: never[]) => unknown;
+/** Milliseconds or a Duration value. */
+type PolicyDelay = number | Duration;
+/** The unwrapped success value a policy resolves to for a given function. */
+type PolicyValue<F extends AnyFunction> = DepValueOfReturn<ReturnType<F>>;
+/** A function wrapped by a policy: same arguments, Result-returning. */
+type PolicyFn<F extends AnyFunction, E> = (...args: Parameters<F>) => AsyncResult<PolicyValue<F>, E>;
+interface RetryPolicyOptions {
+    /** Total attempts including the first call (minimum 1). */
+    attempts: number;
+    /** Base delay between attempts. Default: no delay. */
+    delay?: PolicyDelay;
+    /** How the delay grows per attempt. Default: "fixed". */
+    backoff?: "fixed" | "linear" | "exponential";
+    /** Upper bound for the computed delay. */
+    maxDelay?: PolicyDelay;
+    /**
+     * Decide whether a failure is retryable. Receives the Result error, or
+     * the thrown value for plain functions. Default: retry everything.
+     */
+    retryIf?: (failure: unknown) => boolean;
+    /** Observer invoked before each re-attempt. */
+    onRetry?: (info: {
+        attempt: number;
+        failure: unknown;
+    }) => void;
+}
+/**
+ * Retry a dependency. The error union is unchanged: if all attempts fail,
+ * the last failure propagates exactly as it would have without the policy
+ * (typed err for Result functions, throw for plain functions).
+ */
+declare function retry<F extends AnyFunction>(fn: F, options: RetryPolicyOptions): PolicyFn<F, ErrorOf<F>>;
+/**
+ * Bound a dependency's execution time. On timeout, resolves to
+ * `err(TimeoutError)` — adding `TimeoutError` to the error union. The
+ * underlying operation is not cancelled (no AbortSignal is threaded);
+ * its eventual result is discarded.
+ */
+declare function timeout<F extends AnyFunction>(fn: F, after: PolicyDelay): PolicyFn<F, ErrorOf<F> | TimeoutError>;
+/**
+ * Recover from a dependency's failure. The handler receives the failure
+ * (the typed Result error, or `UnexpectedError` wrapping a throw) plus the
+ * original arguments, and its result becomes the outcome. The base
+ * function's errors are consumed; only the handler's errors remain in the
+ * union — `fallback(fn, () => defaultValue)` has no typed errors at all.
+ */
+declare function fallback<F extends AnyFunction, FB extends (failure: ErrorOf<F> | UnexpectedError, ...args: Parameters<F>) => unknown>(fn: F, onFailure: FB): (...args: Parameters<F>) => AsyncResult<PolicyValue<F> | DepValueOfReturn<ReturnType<FB>>, ErrorOf<FB>>;
+
+export { type PolicyDelay, type PolicyFn, type RetryPolicyOptions, fallback, retry, timeout };

package/dist/run.d.ts

@@ -0,0 +1,90 @@
+import { v as DepValueOfReturn } from './index-Cv4K_3sZ.js';
+export { B as BackoffStrategy, b as BoundSteps, E as EARLY_EXIT_SYMBOL, c as EarlyExit, w as ErrorsOf, d as RetryOptions, e as RunOptions, f as RunOptionsWithCatch, g as RunOptionsWithoutCatch, a as RunStep, S as STEP_TIMEOUT_MARKER, h as ScopeType, i as StepFailureMeta, j as StepOptions, k as StepTimeoutError, l as StepTimeoutMarkerMeta, T as TimeoutOptions, W as WorkflowEvent, m as createEarlyExit, n as getStepTimeoutMeta, o as isEarlyExit, p as isStepTimeoutError, r as run } from './index-Cv4K_3sZ.js';
+import { AsyncResult, ErrorOf } from './result.js';
+import { U as UnexpectedError, o as TimeoutError } from './errors-sDSeaZBO.js';
+import { D as Duration } from './duration-BjVn3QpB.js';
+
+/**
+ * Per-dependency policies: retry, timeout, fallback.
+ *
+ * Policies are value-level function wrappers declared where dependencies
+ * are declared — in the deps object — so call sites stay pristine and the
+ * policy is statically visible in the deps literal (the analyzer reads it
+ * as fact, not inference):
+ *
+ * ```typescript
+ * const result = await run(
+ *   {
+ *     getUser,
+ *     charge: retry(timeout(charge, 5000), { attempts: 3 }),
+ *     sendEmail: fallback(sendEmail, () => ({ queued: true })),
+ *   },
+ *   async (s) => {
+ *     const user = await s.getUser(userId);   // call sites unchanged
+ *     const payment = await s.charge(user.id);
+ *     return s.sendEmail(user.id);
+ *   }
+ * );
+ * ```
+ *
+ * Every policy returns a Result-returning function with exact error-union
+ * math:
+ * - `retry(fn, opts)` — same errors as `fn` (the last failure propagates)
+ * - `timeout(fn, ms)` — errors of `fn` plus `TimeoutError`
+ * - `fallback(fn, fb)` — errors of `fn` are consumed; only `fb`'s errors remain
+ *
+ * Plain (non-Result) functions are valid inputs: their values are
+ * normalized to `ok()`, and their throws keep throwing (so they surface as
+ * `UnexpectedError` at the run/workflow layer, same as unwrapped deps).
+ */
+
+type AnyFunction = (...args: never[]) => unknown;
+/** Milliseconds or a Duration value. */
+type PolicyDelay = number | Duration;
+/** The unwrapped success value a policy resolves to for a given function. */
+type PolicyValue<F extends AnyFunction> = DepValueOfReturn<ReturnType<F>>;
+/** A function wrapped by a policy: same arguments, Result-returning. */
+type PolicyFn<F extends AnyFunction, E> = (...args: Parameters<F>) => AsyncResult<PolicyValue<F>, E>;
+interface RetryPolicyOptions {
+    /** Total attempts including the first call (minimum 1). */
+    attempts: number;
+    /** Base delay between attempts. Default: no delay. */
+    delay?: PolicyDelay;
+    /** How the delay grows per attempt. Default: "fixed". */
+    backoff?: "fixed" | "linear" | "exponential";
+    /** Upper bound for the computed delay. */
+    maxDelay?: PolicyDelay;
+    /**
+     * Decide whether a failure is retryable. Receives the Result error, or
+     * the thrown value for plain functions. Default: retry everything.
+     */
+    retryIf?: (failure: unknown) => boolean;
+    /** Observer invoked before each re-attempt. */
+    onRetry?: (info: {
+        attempt: number;
+        failure: unknown;
+    }) => void;
+}
+/**
+ * Retry a dependency. The error union is unchanged: if all attempts fail,
+ * the last failure propagates exactly as it would have without the policy
+ * (typed err for Result functions, throw for plain functions).
+ */
+declare function retry<F extends AnyFunction>(fn: F, options: RetryPolicyOptions): PolicyFn<F, ErrorOf<F>>;
+/**
+ * Bound a dependency's execution time. On timeout, resolves to
+ * `err(TimeoutError)` — adding `TimeoutError` to the error union. The
+ * underlying operation is not cancelled (no AbortSignal is threaded);
+ * its eventual result is discarded.
+ */
+declare function timeout<F extends AnyFunction>(fn: F, after: PolicyDelay): PolicyFn<F, ErrorOf<F> | TimeoutError>;
+/**
+ * Recover from a dependency's failure. The handler receives the failure
+ * (the typed Result error, or `UnexpectedError` wrapping a throw) plus the
+ * original arguments, and its result becomes the outcome. The base
+ * function's errors are consumed; only the handler's errors remain in the
+ * union — `fallback(fn, () => defaultValue)` has no typed errors at all.
+ */
+declare function fallback<F extends AnyFunction, FB extends (failure: ErrorOf<F> | UnexpectedError, ...args: Parameters<F>) => unknown>(fn: F, onFailure: FB): (...args: Parameters<F>) => AsyncResult<PolicyValue<F> | DepValueOfReturn<ReturnType<FB>>, ErrorOf<FB>>;
+
+export { type PolicyDelay, type PolicyFn, type RetryPolicyOptions, fallback, retry, timeout };