immortal-js 1.0.0

package/docs/guides/fastify.md

@@ -0,0 +1,188 @@
+# Guide — Fastify Integration
+
+This guide walks you through integrating Immortal.js with a Fastify application.
+
+---
+
+## Installation
+
+```bash
+npm install @immortal/core @immortal/fastify fastify
+```
+
+---
+
+## Quick start
+
+```typescript
+import Fastify from 'fastify';
+import immortalPlugin from '@immortal/fastify';
+
+const app = Fastify({ logger: true });
+
+await app.register(immortalPlugin, {
+  circuitBreakers: true,
+  bulkheads: true,
+  metrics: true,
+  gracefulShutdown: true,
+  immortalConfig: {
+    logger: { level: 'info' },
+    memoryGuard: { enabled: true, warningThresholdMb: 400 },
+  },
+});
+
+app.get('/api/products', async (req, reply) => {
+  return { products: [] };
+});
+
+await app.listen({ port: 3000, host: '0.0.0.0' });
+```
+
+---
+
+## Manual integration (full control)
+
+```typescript
+import Fastify from 'fastify';
+import {
+  createImmortal,
+  CircuitBreaker,
+  BulkheadPool,
+  withRetry,
+  withTimeout,
+  RouteFallbackCache,
+  ChaosEngine,
+  asyncBoundary,
+} from '@immortal/core';
+
+const immortal = await createImmortal({
+  logger: { level: process.env.LOG_LEVEL ?? 'info' },
+  healthMonitor: { enabled: true },
+  gracefulShutdown: { enabled: true, timeoutMs: 30_000 },
+});
+
+const app = Fastify();
+
+// Circuit breaker per downstream service
+const dbBreaker = new CircuitBreaker('postgres', { threshold: 5, timeout: 30_000 });
+const cacheBreaker = new CircuitBreaker('redis', { threshold: 3, timeout: 10_000 });
+
+// Bulkheads per resource type
+const dbPool = new BulkheadPool('database', { maxConcurrent: 10, maxQueueSize: 50 });
+const apiPool = new BulkheadPool('external-api', { maxConcurrent: 5 });
+
+// Fallback cache for stale data
+const fallbackCache = new RouteFallbackCache({ ttlMs: 5 * 60_000 });
+
+// Request tracing hook
+app.addHook('onRequest', async (req) => {
+  req.immortalRequestId = req.headers['x-request-id'] as string ?? crypto.randomUUID();
+});
+
+// Metrics hook
+app.addHook('onResponse', async (req, reply) => {
+  // record metrics if needed
+});
+
+// ─────────────────────────────────────────────────────────
+// Routes
+// ─────────────────────────────────────────────────────────
+
+app.get('/api/products/:id', asyncBoundary(async (req, reply) => {
+  const { id } = req.params as { id: string };
+  const cacheKey = `GET /products/${id}`;
+
+  try {
+    const product = await dbPool.run(() =>
+      dbBreaker.run(() =>
+        withRetry(() => db.findProduct(id), { maxAttempts: 2 })
+      )
+    );
+
+    fallbackCache.set(cacheKey, product);
+    return product;
+  } catch (err) {
+    const cached = fallbackCache.get(cacheKey);
+    if (cached) return { ...cached, stale: true };
+    throw err;
+  }
+}));
+
+app.post('/api/orders', asyncBoundary(async (req, reply) => {
+  const body = req.body as CreateOrderDto;
+
+  const result = await dbPool.run(() =>
+    withTimeout(
+      () => dbBreaker.run(() => db.createOrder(body)),
+      10_000,
+      'create-order'
+    )
+  );
+
+  reply.code(201);
+  return result;
+}));
+
+// Health endpoint (Kubernetes liveness/readiness)
+app.get('/health', async () => ({
+  status: immortal.isHealthy() ? 'ok' : 'degraded',
+  timestamp: new Date().toISOString(),
+  metrics: immortal.getMetrics(),
+}));
+
+// Metrics endpoint
+app.get('/metrics', async () => immortal.getMetrics());
+
+// ─────────────────────────────────────────────────────────
+// Graceful shutdown
+// ─────────────────────────────────────────────────────────
+
+process.on('SIGTERM', async () => {
+  await app.close();
+  await immortal.shutdown('SIGTERM');
+  process.exit(0);
+});
+
+await app.listen({ port: 3000, host: '0.0.0.0' });
+```
+
+---
+
+## Full example
+
+See [`examples/fastify-microservice/index.ts`](../../examples/fastify-microservice/index.ts) for a production-ready example with:
+
+- Circuit breakers for every downstream service
+- Bulkheads for database and external API calls
+- Retry with exponential backoff
+- Fallback cache for stale data
+- Chaos engineering endpoints
+- Health and metrics routes
+- Graceful shutdown
+
+---
+
+## Error handling
+
+Immortal.js provides structured error types. Map them to HTTP status codes:
+
+```typescript
+import { ImmortalError, BulkheadRejectedError, CircuitOpenError, classifyError } from '@immortal/core';
+
+app.setErrorHandler((err, req, reply) => {
+  if (err instanceof BulkheadRejectedError) {
+    return reply.code(503).send({ error: 'Service overloaded', retryAfter: 1 });
+  }
+  if (err instanceof CircuitOpenError) {
+    return reply.code(503).send({ error: 'Dependency unavailable' });
+  }
+  if (err instanceof ImmortalError) {
+    const code = err.statusCode ?? (err.kind === 'programming' ? 500 : 503);
+    return reply.code(code).send({ error: err.message, kind: err.kind });
+  }
+
+  const kind = classifyError(err);
+  const code = kind === 'programming' ? 500 : 503;
+  return reply.code(code).send({ error: 'Internal error', kind });
+});
+```

