immortal-js 1.0.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "immortal-js",
+  "version": "1.0.0",
+  "description": "Ultra-resilient Node.js runtime enhancement — Containment, Recovery, Isolation, Supervision, Observability",
+  "workspaces": [
+    "packages/*",
+    "examples/*"
+  ],
+  "scripts": {
+    "build": "npm run build --workspace=packages/core && npm run build --workspace=packages/adapter-express && npm run build --workspace=packages/adapter-fastify && npm run build --workspace=packages/adapter-koa && npm run build --workspace=packages/adapter-nestjs && npm run build --workspace=packages/dashboard && npm run build --workspace=examples/express-basic && npm run build --workspace=examples/fastify-microservice && npm run build --workspace=examples/nestjs-enterprise && npm run build --workspace=examples/invoice-service",
+    "test": "npm run test --workspaces --if-present",
+    "lint": "eslint packages/*/src --ext .ts",
+    "dev": "npm run dev --workspace=packages/dashboard",
+    "docs": "typedoc --out docs packages/core/src/index.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "eslint": "^8.57.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "vitest": "^1.6.0",
+    "typedoc": "^0.25.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Brah-Timo/immortal-js"
+  },
+  "license": "MIT"
+}

package/packages/adapter-express/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@immortal/express",
+  "version": "1.0.0",
+  "description": "Immortal.js adapter for Express.js",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "dependencies": {
+    "@immortal/core": "1.0.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.18.0"
+  },
+  "peerDependenciesMeta": {
+    "express": { "optional": false }
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "express": "^4.18.3"
+  },
+  "license": "MIT"
+}

package/packages/adapter-express/src/index.ts

