tryharder 0.1.0 → 0.1.2

package/README.md

@@ -59,10 +59,9 @@ const result = await try$
   - [all and allSettled](#all-and-allsettled)
   - [flow and $exit](#flow-and-exit)
   - [gen](#gen)
-  - [dispose](#dispose)
+- [dispose](#dispose)
 - [API Reference](#api-reference)
 - [Common Recipes](#common-recipes)
-- [Limitations](#limitations)
 - [When not to use tryharder](#when-not-to-use-tryharder)
 - [Contributing](#contributing)
 - [Acknowledgments](#acknowledgments)
@@ -498,37 +497,46 @@ const value = await try$.gen(function* (use) {
 
 ### dispose
 
-Use `dispose()` when cleanup should stay colocated with the workflow that allocates the resource, even across async boundaries.
+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:
+
+- `add(fn)` registers a cleanup callback.
+- `use(resource)` tracks a disposable resource.
+- `cleanup()` runs the registered teardown in reverse order.
 
 ```ts
 await using disposer = try$.dispose()
-const connection = await db.connect()
 
-disposer.defer(async () => {
-  await connection.close()
-})
+{
+  const connection = await db.connect()
+
+  disposer.add(async () => {
+    await connection.close()
+  })
 
-const user = await connection.users.findById("user_123")
+  const user = await connection.users.findById("user_123")
+}
 ```
 
+`tryharder` handles the cleanup bookkeeping internally, so native `DisposableStack` or `AsyncDisposableStack` globals are not required.
+
 ## API Reference
 
 ### 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 `AsyncDisposableStack` helper                            |
+| 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()` |
 
 ### Errors
 
@@ -549,6 +557,7 @@ Exports from `tryharder/types`:
 | Export             | Description                                          |
 | ------------------ | ---------------------------------------------------- |
 | `AllSettledResult` | Settled result map returned by `allSettled(...)`     |
+| `AsyncDisposer`    | Async cleanup helper returned by `dispose()`         |
 | `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 |
@@ -557,7 +566,7 @@ Exports from `tryharder/types`:
 ```ts
 import * as try$ from "tryharder"
 import { Panic, TimeoutError, UnhandledException } from "tryharder/errors"
-import type { FlowExit, SettledResult } from "tryharder/types"
+import type { AsyncDisposer, FlowExit, SettledResult } from "tryharder/types"
 ```
 
 ## Common Recipes
@@ -672,20 +681,11 @@ const value = await try$.run({
 })
 ```
 
-## Limitations
-
-- `tryharder` currently assumes `DisposableStack` and `AsyncDisposableStack` are available at runtime because the executor layer uses them internally, not just when you call `dispose()` yourself.
-- This can break consumers on runtimes that do not yet provide those globals, notably Firefox and Safari.
-- The tracked fix is [#36 Bundle DisposableStack polyfill for runtimes without native support](https://github.com/adelrodriguez/tryharder/issues/36).
-- Until that issue is resolved, use `tryharder` on runtimes with native disposable-stack support or provide a compatible polyfill before loading the package.
+## When not to use
 
-## When not to use tryharder
+When you can use [`Effect`](https://github.com/Effect-TS/effect) in your codebase.
 
-- **Small scripts or one-off tasks** - Plain `try/catch` is often simpler when you do not need retries, cancellation, or orchestration.
-- **You already use an effect system or result abstraction** - If your codebase already has a consistent execution model, adding `tryharder` may be redundant.
-- **Your workflows are mostly straightforward Promise chains** - `all(...)` and `flow(...)` help when coordination matters; otherwise native composition may be clearer.
-- **Your team prefers explicit `Result` values everywhere** - `tryharder` centers execution wrappers, not a dedicated result data type.
-- **You do not want policy-driven execution behavior** - If retry and timeout semantics are unnecessary overhead, the abstraction may not pay for itself.
+Seriously, Effect is a much more powerful and complete solution.
 
 ## Contributing
 

package/dist/errors.d.ts

@@ -1,6 +1,10 @@
 type PanicCode = "ALL_CATCH_HANDLER_REJECT" | "ALL_CATCH_HANDLER_THROW" | "FLOW_NO_EXIT" | "ORCHESTRATION_UNSUPPORTED_POLICY" | "RETRY_INVALID_LIMIT" | "RUN_CATCH_HANDLER_REJECT" | "RUN_CATCH_HANDLER_THROW" | "RUN_SYNC_ASYNC_RETRY_POLICY" | "RUN_SYNC_CATCH_HANDLER_THROW" | "RUN_SYNC_CATCH_PROMISE" | "RUN_SYNC_TRY_PROMISE" | "RUN_SYNC_WRAPPED_RESULT_PROMISE" | "TASK_INVALID_HANDLER" | "TASK_SELF_REFERENCE" | "TIMEOUT_INVALID_MS" | "TASK_UNKNOWN_REFERENCE" | "UNREACHABLE_RETRY_POLICY_BACKOFF";
-/** @internal */
-declare class ControlError extends Error {}
+/**
+* @internal
+*/
+declare class ControlError extends Error {
+	constructor(message?: string, options?: ErrorOptions);
+}
 declare class CancellationError extends ControlError {
 	constructor(message?: string, options?: ErrorOptions);
 }

package/dist/errors.js

@@ -4,7 +4,7 @@ import {
   RetryExhaustedError,
   TimeoutError,
   UnhandledException
-} from "./shared/chunk-vqm4xgxv.js";
+} from "./shared/chunk-f024nrjy.js";
 export {
   UnhandledException,
   TimeoutError,

package/dist/index.d.ts

@@ -1,5 +1,9 @@
-/** @internal */
-declare class ControlError extends Error {}
+/**
+* @internal
+*/
+declare class ControlError extends Error {
+	constructor(message?: string, options?: ErrorOptions);
+}
 declare class CancellationError extends ControlError {
 	constructor(message?: string, options?: ErrorOptions);
 }
@@ -12,13 +16,20 @@ declare class RetryExhaustedError extends Error {
 declare class UnhandledException extends Error {
 	constructor(message?: string, options?: ErrorOptions);
 }
+interface AsyncDisposer extends AsyncDisposable {
+	add(fn: () => void | PromiseLike<void>): void;
+	cleanup(): Promise<void>;
+	defer(fn: () => void | PromiseLike<void>): void;
+	use<T extends AsyncDisposable | Disposable | null | undefined>(value: T): T;
+	disposeAsync(): 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 };
 type TaskResult<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
 type InferredTaskContext<T extends TaskRecord> = {
 	$result: { readonly [K in keyof T] : ReturnType<T[K]> extends Promise<infer R> ? Promise<R> : Promise<ReturnType<T[K]>> };
 	$signal: AbortSignal;
-	$disposer: AsyncDisposableStack;
+	$disposer: AsyncDisposer;
 };
 type AllValue<T extends TaskRecord> = { [K in keyof T] : TaskResult<T[K]> };
 interface AllCatchContext<T extends TaskRecord> {
@@ -168,8 +179,8 @@ type SyncRunInput<
 	Ctx extends BaseTryCtx = BaseTryCtx
 > = SyncRunTryFn<T, Ctx> | SyncRunOptions<T, E, Ctx>;
 /**
-* Wraps are observational hooks: they can inspect execution context and
-* surround execution, but they must not mutate context or replace it.
+* Wraps are observational hooks: they can inspect execution context and surround execution, but
+* they must not mutate context or replace it.
 */
 type WrapCtx = Readonly<Omit<TryCtx, "retry">> & {
 	readonly retry: Readonly<TryCtx["retry"]>;
@@ -216,7 +227,6 @@ declare class RunBuilder<
 > {
 	protected readonly config: BuilderConfig;
 	constructor(config?: BuilderConfig);
-	protected buildRetryConfig(policy: RetryOptions): BuilderConfig;
 	protected buildTimeoutConfig(ms: number): BuilderConfig;
 	protected buildSignalConfig(signal: AbortSignal): BuilderConfig;
 	retry(policy: number): ExecutionBuilderSurface<E | RetryExhaustedError, true>;
@@ -241,7 +251,7 @@ 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(): AsyncDisposableStack;
+declare function dispose(): 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>;