clutchit 0.0.3 → 0.0.5

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

@@ -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;
 }
+export {};
 //# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/circuit/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++;
         }

package/dist/circuit/index.d.ts

@@ -1,6 +1,6 @@
 import { CircuitBreaker as _CircuitBreaker } from './circuit-breaker.js';
 export type { CircuitState, CircuitBreakerOptions } from './circuit-breaker.js';
-export type { CircuitOpenFault } from './circuit-breaker.js';
+export { CircuitOpenFault } from './circuit-breaker.js';
 export declare namespace Circuit {
     const Breaker: typeof _CircuitBreaker;
 }

package/dist/circuit/index.js

@@ -1,4 +1,5 @@
 import { CircuitBreaker as _CircuitBreaker } from './circuit-breaker.js';
+export { CircuitOpenFault } from './circuit-breaker.js';
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export var Circuit;
 (function (Circuit) {

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();

package/dist/concurrency/index.d.ts

@@ -4,9 +4,9 @@ import { Bulkhead as _Bulkhead } from './bulkhead.js';
 import { Ref as _Ref } from './ref.js';
 export type { SemaphoreOptions } from './semaphore.js';
 export type { RateLimiterOptions } from './rate-limiter.js';
-export type { RateLimitFault } from './rate-limiter.js';
+export { RateLimitFault } from './rate-limiter.js';
 export type { BulkheadOptions } from './bulkhead.js';
-export type { BulkheadRejectedFault } from './bulkhead.js';
+export { BulkheadRejectedFault } from './bulkhead.js';
 export declare namespace Concurrency {
     const Semaphore: typeof _Semaphore;
     const RateLimiter: typeof _RateLimiter;

package/dist/concurrency/index.js

@@ -2,6 +2,8 @@ import { Semaphore as _Semaphore } from './semaphore.js';
 import { RateLimiter as _RateLimiter } from './rate-limiter.js';
 import { Bulkhead as _Bulkhead } from './bulkhead.js';
 import { Ref as _Ref } from './ref.js';
+export { RateLimitFault } from './rate-limiter.js';
+export { BulkheadRejectedFault } from './bulkhead.js';
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export var Concurrency;
 (function (Concurrency) {

package/dist/concurrency/rate-limiter.d.ts

@@ -1,14 +1,17 @@
 import { ResultAsync } from '../unthrow/index.js';
-export declare const RateLimitFault: (retryAfter: number) => Readonly<{
-    code: "RATE_LIMITED";
-    _category: "infrastructure";
-    _transient: true;
-    message: string;
-} & Omit<{
-    message: string;
+declare const RateLimitFault_base: abstract new (fields: {
     retryAfter: number;
-}, "message">>;
-export type RateLimitFault = ReturnType<typeof RateLimitFault>;
+}) => Readonly<{
+    retryAfter: number;
+}> & {
+    readonly code: "RATE_LIMITED";
+    readonly _category: "infrastructure";
+    readonly _transient: true;
+    readonly message: string;
+};
+export declare class RateLimitFault extends RateLimitFault_base {
+    readonly message: string;
+}
 export interface RateLimiterOptions {
     limit: number;
     window: number;
@@ -22,4 +25,5 @@ export declare class RateLimiter {
     get remaining(): number;
     private cleanup;
 }
+export {};
 //# sourceMappingURL=rate-limiter.d.ts.map

package/dist/concurrency/rate-limiter.js

@@ -1,13 +1,7 @@
 import { Fault, ResultAsync } from '../unthrow/index.js';
-export const RateLimitFault = Fault.define({
-    code: 'RATE_LIMITED',
-    category: 'infrastructure',
-    transient: true,
-    create: (retryAfter) => ({
-        message: `Rate limit exceeded. Retry after ${retryAfter}ms`,
-        retryAfter,
-    }),
-});
+export class RateLimitFault extends Fault.Tagged('RATE_LIMITED', 'infrastructure', true)() {
+    message = `Rate limit exceeded. Retry after ${this.retryAfter}ms`;
+}
 export class RateLimiter {
     _limit;
     _window;
@@ -21,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(RateLimitFault(retryAfter));
+            return ResultAsync.err(new RateLimitFault({ retryAfter }));
         }
         this._timestamps.push(Date.now());
         return fn();

package/dist/queue/base.queue.js

@@ -11,7 +11,7 @@ export class BaseQueue {
         if (this._buffer.length > 0) {
             return Result.ok(this._buffer.shift());
         }
-        return Result.err(QueueEmptyFault());
+        return Result.err(new QueueEmptyFault());
     }
     take(signal) {
         const taken = this._tryTake();

package/dist/queue/bounded.queue.d.ts

@@ -4,8 +4,8 @@ import { BaseQueue, type QueueOptions } from './base.queue.js';
 export declare class BoundedQueue<T> extends BaseQueue<T> {
     private readonly _putWaiters;
     constructor(options: QueueOptions);
-    protected _tryTake(): Result<T, ReturnType<typeof QueueEmptyFault>>;
-    offer(item: T): Result<void, ReturnType<typeof QueueFullFault>>;
+    protected _tryTake(): Result<T, QueueEmptyFault>;
+    offer(item: T): Result<void, QueueFullFault>;
     put(item: T, signal?: AbortSignal): ResultAsync<void, never>;
 }
 //# sourceMappingURL=bounded.queue.d.ts.map

package/dist/queue/bounded.queue.js

@@ -23,7 +23,7 @@ export class BoundedQueue extends BaseQueue {
             pw.resolve();
             return Result.ok(pw.item);
         }
-        return Result.err(QueueEmptyFault());
+        return Result.err(new QueueEmptyFault());
     }
     offer(item) {
         // Give directly to a waiting consumer
@@ -33,7 +33,7 @@ export class BoundedQueue extends BaseQueue {
             return Result.ok(undefined);
         }
         if (this._buffer.length >= this._capacity) {
-            return Result.err(QueueFullFault(this._capacity));
+            return Result.err(new QueueFullFault({ capacity: this._capacity }));
         }
         this._buffer.push(item);
         return Result.ok(undefined);

package/dist/queue/faults.d.ts

@@ -1,20 +1,24 @@
-export declare const QueueFullFault: (capacity: number) => Readonly<{
-    code: "QUEUE_FULL";
-    _category: "infrastructure";
-    _transient: false;
-    message: string;
-} & Omit<{
-    message: string;
+declare const QueueFullFault_base: abstract new (fields: {
     capacity: number;
-}, "message">>;
-export type QueueFullFault = ReturnType<typeof QueueFullFault>;
-export declare const QueueEmptyFault: () => Readonly<{
-    code: "QUEUE_EMPTY";
-    _category: "infrastructure";
-    _transient: false;
-    message: string;
-} & Omit<{
-    message: string;
-}, "message">>;
-export type QueueEmptyFault = ReturnType<typeof QueueEmptyFault>;
+}) => Readonly<{
+    capacity: number;
+}> & {
+    readonly code: "QUEUE_FULL";
+    readonly _category: "infrastructure";
+    readonly _transient: false;
+    readonly message: string;
+};
+export declare class QueueFullFault extends QueueFullFault_base {
+    readonly message: string;
+}
+declare const QueueEmptyFault_base: abstract new () => Readonly<Record<string, unknown>> & {
+    readonly code: "QUEUE_EMPTY";
+    readonly _category: "infrastructure";
+    readonly _transient: false;
+    readonly message: string;
+};
+export declare class QueueEmptyFault extends QueueEmptyFault_base {
+    readonly message = "Queue is empty";
+}
+export {};
 //# sourceMappingURL=faults.d.ts.map

package/dist/queue/faults.js

@@ -1,17 +1,8 @@
 import { Fault } from '../unthrow/index.js';
-export const QueueFullFault = Fault.define({
-    code: 'QUEUE_FULL',
-    category: 'infrastructure',
-    create: (capacity) => ({
-        message: `Queue is full (capacity: ${capacity})`,
-        capacity,
-    }),
-});
-export const QueueEmptyFault = Fault.define({
-    code: 'QUEUE_EMPTY',
-    category: 'infrastructure',
-    create: () => ({
-        message: 'Queue is empty',
-    }),
-});
+export class QueueFullFault extends Fault.Tagged('QUEUE_FULL', 'infrastructure')() {
+    message = `Queue is full (capacity: ${this.capacity})`;
+}
+export class QueueEmptyFault extends Fault.Tagged('QUEUE_EMPTY', 'infrastructure')() {
+    message = 'Queue is empty';
+}
 //# sourceMappingURL=faults.js.map

package/dist/queue/index.d.ts

@@ -2,7 +2,7 @@ import { BoundedQueue as _BoundedQueue } from './bounded.queue.js';
 import { DroppingQueue as _DroppingQueue } from './dropping.queue.js';
 import { SlidingQueue as _SlidingQueue } from './sliding.queue.js';
 export type { QueueOptions } from './base.queue.js';
-export type { QueueFullFault, QueueEmptyFault } from './faults.js';
+export { QueueFullFault, QueueEmptyFault } from './faults.js';
 export declare namespace Queue {
     const Bounded: typeof _BoundedQueue;
     const Dropping: typeof _DroppingQueue;

package/dist/queue/index.js

@@ -1,6 +1,7 @@
 import { BoundedQueue as _BoundedQueue } from './bounded.queue.js';
 import { DroppingQueue as _DroppingQueue } from './dropping.queue.js';
 import { SlidingQueue as _SlidingQueue } from './sliding.queue.js';
+export { QueueFullFault, QueueEmptyFault } from './faults.js';
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export var Queue;
 (function (Queue) {

package/dist/schedule/index.d.ts

@@ -15,6 +15,9 @@ export declare namespace Schedule {
     const forever: ScheduleClass<unknown, number>;
     const once: ScheduleClass<unknown, number>;
     const fibonacci: (one: number) => ScheduleClass;
+    const cron: (expression: string, options?: {
+        timezone?: string;
+    }) => ScheduleClass;
     const recurs: typeof _recurs;
     const cappedDelay: typeof _cappedDelay;
     const jittered: typeof _jittered;

package/dist/schedule/index.js

@@ -14,6 +14,7 @@ export var Schedule;
     Schedule.forever = ScheduleClass.forever;
     Schedule.once = ScheduleClass.once;
     Schedule.fibonacci = ScheduleClass.fibonacci;
+    Schedule.cron = ScheduleClass.cron;
     Schedule.recurs = _recurs;
     Schedule.cappedDelay = _cappedDelay;
     Schedule.jittered = _jittered;

package/dist/schedule/runner.d.ts

@@ -1,14 +1,14 @@
 import { ResultAsync } from '../unthrow/index.js';
 import type { Schedule } from './schedule.js';
-export declare const ScheduleInterruptedFault: () => Readonly<{
-    code: "SCHEDULE_INTERRUPTED";
-    _category: "infrastructure";
-    _transient: false;
-    message: string;
-} & Omit<{
-    message: string;
-}, "message">>;
-export type ScheduleInterruptedFault = ReturnType<typeof ScheduleInterruptedFault>;
+declare const ScheduleInterruptedFault_base: abstract new () => Readonly<Record<string, unknown>> & {
+    readonly code: "SCHEDULE_INTERRUPTED";
+    readonly _category: "infrastructure";
+    readonly _transient: false;
+    readonly message: string;
+};
+export declare class ScheduleInterruptedFault extends ScheduleInterruptedFault_base {
+    readonly message = "Scheduled execution was interrupted";
+}
 export interface RepeatOptions {
     /** External cancellation signal. Aborts the loop when signalled. */
     signal?: AbortSignal;
@@ -27,4 +27,5 @@ export interface RepeatOptions {
  * Returns the last schedule output on completion.
  */
 export declare function repeat<Out, E>(schedule: Schedule<unknown, Out>, fn: (signal: AbortSignal) => ResultAsync<void, E>, options?: RepeatOptions): ResultAsync<Out, E | ScheduleInterruptedFault>;
+export {};
 //# sourceMappingURL=runner.d.ts.map

package/dist/schedule/runner.js

@@ -1,11 +1,7 @@
 import { Fault, ResultAsync } from '../unthrow/index.js';
-export const ScheduleInterruptedFault = Fault.define({
-    code: 'SCHEDULE_INTERRUPTED',
-    category: 'infrastructure',
-    create: () => ({
-        message: 'Scheduled execution was interrupted',
-    }),
-});
+export class ScheduleInterruptedFault extends Fault.Tagged('SCHEDULE_INTERRUPTED', 'infrastructure')() {
+    message = 'Scheduled execution was interrupted';
+}
 const NEVER_ABORT = new AbortController().signal;
 function sleep(ms, signal) {
     return new Promise((resolve) => {
@@ -38,7 +34,7 @@ export function repeat(schedule, fn, options) {
         for (let attempt = 0;; attempt++) {
             // eslint-disable-next-line @typescript-eslint/only-throw-error -- intentional: fromPromise catches and maps E
             if (signal?.aborted)
-                throw ScheduleInterruptedFault();
+                throw new ScheduleInterruptedFault();
             const result = await fn(signal ?? NEVER_ABORT);
             // eslint-disable-next-line @typescript-eslint/only-throw-error -- intentional: fromPromise catches and maps E
             if (result.isErr())
@@ -50,7 +46,7 @@ export function repeat(schedule, fn, options) {
             await sleep(step.delay, signal);
             // eslint-disable-next-line @typescript-eslint/only-throw-error -- intentional: fromPromise catches and maps E
             if (signal?.aborted)
-                throw ScheduleInterruptedFault();
+                throw new ScheduleInterruptedFault();
         }
     })(), (e) => e);
 }

package/dist/schedule/schedule.d.ts

@@ -27,5 +27,9 @@ export declare class Schedule<In = unknown, Out = number> {
     static once: Schedule;
     /** Fibonacci delay sequence: one, one, 2*one, 3*one, 5*one, 8*one, ... */
     static fibonacci: (one: number) => Schedule;
+    /** Cron expression schedule (aligned to cron windows) */
+    static cron: (expression: string, options?: {
+        timezone?: string;
+    }) => Schedule;
 }
 //# sourceMappingURL=schedule.d.ts.map

package/dist/schedule/schedule.js

@@ -1,3 +1,4 @@
+import { Cron } from 'croner';
 export class Schedule {
     _next;
     constructor(_next) {
@@ -90,5 +91,16 @@ export class Schedule {
             return { delay, continue: true, output: attempt };
         });
     };
+    /** Cron expression schedule (aligned to cron windows) */
+    static cron = (expression, options) => {
+        const pattern = new Cron(expression, options?.timezone ? { timezone: options.timezone } : undefined);
+        return new Schedule((_input, attempt) => {
+            const next = pattern.nextRun();
+            if (!next)
+                return { delay: 0, continue: false, output: attempt };
+            const delay = Math.max(0, next.getTime() - Date.now());
+            return { delay, continue: true, output: attempt };
+        });
+    };
 }
 //# sourceMappingURL=schedule.js.map

package/dist/timeout/index.d.ts

@@ -1,16 +1,8 @@
-import { withTimeout as _withTimeout, createTimeout as _createTimeout } from './timeout.js';
-export type { TimeoutFault } from './timeout.js';
+import { TimeoutFault as _TimeoutFault, withTimeout as _withTimeout, createTimeout as _createTimeout } from './timeout.js';
+export { TimeoutFault } from './timeout.js';
 export declare namespace Timeout {
     const wrap: typeof _withTimeout;
     const create: typeof _createTimeout;
-    const Fault: (duration: number) => Readonly<{
-        code: "TIMEOUT";
-        _category: "infrastructure";
-        _transient: true;
-        message: string;
-    } & Omit<{
-        message: string;
-        duration: number;
-    }, "message">>;
+    const Fault: typeof _TimeoutFault;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/timeout/index.js

@@ -1,4 +1,5 @@
 import { TimeoutFault as _TimeoutFault, withTimeout as _withTimeout, createTimeout as _createTimeout, } from './timeout.js';
+export { TimeoutFault } from './timeout.js';
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export var Timeout;
 (function (Timeout) {

package/dist/timeout/timeout.d.ts

@@ -1,14 +1,18 @@
 import { ResultAsync } from '../unthrow/index.js';
-export declare const TimeoutFault: (duration: number) => Readonly<{
-    code: "TIMEOUT";
-    _category: "infrastructure";
-    _transient: true;
-    message: string;
-} & Omit<{
-    message: string;
+declare const TimeoutFault_base: abstract new (fields: {
     duration: number;
-}, "message">>;
-export type TimeoutFault = ReturnType<typeof TimeoutFault>;
+}) => Readonly<{
+    duration: number;
+}> & {
+    readonly code: "TIMEOUT";
+    readonly _category: "infrastructure";
+    readonly _transient: true;
+    readonly message: string;
+};
+export declare class TimeoutFault extends TimeoutFault_base {
+    readonly message: string;
+}
 export declare function withTimeout<T, E>(fn: (signal: AbortSignal) => ResultAsync<T, E>, duration: number): ResultAsync<T, E | TimeoutFault>;
 export declare function createTimeout(duration: number): <T, E>(fn: (signal: AbortSignal) => ResultAsync<T, E>) => ResultAsync<T, E | TimeoutFault>;
+export {};
 //# sourceMappingURL=timeout.d.ts.map

package/dist/timeout/timeout.js

@@ -1,13 +1,7 @@
 import { Fault, ResultAsync } from '../unthrow/index.js';
-export const TimeoutFault = Fault.define({
-    code: 'TIMEOUT',
-    category: 'infrastructure',
-    transient: true,
-    create: (duration) => ({
-        message: `Operation timed out after ${duration}ms`,
-        duration,
-    }),
-});
+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(
@@ -15,7 +9,7 @@ export function withTimeout(fn, duration) {
     new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
             controller.abort();
-            reject(TimeoutFault(duration));
+            reject(new TimeoutFault({ duration }));
         }, duration);
         void fn(controller.signal).then((result) => {
             clearTimeout(timer);

package/dist/unthrow/fault.d.ts

@@ -4,34 +4,19 @@ export interface Fault {
     readonly _category: 'domain' | 'infrastructure';
     readonly _transient: boolean;
 }
-export type DomainFault = Fault & {
+export declare function isDomainFault(error: Fault): error is Fault & {
     readonly _category: 'domain';
-    readonly _transient: false;
 };
-export type InfrastructureFault = Fault & {
+export declare function isInfrastructureFault(error: Fault): error is Fault & {
     readonly _category: 'infrastructure';
 };
-export type TransientFault = InfrastructureFault & {
+export declare function isTransientFault(error: Fault): error is Fault & {
     readonly _transient: true;
 };
-export declare function isTransient(error: Fault): error is TransientFault;
-export declare function isDomainFault(error: Fault): error is DomainFault;
-export declare function isInfrastructureFault(error: Fault): error is InfrastructureFault;
-type InferTransient<O> = O extends {
-    transient: infer T extends boolean;
-} ? T : false;
-export declare function defineFault<const O extends {
-    code: string;
-    category: 'domain' | 'infrastructure';
-    transient?: boolean;
-    create: (...args: any[]) => {
-        message: string;
-    };
-}>(options: O): (...args: Parameters<O['create']>) => Readonly<{
-    code: O['code'];
-    _category: O['category'];
-    _transient: InferTransient<O>;
-    message: string;
-} & Omit<ReturnType<O['create']>, 'message'>>;
-export {};
+export declare function Fault<const Code extends string, const Category extends 'domain' | 'infrastructure', const Transient extends boolean = false>(code: Code, category: Category, transient?: Transient): <A extends Record<string, unknown> = Record<string, unknown>>() => abstract new (...args: Record<string, unknown> extends A ? [] : [fields: A]) => Readonly<A> & {
+    readonly code: Code;
+    readonly _category: Category;
+    readonly _transient: Transient;
+    readonly message: string;
+};
 //# sourceMappingURL=fault.d.ts.map

package/dist/unthrow/fault.js

@@ -1,22 +1,27 @@
-export function isTransient(error) {
-    return error._transient && error._category === 'infrastructure';
-}
 export function isDomainFault(error) {
     return error._category === 'domain';
 }
 export function isInfrastructureFault(error) {
     return error._category === 'infrastructure';
 }
-export function defineFault(options) {
-    const transient = (options.transient ?? false);
-    return (...args) => {
-        const extra = options.create(...args);
-        return Object.freeze({
-            code: options.code,
-            _category: options.category,
-            _transient: transient,
-            ...extra,
-        });
+export function isTransientFault(error) {
+    return error._transient && error._category === 'infrastructure';
+}
+export function Fault(code, category, transient) {
+    const _transient = (transient ?? false);
+    return () => {
+        class FaultImpl {
+            code = code;
+            _category = category;
+            _transient = _transient;
+            constructor(...args) {
+                const fields = args[0];
+                if (fields) {
+                    Object.assign(this, fields);
+                }
+            }
+        }
+        return FaultImpl;
     };
 }
 //# sourceMappingURL=fault.js.map

package/dist/unthrow/index.d.ts

@@ -1,8 +1,7 @@
 import { ResultAsync as ResultAsyncClass, okAsync, errAsync } from './result.async.js';
 import { DoAsync } from './do.js';
-import { defineFault, isDomainFault, isInfrastructureFault } from './fault.js';
+import { Fault as _Fault, isDomainFault as _isDomainFault, isInfrastructureFault as _isInfrastructureFault, isTransientFault as _isTransientFault } from './fault.js';
 export { Ok, Err } from './result.js';
-export type { DomainFault, InfrastructureFault, TransientFault, } from './fault.js';
 export type Result<T, E> = import('./result.js').Ok<T, E> | import('./result.js').Err<T, E>;
 type _Result<T, E> = Result<T, E>;
 export declare namespace Result {
@@ -24,9 +23,9 @@ export declare namespace ResultAsync {
 }
 export type Fault = import('./fault.js').Fault;
 export declare namespace Fault {
-    const define: typeof defineFault;
-    const isTransient: typeof import("./fault.js").isTransient;
-    const isDomain: typeof isDomainFault;
-    const isInfrastructure: typeof isInfrastructureFault;
+    const Tagged: typeof _Fault;
+    const isDomain: typeof _isDomainFault;
+    const isInfrastructure: typeof _isInfrastructureFault;
+    const isTransient: typeof _isTransientFault;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/unthrow/index.js

@@ -2,7 +2,7 @@ import { ok, err } from './result.js';
 import { okAsync, errAsync, } from './result.async.js';
 import { fromPromise, fromThrowable, combine as combineFn, combineWithAllErrors as combineWithAllErrorsFn, } from './helpers.js';
 import { Do, DoAsync } from './do.js';
-import { defineFault, isTransient, isDomainFault, isInfrastructureFault, } from './fault.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';
 // Internal aliases (must precede namespaces that reference them)
@@ -10,7 +10,6 @@ const _ok = ok;
 const _err = err;
 const _fromThrowable = fromThrowable;
 const _fromPromise = fromPromise;
-const _isTransient = isTransient;
 const _Do = Do;
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export var Result;
@@ -47,9 +46,9 @@ export var ResultAsync;
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export var Fault;
 (function (Fault) {
-    Fault.define = defineFault;
-    Fault.isTransient = _isTransient;
-    Fault.isDomain = isDomainFault;
-    Fault.isInfrastructure = isInfrastructureFault;
+    Fault.Tagged = _Fault;
+    Fault.isDomain = _isDomainFault;
+    Fault.isInfrastructure = _isInfrastructureFault;
+    Fault.isTransient = _isTransientFault;
 })(Fault || (Fault = {}));
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clutchit",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "",
   "author": {
     "name": "hexac",
@@ -94,6 +94,9 @@
     "node": ">=20",
     "bun": ">=1"
   },
+  "dependencies": {
+    "croner": "^10.0.1"
+  },
   "scripts": {
     "build": "rimraf dist && tsc -p tsconfig.build.json",
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",