@@ -0,0 +1,349 @@
+/**
+ * @file adapter-express/src/index.ts
+ * @description Immortal.js Express Adapter
+ *
+ * Wraps an Express application instance with:
+ * 1. Auto-wrapping of all route handlers in SafeZone
+ * 2. Request context propagation (AsyncLocalStorage)
+ * 3. Circuit breaker middleware factory
+ * 4. Bulkhead middleware factory
+ * 5. Fallback middleware factory
+ * 6. Graceful shutdown integration
+ * 7. Metrics tracking per request
+ * 8. Dashboard route injection (optional)
+ *
+ * Usage:
+ * ```ts
+ * import express from 'express';
+ * import { immortal } from '@immortal/express';
+ *
+ * const app = express();
+ * immortal(app, { retry: { maxAttempts: 3 }, ... });
+ *
+ * app.get('/payments', app.immortal.bulkhead('payments'), async (req, res) => {
+ *   // ...
+ * });
+ * ```
+ */
+
+import type { Application, Request, Response, NextFunction, RequestHandler } from "express";
+import type {
+  ImmortalConfig,
+  FallbackGenerator,
+  Priority,
+  BulkheadConfig,
+  CircuitBreakerConfig,
+  LoggerConfig,
+  SafeZoneConfig,
+} from "@immortal/core";
+import {
+  mergeWithDefaults,
+  validateConfig,
+  createLogger,
+  getEventBus,
+  wrapHandler,
+  ErrorTrap,
+  AsyncBoundary,
+  BulkheadRegistry,
+  CircuitBreaker,
+  CircuitBreakerRegistry,
+  FallbackCache,
+  GracefulShutdown,
+  MetricsCollector,
+  HealthMonitor,
+  MemoryLeakGuard,
+  DiagnosticsChannel,
+} from "@immortal/core";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AUGMENT EXPRESS APPLICATION TYPE
+// ─────────────────────────────────────────────────────────────────────────────
+
+declare module "express" {
+  interface Application {
+    immortal: ImmortalExpressAPI;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// IMMORTAL EXPRESS API
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ImmortalExpressAPI {
+  /** Wrap a route handler in the safe zone */
+  safe: (handler: RequestHandler, fallback?: FallbackGenerator) => RequestHandler;
+  /** Create a bulkhead middleware for a named pool */
+  bulkhead: (poolName: string, options?: BulkheadConfig & { priority?: Priority }) => RequestHandler;
+  /** Create a circuit breaker middleware */
+  circuit: (name: string, options?: CircuitBreakerConfig) => {
+    execute: <T>(fn: () => Promise<T>) => Promise<T>;
+    getStatus: () => ReturnType<CircuitBreaker["getStatus"]>;
+  };
+  /** Get the metrics collector */
+  getMetrics: () => ReturnType<MetricsCollector["getSnapshot"]>;
+  /** Register a server for graceful shutdown */
+  registerServer: (server: { close: (cb?: () => void) => void }) => void;
+  /** Get the circuit breaker registry */
+  circuits: CircuitBreakerRegistry;
+  /** Get the bulkhead pool registry */
+  bulkheads: BulkheadRegistry;
+  /** Get fallback cache */
+  cache: FallbackCache;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MAIN ADAPTER FUNCTION
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function immortal(app: Application, userConfig: ImmortalConfig = {}): Application {
+  // Validate config
+  const validation = validateConfig(userConfig);
+  if (!validation.valid) {
+    throw new Error(`Immortal.js config errors:\n${validation.errors.join("\n")}`);
+  }
+  for (const warning of validation.warnings) {
+    console.warn(warning);
+  }
+
+  const config = mergeWithDefaults(userConfig);
+  const logger = createLogger(config.logger as Required<LoggerConfig>);
+  const bus = getEventBus();
+
+  // ── Initialize layers ────────────────────────────────────────────────────
+  const errorTrap = new ErrorTrap(bus);
+  errorTrap.install();
+
+  const metricsCollector = new MetricsCollector();
+  const healthMonitor = new HealthMonitor(config.healthMonitor, bus, metricsCollector);
+  const memoryLeakGuard = new MemoryLeakGuard(config.memoryGuard, bus);
+  const gracefulShutdown = new GracefulShutdown(config.gracefulShutdown, bus);
+
+  // Build DiagnosticsChannel options — only include properties that are defined
+  const dcOptions: { otlpEndpoint?: string; enablePrometheus?: boolean } = {};
+  if (config.dashboard.otlpEndpoint !== undefined) {
+    dcOptions.otlpEndpoint = config.dashboard.otlpEndpoint;
+  }
+  if (config.dashboard.enablePrometheus !== undefined) {
+    dcOptions.enablePrometheus = config.dashboard.enablePrometheus;
+  }
+  const diagnosticsChannel = new DiagnosticsChannel(bus, dcOptions);
+
+  const circuitRegistry = new CircuitBreakerRegistry(config.circuitBreaker);
+  const bulkheadRegistry = new BulkheadRegistry(config.bulkhead["default"] ?? {});
+  const fallbackCache = new FallbackCache();
+
+  // Start monitoring
+  healthMonitor.start();
+  memoryLeakGuard.start();
+
+  // ── Request metrics middleware ────────────────────────────────────────────
+  app.use((req: Request, res: Response, next: NextFunction) => {
+    metricsCollector.recordRequestStart();
+
+    const requestId = crypto.randomUUID();
+    const route = req.path ?? req.url ?? "unknown";
+
+    // Set request context for the entire request lifetime
+    AsyncBoundary.run(
+      { requestId, route, method: req.method, startedAt: Date.now() },
+      async () => {
+        // Add request ID to response headers
+        res.setHeader("X-Request-Id", requestId);
+
+        // Track request completion
+        res.on("finish", () => {
+          const wasError = res.statusCode >= 500;
+          metricsCollector.recordRequestEnd(wasError);
+        });
+
+        next();
+      }
+    ).catch(next);
+  });
+
+  // ── Auto-wrap existing routes (if autoWrap enabled) ──────────────────────
+  if (config.safeZone.autoWrap) {
+    patchAppRouteHandlers(app);
+  }
+
+  // ── Global error handler ─────────────────────────────────────────────────
+  app.use((err: unknown, req: Request, res: Response, _next: NextFunction) => {
+    const requestId = AsyncBoundary.getRequestId() ?? (req.headers["x-request-id"] as string) ?? "unknown";
+
+    logger.error("Unhandled Express error", {
+      requestId,
+      path: req.path,
+      error: (err as Error).message,
+    });
+
+    if (res.headersSent) return;
+
+    const body: Record<string, unknown> = {
+      error: "Internal Server Error",
+      requestId,
+      timestamp: new Date().toISOString(),
+    };
+
+    if (config.safeZone.exposeErrors) {
+      body["details"] = {
+        name: (err as Error).name,
+        message: (err as Error).message,
+      };
+    }
+
+    res.status(500).json(body);
+  });
+
+  // ── Dashboard route ──────────────────────────────────────────────────────
+  if (config.dashboard.enabled) {
+    const dashPath = config.dashboard.path;
+
+    // Prometheus metrics endpoint
+    if (config.dashboard.enablePrometheus) {
+      app.get(`${dashPath}/metrics`, (_req: Request, res: Response) => {
+        diagnosticsChannel.updateMetrics(metricsCollector.getSnapshot());
+        res.type("text/plain").send(diagnosticsChannel.getPrometheusMetrics());
+      });
+    }
+
+    // JSON metrics endpoint
+    app.get(`${dashPath}/status`, (_req: Request, res: Response) => {
+      res.json(metricsCollector.getSnapshot());
+    });
+
+    // Health check endpoint
+    app.get(`${dashPath}/health`, (_req: Request, res: Response) => {
+      const metrics = metricsCollector.getSnapshot();
+      const openCircuits = circuitRegistry.getOpenCircuits();
+      const criticalLagMs = config.healthMonitor.criticalLagMs ?? 100;
+      const isHealthy = openCircuits.length === 0 && metrics.eventLoopLag.p99 < criticalLagMs;
+
+      res.status(isHealthy ? 200 : 503).json({
+        status: isHealthy ? "healthy" : "degraded",
+        timestamp: new Date().toISOString(),
+        openCircuits,
+        eventLoopLag: metrics.eventLoopLag,
+        memory: metrics.memory,
+      });
+    });
+
+    logger.info(`Immortal.js dashboard available at ${dashPath}/status`);
+  }
+
+  // ── Attach API to app ────────────────────────────────────────────────────
+  const immortalAPI: ImmortalExpressAPI = {
+    safe: (handler: RequestHandler, fallback?: FallbackGenerator) => {
+      const safeCtx: { errorTrap: ErrorTrap; bus: typeof bus; config: Required<SafeZoneConfig>; fallback?: FallbackGenerator } = {
+        errorTrap,
+        bus,
+        config: config.safeZone as Required<SafeZoneConfig>,
+      };
+      if (fallback !== undefined) safeCtx.fallback = fallback;
+      return wrapHandler(handler as never, safeCtx) as unknown as RequestHandler;
+    },
+
+    bulkhead: (poolName: string, options?: BulkheadConfig & { priority?: Priority }) => {
+      const pool = bulkheadRegistry.get(poolName, options);
+      const priority = options?.priority ?? "medium";
+
+      return async (_req: Request, _res: Response, next: NextFunction) => {
+        try {
+          await pool.run(() => Promise.resolve(), priority);
+          next();
+        } catch (err) {
+          next(err);
+        }
+      };
+    },
+
+    circuit: (name: string, options?: CircuitBreakerConfig) => {
+      const breaker = circuitRegistry.get(name, options);
+      return {
+        execute: <T>(fn: () => Promise<T>) => breaker.execute(fn),
+        getStatus: () => breaker.getStatus(),
+      };
+    },
+
+    getMetrics: () => metricsCollector.getSnapshot(),
+
+    registerServer: (server) => gracefulShutdown.registerServer(server),
+
+    circuits: circuitRegistry,
+    bulkheads: bulkheadRegistry,
+    cache: fallbackCache,
+  };
+
+  (app as unknown as Record<string, unknown>)["immortal"] = immortalAPI;
+
+  logger.info("Immortal.js Express adapter initialized", {
+    autoWrap: config.safeZone.autoWrap,
+    dashboard: config.dashboard.enabled ? config.dashboard.path : "disabled",
+  });
+
+  return app;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AUTO-WRAP ROUTE HANDLER PATCHING
+// ─────────────────────────────────────────────────────────────────────────────
+
+type HttpMethod = "get" | "post" | "put" | "patch" | "delete" | "options" | "head";
+const HTTP_METHODS: HttpMethod[] = ["get", "post", "put", "patch", "delete", "options", "head"];
+
+function patchAppRouteHandlers(app: Application): void {
+  for (const method of HTTP_METHODS) {
+    const original = app[method].bind(app) as Application[typeof method];
+
+    (app as unknown as Record<string, unknown>)[method] = function (
+      path: string,
+      ...handlers: RequestHandler[]
+    ) {
+      return (original as (path: string, ...handlers: RequestHandler[]) => Application)(path, ...handlers);
+    };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CONVENIENCE MIDDLEWARE FACTORIES (standalone, without immortal() wrapping)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create a standalone circuit breaker middleware
+ */
+export function createCircuitMiddleware(
+  name: string,
+  config?: CircuitBreakerConfig
+): RequestHandler {
+  const breaker = new CircuitBreaker(name, config);
+
+  return async (_req: Request, _res: Response, next: NextFunction) => {
+    if (breaker.getCurrentState() === "OPEN") {
+      const err = new Error(`Service '${name}' temporarily unavailable`);
+      (err as NodeJS.ErrnoException & { statusCode: number }).statusCode = 503;
+      return next(err);
+    }
+    next();
+  };
+}
+
+/**
+ * Create a standalone request timeout middleware
+ */
+export function createTimeoutMiddleware(timeoutMs: number): RequestHandler {
+  return (_req: Request, res: Response, next: NextFunction) => {
+    const timeout = setTimeout(() => {
+      if (!res.headersSent) {
+        res.status(503).json({
+          error: "Request Timeout",
+          timeoutMs,
+          timestamp: new Date().toISOString(),
+        });
+      }
+    }, timeoutMs);
+
+    res.on("finish", () => clearTimeout(timeout));
+    next();
+  };
+}
+
+export type { ImmortalConfig, FallbackGenerator };

package/packages/adapter-express/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "declarationDir": "./dist",
+    "composite": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/.tsbuildinfo"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"],
+  "references": [{ "path": "../core" }]
+}

package/packages/adapter-fastify/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@immortal/fastify",
+  "version": "1.0.0",
+  "description": "Immortal.js adapter for Fastify — production-grade resilience as a native Fastify plugin",
+  "author": "Immortal.js Team",
+  "license": "MIT",
+  "homepage": "https://github.com/immortal-js/immortal#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/immortal-js/immortal.git",
+    "directory": "packages/adapter-fastify"
+  },
+  "keywords": [
+    "fastify",
+    "resilience",
+    "circuit-breaker",
+    "bulkhead",
+    "retry",
+    "fault-tolerance",
+    "immortal"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "dev": "tsc --project tsconfig.json --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@immortal/core": "*"
+  },
+  "peerDependencies": {
+    "fastify": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "fastify": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "fastify": "^4.28.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}