package/docs/guides/koa.md

@@ -0,0 +1,102 @@
+# Guide — Koa Integration
+
+This guide covers integrating Immortal.js with Koa.
+
+---
+
+## Installation
+
+```bash
+npm install @immortal/core @immortal/koa koa
+npm install -D @types/koa
+```
+
+---
+
+## Plugin setup
+
+```typescript
+import Koa from 'koa';
+import { immortalMiddleware } from '@immortal/koa';
+
+const app = new Koa();
+
+app.use(immortalMiddleware({
+  circuitBreakers: true,
+  bulkheads: true,
+  metrics: true,
+  immortalConfig: {
+    logger: { level: 'info' },
+    gracefulShutdown: { enabled: true, timeoutMs: 30_000 },
+  },
+}));
+```
+
+---
+
+## Manual integration
+
+```typescript
+import Koa from 'koa';
+import Router from '@koa/router';
+import {
+  createImmortal,
+  CircuitBreaker,
+  BulkheadPool,
+  withRetry,
+  asyncBoundary,
+  classifyError,
+} from '@immortal/core';
+
+const immortal = await createImmortal({ logger: { level: 'info' } });
+const app = new Koa();
+const router = new Router();
+
+const dbBreaker = new CircuitBreaker('database', { threshold: 5 });
+const dbPool = new BulkheadPool('database', { maxConcurrent: 10 });
+
+// Request tracing
+app.use(async (ctx, next) => {
+  const requestId = ctx.get('x-request-id') || crypto.randomUUID();
+  ctx.set('x-request-id', requestId);
+  ctx.state.requestId = requestId;
+  await next();
+});
+
+// Error handling
+app.use(async (ctx, next) => {
+  try {
+    await next();
+  } catch (err) {
+    const kind = classifyError(err);
+    ctx.status = kind === 'programming' ? 500 : 503;
+    ctx.body = { error: (err as Error).message, kind };
+  }
+});
+
+// Route
+router.get('/api/products/:id', async (ctx) => {
+  const { id } = ctx.params;
+
+  ctx.body = await dbPool.run(() =>
+    dbBreaker.run(() =>
+      withRetry(() => db.findProduct(id), { maxAttempts: 2 })
+    )
+  );
+});
+
+router.get('/health', (ctx) => {
+  ctx.body = { status: immortal.isHealthy() ? 'ok' : 'degraded' };
+});
+
+app.use(router.routes());
+app.use(router.allowedMethods());
+
+const server = app.listen(3000);
+
+process.on('SIGTERM', async () => {
+  server.close();
+  await immortal.shutdown('SIGTERM');
+  process.exit(0);
+});
+```

