clutchit 0.0.8 → 0.0.9

package/CHANGELOG.md

@@ -11,22 +11,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 #### `clutchit/unthrow`
 
-- `Result<T, E>` — synchronous typed error container with `Ok` and `Err` variants
-- `ResultAsync<T, E>` — async equivalent backed by `Promise<Result<T, E>>`, implements `PromiseLike`
-- `Result.Do` / `ResultAsync.Do` — generator-based Do notation for ergonomic sequential chaining
-- `Result.combine` / `ResultAsync.combine` — combine arrays of results, short-circuit on first error
-- `Result.combineWithAllErrors` / `ResultAsync.combineWithAllErrors` — collect all errors instead of stopping at first
-- `Result.fromThrowable` — wrap a throwing sync function into a `Result`
-- `ResultAsync.fromPromise` — lift a `Promise` into a `ResultAsync` with typed error mapping
+- `Try<T, E>` — synchronous typed error container with `Ok` and `Err` variants
+- `TryAsync<T, E>` — async equivalent backed by `Promise<Try<T, E>>`, implements `PromiseLike`
+- `ok()`, `err()`, `okAsync()`, `errAsync()` — standalone constructors
+- `Do` / `DoAsync` — generator-based Do notation with optional context parameter
+- Instance methods: `map`, `mapErr`, `andThen`, `orElse`, `tap`, `tapErr`, `andThrough`, `orThrough`, `catchFault`, `unwrapOr`, `match`
+- `fromPromise` — lift a `Promise` into a `TryAsync` with typed error mapping
+- `fromSafePromise` — lift a never-rejecting promise into `TryAsync<T, never>`
+- `fromThrowable` — wrap a throwing sync function into a `Try`
+- `fromAsyncThrowable` — wrap an async throwing function into a `TryAsync`
+- `combine` / `combineWithAllErrors` — combine arrays of `Try` or `TryAsync`
+- `unwrap` — assert a value is non-null/undefined, or return the fault
+- `flatten` — flatten nested `Try<Try<T, E2>, E1>` or `TryAsync<Try<T, E2>, E1>`
+- `race` — race multiple `TryAsync` values, like `Promise.race`
 - `Fault.Tagged` — factory for structured, tagged error classes with `code`, `_category`, and `_transient`
-- `Fault.isDomain` / `Fault.isInfrastructure` / `Fault.isTransient` — type guard helpers
+- `Fault.is` — duck-type guard for the `Fault` interface (accepts `unknown`)
+- `Fault.isDomain` / `Fault.isInfrastructure` / `Fault.isTransient` — type guard helpers (accept `unknown`)
 
 #### `clutchit/schedule`
 
 - `Schedule` — composable timing primitive with `.next(input, attempt)` and `.pipe(operator)` API
 - Factories: `spaced`, `exponential`, `linear`, `constant`, `fixed`, `windowed`, `fibonacci`, `cron`, `forever`, `once`
 - Operators: `recurs`, `cappedDelay`, `jittered`, `upTo`, `andThen`, `union`, `intersect`, `whileInput`, `whileOutput`, `map`
-- `Schedule.repeat` — run a `ResultAsync`-returning function repeatedly on a schedule with abort signal support
+- `Schedule.repeat` — run a `TryAsync`-returning function repeatedly on a schedule with abort signal support
 - `ScheduleInterruptedFault` — returned when `repeat` is cancelled via `AbortSignal`
 
 #### `clutchit/retry`
@@ -36,7 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 #### `clutchit/timeout`
 
-- `withTimeout(fn, duration)` — wrap a `ResultAsync`-returning function with a deadline
+- `withTimeout(fn, duration)` — wrap a `TryAsync`-returning function with a deadline
 - `createTimeout(duration)` — create a reusable timeout wrapper
 - `TimeoutFault` — transient infrastructure fault emitted on deadline exceeded; aborts the underlying operation
 

package/README.md

@@ -1,11 +1,10 @@
 # clutchit
 
