immortal-js 1.0.0

package/examples/nestjs-enterprise/app.module.ts

@@ -0,0 +1,561 @@
+/**
+ * @file examples/nestjs-enterprise/app.module.ts
+ * @description Immortal.js — NestJS Enterprise Root Module (Ultra Pro)
+ *
+ * ─── DI Strategy ────────────────────────────────────────────────────────────
+ *  tsx/esm does NOT emit decorator metadata (emitDecoratorMetadata is ignored
+ *  at runtime), so NestJS cannot resolve constructor parameter types from
+ *  TypeScript types alone.
+ *
+ *  Fix: Use explicit string injection tokens + @Inject('TOKEN') on every
+ *  constructor parameter so NestJS never needs reflect-metadata at all.
+ *
+ * ─── Architecture ───────────────────────────────────────────────────────────
+ *   IMMORTAL_RUNTIME  → singleton ImmortalRuntimeService (all primitives)
+ *   OrdersService     → injected via @Inject('IMMORTAL_RUNTIME')
+ *   PaymentsService   → injected via @Inject('IMMORTAL_RUNTIME')
+ *   All Controllers   → injected via @Inject('ORDERS_SERVICE') etc.
+ *
+ * Routes:
+ *   GET  /                    — welcome + route map
+ *   GET  /health              — full system health
+ *   GET  /orders              — list orders  (Bulkhead + Circuit)
+ *   POST /orders              — create order (Retry + Bulkhead)
+ *   GET  /payments/:id        — get payment  (Circuit + Retry)
+ *   GET  /status/circuits     — circuit breaker statuses
+ *   GET  /status/bulkheads    — bulkhead pool statuses
+ *   GET  /status/cache        — cache stats
+ *   GET  /chaos/trip/:name    — force-trip circuit (dev only)
+ *   GET  /chaos/reset         — reset all circuits (dev only)
+ */
+
+import "reflect-metadata";
+import {
+  Module,
+  Controller,
+  Get,
+  Post,
+  Body,
+  Param,
+  Inject,
+  Injectable,
+  HttpException,
+  HttpStatus,
+  type DynamicModule,
+} from "@nestjs/common";
+
+import {
+  CircuitBreaker,
+  BulkheadPool,
+  FallbackCache,
+  GracefulShutdown,
+  MetricsCollector,
+  HealthMonitor,
+  MemoryLeakGuard,
+  ErrorTrap,
+  withRetry,
+  withTimeout,
+  getEventBus,
+  mergeWithDefaults,
+} from "@immortal/core";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// INJECTION TOKENS  (string-based — works without reflect-metadata)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const IMMORTAL_RUNTIME = "IMMORTAL_RUNTIME";
+export const ORDERS_SVC       = "ORDERS_SERVICE";
+export const PAYMENTS_SVC     = "PAYMENTS_SERVICE";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DOMAIN TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface Order {
+  id: string;
+  productId: string;
+  quantity: number;
+  amount: number;
+  status: "pending" | "confirmed" | "failed";
+  createdAt: string;
+}
+
+export interface CreateOrderDto {
+  productId: string;
+  quantity: number;
+  amount: number;
+}
+
+export interface PaymentResult {
+  transactionId: string;
+  status: "settled" | "pending" | "failed";
+  amount?: number;
+  processedAt?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// IMMORTAL RUNTIME SERVICE
+//   All Immortal.js primitives live here.
+//   Registered with token IMMORTAL_RUNTIME → no metadata needed.
+// ─────────────────────────────────────────────────────────────────────────────
+
+@Injectable()
+export class ImmortalRuntimeService {
+  readonly circuitOrders: CircuitBreaker;
+  readonly circuitPayment: CircuitBreaker;
+  readonly bulkheadOrders: BulkheadPool;
+  readonly bulkheadPayment: BulkheadPool;
+  readonly cache: FallbackCache<unknown>;
+  readonly metrics: MetricsCollector;
+  private readonly healthMonitor: HealthMonitor;
+  private readonly memoryGuard: MemoryLeakGuard;
+  private readonly gracefulShutdown: GracefulShutdown;
+
+  constructor() {
+    const config = mergeWithDefaults({});
+    const bus    = getEventBus();
+
+    new ErrorTrap(bus).install();
+
+    this.circuitOrders = new CircuitBreaker("order-db", {
+      threshold: 5, cooldownMs: 15_000, slidingWindowSize: 20,
+    });
+    this.circuitPayment = new CircuitBreaker("payment-gateway", {
+      threshold: 3, cooldownMs: 30_000, slidingWindowSize: 10,
+    });
+
+    this.bulkheadOrders  = new BulkheadPool("orders",   { maxConcurrent: 20, maxQueueSize: 100, queueTimeoutMs: 10_000 });
+    this.bulkheadPayment = new BulkheadPool("payments", { maxConcurrent: 10, maxQueueSize:  30, queueTimeoutMs: 15_000 });
+
+    this.cache   = new FallbackCache<unknown>({ maxSize: 500, defaultTtlMs: 30_000 });
+    this.metrics = new MetricsCollector();
+
+    this.healthMonitor = new HealthMonitor(config.healthMonitor, bus, this.metrics);
+    this.memoryGuard   = new MemoryLeakGuard(
+      { checkIntervalMs: 15_000, restartThresholdMb: 1_500 },
+      bus
+    );
+    this.gracefulShutdown = new GracefulShutdown(
+      { timeoutMs: 25_000, signals: ["SIGTERM", "SIGINT"] },
+      bus
+    );
+
+    this.healthMonitor.start();
+    this.memoryGuard.start();
+    void this.gracefulShutdown;
+  }
+
+  getSnapshot()    { return this.metrics.getSnapshot(); }
+  getAllCircuits()  {
+    return {
+      "order-db":       this.circuitOrders.getStatus(),
+      "payment-gateway": this.circuitPayment.getStatus(),
+    };
+  }
+  getAllBulkheads() {
+    return {
+      orders:   this.bulkheadOrders.getStatus(),
+      payments: this.bulkheadPayment.getStatus(),
+    };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ORDERS SERVICE
+// ─────────────────────────────────────────────────────────────────────────────
+
+@Injectable()
+export class OrdersService {
+  constructor(
+    @Inject(IMMORTAL_RUNTIME)
+    private readonly runtime: ImmortalRuntimeService
+  ) {}
+
+  async findAll(): Promise<{ orders: Order[]; count: number }> {
+    return this.runtime.bulkheadOrders.run(
+      () =>
+        this.runtime.circuitOrders.execute(
+          async () => {
+            await sleep(20 + rnd(80));
+            if (Math.random() < 0.04) throw new Error("DB read timeout");
+            return {
+              orders: [
+                makeOrder("ord-0001", "SKU-ALPHA", 2,  49.99),
+                makeOrder("ord-0002", "SKU-BETA",  1,  99.99),
+                makeOrder("ord-0003", "SKU-GAMMA", 5,   9.99),
+                makeOrder("ord-0004", "SKU-DELTA", 3, 199.99),
+              ],
+              count: 4,
+            };
+          },
+          () => ({ orders: [] as Order[], count: 0 })
+        ),
+      "medium"
+    );
+  }
+
+  async create(dto: CreateOrderDto): Promise<Order> {
+    return withRetry(
+      () =>
+        this.runtime.bulkheadOrders.run(async () => {
+          await sleep(50 + rnd(100));
+          if (Math.random() < 0.06) throw new Error("Transient write error");
+          const order = makeOrder(
+            `ord-${Date.now()}`,
+            dto.productId,
+            dto.quantity,
+            dto.amount
+          );
+          this.runtime.cache.set(`order:${order.id}`, order);
+          return order;
+        }, "high"),
+      { maxAttempts: 3, baseDelayMs: 200, maxDelayMs: 2_000 }
+    );
+  }
+
+  async checkInventory(productId: string): Promise<{ stock: number }> {
+    return withTimeout(
+      () =>
+        this.runtime.circuitOrders.execute(
+          async () => {
+            await sleep(20 + rnd(60));
+            if (Math.random() < 0.08) throw new Error("Inventory service unavailable");
+            return { stock: Math.floor(Math.random() * 200) + 1 };
+          },
+          () => ({ stock: 0 })
+        ),
+      5_000,
+      `inventory-check-${productId}`
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PAYMENTS SERVICE
+// ─────────────────────────────────────────────────────────────────────────────
+
+@Injectable()
+export class PaymentsService {
+  constructor(
+    @Inject(IMMORTAL_RUNTIME)
+    private readonly runtime: ImmortalRuntimeService
+  ) {}
+
+  async getPayment(id: string): Promise<PaymentResult> {
+    const fallback = (): PaymentResult => ({
+      transactionId: `queued-${Date.now()}`,
+      status: "pending" as const,
+    });
+    return this.runtime.circuitPayment.execute(
+      () =>
+        withRetry(
+          async (): Promise<PaymentResult> => {
+            await sleep(100 + rnd(200));
+            if (Math.random() < 0.08) throw new Error("Payment gateway timeout");
+            return {
+              transactionId: id,
+              status: "settled" as const,
+              amount: Math.round(Math.random() * 10_000) / 100,
+              processedAt: new Date().toISOString(),
+            };
+          },
+          { maxAttempts: 2, baseDelayMs: 500, maxDelayMs: 3_000 }
+        ),
+      fallback
+    );
+  }
+
+  async charge(orderId: string, amount: number): Promise<PaymentResult> {
+    const fallback = (): PaymentResult => ({
+      transactionId: `queued-${orderId}`,
+      status: "pending" as const,
+    });
+    return this.runtime.bulkheadPayment.run(
+      () =>
+        this.runtime.circuitPayment.execute(
+          () =>
+            withRetry(
+              () =>
+                withTimeout(
+                  async (): Promise<PaymentResult> => {
+                    await sleep(100 + rnd(200));
+                    if (Math.random() < 0.05) throw new Error("Charge failed");
+                    return {
+                      transactionId: `txn-${orderId}-${Date.now()}`,
+                      status: "settled" as const,
+                      amount,
+                      processedAt: new Date().toISOString(),
+                    };
+                  },
+                  10_000,
+                  "payment-charge"
+                ),
+              { maxAttempts: 2, baseDelayMs: 300 }
+            ),
+          fallback
+        ),
+      "high"
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CONTROLLERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Root controller — GET / returns a route map */
+@Controller()
+export class AppController {
+  @Get()
+  index() {
+    return {
+      name: "Immortal.js NestJS Enterprise API",
+      version: "1.0.0",
+      status: "running",
+      timestamp: new Date().toISOString(),
+      routes: {
+        "GET  /":                   "This route map",
+        "GET  /health":             "Full system health snapshot",
+        "GET  /orders":             "List orders  [Bulkhead + Circuit]",
+        "POST /orders":             "Create order [Retry + Bulkhead]",
+        "GET  /payments/:id":       "Get payment  [Circuit + Retry]",
+        "GET  /status/circuits":    "All circuit breaker statuses",
+        "GET  /status/bulkheads":   "All bulkhead pool statuses",
+        "GET  /status/cache":       "Cache stats",
+        "GET  /chaos/trip/:name":   "Force-trip a circuit (dev only)",
+        "GET  /chaos/reset":        "Reset all circuits (dev only)",
+      },
+    };
+  }
+}
+
+@Controller("orders")
+export class OrdersController {
+  constructor(
+    @Inject(ORDERS_SVC)
+    private readonly ordersService: OrdersService
+  ) {}
+
+  /** GET /orders */
+  @Get()
+  findAll() {
+    return this.ordersService.findAll();
+  }
+
+  /** POST /orders  Body: { productId, quantity, amount } */
+  @Post()
+  async create(@Body() dto: CreateOrderDto) {
+    if (!dto.productId?.trim())
+      throw new HttpException("productId is required", HttpStatus.BAD_REQUEST);
+    if (!dto.quantity || dto.quantity < 1)
+      throw new HttpException("quantity must be ≥ 1", HttpStatus.BAD_REQUEST);
+    if (!dto.amount || dto.amount <= 0)
+      throw new HttpException("amount must be > 0", HttpStatus.BAD_REQUEST);
+    return this.ordersService.create(dto);
+  }
+}
+
+@Controller("payments")
+export class PaymentsController {
+  constructor(
+    @Inject(PAYMENTS_SVC)
+    private readonly paymentsService: PaymentsService
+  ) {}
+
+  /** GET /payments/:id */
+  @Get(":id")
+  getPayment(@Param("id") id: string) {
+    return this.paymentsService.getPayment(id);
+  }
+}
+
+@Controller("health")
+export class HealthController {
+  constructor(
+    @Inject(IMMORTAL_RUNTIME)
+    private readonly runtime: ImmortalRuntimeService
+  ) {}
+
+  @Get()
+  getHealth() {
+    const snap = this.runtime.getSnapshot();
+    const bk   = this.runtime.getAllBulkheads();
+
+    return {
+      status: "healthy",
+      uptime:   Math.round(process.uptime()),
+      memoryMb: {
+        heapUsed: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
+        rss:      Math.round(process.memoryUsage().rss / 1024 / 1024),
+      },
+      eventLoop:  snap.eventLoopLag,
+      circuits:   this.runtime.getAllCircuits(),
+      bulkheads: {
+        orders:   { active: bk.orders.active,   queued: bk.orders.queued   },
+        payments: { active: bk.payments.active, queued: bk.payments.queued },
+      },
+    };
+  }
+}
+
+@Controller("status")
+export class StatusController {
+  constructor(
+    @Inject(IMMORTAL_RUNTIME)
+    private readonly runtime: ImmortalRuntimeService
+  ) {}
+
+  @Get("circuits")
+  circuits() { return this.runtime.getAllCircuits(); }
+
+  @Get("bulkheads")
+  bulkheads() { return this.runtime.getAllBulkheads(); }
+
+  @Get("cache")
+  cacheStats() {
+    const snap = this.runtime.getSnapshot();
+    return {
+      eventLoopLag: snap.eventLoopLag,
+      memory: process.memoryUsage(),
+      uptime: process.uptime(),
+    };
+  }
+}
+
+@Controller("chaos")
+export class ChaosController {
+  constructor(
+    @Inject(IMMORTAL_RUNTIME)
+    private readonly runtime: ImmortalRuntimeService
+  ) {}
+
+  @Get("trip/:name")
+  trip(@Param("name") name: string) {
+    if (process.env["NODE_ENV"] === "production")
+      throw new HttpException("Chaos disabled in production", HttpStatus.FORBIDDEN);
+
+    const circuits: Record<string, CircuitBreaker> = {
+      "order-db":       this.runtime.circuitOrders,
+      "payment-gateway": this.runtime.circuitPayment,
+    };
+    const cb = circuits[name];
+    if (!cb)
+      throw new HttpException(
+        `Unknown circuit '${name}'. Known: ${Object.keys(circuits).join(", ")}`,
+        HttpStatus.NOT_FOUND
+      );
+    cb.forceState("OPEN");
+    return { message: `Circuit '${name}' forced OPEN`, state: cb.getStatus().state };
+  }
+
+  @Get("reset")
+  reset() {
+    if (process.env["NODE_ENV"] === "production")
+      throw new HttpException("Chaos disabled in production", HttpStatus.FORBIDDEN);
+    this.runtime.circuitOrders.forceState("CLOSED");
+    this.runtime.circuitPayment.forceState("CLOSED");
+    return {
+      message: "All circuits reset to CLOSED",
+      circuits: this.runtime.getAllCircuits(),
+    };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// IMMORTAL CORE MODULE
+//   Provides ImmortalRuntimeService, OrdersService, PaymentsService.
+//   All providers use explicit string tokens + useFactory so NestJS never
+//   needs to resolve types from reflect-metadata.
+// ─────────────────────────────────────────────────────────────────────────────
+
+@Module({
+  providers: [
+    // ── Singleton runtime (all Immortal.js primitives) ─────────────────────
+    {
+      provide: IMMORTAL_RUNTIME,
+      useFactory: () => new ImmortalRuntimeService(),
+    },
+    // ── Domain services (explicitly injected via factory) ──────────────────
+    {
+      provide: ORDERS_SVC,
+      useFactory: (runtime: ImmortalRuntimeService) => new OrdersService(runtime),
+      inject: [IMMORTAL_RUNTIME],
+    },
+    {
+      provide: PAYMENTS_SVC,
+      useFactory: (runtime: ImmortalRuntimeService) => new PaymentsService(runtime),
+      inject: [IMMORTAL_RUNTIME],
+    },
+  ],
+  exports: [IMMORTAL_RUNTIME, ORDERS_SVC, PAYMENTS_SVC],
+})
+export class ImmortalCoreModule {
+  static forRoot(): DynamicModule {
+    return {
+      module: ImmortalCoreModule,
+      global: true,
+      providers: [
+        {
+          provide: IMMORTAL_RUNTIME,
+          useFactory: () => new ImmortalRuntimeService(),
+        },
+        {
+          provide: ORDERS_SVC,
+          useFactory: (runtime: ImmortalRuntimeService) => new OrdersService(runtime),
+          inject: [IMMORTAL_RUNTIME],
+        },
+        {
+          provide: PAYMENTS_SVC,
+          useFactory: (runtime: ImmortalRuntimeService) => new PaymentsService(runtime),
+          inject: [IMMORTAL_RUNTIME],
+        },
+      ],
+      exports: [IMMORTAL_RUNTIME, ORDERS_SVC, PAYMENTS_SVC],
+    };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ROOT MODULE
+// ─────────────────────────────────────────────────────────────────────────────
+
+@Module({
+  imports: [ImmortalCoreModule.forRoot()],
+  controllers: [
+    AppController,
+    OrdersController,
+    PaymentsController,
+    HealthController,
+    StatusController,
+    ChaosController,
+  ],
+})
+export class AppModule {}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// UTILITIES
+// ─────────────────────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function rnd(max: number): number {
+  return Math.random() * max;
+}
+
+function makeOrder(
+  id: string,
+  productId: string,
+  quantity: number,
+  amount: number
+): Order {
+  return {
+    id,
+    productId,
+    quantity,
+    amount,
+    status: "confirmed",
+    createdAt: new Date().toISOString(),
+  };
+}

package/examples/nestjs-enterprise/main.ts

@@ -0,0 +1,67 @@
+/**
+ * @file examples/nestjs-enterprise/main.ts
+ * @description Immortal.js — NestJS Enterprise Bootstrap
+ *
+ * Run:   npm run dev           (tsx ESM — Windows/Linux/macOS)
+ * Build: npm run build
+ * Start: PORT=3000 npm start
+ *
+ * DI Note:
+ *   tsx ESM does NOT emit decorator metadata even with emitDecoratorMetadata:true.
+ *   All injection uses string tokens + @Inject('TOKEN') — no metadata needed.
+ */
+
+import "reflect-metadata";
+import { NestFactory } from "@nestjs/core";
+import { AppModule } from "./app.module.js";
+
+async function bootstrap(): Promise<void> {
+  const app = await NestFactory.create(AppModule, {
+    logger: ["log", "error", "warn"],
+    bodyParser: true,
+  });
+
+  app.enableCors({
+    origin: "*",
+    methods: ["GET", "POST", "PATCH", "DELETE", "OPTIONS"],
+    allowedHeaders: ["Content-Type", "Authorization"],
+  });
+  app.enableShutdownHooks();
+
+  const PORT = parseInt(process.env["PORT"] ?? "3000", 10);
+  await app.listen(PORT, "0.0.0.0");
+
+  console.log(`
+╔══════════════════════════════════════════════════════════════════╗
+║      Immortal.js — NestJS Enterprise Example  🚀  Ultra Pro      ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Server         →  http://localhost:${PORT}/                       ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Routes                                                           ║
+║  GET  /                   Route map                               ║
+║  GET  /health             System health snapshot                  ║
+║  GET  /orders             List orders  [Bulkhead + Circuit]       ║
+║  POST /orders             Create order [Retry + Bulkhead]         ║
+║  GET  /payments/:id       Get payment  [Circuit + Retry]          ║
+║  GET  /status/circuits    Circuit breaker statuses                ║
+║  GET  /status/bulkheads   Bulkhead pool statuses                  ║
+║  GET  /chaos/trip/:name   Force-trip circuit (dev only)           ║
+║  GET  /chaos/reset        Reset all circuits (dev only)           ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Immortal.js Resilience Patterns                                  ║
+║  ● CircuitBreaker  order-db, payment-gateway                      ║
+║  ● BulkheadPool    orders (max 20), payments (max 10)             ║
+║  ● withRetry       exponential back-off on transient errors       ║
+║  ● withTimeout     hard deadline on external ops (5s / 10s)       ║
+║  ● GracefulShutdown SIGTERM/SIGINT → drain → close                ║
+║  ● MemoryLeakGuard  restart at 1500 MB heap                       ║
+╠══════════════════════════════════════════════════════════════════╣
+║  DI Strategy: string tokens + @Inject() — no reflect-metadata     ║
+╚══════════════════════════════════════════════════════════════════╝
+`);
+}
+
+bootstrap().catch((err: unknown) => {
+  console.error("Fatal startup error:", err);
+  process.exit(1);
+});

package/examples/nestjs-enterprise/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "immortal-nestjs-enterprise-example",
+  "version": "1.0.0",
+  "description": "Immortal.js — NestJS enterprise example with DI decorators, interceptors, and resilience",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node --import tsx/esm --no-warnings main.ts",
+    "start": "node dist/main.js",
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@immortal/core": "*",
+    "@immortal/nestjs": "*",
+    "@nestjs/common": "^10.3.0",
+    "@nestjs/core": "^10.3.0",
+    "@nestjs/platform-express": "^10.3.0",
+    "reflect-metadata": "^0.2.1",
+    "rxjs": "^7.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}

package/examples/nestjs-enterprise/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "strict": true,
+    "strictNullChecks": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "./"
+  },
+  "include": ["main.ts", "app.module.ts"],
+  "exclude": ["node_modules", "dist"]
+}