@saga-bus/express 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dean Foran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# @saga-bus/express
+
+Express.js integration for saga-bus with middleware, health checks, and graceful shutdown.
+
+## Installation
+
+```bash
+npm install @saga-bus/express express
+# or
+pnpm add @saga-bus/express express
+```
+
+## Features
+
+- **Bus Middleware**: Attaches bus instance to `req.bus`
+- **Correlation ID**: Extract or generate correlation IDs from headers
+- **Health Checks**: Ready-to-use health and readiness endpoints
+- **Error Handler**: Saga-specific error handling middleware
+- **Graceful Shutdown**: Clean shutdown with bus draining
+
+## Quick Start
+
+```typescript
+import express from "express";
+import { createBus } from "@saga-bus/core";
+import {
+  sagaBusMiddleware,
+  sagaErrorHandler,
+  createHealthRouter,
+  setupGracefulShutdown,
+} from "@saga-bus/express";
+
+const bus = createBus({ /* config */ });
+await bus.start();
+
+const app = express();
+
+// Attach bus to requests
+app.use(sagaBusMiddleware({ bus }));
+
+// Health check endpoint
+app.use(createHealthRouter({ bus }));
+
+// Your routes
+app.post("/orders", async (req, res) => {
+  await req.bus.publish({
+    type: "CreateOrder",
+    payload: req.body,
+  });
+  res.json({ correlationId: req.correlationId });
+});
+
+// Error handler (must be last)
+app.use(sagaErrorHandler());
+
+const server = app.listen(3000);
+
+// Graceful shutdown
+setupGracefulShutdown(server, { bus });
+```
+
+## API Reference
+
+### sagaBusMiddleware(options)
+
+Creates middleware that attaches the bus instance to requests.
+
+```typescript
+interface SagaBusExpressOptions {
+  /** The bus instance to attach */
+  bus: Bus;
+
+  /** Header name for correlation ID (default: "x-correlation-id") */
+  correlationIdHeader?: string;
+
+  /** Whether to generate correlation ID if not present (default: true) */
+  generateCorrelationId?: boolean;
+
+  /** Custom correlation ID generator */
+  correlationIdGenerator?: () => string;
+}
+```
+
+Example:
+
+```typescript
+app.use(sagaBusMiddleware({
+  bus,
+  correlationIdHeader: "x-request-id",
+  correlationIdGenerator: () => `req-${Date.now()}`,
+}));
+```
+
+### sagaErrorHandler()
+
+Error handler middleware for saga-related errors.
+
+- **SagaTimeoutError**: Returns 408 Request Timeout
+- **ConcurrencyError**: Returns 409 Conflict
+
+```typescript
+app.use(sagaErrorHandler());
+```
+
+### createHealthRouter(options)
+
+Creates a health check router.
+
+```typescript
+interface HealthCheckOptions {
+  /** The bus instance to check */
+  bus: Bus;
+
+  /** Path for health endpoint (default: "/health") */
+  path?: string;
+
+  /** Additional health checks */
+  checks?: Array<{
+    name: string;
+    check: () => Promise<boolean>;
+  }>;
+}
+```
+
+Example:
+
+```typescript
+app.use(createHealthRouter({
+  bus,
+  path: "/health",
+  checks: [
+    {
+      name: "database",
+      check: async () => {
+        await pool.query("SELECT 1");
+        return true;
+      },
+    },
+  ],
+}));
+```
+
+Response format:
+
+```json
+{
+  "status": "healthy",
+  "timestamp": "2024-01-01T00:00:00.000Z",
+  "checks": {
+    "bus": { "status": "pass" },
+    "database": { "status": "pass" }
+  }
+}
+```
+
+### createReadinessRouter(options)
+
+Same as `createHealthRouter` but defaults to `/ready` path.
+
+```typescript
+app.use(createReadinessRouter({ bus }));
+```
+
+### setupGracefulShutdown(server, options)
+
+Sets up graceful shutdown with bus draining.
+
+```typescript
+interface GracefulShutdownOptions {
+  /** The bus instance to drain */
+  bus: Bus;
+
+  /** Timeout for graceful shutdown in ms (default: 30000) */
+  timeoutMs?: number;
+
+  /** Callback before shutdown starts */
+  onShutdownStart?: () => void | Promise<void>;
+
+  /** Callback after shutdown completes */
+  onShutdownComplete?: () => void | Promise<void>;
+}
+```
+
+Example:
+
+```typescript
+setupGracefulShutdown(server, {
+  bus,
+  timeoutMs: 60000,
+  onShutdownStart: async () => {
+    console.log("Stopping background jobs...");
+  },
+  onShutdownComplete: async () => {
+    await pool.end();
+    console.log("Cleanup complete");
+  },
+});
+```
+
+## TypeScript Support
+
+The package extends Express types to add `bus` and `correlationId` to requests:
+
+```typescript
+// In your route handlers
+app.post("/orders", async (req, res) => {
+  // req.bus is typed as Bus
+  await req.bus.publish(message);
+
+  // req.correlationId is typed as string | undefined
+  console.log(`Processing ${req.correlationId}`);
+});
+```
+
+## Example: Complete Application
+
+```typescript
+import express from "express";
+import { createBus, InMemoryTransport, InMemorySagaStore } from "@saga-bus/core";
+import {
+  sagaBusMiddleware,
+  sagaErrorHandler,
+  createHealthRouter,
+  createReadinessRouter,
+  setupGracefulShutdown,
+} from "@saga-bus/express";
+
+// Create bus
+const bus = createBus({
+  transport: new InMemoryTransport(),
+  store: new InMemorySagaStore(),
+});
+
+await bus.start();
+
+// Create Express app
+const app = express();
+app.use(express.json());
+
+// Saga bus middleware
+app.use(sagaBusMiddleware({ bus }));
+
+// Health endpoints
+app.use(createHealthRouter({ bus }));
+app.use(createReadinessRouter({ bus }));
+
+// Routes
+app.post("/messages", async (req, res) => {
+  await req.bus.publish({
+    type: req.body.type,
+    payload: req.body.payload,
+  });
+  res.json({ success: true, correlationId: req.correlationId });
+});
+
+// Error handler (must be last middleware)
+app.use(sagaErrorHandler());
+
+// Start server
+const server = app.listen(3000, () => {
+  console.log("Server running on port 3000");
+});
+
+// Graceful shutdown
+setupGracefulShutdown(server, {
+  bus,
+  timeoutMs: 30000,
+});
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,176 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createHealthRouter: () => createHealthRouter,
+  createReadinessRouter: () => createReadinessRouter,
+  sagaBusMiddleware: () => sagaBusMiddleware,
+  sagaErrorHandler: () => sagaErrorHandler,
+  setupGracefulShutdown: () => setupGracefulShutdown
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/middleware.ts
+var import_crypto = require("crypto");
+function sagaBusMiddleware(options) {
+  const {
+    bus,
+    correlationIdHeader = "x-correlation-id",
+    generateCorrelationId = true,
+    correlationIdGenerator = import_crypto.randomUUID
+  } = options;
+  return (req, res, next) => {
+    req.bus = bus;
+    let correlationId = req.headers[correlationIdHeader.toLowerCase()];
+    if (!correlationId && generateCorrelationId) {
+      correlationId = correlationIdGenerator();
+    }
+    if (correlationId) {
+      req.correlationId = correlationId;
+      res.setHeader(correlationIdHeader, correlationId);
+    }
+    next();
+  };
+}
+function sagaErrorHandler() {
+  return (err, req, res, next) => {
+    if (err.name === "SagaTimeoutError") {
+      res.status(408).json({
+        error: "Saga Timeout",
+        message: err.message,
+        correlationId: req.correlationId
+      });
+      return;
+    }
+    if (err.name === "ConcurrencyError") {
+      res.status(409).json({
+        error: "Concurrency Conflict",
+        message: err.message,
+        correlationId: req.correlationId
+      });
+      return;
+    }
+    next(err);
+  };
+}
+
+// src/health.ts
+var import_express = require("express");
+function createHealthRouter(options) {
+  const {
+    bus,
+    path = "/health",
+    checks = []
+  } = options;
+  const router = (0, import_express.Router)();
+  router.get(path, async (_req, res) => {
+    const healthStatus = {
+      status: "healthy",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      checks: {}
+    };
+    try {
+      if (bus) {
+        healthStatus.checks.bus = {
+          status: "pass"
+        };
+      } else {
+        throw new Error("Bus not available");
+      }
+    } catch (error) {
+      healthStatus.status = "unhealthy";
+      healthStatus.checks.bus = {
+        status: "fail",
+        message: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+    for (const check of checks) {
+      try {
+        const result = await check.check();
+        healthStatus.checks[check.name] = {
+          status: result ? "pass" : "fail"
+        };
+        if (!result) {
+          healthStatus.status = "unhealthy";
+        }
+      } catch (error) {
+        healthStatus.status = "unhealthy";
+        healthStatus.checks[check.name] = {
+          status: "fail",
+          message: error instanceof Error ? error.message : "Unknown error"
+        };
+      }
+    }
+    const statusCode = healthStatus.status === "healthy" ? 200 : 503;
+    res.status(statusCode).json(healthStatus);
+  });
+  return router;
+}
+function createReadinessRouter(options) {
+  return createHealthRouter({
+    ...options,
+    path: options.path ?? "/ready"
+  });
+}
+
+// src/index.ts
+function setupGracefulShutdown(server, options) {
+  const {
+    bus,
+    timeoutMs = 3e4,
+    onShutdownStart,
+    onShutdownComplete
+  } = options;
+  const shutdown = async (signal) => {
+    console.log(`Received ${signal}, starting graceful shutdown...`);
+    if (onShutdownStart) {
+      await onShutdownStart();
+    }
+    const timeout = setTimeout(() => {
+      console.error("Graceful shutdown timeout, forcing exit");
+      process.exit(1);
+    }, timeoutMs);
+    try {
+      server.close();
+      await bus.stop();
+      clearTimeout(timeout);
+      if (onShutdownComplete) {
+        await onShutdownComplete();
+      }
+      console.log("Graceful shutdown complete");
+      process.exit(0);
+    } catch (error) {
+      console.error("Error during graceful shutdown:", error);
+      process.exit(1);
+    }
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createHealthRouter,
+  createReadinessRouter,
+  sagaBusMiddleware,
+  sagaErrorHandler,
+  setupGracefulShutdown
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/middleware.ts","../src/health.ts"],"sourcesContent":["export { sagaBusMiddleware, sagaErrorHandler } from \"./middleware.js\";\nexport { createHealthRouter, createReadinessRouter } from \"./health.js\";\nexport type {\n  SagaBusExpressOptions,\n  HealthCheckOptions,\n  GracefulShutdownOptions,\n} from \"./types.js\";\nexport type { HealthStatus } from \"./health.js\";\n\n// Re-export graceful shutdown helper\nimport type { Server } from \"http\";\nimport type { GracefulShutdownOptions } from \"./types.js\";\n\n/**\n * Sets up graceful shutdown for Express server with bus drain.\n */\nexport function setupGracefulShutdown(\n  server: Server,\n  options: GracefulShutdownOptions\n): void {\n  const {\n    bus,\n    timeoutMs = 30000,\n    onShutdownStart,\n    onShutdownComplete,\n  } = options;\n\n  const shutdown = async (signal: string) => {\n    console.log(`Received ${signal}, starting graceful shutdown...`);\n\n    if (onShutdownStart) {\n      await onShutdownStart();\n    }\n\n    // Set shutdown timeout\n    const timeout = setTimeout(() => {\n      console.error(\"Graceful shutdown timeout, forcing exit\");\n      process.exit(1);\n    }, timeoutMs);\n\n    try {\n      // Stop accepting new connections\n      server.close();\n\n      // Stop the bus (drains workers)\n      await bus.stop();\n\n      clearTimeout(timeout);\n\n      if (onShutdownComplete) {\n        await onShutdownComplete();\n      }\n\n      console.log(\"Graceful shutdown complete\");\n      process.exit(0);\n    } catch (error) {\n      console.error(\"Error during graceful shutdown:\", error);\n      process.exit(1);\n    }\n  };\n\n  process.on(\"SIGTERM\", () => shutdown(\"SIGTERM\"));\n  process.on(\"SIGINT\", () => shutdown(\"SIGINT\"));\n}\n","import type { Request, Response, NextFunction, RequestHandler, ErrorRequestHandler } from \"express\";\nimport { randomUUID } from \"crypto\";\nimport type { SagaBusExpressOptions } from \"./types.js\";\n\n/**\n * Creates middleware that attaches the bus instance to requests.\n */\nexport function sagaBusMiddleware(options: SagaBusExpressOptions): RequestHandler {\n  const {\n    bus,\n    correlationIdHeader = \"x-correlation-id\",\n    generateCorrelationId = true,\n    correlationIdGenerator = randomUUID,\n  } = options;\n\n  return (req: Request, res: Response, next: NextFunction) => {\n    // Attach bus to request\n    req.bus = bus;\n\n    // Extract or generate correlation ID\n    let correlationId = req.headers[correlationIdHeader.toLowerCase()] as string | undefined;\n\n    if (!correlationId && generateCorrelationId) {\n      correlationId = correlationIdGenerator();\n    }\n\n    if (correlationId) {\n      req.correlationId = correlationId;\n      // Also set on response for tracing\n      res.setHeader(correlationIdHeader, correlationId);\n    }\n\n    next();\n  };\n}\n\n/**\n * Error handler middleware for saga-related errors.\n */\nexport function sagaErrorHandler(): ErrorRequestHandler {\n  return (err: Error, req: Request, res: Response, next: NextFunction) => {\n    // Check if it's a saga-related error\n    if (err.name === \"SagaTimeoutError\") {\n      res.status(408).json({\n        error: \"Saga Timeout\",\n        message: err.message,\n        correlationId: req.correlationId,\n      });\n      return;\n    }\n\n    if (err.name === \"ConcurrencyError\") {\n      res.status(409).json({\n        error: \"Concurrency Conflict\",\n        message: err.message,\n        correlationId: req.correlationId,\n      });\n      return;\n    }\n\n    // Pass to default error handler\n    next(err);\n  };\n}\n","import type { Request, Response, Router } from \"express\";\nimport { Router as createRouter } from \"express\";\nimport type { HealthCheckOptions } from \"./types.js\";\n\nexport interface HealthStatus {\n  status: \"healthy\" | \"unhealthy\";\n  timestamp: string;\n  checks: Record<string, {\n    status: \"pass\" | \"fail\";\n    message?: string;\n  }>;\n}\n\n/**\n * Creates a health check router for the bus.\n */\nexport function createHealthRouter(options: HealthCheckOptions): Router {\n  const {\n    bus,\n    path = \"/health\",\n    checks = [],\n  } = options;\n\n  const router = createRouter();\n\n  router.get(path, async (_req: Request, res: Response) => {\n    const healthStatus: HealthStatus = {\n      status: \"healthy\",\n      timestamp: new Date().toISOString(),\n      checks: {},\n    };\n\n    // Check bus status\n    try {\n      // Simple check - bus exists and is accessible\n      if (bus) {\n        healthStatus.checks.bus = {\n          status: \"pass\",\n        };\n      } else {\n        throw new Error(\"Bus not available\");\n      }\n    } catch (error) {\n      healthStatus.status = \"unhealthy\";\n      healthStatus.checks.bus = {\n        status: \"fail\",\n        message: error instanceof Error ? error.message : \"Unknown error\",\n      };\n    }\n\n    // Run additional checks\n    for (const check of checks) {\n      try {\n        const result = await check.check();\n        healthStatus.checks[check.name] = {\n          status: result ? \"pass\" : \"fail\",\n        };\n        if (!result) {\n          healthStatus.status = \"unhealthy\";\n        }\n      } catch (error) {\n        healthStatus.status = \"unhealthy\";\n        healthStatus.checks[check.name] = {\n          status: \"fail\",\n          message: error instanceof Error ? error.message : \"Unknown error\",\n        };\n      }\n    }\n\n    const statusCode = healthStatus.status === \"healthy\" ? 200 : 503;\n    res.status(statusCode).json(healthStatus);\n  });\n\n  return router;\n}\n\n/**\n * Creates a readiness check router.\n */\nexport function createReadinessRouter(options: HealthCheckOptions): Router {\n  return createHealthRouter({\n    ...options,\n    path: options.path ?? \"/ready\",\n  });\n}\n"],"mappings":"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","names":["createRouter"]}

package/dist/index.d.cts

@@ -0,0 +1,76 @@
+import { RequestHandler, ErrorRequestHandler, Router } from 'express';
+import { Bus } from '@saga-bus/core';
+import { Server } from 'http';
+
+declare global {
+    namespace Express {
+        interface Request {
+            bus?: Bus;
+            correlationId?: string;
+        }
+    }
+}
+interface SagaBusExpressOptions {
+    /** The bus instance to attach */
+    bus: Bus;
+    /** Header name for correlation ID */
+    correlationIdHeader?: string;
+    /** Whether to generate correlation ID if not present */
+    generateCorrelationId?: boolean;
+    /** Custom correlation ID generator */
+    correlationIdGenerator?: () => string;
+}
+interface HealthCheckOptions {
+    /** The bus instance to check */
+    bus: Bus;
+    /** Path for health endpoint */
+    path?: string;
+    /** Additional health checks */
+    checks?: Array<{
+        name: string;
+        check: () => Promise<boolean>;
+    }>;
+}
+interface GracefulShutdownOptions {
+    /** The bus instance to drain */
+    bus: Bus;
+    /** Timeout for graceful shutdown in ms */
+    timeoutMs?: number;
+    /** Callback before shutdown starts */
+    onShutdownStart?: () => void | Promise<void>;
+    /** Callback after shutdown completes */
+    onShutdownComplete?: () => void | Promise<void>;
+}
+
+/**
+ * Creates middleware that attaches the bus instance to requests.
+ */
+declare function sagaBusMiddleware(options: SagaBusExpressOptions): RequestHandler;
+/**
+ * Error handler middleware for saga-related errors.
+ */
+declare function sagaErrorHandler(): ErrorRequestHandler;
+
+interface HealthStatus {
+    status: "healthy" | "unhealthy";
+    timestamp: string;
+    checks: Record<string, {
+        status: "pass" | "fail";
+        message?: string;
+    }>;
+}
+/**
+ * Creates a health check router for the bus.
+ */
+declare function createHealthRouter(options: HealthCheckOptions): Router;
+/**
+ * Creates a readiness check router.
+ */
+declare function createReadinessRouter(options: HealthCheckOptions): Router;
+
+/**
+ * Sets up graceful shutdown for Express server with bus drain.
+ */
+declare function setupGracefulShutdown(server: Server, options: GracefulShutdownOptions): void;
+
+export { type GracefulShutdownOptions, type HealthCheckOptions, type HealthStatus, type SagaBusExpressOptions, createHealthRouter, createReadinessRouter, sagaBusMiddleware, sagaErrorHandler, setupGracefulShutdown };

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+import { RequestHandler, ErrorRequestHandler, Router } from 'express';
+import { Bus } from '@saga-bus/core';
+import { Server } from 'http';
+
+declare global {
+    namespace Express {
+        interface Request {
+            bus?: Bus;
+            correlationId?: string;
+        }
+    }
+}
+interface SagaBusExpressOptions {
+    /** The bus instance to attach */
+    bus: Bus;
+    /** Header name for correlation ID */
+    correlationIdHeader?: string;
+    /** Whether to generate correlation ID if not present */
+    generateCorrelationId?: boolean;
+    /** Custom correlation ID generator */
+    correlationIdGenerator?: () => string;
+}
+interface HealthCheckOptions {
+    /** The bus instance to check */
+    bus: Bus;
+    /** Path for health endpoint */
+    path?: string;
+    /** Additional health checks */
+    checks?: Array<{
+        name: string;
+        check: () => Promise<boolean>;
+    }>;
+}
+interface GracefulShutdownOptions {
+    /** The bus instance to drain */
+    bus: Bus;
+    /** Timeout for graceful shutdown in ms */
+    timeoutMs?: number;
+    /** Callback before shutdown starts */
+    onShutdownStart?: () => void | Promise<void>;
+    /** Callback after shutdown completes */
+    onShutdownComplete?: () => void | Promise<void>;
+}
+
+/**
+ * Creates middleware that attaches the bus instance to requests.
+ */
+declare function sagaBusMiddleware(options: SagaBusExpressOptions): RequestHandler;
+/**
+ * Error handler middleware for saga-related errors.
+ */
+declare function sagaErrorHandler(): ErrorRequestHandler;
+
+interface HealthStatus {
+    status: "healthy" | "unhealthy";
+    timestamp: string;
+    checks: Record<string, {
+        status: "pass" | "fail";
+        message?: string;
+    }>;
+}
+/**
+ * Creates a health check router for the bus.
+ */
+declare function createHealthRouter(options: HealthCheckOptions): Router;
+/**
+ * Creates a readiness check router.
+ */
+declare function createReadinessRouter(options: HealthCheckOptions): Router;
+
+/**
+ * Sets up graceful shutdown for Express server with bus drain.
+ */
+declare function setupGracefulShutdown(server: Server, options: GracefulShutdownOptions): void;
+
+export { type GracefulShutdownOptions, type HealthCheckOptions, type HealthStatus, type SagaBusExpressOptions, createHealthRouter, createReadinessRouter, sagaBusMiddleware, sagaErrorHandler, setupGracefulShutdown };

package/dist/index.js

@@ -0,0 +1,145 @@
+// src/middleware.ts
+import { randomUUID } from "crypto";
+function sagaBusMiddleware(options) {
+  const {
+    bus,
+    correlationIdHeader = "x-correlation-id",
+    generateCorrelationId = true,
+    correlationIdGenerator = randomUUID
+  } = options;
+  return (req, res, next) => {
+    req.bus = bus;
+    let correlationId = req.headers[correlationIdHeader.toLowerCase()];
+    if (!correlationId && generateCorrelationId) {
+      correlationId = correlationIdGenerator();
+    }
+    if (correlationId) {
+      req.correlationId = correlationId;
+      res.setHeader(correlationIdHeader, correlationId);
+    }
+    next();
+  };
+}
+function sagaErrorHandler() {
+  return (err, req, res, next) => {
+    if (err.name === "SagaTimeoutError") {
+      res.status(408).json({
+        error: "Saga Timeout",
+        message: err.message,
+        correlationId: req.correlationId
+      });
+      return;
+    }
+    if (err.name === "ConcurrencyError") {
+      res.status(409).json({
+        error: "Concurrency Conflict",
+        message: err.message,
+        correlationId: req.correlationId
+      });
+      return;
+    }
+    next(err);
+  };
+}
+
+// src/health.ts
+import { Router as createRouter } from "express";
+function createHealthRouter(options) {
+  const {
+    bus,
+    path = "/health",
+    checks = []
+  } = options;
+  const router = createRouter();
+  router.get(path, async (_req, res) => {
+    const healthStatus = {
+      status: "healthy",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      checks: {}
+    };
+    try {
+      if (bus) {
+        healthStatus.checks.bus = {
+          status: "pass"
+        };
+      } else {
+        throw new Error("Bus not available");
+      }
+    } catch (error) {
+      healthStatus.status = "unhealthy";
+      healthStatus.checks.bus = {
+        status: "fail",
+        message: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+    for (const check of checks) {
+      try {
+        const result = await check.check();
+        healthStatus.checks[check.name] = {
+          status: result ? "pass" : "fail"
+        };
+        if (!result) {
+          healthStatus.status = "unhealthy";
+        }
+      } catch (error) {
+        healthStatus.status = "unhealthy";
+        healthStatus.checks[check.name] = {
+          status: "fail",
+          message: error instanceof Error ? error.message : "Unknown error"
+        };
+      }
+    }
+    const statusCode = healthStatus.status === "healthy" ? 200 : 503;
+    res.status(statusCode).json(healthStatus);
+  });
+  return router;
+}
+function createReadinessRouter(options) {
+  return createHealthRouter({
+    ...options,
+    path: options.path ?? "/ready"
+  });
+}
+
+// src/index.ts
+function setupGracefulShutdown(server, options) {
+  const {
+    bus,
+    timeoutMs = 3e4,
+    onShutdownStart,
+    onShutdownComplete
+  } = options;
+  const shutdown = async (signal) => {
+    console.log(`Received ${signal}, starting graceful shutdown...`);
+    if (onShutdownStart) {
+      await onShutdownStart();
+    }
+    const timeout = setTimeout(() => {
+      console.error("Graceful shutdown timeout, forcing exit");
+      process.exit(1);
+    }, timeoutMs);
+    try {
+      server.close();
+      await bus.stop();
+      clearTimeout(timeout);
+      if (onShutdownComplete) {
+        await onShutdownComplete();
+      }
+      console.log("Graceful shutdown complete");
+      process.exit(0);
+    } catch (error) {
+      console.error("Error during graceful shutdown:", error);
+      process.exit(1);
+    }
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+}
+export {
+  createHealthRouter,
+  createReadinessRouter,
+  sagaBusMiddleware,
+  sagaErrorHandler,
+  setupGracefulShutdown
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/middleware.ts","../src/health.ts","../src/index.ts"],"sourcesContent":["import type { Request, Response, NextFunction, RequestHandler, ErrorRequestHandler } from \"express\";\nimport { randomUUID } from \"crypto\";\nimport type { SagaBusExpressOptions } from \"./types.js\";\n\n/**\n * Creates middleware that attaches the bus instance to requests.\n */\nexport function sagaBusMiddleware(options: SagaBusExpressOptions): RequestHandler {\n  const {\n    bus,\n    correlationIdHeader = \"x-correlation-id\",\n    generateCorrelationId = true,\n    correlationIdGenerator = randomUUID,\n  } = options;\n\n  return (req: Request, res: Response, next: NextFunction) => {\n    // Attach bus to request\n    req.bus = bus;\n\n    // Extract or generate correlation ID\n    let correlationId = req.headers[correlationIdHeader.toLowerCase()] as string | undefined;\n\n    if (!correlationId && generateCorrelationId) {\n      correlationId = correlationIdGenerator();\n    }\n\n    if (correlationId) {\n      req.correlationId = correlationId;\n      // Also set on response for tracing\n      res.setHeader(correlationIdHeader, correlationId);\n    }\n\n    next();\n  };\n}\n\n/**\n * Error handler middleware for saga-related errors.\n */\nexport function sagaErrorHandler(): ErrorRequestHandler {\n  return (err: Error, req: Request, res: Response, next: NextFunction) => {\n    // Check if it's a saga-related error\n    if (err.name === \"SagaTimeoutError\") {\n      res.status(408).json({\n        error: \"Saga Timeout\",\n        message: err.message,\n        correlationId: req.correlationId,\n      });\n      return;\n    }\n\n    if (err.name === \"ConcurrencyError\") {\n      res.status(409).json({\n        error: \"Concurrency Conflict\",\n        message: err.message,\n        correlationId: req.correlationId,\n      });\n      return;\n    }\n\n    // Pass to default error handler\n    next(err);\n  };\n}\n","import type { Request, Response, Router } from \"express\";\nimport { Router as createRouter } from \"express\";\nimport type { HealthCheckOptions } from \"./types.js\";\n\nexport interface HealthStatus {\n  status: \"healthy\" | \"unhealthy\";\n  timestamp: string;\n  checks: Record<string, {\n    status: \"pass\" | \"fail\";\n    message?: string;\n  }>;\n}\n\n/**\n * Creates a health check router for the bus.\n */\nexport function createHealthRouter(options: HealthCheckOptions): Router {\n  const {\n    bus,\n    path = \"/health\",\n    checks = [],\n  } = options;\n\n  const router = createRouter();\n\n  router.get(path, async (_req: Request, res: Response) => {\n    const healthStatus: HealthStatus = {\n      status: \"healthy\",\n      timestamp: new Date().toISOString(),\n      checks: {},\n    };\n\n    // Check bus status\n    try {\n      // Simple check - bus exists and is accessible\n      if (bus) {\n        healthStatus.checks.bus = {\n          status: \"pass\",\n        };\n      } else {\n        throw new Error(\"Bus not available\");\n      }\n    } catch (error) {\n      healthStatus.status = \"unhealthy\";\n      healthStatus.checks.bus = {\n        status: \"fail\",\n        message: error instanceof Error ? error.message : \"Unknown error\",\n      };\n    }\n\n    // Run additional checks\n    for (const check of checks) {\n      try {\n        const result = await check.check();\n        healthStatus.checks[check.name] = {\n          status: result ? \"pass\" : \"fail\",\n        };\n        if (!result) {\n          healthStatus.status = \"unhealthy\";\n        }\n      } catch (error) {\n        healthStatus.status = \"unhealthy\";\n        healthStatus.checks[check.name] = {\n          status: \"fail\",\n          message: error instanceof Error ? error.message : \"Unknown error\",\n        };\n      }\n    }\n\n    const statusCode = healthStatus.status === \"healthy\" ? 200 : 503;\n    res.status(statusCode).json(healthStatus);\n  });\n\n  return router;\n}\n\n/**\n * Creates a readiness check router.\n */\nexport function createReadinessRouter(options: HealthCheckOptions): Router {\n  return createHealthRouter({\n    ...options,\n    path: options.path ?? \"/ready\",\n  });\n}\n","export { sagaBusMiddleware, sagaErrorHandler } from \"./middleware.js\";\nexport { createHealthRouter, createReadinessRouter } from \"./health.js\";\nexport type {\n  SagaBusExpressOptions,\n  HealthCheckOptions,\n  GracefulShutdownOptions,\n} from \"./types.js\";\nexport type { HealthStatus } from \"./health.js\";\n\n// Re-export graceful shutdown helper\nimport type { Server } from \"http\";\nimport type { GracefulShutdownOptions } from \"./types.js\";\n\n/**\n * Sets up graceful shutdown for Express server with bus drain.\n */\nexport function setupGracefulShutdown(\n  server: Server,\n  options: GracefulShutdownOptions\n): void {\n  const {\n    bus,\n    timeoutMs = 30000,\n    onShutdownStart,\n    onShutdownComplete,\n  } = options;\n\n  const shutdown = async (signal: string) => {\n    console.log(`Received ${signal}, starting graceful shutdown...`);\n\n    if (onShutdownStart) {\n      await onShutdownStart();\n    }\n\n    // Set shutdown timeout\n    const timeout = setTimeout(() => {\n      console.error(\"Graceful shutdown timeout, forcing exit\");\n      process.exit(1);\n    }, timeoutMs);\n\n    try {\n      // Stop accepting new connections\n      server.close();\n\n      // Stop the bus (drains workers)\n      await bus.stop();\n\n      clearTimeout(timeout);\n\n      if (onShutdownComplete) {\n        await onShutdownComplete();\n      }\n\n      console.log(\"Graceful shutdown complete\");\n      process.exit(0);\n    } catch (error) {\n      console.error(\"Error during graceful shutdown:\", error);\n      process.exit(1);\n    }\n  };\n\n  process.on(\"SIGTERM\", () => shutdown(\"SIGTERM\"));\n  process.on(\"SIGINT\", () => shutdown(\"SIGINT\"));\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@saga-bus/express",
+  "version": "1.0.0",
+  "description": "Express.js integration for saga-bus",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanforan/saga-bus.git",
+    "directory": "packages/express"
+  },
+  "bugs": {
+    "url": "https://github.com/deanforan/saga-bus/issues"
+  },
+  "homepage": "https://github.com/deanforan/saga-bus#readme",
+  "keywords": [
+    "saga",
+    "message-bus",
+    "express",
+    "middleware",
+    "integration"
+  ],
+  "dependencies": {
+    "@saga-bus/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "express": "^4.21.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.0.0",
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "peerDependencies": {
+    "@saga-bus/core": ">=0.1.0",
+    "express": ">=4.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}