clutchit 0.0.3 → 0.0.6

package/README.md

@@ -0,0 +1,530 @@
+# clutchit
+
+Resilience primitives for TypeScript — retry, circuit breaker, timeout, rate limiting, and more with typed errors.
+
+[![npm](https://img.shields.io/npm/v/clutchit)](https://www.npmjs.com/package/clutchit)
+[![license](https://img.shields.io/npm/l/clutchit)](./LICENSE)
+
+## Install
+
+```bash
+npm install clutchit
+```
+
+## Quick Example
+
+```typescript
+import { ResultAsync, Fault } from 'clutchit/unthrow';
+import { Retry } from 'clutchit/retry';
+import { Timeout } from 'clutchit/timeout';
+import { Schedule } from 'clutchit/schedule';
+
+class ApiFault extends Fault.Tagged('API_ERROR', 'infrastructure', true)<{
+  status: number;
+}>() {
+  readonly message = `API returned ${this.status}`;
+}
+
+function fetchUser(id: string, signal: AbortSignal) {
+  return ResultAsync.fromPromise(
+    fetch(`/api/users/${id}`, { signal }).then((r) => r.json()),
+    (err) => new ApiFault({ status: 500 }),
+  );
+}
+
+const retry = new Retry.Policy({
+  schedule: Schedule.exponential(200).pipe(Schedule.recurs(3)),
+});
+
+const result = Timeout.wrap(
+  (signal) => retry.execute((s) => fetchUser('123', s)),
+  5000,
+);
+
+await result.match({
+  ok: (user) => console.log(user),
+  err: (fault) => console.error(fault.code, fault.message),
+});
+```
+
+## Modules
+
+| Import | Description |
+|--------|-------------|
+| `clutchit/unthrow` | `Result<T, E>`, `ResultAsync<T, E>`, `Fault`, Do notation |
+| `clutchit/schedule` | Composable timing schedules (exponential, linear, fibonacci, cron, ...) |
+| `clutchit/retry` | Retry policies with configurable backoff and cancellation |
+| `clutchit/timeout` | Timeout wrappers with `AbortSignal` propagation |
+| `clutchit/concurrency` | Semaphore, RateLimiter, Bulkhead, Ref |
+| `clutchit/circuit` | Circuit breaker with progressive reset |
+| `clutchit/queue` | Bounded, Dropping, and Sliding queues with backpressure |
+
+---
+
+## `clutchit/unthrow`
+
+Typed error handling without exceptions. `Result<T, E>` for sync, `ResultAsync<T, E>` for async.
+
+### Result
+
+```typescript
+import { Result } from 'clutchit/unthrow';
+
+const ok = Result.ok(42);         // Ok<number, never>
+const fail = Result.err('oops');  // Err<never, string>
+
+ok.map((n) => n * 2);            // Ok(84)
+ok.andThen((n) => Result.ok(n)); // Ok(42)
+ok.unwrapOr(0);                  // 42
+fail.unwrapOr(0);                // 0
+
+ok.match({
+  ok: (value) => `got ${value}`,
+  err: (error) => `failed: ${error}`,
+});
+```
+
+Methods: `map`, `mapErr`, `andThen`, `orElse`, `unwrapOr`, `match`, `isOk`, `isErr`
+
+### ResultAsync
+
+Wraps `Promise<Result<T, E>>` with the same chainable methods. Awaitable via `PromiseLike`.
+
+```typescript
+import { ResultAsync } from 'clutchit/unthrow';
+
+const result = ResultAsync.fromPromise(
+  fetch('/api/data').then((r) => r.json()),
+  (err) => ({ code: 'FETCH_FAILED', message: String(err) }),
+);
+
+const final = result
+  .map((data) => data.items)
+  .andThen((items) => validateItems(items))
+  .mapErr((err) => normalize(err));
+```
+
+### Helpers
+
+```typescript
+import { Result, ResultAsync } from 'clutchit/unthrow';
+
+// Wrap a throwable sync function
+Result.fromThrowable(() => JSON.parse(raw), (err) => ParseFault(String(err)));
+
+// Combine results — fail on first error
+Result.combine([resultA, resultB, resultC]);      // Result<[A, B, C], E>
+ResultAsync.combine([asyncA, asyncB]);             // ResultAsync<[A, B], E>
+
+// Combine results — accumulate all errors
+Result.combineWithAllErrors([resultA, resultB]);   // Result<[A, B], E[]>
+```
+
+### Do Notation
+
+Generator-based monadic syntax. Yields unwrap `Ok` values; any `Err` short-circuits.
+
+```typescript
+import { Result, ResultAsync } from 'clutchit/unthrow';
+
+// Sync
+const result = Result.Do(function* () {
+  const user = yield* findUser(id);
+  const perms = yield* getPermissions(user);
+  return { user, perms };
+});
+// Result<{ user: User; perms: Permissions }, NotFoundFault | PermissionFault>
+
+// Async
+const result = ResultAsync.Do(async function* () {
+  const user = yield* findUser(id);
+  const order = yield* createOrder(user, items);
+  yield* sendConfirmation(order);
+  return order;
+});
+```
+
+---
+
+## `clutchit/schedule`
+
+Composable timing primitive. Determines delay and continuation for each attempt. Used internally by retry and circuit breaker — also useful standalone.
+
+### Factories
+
+```typescript
+import { Schedule } from 'clutchit/schedule';
+
+Schedule.spaced(1000);              // Fixed 1s delay
+Schedule.exponential(200);          // 200, 400, 800, 1600, ...
+Schedule.exponential(200, 3);       // 200, 600, 1800, ... (custom multiplier)
+Schedule.linear(100);               // 100, 200, 300, 400, ...
+Schedule.fibonacci(100);            // 100, 100, 200, 300, 500, ...
+Schedule.constant(5000);            // Alias for spaced
+Schedule.fixed(1000);               // Fixed 1s intervals (compensates for execution time)
+Schedule.windowed(60_000);          // Aligned to wall-clock minute boundaries
+Schedule.cron('*/5 * * * *');       // Every 5 minutes (cron expression)
+Schedule.cron('0 4 * * MON-FRI', { timezone: 'UTC' }); // 4am weekdays UTC
+Schedule.forever;                   // Zero-delay, never stops
+Schedule.once;                      // Single attempt then stop
+```
+
+### Operators
+
+Compose via `.pipe()`:
+
+```typescript
+const schedule = Schedule.exponential(200)
+  .pipe(Schedule.recurs(5))           // Max 5 attempts
+  .pipe(Schedule.cappedDelay(10_000)) // Cap at 10s
+  .pipe(Schedule.jittered())          // +/- 25% random jitter
+  .pipe(Schedule.upTo(60_000));       // Stop after 60s total
+```
+
+| Operator | Description |
+|----------|-------------|
+| `recurs(n)` | Limit to `n` total attempts |
+| `cappedDelay(ms)` | Cap individual delay |
+| `jittered(factor?)` | Random jitter (default +/- 25%) |
+| `upTo(ms)` | Stop after total elapsed time |
+| `andThen(schedule)` | Run first schedule, then second |
+| `union(schedule)` | Shorter delay wins, either continues |
+| `intersect(schedule)` | Longer delay wins, both must continue |
+| `whileInput(pred)` | Continue while input matches |
+| `whileOutput(pred)` | Continue while output matches |
+| `map(fn)` | Transform schedule output |
+
+### Repeat
+
+Execute a function repeatedly on a schedule:
+
+```typescript
+const schedule = Schedule.spaced(5000).pipe(Schedule.recurs(10));
+
+await Schedule.repeat(
+  schedule,
+  (signal) => pollForUpdates(signal),
+  { signal: controller.signal },
+);
+```
+
+Returns `ScheduleInterruptedFault` if cancelled via signal.
+
+---
+
+## `clutchit/retry`
+
+Retry policies with configurable backoff, error filtering, and cancellation.
+
+```typescript
+import { Retry } from 'clutchit/retry';
+import { Schedule } from 'clutchit/schedule';
+
+const policy = new Retry.Policy({
+  schedule: Schedule.exponential(200).pipe(Schedule.recurs(3)),
+  retryOn: (error) => Fault.isTransient(error),
+  onRetry: (error, attempt, delay) => {
+    console.log(`Retry #${attempt} in ${delay}ms: ${error.code}`);
+  },
+});
+
+const result = policy.execute((signal) => fetchData(signal));
+```
+
+### RetryOptions
+
+| Option | Type | Default |
+|--------|------|---------|
+| `schedule` | `Schedule` | `exponential(200) \| recurs(3)` |
+| `retryOn` | `(error: E) => boolean` | Retries transient errors (`_transient === true`) |
+| `onRetry` | `(error, attempt, delay) => void` | — |
+| `signal` | `AbortSignal` | — |
+
+Per-call options override constructor defaults.
+
+---
+
+## `clutchit/timeout`
+
+Wrap async operations with a timeout. Propagates cancellation via `AbortSignal`.
+
+```typescript
+import { Timeout } from 'clutchit/timeout';
+
+// Inline
+const result = Timeout.wrap(
+  (signal) => fetchData(signal),
+  5000,
+);
+// ResultAsync<Data, FetchFault | TimeoutFault>
+
+// Reusable wrapper
+const withTimeout = Timeout.create(5000);
+const result = withTimeout((signal) => fetchData(signal));
+```
+
+`TimeoutFault` is `transient: true` — it will be retried by default when composed with `Retry.Policy`.
+
+---
+
+## `clutchit/concurrency`
+
+### Semaphore
+
+Limit concurrent access to a resource:
+
+```typescript
+import { Concurrency } from 'clutchit/concurrency';
+
+const sem = new Concurrency.Semaphore({ permits: 3 });
+
+const result = sem.execute(() => fetchData());
+
+sem.available; // remaining permits
+sem.waiting;   // queued requests
+```
+
+### RateLimiter
+
+Sliding-window rate limiting:
+
+```typescript
+const limiter = new Concurrency.RateLimiter({
+  limit: 100,
+  window: 60_000, // 100 requests per minute
+});
+
+const result = limiter.execute(() => callApi());
+// Err(RateLimitFault) if limit exceeded
+
+limiter.remaining; // available capacity
+```
+
+`RateLimitFault` is `transient: true` with a `retryAfter` field.
+
+### Bulkhead
+
+Isolate failures by limiting concurrent executions with an optional queue:
+
+```typescript
+const bulkhead = new Concurrency.Bulkhead({
+  concurrency: 5,
+  queue: 10, // default: 0
+});
+
+const result = bulkhead.execute(() => processRequest());
+// Err(BulkheadRejectedFault) if capacity + queue full
+
+bulkhead.activeCount; // currently executing
+bulkhead.queueSize;   // waiting in queue
+```
+
+### Ref
+
+Thread-safe mutable reference (atomic via internal mutex):
+
+```typescript
+const counter = new Concurrency.Ref(0);
+
+await counter.update((n) => n + 1);
+await counter.set(0);
+
+const prev = await counter.modify((n) => [n + 1, n]); // [newValue, result]
+counter.get(); // current value (non-atomic read)
+```
+
+---
+
+## `clutchit/circuit`
+
+Circuit breaker with three states: **closed** (normal), **open** (rejecting), **half-open** (testing recovery).
+
+```typescript
+import { Circuit } from 'clutchit/circuit';
+import { Schedule } from 'clutchit/schedule';
+
+const breaker = new Circuit.Breaker({
+  failureThreshold: 5,
+  resetSchedule: Schedule.exponential(30_000).pipe(Schedule.cappedDelay(300_000)),
+  halfOpenAttempts: 1,
+  isFailure: (error) => error.code !== 'NOT_FOUND',
+  onStateChange: (from, to) => console.log(`Circuit: ${from} -> ${to}`),
+});
+
+const result = breaker.protect(() => callService());
+// Err(CircuitOpenFault) when circuit is open
+
+breaker.state;        // 'closed' | 'open' | 'half-open'
+breaker.failureCount; // consecutive failures
+breaker.reset();      // force-close
+```
+
+### State Machine
+
+```
+CLOSED ──(failures >= threshold)──> OPEN
+OPEN   ──(reset delay expires)───> HALF-OPEN
+HALF-OPEN ──(success)────────────> CLOSED
+HALF-OPEN ──(failure)────────────> OPEN (progressive delay increase)
+```
+
+### CircuitBreakerOptions
+
+| Option | Type | Default |
+|--------|------|---------|
+| `failureThreshold` | `number` | `5` |
+| `resetSchedule` | `Schedule` | `constant(30_000)` |
+| `halfOpenAttempts` | `number` | `1` |
+| `isFailure` | `(error) => boolean` | All errors count |
+| `onStateChange` | `(from, to) => void` | — |
+
+---
+
+## `clutchit/queue`
+
+In-memory bounded queues with backpressure. All blocking operations support `AbortSignal`.
+
+### BoundedQueue
+
+Both producers and consumers can block:
+
+```typescript
+import { Queue } from 'clutchit/queue';
+
+const q = new Queue.Bounded<Job>({ capacity: 100 });
+
+q.offer(job);                        // Result<void, QueueFullFault> — non-blocking
+await q.put(job);                    // blocks until space 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<T, QueueEmptyFault> — non-blocking
+```
+
+### DroppingQueue
+
+Drops the **newest** item when full. Producer never blocks:
+
+```typescript
+const q = new Queue.Dropping<Event>({ capacity: 1000 });
+
+q.offer(event); // boolean — true if accepted, false if dropped
+```
+
+### SlidingQueue
+
+Drops the **oldest** item when full. Producer never blocks:
+
+```typescript
+const q = new Queue.Sliding<Event>({ capacity: 1000 });
+
+q.offer(event); // void — always accepts, evicts oldest if needed
+```
+
+---
+
+## Fault Model
+
+Faults are classes created via `Fault.Tagged(code, category, transient?)`. Each class serves as both a value (constructor) and a type — no separate `type X = ReturnType<typeof X>` needed. Discriminated via `code` string literal and `instanceof`.
+
+### Defining Faults
+
+```typescript
+import { Fault } from 'clutchit/unthrow';
+
+// Domain fault with fields
+class NotFoundFault extends Fault.Tagged('NOT_FOUND', 'domain')<{
+  resource: string;
+  id: string;
+}>() {
+  readonly message = `${this.resource} "${this.id}" not found`;
+}
+
+// Infrastructure fault, no fields
+class ServiceDownFault extends Fault.Tagged('SERVICE_DOWN', 'infrastructure')() {
+  readonly message = 'Service is unavailable';
+}
+
+// Transient fault (eligible for automatic retry)
+class TimeoutFault extends Fault.Tagged('TIMEOUT', 'infrastructure', true)<{
+  duration: number;
+}>() {
+  readonly message = `Operation timed out after ${this.duration}ms`;
+}
+
+// Usage
+const fault = new NotFoundFault({ resource: 'User', id: '123' });
+fault.code;      // 'NOT_FOUND'
+fault.resource;  // 'User'
+fault instanceof NotFoundFault; // true
+```
+
+### Categories
+
+| Category | `_category` | `_transient` | Meaning |
+|----------|------------|-------------|---------|
+| Domain | `'domain'` | `false` | Business rule violation — not retryable |
+| Infrastructure | `'infrastructure'` | `false` | System failure — not retryable |
+| Transient | `'infrastructure'` | `true` | Temporary failure — safe to retry |
+
+### Type Guards
+
+```typescript
+Fault.isTransient(fault);       // infrastructure + transient
+Fault.isDomain(fault);          // domain fault
+Fault.isInfrastructure(fault);  // infrastructure (transient or not)
+```
+
+### Built-in Faults
+
+| Fault | Code | Transient | Module |
+|-------|------|-----------|--------|
+| `TimeoutFault` | `TIMEOUT` | yes | `clutchit/timeout` |
+| `RateLimitFault` | `RATE_LIMITED` | yes | `clutchit/concurrency` |
+| `CircuitOpenFault` | `CIRCUIT_OPEN` | no | `clutchit/circuit` |
+| `BulkheadRejectedFault` | `BULKHEAD_REJECTED` | no | `clutchit/concurrency` |
+| `ScheduleInterruptedFault` | `SCHEDULE_INTERRUPTED` | no | `clutchit/schedule` |
+| `QueueFullFault` | `QUEUE_FULL` | no | `clutchit/queue` |
+| `QueueEmptyFault` | `QUEUE_EMPTY` | no | `clutchit/queue` |
+
+---
+
+## Composing Primitives
+
+Retry, timeout, and circuit breaker compose naturally:
+
+```typescript
+import { Retry } from 'clutchit/retry';
+import { Timeout } from 'clutchit/timeout';
+import { Circuit } from 'clutchit/circuit';
+import { Schedule } from 'clutchit/schedule';
+
+const retry = new Retry.Policy({
+  schedule: Schedule.exponential(200).pipe(
+    Schedule.recurs(3),
+    Schedule.cappedDelay(5000),
+    Schedule.jittered(),
+  ),
+});
+
+const breaker = new Circuit.Breaker({
+  failureThreshold: 5,
+  resetSchedule: Schedule.exponential(30_000),
+});
+
+function callService() {
+  return breaker.protect(() =>
+    Timeout.wrap(
+      (signal) => retry.execute(
+        (signal) => doRequest(signal),
+      ),
+      10_000,
+    ),
+  );
+}
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/circuit/{circuit-breaker.d.ts → circuit.breaker.d.ts}

@@ -1,16 +1,19 @@
 import { ResultAsync } from '../unthrow/index.js';
 import { Schedule } from '../schedule/index.js';
 export type CircuitState = 'closed' | 'open' | 'half-open';
-export declare const CircuitOpenFault: (remainingTimeout: number) => Readonly<{
-    code: "CIRCUIT_OPEN";
-    _category: "infrastructure";
-    _transient: false;
-    message: string;
-} & Omit<{
-    message: string;
+declare const CircuitOpenFault_base: abstract new (fields: {
     remainingTimeout: number;
-}, "message">>;
-export type CircuitOpenFault = ReturnType<typeof CircuitOpenFault>;
+}) => Readonly<{
+    remainingTimeout: number;
+}> & {
+    readonly code: "CIRCUIT_OPEN";
+    readonly _category: "infrastructure";
+    readonly _transient: false;
+    readonly message: string;
+};
+export declare class CircuitOpenFault extends CircuitOpenFault_base {
+    readonly message: string;
+}
 export interface CircuitBreakerOptions {
     /** Number of consecutive failures before opening. Default: 5 */
     failureThreshold?: number;
@@ -44,4 +47,5 @@ export declare class CircuitBreaker {
     private scheduleReset;
     private transition;
 }
-//# sourceMappingURL=circuit-breaker.d.ts.map
+export {};
+//# sourceMappingURL=circuit.breaker.d.ts.map

package/dist/circuit/{circuit-breaker.js → circuit.breaker.js}

@@ -1,13 +1,8 @@
 import { Fault, ResultAsync } from '../unthrow/index.js';
 import { Schedule } from '../schedule/index.js';
-export const CircuitOpenFault = Fault.define({
-    code: 'CIRCUIT_OPEN',
-    category: 'infrastructure',
-    create: (remainingTimeout) => ({
-        message: `Circuit breaker is open. Retry after ${remainingTimeout}ms`,
-        remainingTimeout,
-    }),
-});
+export class CircuitOpenFault extends Fault.Tagged('CIRCUIT_OPEN', 'infrastructure')() {
+    message = `Circuit breaker is open. Retry after ${this.remainingTimeout}ms`;
+}
 export class CircuitBreaker {
     _state = 'closed';
     _failureCount = 0;
@@ -33,15 +28,15 @@ export class CircuitBreaker {
                 this._halfOpenTrials = 0;
             }
             else {
-                const remaining = this._nextResetTime
+                const remainingTimeout = this._nextResetTime
                     ? Math.max(0, this._nextResetTime - Date.now())
                     : 0;
-                return ResultAsync.err(CircuitOpenFault(remaining));
+                return ResultAsync.err(new CircuitOpenFault({ remainingTimeout }));
             }
         }
         if (this._state === 'half-open') {
             if (this._halfOpenTrials >= this._maxHalfOpenAttempts) {
-                return ResultAsync.err(CircuitOpenFault(0));
+                return ResultAsync.err(new CircuitOpenFault({ remainingTimeout: 0 }));
             }
             this._halfOpenTrials++;
         }
@@ -111,4 +106,4 @@ export class CircuitBreaker {
         }
     }
 }
