tryharder 0.1.2 → 0.2.1

package/README.md

@@ -38,7 +38,7 @@ const result = await try$
     catch: () => new RequestFailedError("request failed"),
   })
 
-// result is OrderStatus | RequestFailedError | RetryExhaustedError | TimeoutError
+// result is OrderStatus | RequestFailedError | TimeoutError
 ```
 
 <details>
@@ -47,7 +47,6 @@ const result = await try$
 - [Why not plain try/catch?](#why-not-plain-trycatch)
 - [Features](#features)
 - [Installation](#installation)
-- [Migration from hardtry](#migration-from-hardtry)
 - [Execution Model](#execution-model)
 - [Type Semantics](#type-semantics)
 - [Quick Start](#quick-start)
@@ -59,7 +58,7 @@ const result = await try$
   - [all and allSettled](#all-and-allsettled)
   - [flow and $exit](#flow-and-exit)
   - [gen](#gen)
-- [dispose](#dispose)
+  - [disposer](#disposer)
 - [API Reference](#api-reference)
 - [Common Recipes](#common-recipes)
 - [When not to use tryharder](#when-not-to-use-tryharder)
@@ -133,7 +132,7 @@ const result = await try$
   })
 
 // result is
-// User | UserUnavailableError | RetryExhaustedError | TimeoutError | CancellationError
+// User | UserUnavailableError | TimeoutError | CancellationError
 ```
 
 That is the core shift:
@@ -142,7 +141,8 @@ That is the core shift:
 - `tryharder` exposes execution policy in the builder chain and failure shape in the return type.
 - `run(fn)` returns `T | UnhandledException`.
 - `run({ try, catch })` returns `T | C`.
-- Adding `retry(...)`, `timeout(...)`, and `signal(...)` widens the union with `RetryExhaustedError`, `TimeoutError`, and `CancellationError`.
+- Adding `timeout(...)` and `signal(...)` widens the union with `TimeoutError` and `CancellationError`.
+- Adding `retry(...)` changes how persistent failure is reported: with `catch`, the last attempt's error is mapped by `catch`; without `catch`, it surfaces as `RetryExhaustedError` (last error as `cause`) instead of `UnhandledException`.
 
 ## Features
 
@@ -151,7 +151,7 @@ That is the core shift:
 - **Sync and async parity** - Use the same mental model for `runSync(...)` and `run(...)`.
 - **Named task orchestration** - Express concurrent and ordered workflows with object-shaped task graphs instead of positional arrays.
 - **Observable execution hooks** - Add top-level instrumentation with `wrap(...)` without changing task behavior.
-- **Resource cleanup** - Register teardown that survives async boundaries with `dispose()` and task disposers.
+- **Resource cleanup** - Register teardown that survives async boundaries with `disposer()` and task disposers.
 - **No runtime dependencies** - The published package ships without runtime dependencies.
 
 ## Installation
