@julr/tenace 1.0.0-next.0

package/README.md

@@ -0,0 +1,1034 @@
+# Tenace
+
+A fluent resilience library for Node.js. Make any async operation resilient with timeout, retry, circuit breaker, bulkhead, and more.
+
+## Installation
+
+```bash
+pnpm add @julr/tenace
+```
+
+### Imports
+
+```ts
+// Main entry point
+import { Tenace, Semaphore, configStore, backoff } from '@julr/tenace'
+
+// Error classes
+import { TimeoutError, CircuitOpenError, RateLimitError, ... } from '@julr/tenace/errors'
+
+// Type definitions
+import type { RetryConfig, CircuitState, ... } from '@julr/tenace/types'
+
+// Adapters (for cache, rate limiter, distributed lock)
+import { MemoryCacheAdapter, MemoryRateLimiterAdapter } from '@julr/tenace/adapters'
+import type { CacheAdapter, RateLimiterAdapter, LockAdapter } from '@julr/tenace/adapters'
+```
+
+## Quick Start
+
+```ts
+import { Tenace } from '@julr/tenace'
+
+// Without Tenace: hope for the best
+const user = await fetch('/api/users/1')
+
+// With Tenace: be resilient
+const user = await Tenace.call(() => fetch('/api/users/1'))
+  .withTimeout('5s')
+  .withRetry({ times: 3 })
+  .withFallback(() => ({ id: 1, name: 'Guest' }))
+  .execute()
+```
+
+## Understanding the Pipeline
+
+Tenace uses a **pipeline** system for policies. **The order you add policies = the order errors flow through them.**
+
+### The Golden Rule
+
+> **First added = Innermost layer (handles errors first)**
+> **Last added = Outermost layer (catches errors last)**
+
+Think of it like a pipeline: `fn → timeout → retry → fallback`
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  .withFallback()     ← 4th: Catches ALL errors (outermost) │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  .withRetry()     ← 3rd: Retries timeout errors       │  │
+│  │  ┌─────────────────────────────────────────────────┐  │  │
+│  │  │  .withTimeout()  ← 2nd: Timeout per attempt     │  │  │
+│  │  │  ┌───────────────────────────────────────────┐  │  │  │
+│  │  │  │  .withCircuitBreaker()  ← 1st: Tracks     │  │  │  │
+│  │  │  │  ┌─────────────────────────────────────┐  │  │  │  │
+│  │  │  │  │                                     │  │  │  │  │
+│  │  │  │  │          YOUR FUNCTION              │  │  │  │  │
+│  │  │  │  │                                     │  │  │  │  │
+│  │  │  │  └─────────────────────────────────────┘  │  │  │  │
+│  │  │  └───────────────────────────────────────────┘  │  │  │
+│  │  └─────────────────────────────────────────────────┘  │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Order Matters: Common Patterns
+
+#### Pattern 1: Timeout per attempt vs total timeout
+
+```ts
+// ✅ 5s timeout PER attempt
+// timeout is inner (first), retry is outer (second)
+Tenace.call(fn)
+  .withTimeout('5s')
+  .withRetry({ times: 5 })
+  .execute()
+
+// ⚠️ TOTAL timeout of 5s for ALL retries combined
+// retry is inner (first), timeout is outer (second)
+Tenace.call(fn)
+  .withRetry({ times: 5 })
+  .withTimeout('5s')
+  .execute()
+```
+
+#### Pattern 2: Where to place fallback
+
+```ts
+// ✅ Fallback catches EVERYTHING (recommended)
+// retry first (inner) → fallback second (outer)
+Tenace.call(fn)
+  .withRetry({ times: 3 })
+  .withTimeout('5s')
+  .withFallback(() => defaultValue)
+  .execute()
+
+// ⚠️ Fallback only catches fn errors, not retry/timeout
+// fallback is inner, retry is outer
+Tenace.call(fn)
+  .withFallback(() => defaultValue)
+  .withRetry({ times: 3 })
+  .withTimeout('5s')
+  .execute()
+```
+
+#### Pattern 3: Circuit breaker placement
+
+```ts
+// ✅ RECOMMENDED: Circuit breaker inside retry
+// CB first (inner) → retry second (outer)
+// Each retry attempt is tracked separately
+Tenace.call(fn)
+  .withCircuitBreaker({ failureThreshold: 5, halfOpenAfter: '30s' })
+  .withRetry({ times: 3 })
+  .execute()
+
+// ⚠️ Circuit breaker outside retry
+// retry is inner, CB is outer
+// Only the final result (after all retries) is tracked
+Tenace.call(fn)
+  .withRetry({ times: 3 })
+  .withCircuitBreaker({ failureThreshold: 5, halfOpenAfter: '30s' })
+  .execute()
+```
+
+### Recommended Order
+
+For most use cases (reading order = error handling order):
+
+```ts
+Tenace.call(fn)
+  .withCircuitBreaker(...)            // 1. Failure tracking (innermost)
+  .withTimeout('5s')                  // 2. Timeout per attempt
+  .withRetry({ times: 3 })            // 3. Retry on timeout/error
+  .withFallback(() => defaultValue)   // 4. Catch-all safety net (outermost)
+  .execute()
+```
+
+### Errors That Stop Retries
+
+The retry policy will **NOT** retry these errors (fail-fast behavior):
+
+| Error               | Reason                                        |
+| ------------------- | --------------------------------------------- |
+| `CircuitOpenError`  | Circuit breaker is open, no point retrying    |
+| `BulkheadFullError` | System is overloaded, retrying makes it worse |
+
+All other errors (including `TimeoutError`) **will** be retried.
+
+## Policies
+
+### Timeout
+
+Set a maximum execution time. Supports two strategies:
+
+```ts
+// Cooperative (default): Passes AbortSignal, function should respect it
+Tenace.call(({ signal }) => fetch('/api', { signal }))
+  .withTimeout('5s')
+  .execute()
+
+// Aggressive: Rejects immediately on timeout (function may continue in background)
+Tenace.call(() => slowOperation())
+  .withTimeout('5s', 'aggressive')
+  .execute()
+```
+
+### Retry
+
+Retry failed operations with configurable backoff:
+
+```ts
+// Simple retry
+Tenace.call(fn)
+  .withRetry({ times: 3 })
+  .execute()
+
+// With fixed delay
+Tenace.call(fn)
+  .withRetry({ times: 3, delay: '1s' })
+  .execute()
+
+// With exponential backoff
+Tenace.call(fn)
+  .withRetry({
+    times: 5,
+    delay: (attempt) => Math.min(1000 * 2 ** attempt, 30000),
+  })
+  .execute()
+
+// Dynamic delay based on error (e.g., rate limit retry-after)
+Tenace.call(fn)
+  .withRetry({
+    times: 5,
+    delay: (attempt, error) => {
+      if (error instanceof RateLimitError) return error.retryAfterMs
+      return 1000 * 2 ** attempt
+    },
+  })
+  .execute()
+
+// Conditional retry
+Tenace.call(fn)
+  .withRetry({
+    times: 3,
+    retryIf: (error) => error.status === 503,  // Only retry 503s
+    abortIf: (error) => error.status === 401,  // Never retry 401s
+  })
+  .execute()
+```
+
+#### Backoff Presets
+
+Use the `backoff` helper for common backoff patterns:
+
+```ts
+import { Tenace, backoff } from '@julr/tenace'
+
+// Constant delay (1s between each retry)
+Tenace.call(fn)
+  .withRetry({ times: 3, delay: backoff.constant('1s') })
+  .execute()
+
+// Exponential backoff: 100ms, 200ms, 400ms, 800ms... (capped at 30s)
+Tenace.call(fn)
+  .withRetry({ times: 5, delay: backoff.exponential({ initial: 100, max: 30_000 }) })
+  .execute()
+
+// Exponential with jitter (prevents thundering herd)
+Tenace.call(fn)
+  .withRetry({ times: 5, delay: backoff.exponentialWithJitter({ initial: 100, max: 30_000 }) })
+  .execute()
+
+// Linear backoff: 100ms, 200ms, 300ms, 400ms...
+Tenace.call(fn)
+  .withRetry({ times: 5, delay: backoff.linear({ initial: 100, step: 100, max: 5_000 }) })
+  .execute()
+```
+
+Available presets:
+
+| Preset                                | Description                 | Options                                  |
+| ------------------------------------- | --------------------------- | ---------------------------------------- |
+| `backoff.constant(delay)`             | Fixed delay between retries | `Duration`                               |
+| `backoff.exponential(opts)`           | Doubles each time (default) | `{ initial?, max?, exponent? }`          |
+| `backoff.exponentialWithJitter(opts)` | Exponential + randomization | `{ initial?, max?, exponent?, jitter? }` |
+| `backoff.linear(opts)`                | Increases by fixed step     | `{ initial?, step?, max? }`              |
+
+Jitter strategies for `exponentialWithJitter`:
+- `'full'` (default): Random delay between 0 and calculated delay
+- `'decorrelated'`: AWS-style decorrelated jitter ([recommended](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/))
+
+### Circuit Breaker
+
+Stop calling a failing service. After N failures, the circuit "opens" and all calls fail immediately with `CircuitOpenError`.
+
+```ts
+const policy = Tenace.policy()
+  .withCircuitBreaker({
+    failureThreshold: 5,        // Open after 5 consecutive failures
+    halfOpenAfter: '30s',       // Try again after 30s
+    hooks: {
+      onOpen: () => console.log('Circuit opened!'),
+      onClose: () => console.log('Circuit closed.'),
+      onHalfOpen: () => console.log('Circuit half-open, testing...'),
+      onStateChange: (state) => metrics.gauge('circuit', state),
+    },
+  })
+
+// Check circuit breaker state
+policy.circuitBreaker?.state      // 'closed' | 'open' | 'half-open'
+policy.circuitBreaker?.isOpen     // boolean
+
+// Manual isolation (maintenance mode)
+const handle = policy.circuitBreaker?.isolate()
+// All calls now fail with CircuitIsolatedError
+handle?.dispose() // Release isolation
+```
+
+### Bulkhead
+
+Limit concurrent executions to protect downstream services:
+
+```ts
+const policy = Tenace.policy()
+  .withBulkhead(10, 100) // max 10 concurrent, 100 in queue
+
+await policy.call(() => heavyOperation()).execute()
+// Throws BulkheadFullError if queue is also full
+```
+
+### Fallback
+
+Return a default value when everything fails:
+
+```ts
+const user = await Tenace.call(() => fetchUser(id))
+  .withFallback(() => ({ id, name: 'Unknown', cached: true }))
+  .execute()
+
+// Async fallback
+const user = await Tenace.call(() => fetchUser(id))
+  .withFallback(async () => {
+    return cache.get(`user:${id}`)
+  })
+  .execute()
+```
+
+## Adapters
+
+Cache, Rate Limiter, and Distributed Lock are **integrated into the pipeline**. Order matters - just like other policies!
+
+### Cache
+
+Cache successful results to avoid redundant calls:
+
+```ts
+// Basic caching
+const user = await Tenace.call(() => fetchUser(id))
+  .withCache({ key: `user:${id}`, ttl: 60_000 }) // 1 minute TTL
+  .execute()
+```
+
+#### Order patterns for cache
+
+```ts
+// ✅ Fallback BEFORE cache = fallback values ARE cached
+// fallback (inner) → cache (outer) = cache stores fallback result
+Tenace.call(fn)
+  .withFallback(() => defaultValue)
+  .withCache({ key: 'x', ttl: 60_000 })
+  .execute()
+
+// ⚠️ Cache BEFORE fallback = fallback values NOT cached
+// cache (inner) → fallback (outer) = cache doesn't see fallback result
+Tenace.call(fn)
+  .withCache({ key: 'x', ttl: 60_000 })
+  .withFallback(() => defaultValue)
+  .execute()
+
+// ✅ RateLimit BEFORE cache = no token consumed on cache hit
+// rateLimit (inner) → cache (outer) = cache checks first
+Tenace.call(fn)
+  .withRateLimit({ key: 'api', maxCalls: 100, windowMs: 60_000 })
+  .withCache({ key: 'x', ttl: 60_000 })
+  .execute()
+```
+
+#### Graceful degradation
+
+```ts
+// If Redis is down, continue without cache (don't fail the request)
+await Tenace.call(fn)
+  .withCache({ key: 'x', ttl: 60_000, optional: true })
+  .execute()
+```
+
+**Built-in adapter**: `MemoryCacheAdapter` (uses Bentocache under the hood)
+
+```ts
+import { MemoryCacheAdapter } from '@julr/tenace/adapters'
+
+// Use globally
+import { configStore } from '@julr/tenace'
+configStore.configure({
+  cache: new MemoryCacheAdapter({ maxSize: '50mb', maxItems: 5000 })
+})
+
+// Or per-call
+const customCache = new MemoryCacheAdapter()
+await Tenace.call(fn)
+  .withCache({ key: 'my-key', ttl: 60_000, adapter: customCache })
+  .execute()
+```
+
+**Custom adapter**: Implement `CacheAdapter` interface
+
+```ts
+import type { CacheAdapter } from '@julr/tenace/adapters'
+
+class RedisCacheAdapter implements CacheAdapter {
+  async get<T>(key: string): Promise<T | undefined> { /* ... */ }
+  async set<T>(key: string, value: T, ttlMs: number): Promise<void> { /* ... */ }
+  async delete(key: string): Promise<void> { /* ... */ }
+  async has(key: string): Promise<boolean> { /* ... */ }
+}
+```
+
+### Rate Limiter
+
+Limit call frequency to protect APIs or respect external rate limits:
+
+```ts
+// 100 calls per minute
+const result = await Tenace.call(() => callExternalApi())
+  .withRateLimit({
+    key: 'external-api',
+    maxCalls: 100,
+    windowMs: 60_000,
+  })
+  .execute()
+```
+
+Throws `RateLimitError` when limit is exceeded. The error includes `retryAfterMs`.
+
+#### Order patterns for rate limit
+
+```ts
+// ✅ RateLimit BEFORE fallback = fallback catches RateLimitError
+// rateLimit (inner) → fallback (outer)
+Tenace.call(fn)
+  .withRateLimit({ key: 'api', maxCalls: 100, windowMs: 60_000 })
+  .withFallback(() => defaultValue)
+  .execute()
+
+// ⚠️ Fallback BEFORE rateLimit = RateLimitError NOT caught by fallback
+// fallback (inner) → rateLimit (outer)
+Tenace.call(fn)
+  .withFallback(() => defaultValue)
+  .withRateLimit({ key: 'api', maxCalls: 100, windowMs: 60_000 })
+  .execute()
+
+// ✅ Retry with error-based delay for rate limit handling
+await Tenace.call(fn)
+  .withFallback(() => defaultValue)
+  .withRetry({
+    times: 3,
+    delay: (attempt, error) => {
+      if (error instanceof RateLimitError) return error.retryAfterMs
+      return 1000
+    }
+  })
+  .withRateLimit({ key: 'api', maxCalls: 100, windowMs: 60_000 })
+  .execute()
+```
+
+#### Graceful degradation
+
+```ts
+// If Redis is down, allow the call through (don't enforce rate limit)
+await Tenace.call(fn)
+  .withRateLimit({ key: 'api', maxCalls: 100, windowMs: 60_000, optional: true })
+  .execute()
+```
+
+**Built-in adapter**: `MemoryRateLimiterAdapter` (uses rate-limiter-flexible)
+
+```ts
+import { MemoryRateLimiterAdapter } from '@julr/tenace/adapters'
+import { configStore } from '@julr/tenace'
+
+configStore.configure({
+  rateLimiter: new MemoryRateLimiterAdapter()
+})
+```
+
+**Custom adapter**: Implement `RateLimiterAdapter` interface
+
+```ts
+import type { RateLimiterAdapter, RateLimitConfig, RateLimitResult, RateLimitState } from '@julr/tenace/adapters'
+
+class RedisRateLimiterAdapter implements RateLimiterAdapter {
+  async acquire(key: string, options: RateLimitConfig): Promise<RateLimitResult> { /* ... */ }
+  async getState(key: string): Promise<RateLimitState> { /* ... */ }
+  async reset(key: string): Promise<void> { /* ... */ }
+}
+```
+
+### Distributed Lock
+
+Ensure only one process executes a critical section at a time (useful for distributed systems):
+
+```ts
+// Process payment with distributed lock
+const result = await Tenace.call(() => processPayment(orderId))
+  .withDistributedLock({
+    key: `payment:${orderId}`,
+    ttl: 30_000,  // Lock expires after 30s (prevents deadlocks)
+  })
+  .execute()
+```
+
+Throws `LockNotAcquiredError` if the lock cannot be acquired.
+
+#### Order patterns for lock
+
+```ts
+// ✅ Retry BEFORE lock = lock held during ALL retries (atomicity)
+// retry (inner) → lock (outer) = lock acquired once, held during all retries
+Tenace.call(fn)
+  .withRetry({ times: 3 })
+  .withDistributedLock({ key: 'payment', ttl: 30_000 })
+  .execute()
+
+// ⚠️ Lock BEFORE retry = each retry acquires its own lock
+// lock (inner) → retry (outer) = lock released between retries
+Tenace.call(fn)
+  .withDistributedLock({ key: 'payment', ttl: 10_000 })
+  .withRetry({ times: 3 })
+  .execute()
+
+// ✅ Lock BEFORE fallback = fallback catches LockNotAcquiredError
+// lock (inner) → fallback (outer)
+Tenace.call(fn)
+  .withDistributedLock({ key: 'payment', ttl: 30_000 })
+  .withFallback(() => defaultValue)
+  .execute()
+```
+
+**No built-in adapter** - You must provide one (e.g., using [@verrou/core](https://github.com/Julien-R44/verrou)):
+
+```ts
+import { Verrou } from '@verrou/core'
+import { redisStore } from '@verrou/core/drivers/redis'
+import { configStore } from '@julr/tenace'
+import type { LockAdapter } from '@julr/tenace/adapters'
+
+const verrou = new Verrou({ default: 'redis', stores: { redis: redisStore({ /* ... */ }) } })
+
+class VerrouLockAdapter implements LockAdapter {
+  async run<T>(key: string, ttl: number, fn: () => Promise<T>, options?: { retry?: { attempts?: number; delay?: number; timeout?: number } }): Promise<[boolean, T | undefined]> {
+    const lock = verrou.createLock(key, ttl)
+    return lock.run(fn, { retry: options?.retry })
+  }
+}
+
+configStore.configure({ lock: new VerrouLockAdapter() })
+```
+
+**With retry** for lock acquisition:
+
+```ts
+await Tenace.call(fn)
+  .withDistributedLock({
+    key: 'critical-section',
+    ttl: 10_000,
+    retry: {
+      attempts: 5,
+      delay: 100,
+      timeout: 5000,
+    }
+  })
+  .execute()
+```
+
+## Reusable Policies
+
+Create a policy once, reuse everywhere. **Circuit breaker and bulkhead states are shared across calls.**
+
+```ts
+const apiPolicy = Tenace.policy()
+  .withTimeout('5s')
+  .withRetry({ times: 3, delay: (attempt) => 100 * 2 ** attempt })
+  .withCircuitBreaker({ failureThreshold: 5, halfOpenAfter: '30s' })
+
+// All calls share the same circuit breaker state!
+await apiPolicy.call(() => fetch('/api/users')).execute()
+await apiPolicy.call(() => fetch('/api/posts')).execute()
+
+// If 5 total failures occur, ALL calls will fail with CircuitOpenError
+```
+
+### Health Check Example
+
+```ts
+class UserService {
+  #policy = Tenace.policy()
+    .withCircuitBreaker({ failureThreshold: 5, halfOpenAfter: '30s' })
+
+  async getUser(id: string) {
+    return this.#policy.call(() => this.api.fetchUser(id)).execute()
+  }
+
+  // Expose for Kubernetes probes
+  getHealthStatus() {
+    if (this.#policy.circuitBreaker?.isOpen) {
+      return { status: 'degraded', reason: 'circuit-open' }
+    }
+    return { status: 'healthy' }
+  }
+}
+```
+
+## Batch Operations
+
+### Process items with concurrency control
+
+```ts
+const userIds = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+
+const users = await Tenace.map(userIds, (id) => fetchUser(id))
+  .withConcurrency(3)          // max 3 parallel requests
+  .withRetryPerTask(2)         // retry each task up to 2 times
+  .withTimeoutPerTask('5s')    // 5s timeout per task
+  .execute()
+```
+
+### Run multiple tasks in parallel
+
+```ts
+const [users, posts, config] = await Tenace.all([
+  () => fetchUsers(),
+  () => fetchPosts(),
+  () => fetchConfig(),
+])
+  .withConcurrency(3)
+  .execute()
+```
+
+### Get results even if some fail
+
+```ts
+const results = await Tenace.map(urls, (url) => fetch(url))
+  .withConcurrency(5)
+  .settle() // Never throws
+
+for (const result of results) {
+  if (result.status === 'fulfilled') {
+    console.log('Success:', result.value)
+  } else {
+    console.log('Failed:', result.reason.message)
+  }
+}
+```
+
+### Progress tracking
+
+```ts
+await Tenace.map(files, (file) => uploadFile(file))
+  .withConcurrency(5)
+  .onProgress(({ completed, total }) => {
+    console.log(`Progress: ${completed}/${total}`)
+  })
+  .onTaskComplete((value, { index }) => {
+    console.log(`File ${index} uploaded`)
+  })
+  .onTaskError((error, { index }) => {
+    console.log(`File ${index} failed: ${error.message}`)
+  })
+  .execute()
+```
+
+## Semaphore
+
+Low-level concurrency control:
+
+```ts
+import { Semaphore } from '@julr/tenace'
+
+const sem = new Semaphore(5) // max 5 concurrent
+
+// Run with automatic acquire/release
+await sem.run(() => doWork())
+
+// Wrap a function
+const limitedFetch = sem.wrap(fetch)
+await limitedFetch('/api/data')
+
+// Map with concurrency
+const results = await sem.map(items, (item) => process(item))
+
+// Manual acquire/release
+const release = await sem.acquire()
+try {
+  await doWork()
+} finally {
+  release()
+}
+```
+
+## Waiting for Conditions
+
+Poll until a condition becomes true. Useful for waiting on eventual consistency or service readiness.
+
+```ts
+// Wait for a service to be healthy
+await Tenace.waitFor(() => isServiceHealthy(), {
+  interval: '1s',
+  timeout: '30s',
+})
+
+// Wait for a database connection
+await Tenace.waitFor(async () => {
+  try {
+    await db.ping()
+    return true
+  } catch {
+    return false
+  }
+}, { interval: '500ms', timeout: '1m' })
+
+// Wait for eventual consistency
+await orderApi.create(order)
+await Tenace.waitFor(
+  () => orderApi.exists(order.id),
+  { interval: '100ms', timeout: '5s' }
+)
+```
+
+Options:
+- `interval`: Time between checks (default: `100ms`)
+- `timeout`: Max wait time (default: `10s`)
+- `message`: Custom error message
+- `before`: Run check immediately vs wait first (default: `true`)
+- `signal`: AbortSignal to cancel
+
+## Chaos Engineering
+
+Test your resilience patterns by injecting failures and latency.
+
+### Global Chaos
+
+Enable chaos globally to affect all Tenace calls:
+
+```ts
+import { Tenace } from '@julr/tenace'
+
+// Enable 100% failure rate
+Tenace.chaos.enable({ fault: 1 })
+
+// Enable 500ms latency
+Tenace.chaos.enable({ latency: 500 })
+
+// Combined with configuration
+Tenace.chaos.enable({
+  fault: { rate: 0.1, error: new Error('Random failure') },
+  latency: { rate: 0.2, delay: { min: 100, max: 2000 } },
+})
+
+// Disable
+Tenace.chaos.disable()
+
+// Check status
+Tenace.chaos.isEnabled()
+```
+
+### Testing Example
+
+```ts
+import { test } from 'vitest'
+
+test.afterEach(() => Tenace.chaos.disable())
+
+test('returns cached user when API fails', async () => {
+  await cache.set('user:123', { id: 123, name: 'John' })
+  Tenace.chaos.enable({ fault: 1 })
+
+  const user = await userService.getUser(123)
+  expect(user.name).toBe('John')
+})
+
+test('handles slow responses gracefully', async () => {
+  Tenace.chaos.enable({ latency: 2000 })
+
+  const start = Date.now()
+  const result = await userService.getUser(123) // Has 1s timeout + fallback
+
+  expect(Date.now() - start).toBeLessThan(1500)
+  expect(result.cached).toBe(true)
+})
+```
+
+### Per-call Chaos
+
+Add chaos to specific calls:
+
+```ts
+await Tenace.call(() => fetchUser(id))
+  .withChaosLatency({ rate: 1, delay: 2000 })
+  .execute()
+
+await Tenace.call(() => sendEmail(to, body))
+  .withChaosFault({ rate: 0.5, error: new Error('SMTP timeout') })
+  .execute()
+```
+
+## Hooks
+
+Tenace provides two hook systems for observing and reacting to resilience events.
+
+### Config Hooks
+
+Attach hooks directly to a specific policy:
+
+```ts
+// Retry hooks
+Tenace.call(fn)
+  .withRetry({
+    times: 3,
+    onRetry: (e) => console.log(`Retry ${e.attempt}: ${e.error.message}`),
+    onRetryExhausted: (e) => console.log('All retries failed:', e.error),
+  })
+  .execute()
+
+// Timeout hook
+Tenace.call(fn)
+  .withTimeout('5s', { strategy: 'aggressive', onTimeout: () => console.log('Timed out!') })
+  .execute()
+
+// Bulkhead hook
+Tenace.call(fn)
+  .withBulkhead(10, { queue: 5, onRejected: () => console.log('Bulkhead full') })
+  .execute()
+
+// Fallback hook
+Tenace.call(fn)
+  .withFallback(() => 'default', { onFallback: () => console.log('Using fallback') })
+  .execute()
+
+// Cache hooks
+Tenace.call(fn)
+  .withCache({
+    key: 'user:123',
+    ttl: 5000,
+    onHit: ({ key }) => console.log(`Cache hit: ${key}`),
+    onMiss: ({ key }) => console.log(`Cache miss: ${key}`),
+  })
+  .execute()
+
+// RateLimit hook
+Tenace.call(fn)
+  .withRateLimit({
+    key: 'api',
+    maxCalls: 10,
+    windowMs: 1000,
+    onRejected: ({ key, retryAfterMs }) => console.log(`Rate limited: ${key}`),
+  })
+  .execute()
+
+// Lock hooks
+Tenace.call(fn)
+  .withDistributedLock({
+    key: 'resource',
+    ttl: 5000,
+    onAcquired: ({ key }) => console.log(`Lock acquired: ${key}`),
+    onRejected: ({ key }) => console.log(`Lock failed: ${key}`),
+  })
+  .execute()
+```
+
+### Global Hooks
+
+Register hooks that apply to ALL Tenace operations:
+
+```ts
+// Register a global hook (returns unsubscribe function)
+const unsubscribe = Tenace.hooks.onRetry((e) => {
+  console.log(`Retry ${e.attempt}: ${e.error.message}`)
+})
+
+// Later, unsubscribe
+unsubscribe()
+```
+
+Available global hooks:
+
+| Hook | Description |
+|------|-------------|
+| `Tenace.hooks.onRetry(fn)` | Retry triggered |
+| `Tenace.hooks.onRetryExhausted(fn)` | All retries failed |
+| `Tenace.hooks.onTimeout(fn)` | Operation timed out |
+| `Tenace.hooks.onCircuitOpened(fn)` | Circuit breaker opened |
+| `Tenace.hooks.onCircuitClosed(fn)` | Circuit breaker closed |
+| `Tenace.hooks.onCircuitHalfOpened(fn)` | Circuit breaker half-open |
+| `Tenace.hooks.onBulkheadRejected(fn)` | Bulkhead full |
+| `Tenace.hooks.onCacheHit(fn)` | Cache hit |
+| `Tenace.hooks.onCacheMiss(fn)` | Cache miss |
+| `Tenace.hooks.onRateLimitRejected(fn)` | Rate limit exceeded |
+| `Tenace.hooks.onFallback(fn)` | Fallback triggered |
+| `Tenace.hooks.onLockAcquired(fn)` | Lock acquired |
+| `Tenace.hooks.onLockRejected(fn)` | Lock not acquired |
+
+### Plugin API
+
+For more advanced use cases (e.g., telemetry packages), use the plugin API:
+
+```ts
+import { use, type TenacePlugin } from '@julr/tenace'
+
+const myPlugin: TenacePlugin = {
+  onRetry: (e) => metrics.increment('retry', { attempt: e.attempt }),
+  onCircuitOpened: () => metrics.increment('circuit_open'),
+}
+
+use(myPlugin)
+```
+
+## Error Types
+
+All errors extend `TenaceError`:
+
+```ts
+import {
+  TenaceError,           // Base class
+  TimeoutError,          // Operation timed out
+  CancelledError,        // Operation cancelled via AbortSignal
+  CircuitOpenError,      // Circuit breaker is open
+  CircuitIsolatedError,  // Circuit breaker manually isolated
+  BulkheadFullError,     // Bulkhead capacity exceeded
+  AbortError,            // AbortSignal triggered
+  RateLimitError,        // Rate limit exceeded (has retryAfterMs)
+  LockNotAcquiredError,  // Distributed lock not acquired
+  WaitForTimeoutError,   // waitFor() timed out
+} from '@julr/tenace/errors'
+```
+
+### Usage
+
+```ts
+import { TimeoutError, CircuitOpenError } from '@julr/tenace/errors'
+
+try {
+  await Tenace.call(() => slowOperation())
+    .withTimeout('1s')
+    .withCircuitBreaker({ failureThreshold: 5, halfOpenAfter: '30s' })
+    .execute()
+} catch (error) {
+  if (error instanceof TimeoutError) {
+    console.log('Operation timed out')
+  } else if (error instanceof CircuitOpenError) {
+    console.log('Circuit breaker is open, service is down')
+  }
+}
+```
+
+## Durations
+
+All duration parameters accept numbers (milliseconds) or human-readable strings:
+
+```ts
+.withTimeout('5s')      // 5 seconds
+.withTimeout('500ms')   // 500 milliseconds
+.withTimeout('1m')      // 1 minute
+.withTimeout('1h')      // 1 hour
+.withTimeout(5000)      // 5000 ms
+```
+
+## API Reference
+
+### `Tenace.call(fn)`
+
+Execute a single operation with resilience.
+
+```ts
+Tenace.call(fn)
+  .withTimeout(duration, strategy?)     // 'cooperative' | 'aggressive'
+  .withRetry(options?)                  // { times, delay, retryIf, abortIf } - use backoff.* for delay
+  .withCircuitBreaker(options)          // { failureThreshold, halfOpenAfter, hooks? }
+  .withBulkhead(limit, queue?)          // Concurrency limiter
+  .withFallback(fn)                     // Default value on failure
+  .withCache(options)                   // { key, ttl, adapter? }
+  .withRateLimit(options)               // { key, maxCalls, windowMs, adapter? }
+  .withDistributedLock(options)         // { key, timeout?, adapter? }
+  .withSpan(name, attributes?)          // OpenTelemetry tracing
+  .withChaosFault(options)              // { rate, error?, errors? }
+  .withChaosLatency(options)            // { rate, delay }
+  .execute()                            // Run and return result
+```
+
+### `Tenace.policy()`
+
+Create a reusable policy with shared state for circuit breaker and bulkhead.
+
+```ts
+const policy = Tenace.policy()
+  .withTimeout(duration)
+  .withRetry(options)
+  .withCircuitBreaker(options)
+  .withBulkhead(limit, queue?)
+
+await policy.call(fn).execute()
+
+// Access circuit breaker state
+policy.circuitBreaker?.state
+policy.circuitBreaker?.isolate()
+```
+
+### `Tenace.all(tasks)` / `Tenace.map(items, fn)`
+
+Batch operations with concurrency control.
+
+```ts
+Tenace.all(tasks)  // or Tenace.map(items, fn)
+  .withConcurrency(limit)
+  .withRetryPerTask(times, options?)    // options: { delay, retryIf, abortIf } - use backoff.* for delay
+  .withTimeoutPerTask(duration, strategy?)
+  .withSignal(signal)
+  .stopOnError(boolean)
+  .onProgress(fn)
+  .onTaskComplete(fn)
+  .onTaskError(fn)
+  .execute()  // Throws on first error
+  .settle()   // Returns all results (never throws)
+```
+
+### `Tenace.waitFor(condition, options?)`
+
+Wait for a condition to become true.
+
+```ts
+await Tenace.waitFor(
+  () => boolean | Promise<boolean>,
+  {
+    interval?: Duration,  // Default: 100ms
+    timeout?: Duration,   // Default: 10s
+    message?: string,
+    before?: boolean,     // Default: true
+    signal?: AbortSignal,
+  }
+)
+```
+
+### `Tenace.chaos`
+
+Global chaos injection for testing.
+
+```ts
+Tenace.chaos.enable({ fault?, latency? })
+Tenace.chaos.disable()
+Tenace.chaos.isEnabled()
+```
+
+## License
+
+MIT