immortal-js 1.0.0

package/docs/api/recovery.md

@@ -0,0 +1,267 @@
+# API Reference — Recovery (Layer 2)
+
+The **Recovery** layer provides automatic healing after failures: retrying transient errors, circuit breaking broken dependencies, and serving cached fallbacks when live data is unavailable.
+
+---
+
+## Retry Engine
+
+### `withRetry(fn, options?)`
+
+Wraps an async function with automatic retry and exponential backoff.
+
+```typescript
+import { withRetry } from '@immortal/core';
+
+const result = await withRetry(
+  () => fetch('https://api.example.com/data').then(r => r.json()),
+  {
+    maxAttempts: 5,
+    baseDelayMs: 200,
+    backoffFactor: 2,
+    jitter: true,
+    retryOn: (err) => err.code === 'ECONNRESET',
+  }
+);
+```
+
+**Options:**
+
+```typescript
+interface RetryOptions {
+  maxAttempts?: number;       // default: 3
+  baseDelayMs?: number;       // default: 100
+  backoffFactor?: number;     // default: 2
+  maxDelayMs?: number;        // default: 30_000
+  jitter?: boolean;           // default: true
+  retryOn?: (err: unknown, attempt: number) => boolean;
+  onRetry?: (err: unknown, attempt: number, delayMs: number) => void;
+}
+```
+
+**Retry logic:**
+- Attempt 1: immediate
+- Attempt 2: `baseDelayMs * backoffFactor^1` ± jitter
+- Attempt 3: `baseDelayMs * backoffFactor^2` ± jitter
+- Capped at `maxDelayMs`
+
+The `retryOn` predicate receives the raw error and attempt number. Return `false` to stop retrying immediately (for `programming` errors, for example).
+
+---
+
+### `withTimeout(fn, timeoutMs, label?)`
+
+Races an async operation against a deadline.
+
+```typescript
+import { withTimeout } from '@immortal/core';
+
+const result = await withTimeout(
+  () => paymentService.charge(amount),
+  5_000,
+  'payment-charge'
+);
+```
+
+Throws `ImmortalError` with `kind: 'operational'` and `code: 'TIMEOUT'` on expiry.
+
+---
+
+### `withSimpleTimeout(fn, timeoutMs)`
+
+Alias for `withTimeout` without the label parameter.
+
+---
+
+### `calculateBackoff(attempt, baseMs, maxMs)`
+
+Pure utility — computes the delay for retry attempt `n` with full jitter.
+
+```typescript
+import { calculateBackoff } from '@immortal/core';
+
+const delay = calculateBackoff(3, 100, 30_000);
+// e.g. → 347 (ms)
+```
+
+---
+
+## Circuit Breaker
+
+### `new CircuitBreaker(name, config?)`
+
+Creates a named circuit breaker. Circuit breakers prevent cascading failures by stopping calls to a broken dependency.
+
+```typescript
+import { CircuitBreaker } from '@immortal/core';
+
+const cb = new CircuitBreaker('payment-service', {
+  threshold: 5,         // failures to trip open
+  timeout: 60_000,      // ms to stay open before half-open probe
+  halfOpenRequests: 2,  // successful probes needed to close
+  volumeThreshold: 10,  // min requests before tripping
+});
+```
+
+**Config:**
+
+```typescript
+interface CircuitBreakerConfig {
+  threshold?: number;          // default: 5
+  timeout?: number;            // default: 60_000
+  halfOpenRequests?: number;   // default: 1
+  volumeThreshold?: number;    // default: 0
+}
+```
+
+### `cb.run(fn)`
+
+Execute a function protected by the circuit breaker. Throws `CircuitOpenError` when the circuit is open.
+
+```typescript
+const result = await cb.run(() => db.query(sql));
+```
+
+### `cb.getCurrentState()`
+
+Returns `'closed' | 'open' | 'half-open'`.
+
+### `cb.getStatus()`
+
+Returns detailed status object:
+
+```typescript
+interface CircuitBreakerStatus {
+  name: string;
+  state: 'closed' | 'open' | 'half-open';
+  failures: number;
+  successes: number;
+  lastFailureTime?: number;
+  nextAttemptTime?: number;
+}
+```
+
+### `cb.forceState(state)`
+
+Manually set circuit state — useful in tests and admin APIs.
+
+```typescript
+cb.forceState('open');
+cb.forceState('closed');
+```
+
+### Events
+
+Circuit breakers emit events on the Immortal event bus:
+
+| Event | Trigger |
+|-------|---------|
+| `circuit:opened` | Circuit trips open |
+| `circuit:closed` | Circuit resets to closed |
+| `circuit:half-open` | Probe attempt starts |
+| `circuit:rejected` | Call rejected while open |
+
+---
+
+### `CircuitBreakerRegistry`
+
+Singleton registry for named circuit breakers.
+
+```typescript
+import { CircuitBreakerRegistry } from '@immortal/core';
+
+const registry = CircuitBreakerRegistry.getInstance();
+
+// Get or create
+const cb = registry.get('payment-service', config);
+
+// Get all names
+const names = registry.getAll().map(cb => cb.name);
+
+// Reset all (testing)
+registry.resetAll();
+```
+
+---
+
+## Fallback Cache
+
+### `new RouteFallbackCache(config?)`
+
+LRU cache that stores last-known-good responses per route key.
+
+```typescript
+import { RouteFallbackCache } from '@immortal/core';
+
+const cache = new RouteFallbackCache({
+  maxEntries: 1000,
+  ttlMs: 5 * 60_000,  // 5 minutes default TTL
+});
+```
+
+**Config:**
+
+```typescript
+interface FallbackCacheConfig {
+  maxEntries?: number;  // default: 500
+  ttlMs?: number;       // default: 300_000 (5 min)
+  purgIntervalMs?: number;
+}
+```
+
+### `cache.set(key, value, options?)`
+
+Store a value. Per-entry TTL overrides the global default.
+
+```typescript
+cache.set('GET /products/42', productData, { ttlMs: 600_000 });
+```
+
+### `cache.get(key)`
+
+Retrieve a value. Returns `undefined` on miss or expiry.
+
+```typescript
+const cached = cache.get('GET /products/42');
+```
+
+### `cache.has(key)`
+
+Check existence without retrieving.
+
+### `cache.delete(key)`
+
+Remove a specific entry.
+
+### `cache.clear()`
+
+Flush all entries.
+
+### `cache.getStats()`
+
+Returns `{ size, hits, misses, hitRate }`.
+
+---
+
+## Integration Pattern
+
+Combining retry + circuit breaker + fallback cache:
+
+```typescript
+const cache = new RouteFallbackCache();
+const cb = new CircuitBreaker('inventory');
+
+async function getInventory(productId: string) {
+  try {
+    const result = await cb.run(() =>
+      withRetry(() => inventoryApi.get(productId), { maxAttempts: 2 })
+    );
+    cache.set(`inventory:${productId}`, result);
+    return result;
+  } catch (err) {
+    const cached = cache.get(`inventory:${productId}`);
+    if (cached) return { ...cached, stale: true };
+    throw err;
+  }
+}
+```