-//# sourceMappingURL=circuit-breaker.js.map
+//# sourceMappingURL=circuit.breaker.js.map

package/dist/circuit/index.d.ts

@@ -1,7 +1,10 @@
-import { CircuitBreaker as _CircuitBreaker } from './circuit-breaker.js';
-export type { CircuitState, CircuitBreakerOptions } from './circuit-breaker.js';
-export type { CircuitOpenFault } from './circuit-breaker.js';
+import { CircuitBreaker } from './circuit.breaker.js';
+import type { CircuitState, CircuitBreakerOptions } from './circuit.breaker.js';
+export { CircuitOpenFault } from './circuit.breaker.js';
 export declare namespace Circuit {
-    const Breaker: typeof _CircuitBreaker;
+    const Breaker: typeof CircuitBreaker;
+    type Breaker = CircuitBreaker;
+    type BreakerOptions = CircuitBreakerOptions;
+    type State = CircuitState;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/circuit/index.js

@@ -1,7 +1,8 @@
-import { CircuitBreaker as _CircuitBreaker } from './circuit-breaker.js';
+import { CircuitBreaker } from './circuit.breaker.js';
+export { CircuitOpenFault } from './circuit.breaker.js';
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export var Circuit;
 (function (Circuit) {
-    Circuit.Breaker = _CircuitBreaker;
+    Circuit.Breaker = CircuitBreaker;
 })(Circuit || (Circuit = {}));
 //# sourceMappingURL=index.js.map

package/dist/concurrency/bulkhead.d.ts

@@ -1,13 +1,13 @@
 import { ResultAsync } from '../unthrow/index.js';
-export declare const BulkheadRejectedFault: () => Readonly<{
-    code: "BULKHEAD_REJECTED";
-    _category: "infrastructure";
-    _transient: false;
-    message: string;
-} & Omit<{
-    message: string;
-}, "message">>;
-export type BulkheadRejectedFault = ReturnType<typeof BulkheadRejectedFault>;
+declare const BulkheadRejectedFault_base: abstract new () => Readonly<Record<string, unknown>> & {
+    readonly code: "BULKHEAD_REJECTED";
+    readonly _category: "infrastructure";
+    readonly _transient: false;
+    readonly message: string;
+};
+export declare class BulkheadRejectedFault extends BulkheadRejectedFault_base {
+    readonly message = "Bulkhead capacity exceeded";
+}
 export interface BulkheadOptions {
     concurrency: number;
     queue?: number;
@@ -24,4 +24,5 @@ export declare class Bulkhead {
     private acquire;
     private release;
 }
+export {};
 //# sourceMappingURL=bulkhead.d.ts.map

package/dist/concurrency/bulkhead.js

@@ -1,11 +1,7 @@
 import { Fault, ResultAsync } from '../unthrow/index.js';
-export const BulkheadRejectedFault = Fault.define({
-    code: 'BULKHEAD_REJECTED',
-    category: 'infrastructure',
-    create: () => ({
-        message: 'Bulkhead capacity exceeded',
-    }),
-});
+export class BulkheadRejectedFault extends Fault.Tagged('BULKHEAD_REJECTED', 'infrastructure')() {
+    message = 'Bulkhead capacity exceeded';
+}
 export class Bulkhead {
     _active = 0;
     _maxConcurrency;
@@ -18,7 +14,7 @@ export class Bulkhead {
     execute(fn) {
         if (this._active >= this._maxConcurrency &&
             this._queue.length >= this._maxQueue) {
-            return ResultAsync.err(BulkheadRejectedFault());
+            return ResultAsync.err(new BulkheadRejectedFault());
         }
         return ResultAsync.fromPromise((async () => {
             await this.acquire();