-Resilience primitives for TypeScript — typed errors, retry, timeout, circuit breaking, scheduling, concurrency, and queues.
+Resilience primitives for TypeScript.
 
 [![npm](https://img.shields.io/npm/v/clutchit)](https://www.npmjs.com/package/clutchit)
-[![license](https://img.shields.io/npm/l/clutchit)](../LICENSE)
+[![license](https://img.shields.io/npm/l/clutchit)](./LICENSE)
 [![docs](https://img.shields.io/badge/docs-clutchit.existin.space-blue)](https://clutchit.existin.space)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/clutchit)](https://bundlephobia.com/package/clutchit)
 [![types](https://img.shields.io/npm/types/clutchit)](https://www.npmjs.com/package/clutchit)
 
 **[Documentation](https://clutchit.existin.space)** · [npm](https://www.npmjs.com/package/clutchit) · [Changelog](./CHANGELOG.md)
@@ -20,7 +19,7 @@ npm install clutchit
 
 | Import | Description |
 |---|---|
-| `clutchit/unthrow` | `Result<T,E>`, `ResultAsync<T,E>`, `Fault`, Do notation |
+| `clutchit/unthrow` | `Try<T,E>`, `TryAsync<T,E>`, `Fault`, Do notation |
 | `clutchit/schedule` | Composable timing schedules — exponential, linear, fibonacci, cron, … |
 | `clutchit/retry` | Retry policy with backoff schedules and abort signal support |
 | `clutchit/timeout` | Timeout wrapper with `AbortSignal` propagation |
@@ -33,10 +32,10 @@ npm install clutchit
 ## Quick start
 
 ```ts
-import { ResultAsync, Fault } from 'clutchit/unthrow';
-import { RetryPolicy }        from 'clutchit/retry';
-import { withTimeout }        from 'clutchit/timeout';
-import { Schedule }           from 'clutchit/schedule';
+import { ok, err, okAsync, errAsync, fromPromise, Fault } from 'clutchit/unthrow';
+import { RetryPolicy }  from 'clutchit/retry';
+import { withTimeout }  from 'clutchit/timeout';
+import { Schedule }     from 'clutchit/schedule';
 
 class ApiFault extends Fault.Tagged('API_ERROR', 'infrastructure', true)<{
   status: number;
@@ -44,8 +43,8 @@ class ApiFault extends Fault.Tagged('API_ERROR', 'infrastructure', true)<{
   readonly message = `API returned ${this.status}`;
 }
 
-function fetchUser(id: string, signal: AbortSignal): ResultAsync<User, ApiFault> {
-  return ResultAsync.fromPromise(
+function fetchUser(id: string, signal: AbortSignal): TryAsync<User, ApiFault> {
+  return fromPromise(
     fetch(`/api/users/${id}`, { signal }).then((r) => r.json()),
     () => new ApiFault({ status: 500 }),
   );
@@ -72,38 +71,38 @@ await result.match({
 
 Typed error handling without exceptions.
 
-### Result
+### Try
 
 ```ts
-import { Result } from 'clutchit/unthrow';
+import { ok, err } from 'clutchit/unthrow';
 
-const ok   = Result.ok(42);
-const fail = Result.err('oops');
+const success = ok(42);
+const failure = err('oops');
 
-ok.map((n) => n * 2);              // Ok(84)
-ok.andThen((n) => Result.ok(n));   // Ok(42)
-ok.unwrapOr(0);                    // 42
-fail.unwrapOr(0);                  // 0
+success.map((n) => n * 2);              // Ok(84)
+success.andThen((n) => ok(n));           // Ok(42)
+success.unwrapOr(0);                     // 42
+failure.unwrapOr(0);                     // 0
 
-ok.match({
+success.match({
   ok:  (value) => `got ${value}`,
   err: (error) => `failed: ${error}`,
 });
 
-if (ok.isOk())  ok.value;   // narrowed
-if (fail.isErr()) fail.error; // narrowed
+if (success.isOk())  success.value;   // narrowed
+if (failure.isErr()) failure.error;   // narrowed
 ```
 
-Methods: `isOk`, `isErr`, `map`, `mapErr`, `andThen`, `orElse`, `unwrapOr`, `match`
+Methods: `isOk`, `isErr`, `map`, `mapErr`, `andThen`, `orElse`, `tap`, `tapErr`, `andThrough`, `orThrough`, `catchFault`, `unwrapOr`, `match`
 
-### ResultAsync
+### TryAsync
 
-Wraps `Promise<Result<T, E>>`. Awaitable via `PromiseLike`, same chainable API as `Result`.
+Wraps `Promise<Try<T, E>>`. Awaitable via `PromiseLike`, same chainable API as `Try`.
 
 ```ts
-import { ResultAsync } from 'clutchit/unthrow';
+import { fromPromise } from 'clutchit/unthrow';
 
-const result = ResultAsync.fromPromise(
+const result = fromPromise(
   fetch('/api/data').then((r) => r.json()),
   (err) => new NetworkFault({ cause: String(err) }),
 );
@@ -113,26 +112,43 @@ const final = await result
   .andThen((items) => validate(items));
 ```
 
-Methods: `map`, `mapErr`, `andThen`, `orElse`, `unwrapOr`, `match` (all return `ResultAsync` or `Promise`)
+Methods: `map`, `mapErr`, `andThen`, `orElse`, `tap`, `tapErr`, `andThrough`, `orThrough`, `catchFault`, `unwrapOr`, `match` (all return `TryAsync` or `Promise`)
 
 ### Helpers
 
 ```ts
-import { Result, ResultAsync } from 'clutchit/unthrow';
+import { ok, err, okAsync, fromPromise, fromThrowable, fromSafePromise, fromAsyncThrowable, combine, combineWithAllErrors, unwrap, flatten, race } from 'clutchit/unthrow';
 
 // Wrap a throwable sync function
-Result.fromThrowable(
+fromThrowable(
   () => JSON.parse(raw),
   (err) => new ParseFault({ message: String(err) }),
 );
 
+// Wrap an async throwable function
+fromAsyncThrowable(
+  () => fetchData(),
+  (err) => new NetworkFault({ cause: String(err) }),
+);
+
+// Lift a safe (never-rejecting) promise
+fromSafePromise(Promise.resolve(42));
+
+// Assert non-null values
+unwrap(ok<string | null, E>(value), new NullFault());
+
+// Flatten nested results
+flatten(ok(ok(42)));  // Ok(42)
+
 // Combine — short-circuit on first error
-Result.combine([resultA, resultB]);           // Result<[A, B], E>
-ResultAsync.combine([asyncA, asyncB]);         // ResultAsync<[A, B], E>
+combine([ok(1), ok(2)]);              // Ok([1, 2])
+combine([okAsync(1), okAsync(2)]);    // TryAsync<[1, 2], E>
 
 // Combine — collect all errors
-Result.combineWithAllErrors([a, b, c]);        // Result<[A, B, C], E[]>
-ResultAsync.combineWithAllErrors([a, b, c]);   // ResultAsync<[A, B, C], E[]>
+combineWithAllErrors([ok(1), err('a'), err('b')]);  // Err(['a', 'b'])
+
+// Race — first to resolve wins
+race([okAsync(1), okAsync(2)]);
 ```
 
 ### Do notation
@@ -140,22 +156,28 @@ ResultAsync.combineWithAllErrors([a, b, c]);   // ResultAsync<[A, B, C], E[]>
 Generator-based sequential chaining. `yield*` unwraps `Ok`; any `Err` short-circuits the entire block.
 
 ```ts
-import { Result, ResultAsync } from 'clutchit/unthrow';
+import { Do, DoAsync } from 'clutchit/unthrow';
 
 // Sync
-const result = Result.Do(function* () {
-  const user  = yield* findUser(id);        // Result<User, NotFoundFault>
-  const perms = yield* getPermissions(user); // Result<Perms, PermFault>
+const result = Do(function* () {
+  const user  = yield* findUser(id);        // Try<User, NotFoundFault>
+  const perms = yield* getPermissions(user); // Try<Perms, PermFault>
   return { user, perms };
-  // Result<{ user, perms }, NotFoundFault | PermFault>
+  // Try<{ user, perms }, NotFoundFault | PermFault>
 });
 
 // Async
-const result = ResultAsync.Do(async function* () {
-  const user  = yield* fetchUser(id);         // ResultAsync<User, NetworkFault>
-  const order = yield* createOrder(user);     // ResultAsync<Order, OrderFault>
+const result = DoAsync(async function* () {
+  const user  = yield* fetchUser(id);         // TryAsync<User, NetworkFault>
+  const order = yield* createOrder(user);     // TryAsync<Order, OrderFault>
   return order;
-  // ResultAsync<Order, NetworkFault | OrderFault>
+  // TryAsync<Order, NetworkFault | OrderFault>
+});
+
+// With context
+const result = Do({ db }, function* (ctx) {
+  const user = yield* ctx.db.findUser(id);
+  return user;
 });
 ```
 
@@ -222,7 +244,7 @@ const result = Schedule.repeat(
     onExecution: (attempt, delay) => console.log(`#${attempt}, next in ${delay}ms`),
   },
 );
-// ResultAsync<number, SyncError | ScheduleInterruptedFault>
+// TryAsync<number, SyncError | ScheduleInterruptedFault>
 ```
 
 ---
@@ -241,7 +263,7 @@ const retry = new RetryPolicy({
 });
 
 const result = retry.execute((signal) => fetchData(signal));
-// ResultAsync<Data, FetchFault>
+// TryAsync<Data, FetchFault>
 ```
 
 Options can be set on the constructor (defaults for all calls) or overridden per `execute` call.
@@ -265,7 +287,7 @@ const result = withTimeout(
   (signal) => fetchData(signal),
   5_000,
 );
-// ResultAsync<Data, FetchFault | TimeoutFault>
+// TryAsync<Data, FetchFault | TimeoutFault>
 
 // Reusable wrapper
 const withFiveSeconds = createTimeout(5_000);
@@ -322,9 +344,9 @@ Atomic mutable reference with internal mutex:
 ```ts
 const counter = new Concurrency.Ref(0);
 
-await counter.update((n) => n + 1);       // ResultAsync<void, never>
-await counter.set(42);                    // ResultAsync<void, never>
-const next = await counter.modify(        // ResultAsync<number, never>
+await counter.update((n) => n + 1);       // TryAsync<void, never>
+await counter.set(42);                    // TryAsync<void, never>
+const next = await counter.modify(        // TryAsync<number, never>
   (n) => [n + 1, n + 1],
 );
 counter.get();                            // current value (sync)
@@ -347,7 +369,7 @@ const breaker = new Circuit.Breaker({
 });
 
 const result = breaker.protect(() => callService());
-// ResultAsync<T, ServiceFault | CircuitOpenFault>
+// TryAsync<T, ServiceFault | CircuitOpenFault>
 
 breaker.state;        // 'closed' | 'open' | 'half-open'
 breaker.failureCount; // consecutive failures
@@ -367,13 +389,13 @@ import { Queue, QueueFullFault, QueueEmptyFault } from 'clutchit/queue';
 
 const q = new Queue.Bounded<Job>({ capacity: 100 });
 
-q.offer(job);              // Result<void, QueueFullFault> — non-blocking
+q.offer(job);              // Try<void, QueueFullFault> — non-blocking
 await q.put(job);          // blocks until space is available
 await q.put(job, signal);  // cancellable
 
 const item  = await q.take();        // blocks until item available
 const batch = await q.takeBatch(10); // at least 1, up to 10
-const maybe = q.poll();              // Result<Job, QueueEmptyFault>
+const maybe = q.poll();              // Try<Job, QueueEmptyFault>
 ```
 
 ### DroppingQueue — drops newest when full
@@ -422,6 +444,7 @@ class UnauthorizedFault extends Fault.Tagged('UNAUTHORIZED', 'domain')() {
 ### Type guards
 
 ```ts
+Fault.is(value);                // duck-type check for Fault shape
 Fault.isDomain(fault);          // _category === 'domain'
 Fault.isInfrastructure(fault);  // _category === 'infrastructure'
 Fault.isTransient(fault);       // infrastructure + _transient

package/dist/circuit/circuit.breaker.js

@@ -1,4 +1,4 @@
-import { Fault, ResultAsync } from '../unthrow/index.js';
+import { Fault, errAsync, fromPromise, } from '../unthrow/index.js';
 import { Schedule } from '../schedule/index.js';
 export class CircuitOpenFault extends Fault.Tagged('CIRCUIT_OPEN', 'infrastructure')() {
     message = `Circuit breaker is open. Retry after ${this.remainingTimeout}ms`;
@@ -31,16 +31,16 @@ export class CircuitBreaker {
                 const remainingTimeout = this._nextResetTime
                     ? Math.max(0, this._nextResetTime - Date.now())
                     : 0;
-                return ResultAsync.err(new CircuitOpenFault({ remainingTimeout }));
+                return errAsync(new CircuitOpenFault({ remainingTimeout }));
             }
         }
         if (this._state === 'half-open') {
             if (this._halfOpenTrials >= this._maxHalfOpenAttempts) {
-                return ResultAsync.err(new CircuitOpenFault({ remainingTimeout: 0 }));
+                return errAsync(new CircuitOpenFault({ remainingTimeout: 0 }));
             }
             this._halfOpenTrials++;
         }
-        return ResultAsync.fromPromise((async () => {
+        return fromPromise((async () => {
             const result = await fn();
             if (result.isOk()) {
                 this.onSuccess();

package/dist/concurrency/bulkhead.js

@@ -1,4 +1,4 @@
-import { Fault, ResultAsync } from '../unthrow/index.js';
+import { Fault, errAsync, fromPromise, } from '../unthrow/index.js';
 export class BulkheadRejectedFault extends Fault.Tagged('BULKHEAD_REJECTED', 'infrastructure')() {
     message = 'Bulkhead capacity exceeded';
 }
@@ -14,9 +14,9 @@ export class Bulkhead {
     execute(fn) {
         if (this._active >= this._maxConcurrency &&
             this._queue.length >= this._maxQueue) {
-            return ResultAsync.err(new BulkheadRejectedFault());
+            return errAsync(new BulkheadRejectedFault());
         }
-        return ResultAsync.fromPromise((async () => {
+        return fromPromise((async () => {
             await this.acquire();
             try {
                 const result = await fn();

package/dist/concurrency/rate-limiter.js

@@ -1,4 +1,4 @@
-import { Fault, ResultAsync } from '../unthrow/index.js';
+import { Fault, errAsync } from '../unthrow/index.js';
 export class RateLimitFault extends Fault.Tagged('RATE_LIMITED', 'infrastructure', true)() {
     message = `Rate limit exceeded. Retry after ${this.retryAfter}ms`;
 }
@@ -15,7 +15,7 @@ export class RateLimiter {
         if (this._timestamps.length >= this._limit) {
             const oldest = this._timestamps[0];
             const retryAfter = Math.max(0, oldest + this._window - Date.now());
-            return ResultAsync.err(new RateLimitFault({ retryAfter }));
+            return errAsync(new RateLimitFault({ retryAfter }));
         }
         this._timestamps.push(Date.now());
         return fn();

package/dist/concurrency/ref.js

@@ -1,4 +1,4 @@
-import { ResultAsync } from '../unthrow/index.js';
+import { okAsync } from '../unthrow/index.js';
 import { Semaphore } from './semaphore.js';
 export class Ref {
     _value;
@@ -13,7 +13,7 @@ export class Ref {
         return this._mutex.execute(() => {
             const [next, result] = fn(this._value);
             this._value = next;
-            return ResultAsync.ok(result);
+            return okAsync(result);
         });
     }
     update(fn) {

package/dist/concurrency/semaphore.js

@@ -1,4 +1,4 @@
-import { ResultAsync } from '../unthrow/index.js';
+import { fromPromise } from '../unthrow/index.js';
 export class Semaphore {
     _available;
     _queue = [];
@@ -6,7 +6,7 @@ export class Semaphore {
         this._available = options.permits;
     }
     execute(fn) {
-        return ResultAsync.fromPromise((async () => {
+        return fromPromise((async () => {
             await this.acquire();
             try {
                 const result = await fn();

package/dist/queue/base.queue.js

@@ -1,4 +1,4 @@
-import { Result, ResultAsync } from '../unthrow/index.js';
+import { ok, err, okAsync, fromPromise, } from '../unthrow/index.js';
 import { QueueEmptyFault } from './faults.js';
 export class BaseQueue {
     _buffer = [];
@@ -9,15 +9,15 @@ export class BaseQueue {
     }
     _tryTake() {
         if (this._buffer.length > 0) {
-            return Result.ok(this._buffer.shift());
+            return ok(this._buffer.shift());
         }
-        return Result.err(new QueueEmptyFault());
+        return err(new QueueEmptyFault());
     }
     take(signal) {
         const taken = this._tryTake();
         if (taken.isOk())
-            return ResultAsync.ok(taken.value);
-        return ResultAsync.fromPromise(new Promise((resolve) => {
+            return okAsync(taken.value);
+        return fromPromise(new Promise((resolve) => {
             this._takeWaiters.push(resolve);
             signal?.addEventListener('abort', () => {
                 const idx = this._takeWaiters.indexOf(resolve);
@@ -27,7 +27,7 @@ export class BaseQueue {
         }), () => undefined);
     }
     takeBatch(n, signal) {
-        return ResultAsync.fromPromise((async () => {
+        return fromPromise((async () => {
             const taken = this._tryTake();
             let first;
             if (taken.isOk()) {

package/dist/queue/bounded.queue.js

@@ -1,4 +1,4 @@
-import { Result, ResultAsync } from '../unthrow/index.js';
+import { ok, err, okAsync, fromPromise, } from '../unthrow/index.js';
 import { QueueEmptyFault, QueueFullFault } from './faults.js';
 import { BaseQueue } from './base.queue.js';
 export class BoundedQueue extends BaseQueue {
@@ -15,42 +15,42 @@ export class BoundedQueue extends BaseQueue {
                 this._buffer.push(pw.item);
                 pw.resolve();
             }
-            return Result.ok(item);
+            return ok(item);
         }
         // Buffer empty — try put waiters directly
         const pw = this._putWaiters.shift();
         if (pw) {
             pw.resolve();
-            return Result.ok(pw.item);
+            return ok(pw.item);
         }
-        return Result.err(new QueueEmptyFault());
+        return err(new QueueEmptyFault());
     }
     offer(item) {
         // Give directly to a waiting consumer
         const waiter = this._takeWaiters.shift();
         if (waiter) {
             waiter(item);
-            return Result.ok(undefined);
+            return ok(undefined);
         }
         if (this._buffer.length >= this._capacity) {
-            return Result.err(new QueueFullFault({ capacity: this._capacity }));
+            return err(new QueueFullFault({ capacity: this._capacity }));
         }
         this._buffer.push(item);
-        return Result.ok(undefined);
+        return ok(undefined);
     }
     put(item, signal) {
         // Give directly to a waiting consumer
         const waiter = this._takeWaiters.shift();
         if (waiter) {
             waiter(item);
-            return ResultAsync.ok(undefined);
+            return okAsync(undefined);
         }
         if (this._buffer.length < this._capacity) {
             this._buffer.push(item);
-            return ResultAsync.ok(undefined);
+            return okAsync(undefined);
         }
         // Wait for space
-        return ResultAsync.fromPromise(new Promise((resolve) => {
+        return fromPromise(new Promise((resolve) => {
             const entry = { item, resolve };
             this._putWaiters.push(entry);
             signal?.addEventListener('abort', () => {

package/dist/retry/retry.js

@@ -1,4 +1,4 @@
-import { ResultAsync } from '../unthrow/index.js';
+import { fromPromise } from '../unthrow/index.js';
 import { Schedule } from '../schedule/index.js';
 const NEVER_ABORT = new AbortController().signal;
 const DEFAULT_SCHEDULE = Schedule.exponential(200).pipe(Schedule.recurs(3));
@@ -32,7 +32,7 @@ export class RetryPolicy {
         const onRetry = options?.onRetry ??
             this.defaults?.onRetry;
         const signal = options?.signal ?? this.defaults?.signal;
-        return ResultAsync.fromPromise((async () => {
+        return fromPromise((async () => {
             let lastError;
             for (let attempt = 0;; attempt++) {
                 const result = await fn(signal ?? NEVER_ABORT);

package/dist/schedule/runner.js

@@ -1,4 +1,4 @@
-import { Fault, ResultAsync } from '../unthrow/index.js';
+import { Fault, fromPromise } from '../unthrow/index.js';
 export class ScheduleInterruptedFault extends Fault.Tagged('SCHEDULE_INTERRUPTED', 'infrastructure')() {
     message = 'Scheduled execution was interrupted';
 }
@@ -30,7 +30,7 @@ function sleep(ms, signal) {
 export function repeat(schedule, fn, options) {
     const signal = options?.signal;
     const onExecution = options?.onExecution;
-    return ResultAsync.fromPromise((async () => {
+    return fromPromise((async () => {
         for (let attempt = 0;; attempt++) {
             // eslint-disable-next-line @typescript-eslint/only-throw-error -- intentional: fromPromise catches and maps E
             if (signal?.aborted)

package/dist/timeout/timeout.js

@@ -1,10 +1,10 @@
-import { Fault, ResultAsync } from '../unthrow/index.js';
+import { Fault, fromPromise } from '../unthrow/index.js';
 export class TimeoutFault extends Fault.Tagged('TIMEOUT', 'infrastructure', true)() {
     message = `Operation timed out after ${this.duration}ms`;
 }
 export function withTimeout(fn, duration) {
     const controller = new AbortController();
-    return ResultAsync.fromPromise(
+    return fromPromise(
     /* eslint-disable @typescript-eslint/prefer-promise-reject-errors -- intentional: rejections are typed E | TimeoutFault, caught by fromPromise */
     new Promise((resolve, reject) => {
         const timer = setTimeout(() => {

package/dist/unthrow/do.js

@@ -1,7 +1,9 @@
-import { ok } from './result.js';
-import { ResultAsync } from './result.async.js';
-export function Do(generator) {
-    const gen = generator();
+import { ok } from './try.js';
+import { TryAsync } from './try.async.js';
+export function Do(ctxOrGenerator, generator) {
+    const gen = typeof ctxOrGenerator === 'function'
+        ? ctxOrGenerator()
+        : generator(ctxOrGenerator);
     const next = gen.next();
     while (!next.done) {
         // Each yielded value is an Err — short-circuit
@@ -9,9 +11,11 @@ export function Do(generator) {
     }
     return ok(next.value);
 }
-export function DoAsync(generator) {
-    return new ResultAsync((async () => {
-        const gen = generator();
+export function DoAsync(ctxOrGenerator, generator) {
+    return new TryAsync((async () => {
+        const gen = typeof ctxOrGenerator === 'function'
+            ? ctxOrGenerator()
+            : generator(ctxOrGenerator);
         const next = await gen.next();
         while (!next.done) {
             // Each yielded value is an Err — short-circuit

package/dist/unthrow/fault.js

@@ -1,11 +1,20 @@
-export function isDomainFault(error) {
-    return error._category === 'domain';
+export function isFault(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.code === 'string' &&
+        typeof value.message === 'string' &&
+        (value._category === 'domain' ||
+            value._category === 'infrastructure') &&
+        typeof value._transient === 'boolean');
 }
-export function isInfrastructureFault(error) {
-    return error._category === 'infrastructure';
+export function isDomainFault(value) {
+    return isFault(value) && value._category === 'domain';
 }
-export function isTransientFault(error) {
-    return error._transient && error._category === 'infrastructure';
+export function isInfrastructureFault(value) {
+    return isFault(value) && value._category === 'infrastructure';
+}
+export function isTransientFault(value) {
+    return (isFault(value) && value._transient && value._category === 'infrastructure');
 }
 export function Fault(code, category, transient) {
     const _transient = (transient ?? false);

package/dist/unthrow/helpers.js

@@ -1,12 +1,12 @@
-import { ok, err } from './result.js';
-import { ResultAsync } from './result.async.js';
+import { ok, err } from './try.js';
+import { TryAsync } from './try.async.js';
 export function combine(results) {
     if (results.length === 0) {
         return ok([]);
     }
-    if (results[0] instanceof ResultAsync) {
-        const asyncResults = results;
-        return new ResultAsync(Promise.all(asyncResults.map((r) => r.then((v) => v))).then((settled) => combineSync(settled)));
+    if (results[0] instanceof TryAsync) {
+        const asyncTrys = results;
+        return new TryAsync(Promise.all(asyncTrys.map((r) => r.then((v) => v))).then((settled) => combineSync(settled)));
     }
     return combineSync(results);
 }
@@ -23,9 +23,9 @@ export function combineWithAllErrors(results) {
     if (results.length === 0) {
         return ok([]);
     }
-    if (results[0] instanceof ResultAsync) {
-        const asyncResults = results;
-        return new ResultAsync(Promise.all(asyncResults.map((r) => r.then((v) => v))).then((settled) => combineWithAllErrorsSync(settled)));
+    if (results[0] instanceof TryAsync) {
+        const asyncTrys = results;
+        return new TryAsync(Promise.all(asyncTrys.map((r) => r.then((v) => v))).then((settled) => combineWithAllErrorsSync(settled)));
     }
     return combineWithAllErrorsSync(results);
 }
@@ -43,7 +43,10 @@ function combineWithAllErrorsSync(results) {
     return errors.length > 0 ? err(errors) : ok(values);
 }
 export function fromPromise(promise, errorMapper) {
-    return new ResultAsync(promise.then((value) => ok(value), (error) => err(errorMapper(error))));
+    return new TryAsync(promise.then((value) => ok(value), (error) => err(errorMapper(error))));
+}
+export function fromSafePromise(promise) {
+    return new TryAsync(promise.then((value) => ok(value)));
 }
 export function fromThrowable(fn, errorMapper) {
     try {
@@ -53,4 +56,24 @@ export function fromThrowable(fn, errorMapper) {
         return err(errorMapper(error));
     }
 }
+export function fromAsyncThrowable(fn, errorMapper) {
+    try {
+        return fromPromise(fn(), errorMapper);
+    }
+    catch (error) {
+        return new TryAsync(Promise.resolve(err(errorMapper(error))));
+    }
+}
+export function unwrap(result, fault) {
+    return result.andThen((value) => (value != null ? ok(value) : err(fault)));
+}
+export function flatten(result) {
+    return result.andThen((inner) => inner);
+}
+export function race(results) {
+    if (results.length === 0) {
+        return new TryAsync(Promise.reject(new Error('race requires at least one TryAsync')));
+    }
+    return new TryAsync(Promise.race(results.map((r) => r.then((v) => v))));
+}
 //# sourceMappingURL=helpers.js.map

package/dist/unthrow/index.js

@@ -1,48 +1,18 @@
-import { ok as _ok, err as _err } from './result.js';
-import { okAsync, errAsync, } from './result.async.js';
-import { fromPromise as _fromPromise, fromThrowable as _fromThrowable, combine as _combine, combineWithAllErrors as _combineWithAllErrors, } from './helpers.js';
-import { Do as _Do, DoAsync } from './do.js';
-import { Fault as _Fault, isDomainFault as _isDomainFault, isInfrastructureFault as _isInfrastructureFault, isTransientFault as _isTransientFault, } from './fault.js';
-// Re-export instance types (needed in user signatures)
-export { Ok, Err } from './result.js';
-// eslint-disable-next-line @typescript-eslint/no-namespace
-export var Result;
-(function (Result) {
-    Result.ok = _ok;
-    Result.err = _err;
-    Result.fromThrowable = _fromThrowable;
-    function combine(results) {
-        return _combine(results);
-    }
-    Result.combine = combine;
-    function combineWithAllErrors(results) {
-        return _combineWithAllErrors(results);
-    }
-    Result.combineWithAllErrors = combineWithAllErrors;
-    Result.Do = _Do;
-})(Result || (Result = {}));
-// eslint-disable-next-line @typescript-eslint/no-namespace
-export var ResultAsync;
-(function (ResultAsync) {
-    ResultAsync.ok = okAsync;
-    ResultAsync.err = errAsync;
-    ResultAsync.fromPromise = _fromPromise;
-    function combine(results) {
-        return _combine(results);
-    }
-    ResultAsync.combine = combine;
-    function combineWithAllErrors(results) {
-        return _combineWithAllErrors(results);
-    }
-    ResultAsync.combineWithAllErrors = combineWithAllErrors;
-    ResultAsync.Do = DoAsync;
-})(ResultAsync || (ResultAsync = {}));
+// ── Fault ────────────────────────────────────────────────────────
+import { Fault as _Fault, isFault as _isFault, isDomainFault as _isDomainFault, isInfrastructureFault as _isInfrastructureFault, isTransientFault as _isTransientFault, } from './fault.js';
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export var Fault;
 (function (Fault) {
     Fault.Tagged = _Fault;
+    Fault.is = _isFault;
     Fault.isDomain = _isDomainFault;
     Fault.isInfrastructure = _isInfrastructureFault;
     Fault.isTransient = _isTransientFault;
 })(Fault || (Fault = {}));
+// ── Try ──────────────────────────────────────────────────────────
+export { Ok, Err, ok, err } from './try.js';
+export { TryAsync, okAsync, errAsync } from './try.async.js';
+export { fromPromise, fromSafePromise, fromThrowable, fromAsyncThrowable, combine, combineWithAllErrors, unwrap, flatten, race, } from './helpers.js';
+// ── Do ──────────────────────────────────────────────────────────
+export { Do, DoAsync } from './do.js';
 //# sourceMappingURL=index.js.map

package/dist/unthrow/try.async.js

@@ -0,0 +1,114 @@
+import { Ok, Err, ok, err } from './try.js';
+export class TryAsync {
+    _promise;
+    then;
+    constructor(promise) {
+        this._promise = promise;
+        this.then = promise.then.bind(promise);
+    }
+    map(fn) {
+        return new TryAsync(this._promise.then(async (result) => {
+            if (result.isErr())
+                return new Err(result.error);
+            return new Ok(await fn(result.value));
+        }));
+    }
+    mapErr(fn) {
+        return new TryAsync(this._promise.then(async (result) => {
+            if (result.isOk())
+                return new Ok(result.value);
+            return new Err(await fn(result.error));
+        }));
+    }
+    andThen(fn) {
+        return new TryAsync(this._promise.then((result) => {
+            if (result.isErr())
+                return new Err(result.error);
+            const next = fn(result.value);
+            return next instanceof TryAsync ? next._promise : next;
+        }));
+    }
+    orElse(fn) {
+        return new TryAsync(this._promise.then((result) => {
+            if (result.isOk())
+                return new Ok(result.value);
+            const next = fn(result.error);
+            return next instanceof TryAsync ? next._promise : next;
+        }));
+    }
+    tap(fn) {
+        return new TryAsync(this._promise.then(async (result) => {
+            if (result.isOk())
+                await fn(result.value);
+            return result;
+        }));
+    }
+    tapErr(fn) {
+        return new TryAsync(this._promise.then(async (result) => {
+            if (result.isErr())
+                await fn(result.error);
+            return result;
+        }));
+    }
+    andThrough(fn) {
+        return new TryAsync(this._promise.then(async (result) => {
+            if (result.isErr())
+                return new Err(result.error);
+            const through = fn(result.value);
+            const throughResult = through instanceof TryAsync ? await through : through;
+            if (throughResult.isErr())
+                return new Err(throughResult.error);
+            return new Ok(result.value);
+        }));
+    }
+    orThrough(fn) {
+        return new TryAsync(this._promise.then(async (result) => {
+            if (result.isOk())
+                return new Ok(result.value);
+            const through = fn(result.error);
+            const throughResult = through instanceof TryAsync ? await through : through;
+            if (throughResult.isErr())
+                return new Err(throughResult.error);
+            return new Err(result.error);
+        }));
+    }
+    catchFault(code, fn) {
+        return new TryAsync(this._promise.then((result) => {
+            if (result.isOk())
+                return new Ok(result.value);
+            const error = result.error;
+            if (typeof error === 'object' &&
+                error !== null &&
+                'code' in error &&
+                error.code === code) {
+                const next = fn(error);
+                return next instanceof TryAsync ? next._promise : next;
+            }
+            return new Err(error);
+        }));
+    }
+    async unwrapOr(defaultValue) {
+        const result = await this;
+        return result.unwrapOr(defaultValue);
+    }
+    async match(cases) {
+        const result = await this;
+        return result.match(cases);
+    }
+    async *[Symbol.asyncIterator]() {
+        const result = await this._promise;
+        if (result.isErr()) {
+            // @ts-expect-error -- structurally equivalent, safe for DoAsync notation
+            yield result;
+            throw new Error('Unreachable: DoAsync generator continued after Err yield');
+        }
+        return result.value;
+    }
+}
+export function okAsync(value) {
+    return new TryAsync(Promise.resolve(ok(value)));
+}
+export function errAsync(error) {
+    return new TryAsync(Promise.resolve(err(error)));
+}
+//# sourceMappingURL=try.async.js.map

package/dist/unthrow/{result.js → try.js}

@@ -24,6 +24,25 @@ export class Ok {
     orElse(_fn) {
         return new Ok(this.value);
     }
+    tap(fn) {
+        fn(this.value);
+        return this;
+    }
+    tapErr(_fn) {
+        return this;
+    }
+    andThrough(fn) {
+        const result = fn(this.value);
+        if (result.isErr())
+            return new Err(result.error);
+        return this;
+    }
+    orThrough(_fn) {
+        return this;
+    }
+    catchFault(_code, _fn) {
+        return this;
+    }
     unwrapOr(_defaultValue) {
         return this.value;
     }
@@ -59,6 +78,32 @@ export class Err {
     orElse(fn) {
         return fn(this.error);
     }
+    tap(_fn) {
+        return this;
+    }
+    tapErr(fn) {
+        fn(this.error);
+        return this;
+    }
+    andThrough(_fn) {
+        return this;
+    }
+    orThrough(fn) {
+        const result = fn(this.error);
+        if (result.isErr())
+            return new Err(result.error);
+        return this;
+    }
+    catchFault(code, fn) {
+        const error = this.error;
+        if (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === code) {
+            return fn(error);
+        }
+        return this;
+    }
     unwrapOr(defaultValue) {
         return defaultValue;
     }
@@ -77,4 +122,4 @@ export function ok(value) {
 export function err(error) {
     return new Err(error);
 }
-//# sourceMappingURL=result.js.map
+//# sourceMappingURL=try.js.map

package/package.json

@@ -1,7 +1,24 @@
 {
   "name": "clutchit",
-  "version": "0.0.8",
-  "description": "",
+  "version": "0.0.9",
+  "description": "Resilience primitives for TypeScript — typed errors, retry, timeout, circuit breaking, scheduling, concurrency, and queues.",
+  "keywords": [
+    "typescript",
+    "resilience",
+    "error-handling",
+    "result",
+    "typed-errors",
+    "retry",
+    "timeout",
+    "circuit-breaker",
+    "schedule",
+    "backoff",
+    "concurrency",
+    "semaphore",
+    "bulkhead",
+    "rate-limiter",
+    "queue"
+  ],
   "author": {
     "name": "hexac",
     "url": "https://existin.space",

package/dist/unthrow/result.async.js

@@ -1,63 +0,0 @@
-import { Ok, Err, ok, err } from './result.js';
-export class ResultAsync {
-    _promise;
-    then;
-    constructor(promise) {
-        this._promise = promise;
-        this.then = promise.then.bind(promise);
-    }
-    map(fn) {
-        return new ResultAsync(this._promise.then(async (result) => {
-            if (result.isErr())
-                return new Err(result.error);
-            return new Ok(await fn(result.value));
-        }));
-    }
-    mapErr(fn) {
-        return new ResultAsync(this._promise.then(async (result) => {
-            if (result.isOk())
-                return new Ok(result.value);
-            return new Err(await fn(result.error));
-        }));
-    }
-    andThen(fn) {
-        return new ResultAsync(this._promise.then((result) => {
-            if (result.isErr())
-                return new Err(result.error);
-            const next = fn(result.value);
-            return next instanceof ResultAsync ? next._promise : next;
-        }));
-    }
-    orElse(fn) {
-        return new ResultAsync(this._promise.then((result) => {
-            if (result.isOk())
-                return new Ok(result.value);
-            const next = fn(result.error);
-            return next instanceof ResultAsync ? next._promise : next;
-        }));
-    }
-    async unwrapOr(defaultValue) {
-        const result = await this;
-        return result.unwrapOr(defaultValue);
-    }
-    async match(cases) {
-        const result = await this;
-        return result.match(cases);
-    }
-    async *[Symbol.asyncIterator]() {
-        const result = await this._promise;
-        if (result.isErr()) {
-            // @ts-expect-error -- structurally equivalent, safe for DoAsync notation
-            yield result;
-            throw new Error('Unreachable: DoAsync generator continued after Err yield');
-        }
-        return result.value;
-    }
-}
-export function okAsync(value) {
-    return new ResultAsync(Promise.resolve(ok(value)));
-}
-export function errAsync(error) {
-    return new ResultAsync(Promise.resolve(err(error)));
-}
-//# sourceMappingURL=result.async.js.map