package/docs/api/safe-zone.md

@@ -0,0 +1,236 @@
+# API Reference — Safe Zone (Layer 1: Containment)
+
+The **Safe Zone** is the innermost layer of Immortal.js. It captures every unhandled error at the process and request boundary, classifies it, and routes it to the appropriate recovery mechanism.
+
+---
+
+## `classifyError(error)`
+
+Classifies any thrown value into one of five canonical categories.
+
+```typescript
+import { classifyError } from '@immortal/core';
+
+const kind = classifyError(error);
+```
+
+**Returns:** `'operational' | 'programming' | 'transient' | 'external' | 'unknown'`
+
+| Category | Examples | Behaviour |
+|----------|----------|-----------|
+| `operational` | `ECONNREFUSED`, HTTP 5xx, timeout | Retry is safe |
+| `programming` | `TypeError`, `RangeError`, `ReferenceError` | Do NOT retry — fix the code |
+| `transient` | Rate limit (HTTP 429), lock contention | Retry with backoff |
+| `external` | Third-party API error, DNS failure | Circuit break |
+| `unknown` | Generic `Error()`, unrecognised thrown value | Conservative — treat as operational |
+
+**Example:**
+
+```typescript
+try {
+  await db.query(sql);
+} catch (err) {
+  const kind = classifyError(err);
+  if (kind === 'programming') throw err;          // surface immediately
+  if (kind === 'transient') await withRetry(...); // safe to retry
+}
+```
+
+---
+
+## `serializeError(error)`
+
+Converts any thrown value to a plain `SerializedError` object safe for logging / JSON transport.
+
+```typescript
+import { serializeError } from '@immortal/core';
+
+const serialized = serializeError(error);
+```
+
+**Returns:** `SerializedError`
+
+```typescript
+interface SerializedError {
+  message: string;
+  name: string;
+  kind: ErrorKind;
+  stack?: string;       // only in non-production
+  code?: string;        // e.g. 'ECONNREFUSED'
+  statusCode?: number;  // HTTP status if present
+  context?: Record<string, unknown>;
+}
+```
+
+---
+
+## `AsyncBoundary`
+
+Static class that manages async execution context (trace IDs, request IDs, parent spans).
+
+All methods are **static** — never instantiate `AsyncBoundary`.
+
+### `AsyncBoundary.run(fn, context?)`
+
+Executes `fn` inside an isolated async context.
+
+```typescript
+const result = await AsyncBoundary.run(async () => {
+  // All code here shares the same request context
+  return processOrder(order);
+}, { requestId: 'req-abc-123', traceId: 'trace-xyz' });
+```
+
+**Parameters:**
+- `fn: () => Promise<T>` — async function to execute
+- `context?: Partial<BoundaryContext>` — initial context values
+
+**Returns:** `Promise<T>`
+
+### `AsyncBoundary.getContext()`
+
+Returns the current boundary context, or `null` outside a boundary.
+
+```typescript
+const ctx = AsyncBoundary.getContext();
+if (ctx) {
+  console.log(ctx.requestId, ctx.traceId);
+}
+```
+
+### `AsyncBoundary.getRequestId()`
+
+Shorthand for `AsyncBoundary.getContext()?.requestId`.
+
+```typescript
+const reqId = AsyncBoundary.getRequestId();
+```
+
+### `AsyncBoundary.enrich(extra)`
+
+Merges additional data into the current context. No-op if called outside a boundary.
+
+```typescript
+AsyncBoundary.enrich({ userId: 'u-42', tenantId: 'acme' });
+```
+
+---
+
+## `asyncBoundary(fn, options?)`
+
+Higher-order function that wraps a handler with an `AsyncBoundary.run` call automatically.
+
+```typescript
+import { asyncBoundary } from '@immortal/core';
+
+const safeHandler = asyncBoundary(originalHandler, {
+  fallback: (err) => ({ error: 'Service unavailable', kind: classifyError(err) }),
+});
+```
+
+**Options:**
+
+```typescript
+interface AsyncBoundaryOptions<T> {
+  fallback?: (error: unknown) => T | Promise<T>;
+  context?: Partial<BoundaryContext>;
+}
+```
+
+---
+
+## `ErrorTrap`
+
+Installs global handlers for `uncaughtException` and `unhandledRejection`, emitting structured events on the Immortal event bus.
+
+```typescript
+import { ErrorTrap } from '@immortal/core';
+import { getEventBus } from '@immortal/core';
+
+const trap = new ErrorTrap(getEventBus());
+trap.install();
+
+// Later, if needed:
+trap.uninstall();
+```
+
+**Events emitted:**
+
+| Event | Trigger |
+|-------|---------|
+| `error:captured` | Any uncaught exception or unhandled rejection |
+| `error:escalated` | When `programming` errors are detected (non-retriable) |
+
+---
+
+## `ImmortalError`
+
+Custom error class with structured metadata.
+
+```typescript
+import { ImmortalError } from '@immortal/core';
+
+throw new ImmortalError('Payment failed', {
+  kind: 'external',
+  code: 'PAYMENT_DECLINED',
+  statusCode: 402,
+  context: { orderId: '42', amount: 9999 },
+});
+```
+
+**Constructor:**
+
+```typescript
+new ImmortalError(message: string, options?: {
+  kind?: ErrorKind;
+  code?: string;
+  statusCode?: number;
+  context?: Record<string, unknown>;
+  cause?: unknown;
+})
+```
+
+---
+
+## `SafeWrapper` / `createSafeZone`
+
+Creates a safe zone configuration for wrapping multiple route handlers with shared options.
+
+```typescript
+import { createSafeZone } from '@immortal/core';
+
+const safeZone = createSafeZone({
+  defaultFallback: () => ({ error: 'Unavailable' }),
+  onError: (err, ctx) => logger.error('Route error', { err, ...ctx }),
+});
+
+// Wrap individual handlers
+const wrappedHandler = safeZone.handler(myHandler);
+const wrappedWithFallback = safeZone.handler(myHandler, customFallback);
+```
+
+---
+
+## Types
+
+```typescript
+type ErrorKind = 'operational' | 'programming' | 'transient' | 'external' | 'unknown';
+
+interface SerializedError {
+  message: string;
+  name: string;
+  kind: ErrorKind;
+  stack?: string;
+  code?: string;
+  statusCode?: number;
+  context?: Record<string, unknown>;
+}
+
+interface BoundaryContext {
+  requestId: string;
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  [key: string]: unknown;
+}
+```