@@ -170,39 +170,23 @@ yarn add tryharder
 pnpm add tryharder
 ```
 
-## Migration from hardtry
-
-Replace import specifiers only:
-
-- `hardtry` -> `tryharder`
-- `hardtry/errors` -> `tryharder/errors`
-- `hardtry/types` -> `tryharder/types`
-
-You can keep the same namespace alias in your code:
-
-```ts
-import * as try$ from "tryharder"
-```
-
-No runtime API names changed.
-
 ## Execution Model
 
 `tryharder` has three layers: terminal execution APIs, policy builders, and orchestration APIs.
 
-Terminal execution APIs are `run(...)` and `runSync(...)`. They are the points where work is actually executed and a result union is produced. Function form is the minimal shape and returns `T | UnhandledException`. Object form adds a `catch` mapper and returns `T | C`.
+Terminal execution APIs are `run(...)` and `runSync(...)`. They are the points where work is actually executed and a result union is produced. Function form is the minimal shape and returns `T | UnhandledException` by default, or `T | RetryExhaustedError` when retry is configured. Object form adds a `catch` mapper and returns `T | C`.
 
 Policy builders decorate terminal execution. `retry(...)`, `timeout(...)`, and `signal(...)` do not run work by themselves; they configure the next terminal call and widen the resulting union with the policy-level failures they can introduce. `retry(limit)` counts the first attempt. `timeout(ms)` applies one total deadline across attempts, delays, and catch handling. `signal(abortSignal)` forwards external cancellation into execution.
 
 Orchestration APIs scale the same model from one operation to a task graph. `all(...)` runs a fail-fast named task map. `allSettled(...)` preserves every settled task outcome. `flow(...)` runs an ordered workflow that must explicitly terminate through `this.$exit(...)`.
 
-`wrap(...)` sits above those execution APIs as observational middleware. It can inspect readonly execution context and surround terminal calls, but it is not available after `retry(...)`, `timeout(...)`, or execution-scoped `signal(...)` chains. `gen(...)` offers a more linear way to compose returned unions. `dispose()` provides cleanup registration for work that spans async boundaries.
+`wrap(...)` sits above those execution APIs as observational middleware. It can inspect readonly execution context and surround terminal calls, but it is not available after `retry(...)`, `timeout(...)`, or execution-scoped `signal(...)` chains. `gen(...)` offers a more linear way to compose returned unions. `disposer()` provides cleanup registration for work that spans async boundaries.
 
 | Term                  | Meaning                                                                        |
 | --------------------- | ------------------------------------------------------------------------------ |
 | `run`                 | Async terminal execution that returns a value, mapped failure, or policy error |
 | `runSync`             | Sync terminal execution for synchronous work only                              |
-| `retry(limit)`        | Retry policy where `limit` includes the first attempt                          |
+| `retry(limit)`        | Retry policy; `limit` is a positive integer counting the first attempt         |
 | `timeout(ms)`         | Total execution timeout across attempts, delays, and catch handling            |
 | `signal(abortSignal)` | External cancellation for `run(...)` and root-level orchestration              |
 | `wrap(fn)`            | Top-level observational middleware around terminal APIs                        |
@@ -237,10 +221,20 @@ const result = await try$
   })
 
 // result is
-// ValidationError | RetryExhaustedError | TimeoutError
+// ValidationError | TimeoutError
 ```
 
-That inferred union is the contract. A caller can see whether a function returns a domain error, whether retries may exhaust, and whether a deadline may fire, without reading the implementation body.
+That inferred union is the contract. A caller can see whether a function returns a domain error and whether a deadline may fire, without reading the implementation body.
+
+The `catch` contract is strict: `catch` maps errors that originated inside `try` — thrown directly, or carried out of the retry loop as the last attempt's error once the retry policy gives up. Policy outcomes (`TimeoutError`, `CancellationError`) never pass through `catch`; they surface typed in the union so you can handle them at the call site:
+
+```ts
+if (result instanceof TimeoutError) {
+  // deadline expired; map or handle it here
+}
+```
+
+Without `catch`, unmapped failures are wrapped: `RetryExhaustedError` when a retry policy gave up (for any reason — limit exhausted or `shouldRetry` declining), `UnhandledException` otherwise. The original error is always available as `cause`.
 
 `Panic` is intentionally separate from that model. It signals programmer errors such as invalid builder usage or invalid task graphs, not expected business-domain failures.
 
@@ -407,6 +401,8 @@ const result = await try$
 
 `timeout(ms)` measures total execution time, not just a single attempt.
 
+`runSync(...)` stays available after the numeric retry shorthand (`retry(3)`), but not after the object form (`retry({ ... })`) or `timeout(...)` — those policies may need to wait or interrupt, which synchronous execution cannot do. This restriction is intentionally conservative: it is enforced at the type level even for object policies that would be sync-safe at runtime (constant backoff, no delay, no jitter). If you need retries with `runSync(...)`, use the numeric shorthand.
+
 Apply `signal(...)` on the root builder when you want cancellation to cover `all(...)`, `allSettled(...)`, or `flow(...)`.
 
 ### wrap