package/docs/guides/nestjs.md

@@ -0,0 +1,182 @@
+# Guide — NestJS Integration
+
+This guide covers integrating Immortal.js into a NestJS application using the `@immortal/nestjs` module and its method decorators.
+
+---
+
+## Installation
+
+```bash
+npm install @immortal/core @immortal/nestjs @nestjs/core @nestjs/common reflect-metadata rxjs
+```
+
+---
+
+## Module setup
+
+Import `ImmortalModule` in your root `AppModule`:
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { ImmortalModule } from '@immortal/nestjs';
+
+@Module({
+  imports: [
+    ImmortalModule.forRoot({
+      logger: { level: 'info' },
+      healthMonitor: { enabled: true },
+      memoryGuard: { enabled: true, warningThresholdMb: 400 },
+      gracefulShutdown: { enabled: true, timeoutMs: 30_000 },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Async configuration
+
+```typescript
+ImmortalModule.forRootAsync({
+  useFactory: (configService: ConfigService) => ({
+    logger: { level: configService.get('LOG_LEVEL') },
+    gracefulShutdown: { enabled: true },
+  }),
+  inject: [ConfigService],
+});
+```
+
+---
+
+## Injecting the runtime
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { InjectImmortal, ImmortalService } from '@immortal/nestjs';
+
+@Injectable()
+export class MetricsController {
+  constructor(private readonly immortal: ImmortalService) {}
+
+  getHealth() {
+    return {
+      status: this.immortal.isHealthy() ? 'ok' : 'degraded',
+      metrics: this.immortal.getMetrics(),
+    };
+  }
+}
+```
+
+---
+
+## Method decorators
+
+### `@Retry(options?)`
+
+Wrap a service method with automatic retry:
+
+```typescript
+import { Retry } from '@immortal/nestjs';
+
+@Injectable()
+export class PaymentService {
+  @Retry({ maxAttempts: 3, baseDelayMs: 200, backoffFactor: 2 })
+  async chargeCustomer(customerId: string, amount: number) {
+    return this.paymentApi.charge(customerId, amount);
+  }
+}
+```
+
+### `@Circuit(options?)`
+
+Protect a method with a circuit breaker:
+
+```typescript
+import { Circuit } from '@immortal/nestjs';
+
+@Injectable()
+export class OrdersService {
+  @Circuit({ name: 'orders-db', threshold: 5, timeout: 30_000 })
+  async findOrders(customerId: string) {
+    return this.db.orders.findByCustomer(customerId);
+  }
+}
+```
+
+The circuit breaker is shared across all calls to the same `name`. Use the same name for related methods that hit the same downstream service.
+
+### `@Bulkhead(options?)`
+
+Limit concurrency for a method:
+
+```typescript
+import { Bulkhead } from '@immortal/nestjs';
+
+@Injectable()
+export class ReportService {
+  @Bulkhead({ pool: 'reports', maxConcurrent: 2, maxQueueSize: 5 })
+  async generateReport(params: ReportParams) {
+    return this.reportEngine.generate(params);
+  }
+}
+```
+
+### Combining decorators
+
+Decorators compose — apply multiple for layered resilience:
+
+```typescript
+@Injectable()
+export class InventoryService {
+  @Bulkhead({ pool: 'inventory', maxConcurrent: 5 })
+  @Circuit({ name: 'inventory-db', threshold: 3 })
+  @Retry({ maxAttempts: 2 })
+  async getStock(productId: string): Promise<StockLevel> {
+    return this.db.inventory.find(productId);
+  }
+}
+```
+
+**Execution order** (outermost to innermost):
+1. `@Bulkhead` — wait for a slot
+2. `@Circuit` — check if circuit is open
+3. `@Retry` — retry the actual DB call
+
+---
+
+## Health check endpoint
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { ImmortalService } from '@immortal/nestjs';
+
+@Controller()
+export class HealthController {
+  constructor(private readonly immortal: ImmortalService) {}
+
+  @Get('/health')
+  health() {
+    return {
+      status: this.immortal.isHealthy() ? 'ok' : 'degraded',
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  @Get('/metrics')
+  metrics() {
+    return this.immortal.getMetrics();
+  }
+}
+```
+
+---
+
+## Full example
+
+See [`examples/nestjs-enterprise/`](../../examples/nestjs-enterprise/) for a complete application with:
+
+- `ImmortalModule.forRoot` configuration
+- `OrdersService` with `@Bulkhead`, `@Circuit`, `@Retry`
+- `PaymentsService` with circuit breaker
+- Health and metrics endpoints
+- Graceful shutdown integration

package/docs/guides/testing.md

@@ -0,0 +1,91 @@
+# Testing Guide
+
+This guide covers testing patterns for applications using Immortal.js.
+
+---
+
+## Running the test suite
+
+```bash
+# All packages
+npm test --workspaces --if-present
+
+# Core package only
+cd packages/core && npm test
+
+# Watch mode
+cd packages/core && npm test -- --watch
+
+# Coverage
+cd packages/core && npm test -- --coverage
+```
+
+---
+
+## Mocking the event bus
+
+In unit tests, mock the event bus to avoid side effects:
+
+```typescript
+import { vi, describe, it, beforeEach } from 'vitest';
+
+vi.mock('../src/event-bus.js', () => ({
+  getEventBus: () => ({ emit: vi.fn(), on: vi.fn(), onAny: vi.fn() }),
+  resetEventBus: vi.fn(),
+}));
+```
+
+---
+
+## Testing circuit breakers
+
+```typescript
+import { CircuitBreaker } from '@immortal/core';
+
+it('opens after threshold failures', async () => {
+  const cb = new CircuitBreaker('test', { threshold: 2, timeout: 100 });
+
+  for (let i = 0; i < 2; i++) {
+    await expect(cb.run(() => Promise.reject(new Error('fail')))).rejects.toThrow();
+  }
+
+  expect(cb.getCurrentState()).toBe('open');
+  await expect(cb.run(() => Promise.resolve('ok'))).rejects.toThrow(/circuit.*open/i);
+});
+```
+
+---
+
+## Testing bulkheads
+
+```typescript
+import { BulkheadPool, BulkheadRejectedError } from '@immortal/core';
+
+it('rejects when saturated', async () => {
+  const pool = new BulkheadPool('test', { maxConcurrent: 1, maxQueueSize: 0 });
+
+  const hold = pool.run(() => new Promise(resolve => setTimeout(resolve, 100)));
+
+  await expect(pool.run(() => Promise.resolve())).rejects.toBeInstanceOf(BulkheadRejectedError);
+  await hold;
+});
+```
+
+---
+
+## Testing with fake timers
+
+```typescript
+import { vi } from 'vitest';
+
+it('retries with backoff', async () => {
+  vi.useFakeTimers();
+  const fn = vi.fn().mockRejectedValueOnce(new Error('fail')).mockResolvedValue('ok');
+
+  const promise = withRetry(fn, { maxAttempts: 2, baseDelayMs: 1_000 });
+  await vi.advanceTimersByTimeAsync(1_100);
+  expect(await promise).toBe('ok');
+
+  vi.useRealTimers();
+});
+```