@@ -495,21 +491,21 @@ const value = await try$.gen(function* (use) {
 })
 ```
 
-### dispose
+### disposer
 
-Use `dispose()` when cleanup should stay colocated with the workflow that allocates the resource, even across async boundaries. The returned `AsyncDisposer` gives you three core operations:
+Use `disposer()` when cleanup should stay colocated with the workflow that allocates the resource, even across async boundaries. The returned `AsyncDisposer` gives you three operations:
 
-- `add(fn)` registers a cleanup callback.
+- `defer(fn)` registers a cleanup callback.
 - `use(resource)` tracks a disposable resource.
-- `cleanup()` runs the registered teardown in reverse order.
+- `dispose()` runs the registered teardown in reverse order (also triggered by leaving an `await using` scope).
 
 ```ts
-await using disposer = try$.dispose()
+await using disposer = try$.disposer()
 
 {
   const connection = await db.connect()
 
-  disposer.add(async () => {
+  disposer.defer(async () => {
     await connection.close()
   })
 
@@ -523,32 +519,44 @@ await using disposer = try$.dispose()
 
 ### Runtime
 
-| Export         | Description                                                             |
-| -------------- | ----------------------------------------------------------------------- |
-| `run`          | Async terminal execution API                                            |
-| `runSync`      | Sync terminal execution API                                             |
-| `retry`        | Create an execution-scoped retry builder                                |
-| `retryOptions` | Normalize retry policy input                                            |
-| `timeout`      | Add a total execution timeout                                           |
-| `signal`       | Add external cancellation to execution or root-level orchestration      |
-| `wrap`         | Add top-level observational middleware                                  |
-| `all`          | Run a fail-fast parallel named task graph                               |
-| `allSettled`   | Run a settled parallel named task graph                                 |
-| `flow`         | Run an ordered workflow with explicit early exit                        |
-| `gen`          | Compose `run(...)` results through generators                           |
-| `dispose`      | Create an `AsyncDisposer` helper with `add()`, `use()`, and `cleanup()` |
+| Export         | Description                                                               |
+| -------------- | ------------------------------------------------------------------------- |
+| `run`          | Async terminal execution API                                              |
+| `runSync`      | Sync terminal execution API                                               |
+| `retry`        | Create an execution-scoped retry builder                                  |
+| `retryOptions` | Normalize retry policy input                                              |
+| `timeout`      | Add a total execution timeout                                             |
+| `signal`       | Add external cancellation to execution or root-level orchestration        |
+| `wrap`         | Add top-level observational middleware                                    |
+| `all`          | Run a fail-fast parallel named task graph                                 |
+| `allSettled`   | Run a settled parallel named task graph                                   |
+| `flow`         | Run an ordered workflow with explicit early exit                          |
+| `gen`          | Compose `run(...)` results through generators                             |
+| `disposer`     | Create an `AsyncDisposer` helper with `defer()`, `use()`, and `dispose()` |
 
 ### Errors
 
 Exports from `tryharder/errors`:
 
-| Export                | Description                                               |
-| --------------------- | --------------------------------------------------------- |
-| `CancellationError`   | Returned or thrown when execution is externally cancelled |
-| `TimeoutError`        | Returned when timed execution expires                     |
-| `RetryExhaustedError` | Returned when retry attempts are exhausted                |
-| `UnhandledException`  | Returned when function-form execution throws              |
-| `Panic`               | Thrown for programmer errors and invalid API usage        |
+| Export                | Description                                                                                               |
+| --------------------- | --------------------------------------------------------------------------------------------------------- |
+| `CancellationError`   | Returned or thrown when execution is externally cancelled                                                 |
+| `TimeoutError`        | Returned when timed execution expires                                                                     |
+| `RetryExhaustedError` | Returned when a retry policy gives up and no `catch` is provided; the last attempt's error is the `cause` |
+| `UnhandledException`  | Returned when function-form execution throws                                                              |
+| `Panic`               | Thrown for programmer errors and invalid API usage                                                        |
+
+Each error class has a matching type guard: `isCancellationError`, `isTimeoutError`, `isRetryExhaustedError`, `isUnhandledException`, and `isPanic`. Prefer the guards over `instanceof` — they also match by `error.name`, so they keep working when two copies of `tryharder` end up in one dependency graph or when errors cross realm boundaries, where `instanceof` silently fails.
+
+```ts
+import { isTimeoutError } from "tryharder/errors"
+
+const result = await try$.timeout(1_000).run(fetchUser)
+
+if (isTimeoutError(result)) {
+  // handle the deadline here
+}
+```
 
 ### Types
 
@@ -557,7 +565,7 @@ Exports from `tryharder/types`:
 | Export             | Description                                          |
 | ------------------ | ---------------------------------------------------- |
 | `AllSettledResult` | Settled result map returned by `allSettled(...)`     |
-| `AsyncDisposer`    | Async cleanup helper returned by `dispose()`         |
+| `AsyncDisposer`    | Async cleanup helper returned by `disposer()`        |
 | `SettledFulfilled` | Fulfilled branch of a settled task result            |
 | `SettledRejected`  | Rejected branch of a settled task result             |
 | `SettledResult`    | Union of fulfilled and rejected settled task results |

package/dist/errors.d.ts

@@ -23,4 +23,9 @@ declare class Panic extends Error {
 		message?: string;
 	});
 }
-export { UnhandledException, TimeoutError, RetryExhaustedError, PanicCode, Panic, CancellationError };
+declare function isCancellationError(error: unknown): error is CancellationError;
+declare function isTimeoutError(error: unknown): error is TimeoutError;
+declare function isRetryExhaustedError(error: unknown): error is RetryExhaustedError;
+declare function isUnhandledException(error: unknown): error is UnhandledException;
+declare function isPanic(error: unknown): error is Panic;
+export { isUnhandledException, isTimeoutError, isRetryExhaustedError, isPanic, isCancellationError, UnhandledException, TimeoutError, RetryExhaustedError, PanicCode, Panic, CancellationError };

package/dist/errors.js

@@ -3,9 +3,19 @@ import {
   Panic,
   RetryExhaustedError,
   TimeoutError,
-  UnhandledException
-} from "./shared/chunk-f024nrjy.js";
+  UnhandledException,
+  isCancellationError,
+  isPanic,
+  isRetryExhaustedError,
+  isTimeoutError,
+  isUnhandledException
+} from "./shared/chunk-nw88v1ee.js";
 export {
+  isUnhandledException,
+  isTimeoutError,
+  isRetryExhaustedError,
+  isPanic,
+  isCancellationError,
   UnhandledException,
   TimeoutError,
   RetryExhaustedError,
@@ -13,5 +23,5 @@ export {
   CancellationError
 };
 
-//# debugId=7909B944ED0605C464756E2164756E21
-//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFtdLAogICJzb3VyY2VzQ29udGVudCI6IFsKICBdLAogICJtYXBwaW5ncyI6ICIiLAogICJkZWJ1Z0lkIjogIjc5MDlCOTQ0RUQwNjA1QzQ2NDc1NkUyMTY0NzU2RTIxIiwKICAibmFtZXMiOiBbXQp9
+//# debugId=796F554FE5FDACF264756E2164756E21
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFtdLAogICJzb3VyY2VzQ29udGVudCI6IFsKICBdLAogICJtYXBwaW5ncyI6ICIiLAogICJkZWJ1Z0lkIjogIjc5NkY1NTRGRTVGREFDRjI2NDc1NkUyMTY0NzU2RTIxIiwKICAibmFtZXMiOiBbXQp9

package/dist/index.d.ts

@@ -17,11 +17,20 @@ declare class UnhandledException extends Error {
 	constructor(message?: string, options?: ErrorOptions);
 }
 interface AsyncDisposer extends AsyncDisposable {
-	add(fn: () => void | PromiseLike<void>): void;
-	cleanup(): Promise<void>;
+	/**
+	* Registers a cleanup callback. Callbacks run in reverse registration order (LIFO) when the
+	* disposer is disposed.
+	*/
 	defer(fn: () => void | PromiseLike<void>): void;
+	/**
+	* Tracks a disposable resource and returns it.
+	*/
 	use<T extends AsyncDisposable | Disposable | null | undefined>(value: T): T;
-	disposeAsync(): Promise<void>;
+	/**
+	* Runs all registered teardown in reverse registration order. Equivalent to leaving an `await
+	* using` scope.
+	*/
+	dispose(): Promise<void>;
 }
 type TaskRecord = Record<string, any>;
 type TaskValidation<T extends TaskRecord> = { [K in keyof T] : T[K] extends (...args: any[]) => any ? T[K] : never };
@@ -131,6 +140,27 @@ type RetryPolicy = LinearBackoffRetryPolicy | ExponentialBackoffRetryPolicy | Co
 * - `RetryPolicy`: detailed retry settings
 */
 type RetryOptions = number | RetryPolicy;
+declare const INVALID_RETRY_LIMIT: unique symbol;
+type InvalidRetryLimit = {
+	readonly [INVALID_RETRY_LIMIT]: "retry() requires a positive integer limit";
+};
+/**
+* Compile-time validation for literal retry limits. Rejects `0`, negative, and fractional literals;
+* non-literal `number` values pass and are validated at runtime by {@link retryOptions} instead.
+* (`Infinity`/`NaN` have no literal types, so they are runtime-only.)
+*/
+type ValidateRetryLimit<N extends number> = number extends N ? number : `${N}` extends `-${string}` | `${string}.${string}` ? InvalidRetryLimit : N extends 0 ? InvalidRetryLimit : number;
+/**
+* Compile-time validation for full {@link RetryOptions} values, including unions of number and
+* policy forms. Distributes over union members so that mixed inputs like `flag ? 3 : { backoff:
+* "constant", limit: 5 }` are accepted while any member carrying an invalid literal limit still
+* fails to compile.
+*/
+type ValidateRetryOptions<P extends RetryOptions> = P extends number ? ValidateRetryLimit<P> : P extends {
+	limit: infer N extends number;
+} ? {
+	limit: ValidateRetryLimit<N>;
+} : never;
 declare function retryOptions(policy: RetryOptions): RetryPolicy;
 declare const FLOW_EXIT_BRAND: unique symbol;
 type FlowExit<T> = {
@@ -153,6 +183,12 @@ interface RunAsyncOptions<
 	Ctx extends BaseTryCtx = BaseTryCtx
 > {
 	try: RunTryFn<T, Ctx>;
+	/**
+	* Maps errors that originated inside `try` — thrown directly, or carried out of the retry loop as
+	* the last attempt's error once the retry policy gives up. Policy outcomes (timeout,
+	* cancellation) and defects (`Panic`) never pass through `catch`: they are reported directly,
+	* even when they fire while the handler is running.
+	*/
 	catch: RunCatchFn<E>;
 }
 type AsyncRunInput<
@@ -171,6 +207,12 @@ interface SyncRunOptions<
 	Ctx extends BaseTryCtx = BaseTryCtx
 > {
 	try: SyncRunTryFn<T, Ctx>;
+	/**
+	* Maps errors that originated inside `try` — thrown directly, or carried out of the retry loop as
+	* the last attempt's error once the retry policy gives up. Policy outcomes (timeout,
+	* cancellation) and defects (`Panic`) never pass through `catch`: they are reported directly,
+	* even when they fire while the handler is running.
+	*/
 	catch: SyncRunCatchFn<E>;
 }
 type SyncRunInput<
@@ -204,7 +246,13 @@ interface BuilderConfig {
 	*/
 	wraps?: WrapFn[];
 }
-type ConfigRunErrors = RetryExhaustedError | TimeoutError | CancellationError;
+type ConfigRunErrors = TimeoutError | CancellationError;
+/**
+* The failure type for try functions without a catch handler. With retry configured, any give-up
+* (limit exhausted or `shouldRetry` declining) is reported as {@link RetryExhaustedError} carrying
+* the last attempt's error as `cause`; otherwise failures are wrapped in {@link UnhandledException}.
+*/
+type UnmappedError<HasRetry extends boolean> = HasRetry extends true ? RetryExhaustedError : UnhandledException;
 type OrchestrationMethods = "all" | "allSettled" | "flow";
 type SignalBuilderHiddenMethods<SupportsOrchestration extends boolean> = "runSync" | "wrap" | (SupportsOrchestration extends true ? never : OrchestrationMethods);
 type ExecutionBuilderSurface<
@@ -229,17 +277,37 @@ declare class RunBuilder<
 	constructor(config?: BuilderConfig);
 	protected buildTimeoutConfig(ms: number): BuilderConfig;
 	protected buildSignalConfig(signal: AbortSignal): BuilderConfig;
-	retry(policy: number): ExecutionBuilderSurface<E | RetryExhaustedError, true>;
-	retry(policy: RetryOptions): AsyncExecutionBuilderSurface<E | RetryExhaustedError, true>;
+	retry<N extends number>(policy: N & ValidateRetryLimit<N>): ExecutionBuilderSurface<E, true>;
+	retry<N extends number>(policy: RetryPolicy & {
+		limit: N & ValidateRetryLimit<N>;
+	}): AsyncExecutionBuilderSurface<E, true>;
+	retry<const P extends RetryOptions>(policy: P & ValidateRetryOptions<P>): AsyncExecutionBuilderSurface<E, true>;
 	timeout(ms: number): AsyncExecutionBuilderSurface<E | TimeoutError, HasRetry>;
 	signal(signal: AbortSignal): SignalBuilderSurface<E | CancellationError, HasRetry, SupportsOrchestration>;
 	wrap(fn: WrapFn): RunBuilder<E, HasRetry, SupportsOrchestration>;
-	run<T>(tryFn: RunTryFn<T, TryCtxFor<HasRetry>>): Promise<T | UnhandledException | E>;
+	/**
+	* Executes an async unit of work.
+	*
+	* `catch` maps errors that originated inside `try` — thrown directly, or carried out of the retry
+	* loop as the last attempt's error once the retry policy gives up. Policy outcomes ({@link
+	* TimeoutError}, {@link CancellationError}) and defects (`Panic`) never pass through `catch`; they
+	* surface typed in the return union (or are thrown, for `Panic`).
+	*
+	* Without `catch`, unmapped failures are wrapped: {@link RetryExhaustedError} when a retry policy
+	* gave up, {@link UnhandledException} otherwise. The original error is available as `cause`.
+	*/
+	run<T>(tryFn: RunTryFn<T, TryCtxFor<HasRetry>>): Promise<T | UnmappedError<HasRetry> | E>;
 	run<
 		T,
 		C
 	>(options: AsyncRunInput<T, C, TryCtxFor<HasRetry>>): Promise<T | C | E>;
-	runSync<T>(tryFn: SyncRunTryFn<T, TryCtxFor<HasRetry>>): T | UnhandledException | E;
+	/**
+	* Executes a sync unit of work.
+	*
+	* Follows the same `catch` contract as {@link RunBuilder.run}: `catch` maps try-originated errors
+	* (including retry give-up); policy outcomes and defects never pass through it.
+	*/
+	runSync<T>(tryFn: SyncRunTryFn<T, TryCtxFor<HasRetry>>): T | UnmappedError<HasRetry> | E;
 	runSync<
 		T,
 		C
@@ -251,7 +319,11 @@ declare class RunBuilder<
 	allSettled<T extends TaskRecord>(tasks: T & TaskValidation<NoInfer<T>> & ThisType<InferredTaskContext<T>>): Promise<AllSettledResult<T>>;
 	flow<T extends TaskRecord>(tasks: T & ThisType<InferredFlowTaskContext<T>>): Promise<FlowResult<T>>;
 }
-declare function dispose(): AsyncDisposer;
+/**
+* Creates an {@link AsyncDisposer}: register cleanup with `defer(fn)` or `use(resource)`, then run
+* teardown with `await d.dispose()` or by declaring the disposer with `await using`.
+*/
+declare function disposer(): AsyncDisposer;
 type GenUnwrap<T> = Exclude<Awaited<T>, Error>;
 type GenUse = <T>(value: T) => Generator<T, GenUnwrap<T>, GenUnwrap<T>>;
 type GenErrors<TYield> = Extract<Awaited<TYield>, Error>;
@@ -276,4 +348,4 @@ declare const runSync2: RunBuilder["runSync"];
 declare const signal: RunBuilder["signal"];
 declare const timeout: RunBuilder["timeout"];
 declare const wrap: RunBuilder["wrap"];
-export { wrap, timeout, signal, runSync2 as runSync, run, retryOptions, retry, driveGen as gen, flow, dispose, allSettled2 as allSettled, all };
+export { wrap, timeout, signal, runSync2 as runSync, run, retryOptions, retry, driveGen as gen, flow, disposer, allSettled2 as allSettled, all };