@saga-bus/fastify 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,265 @@
+# @saga-bus/fastify
+
+Fastify plugin for saga-bus with lifecycle management, request decoration, and health checks.
+
+## Installation
+
+```bash
+npm install @saga-bus/fastify fastify
+# or
+pnpm add @saga-bus/fastify fastify
+```
+
+## Features
+
+- **Plugin Registration**: Register bus as a Fastify plugin
+- **Request Decoration**: Access bus via `request.bus`
+- **Correlation ID**: Automatic extraction and generation
+- **Lifecycle Hooks**: Auto-start/stop bus with Fastify
+- **Health Check**: Built-in health check route
+- **Error Handler**: Saga-specific error handling
+
+## Quick Start
+
+```typescript
+import Fastify from "fastify";
+import { createBus } from "@saga-bus/core";
+import { sagaBusFastifyPlugin } from "@saga-bus/fastify";
+
+const bus = createBus({ /* config */ });
+
+const app = Fastify({ logger: true });
+
+// Register plugin
+await app.register(sagaBusFastifyPlugin, {
+  bus,
+  healthCheck: true,
+});
+
+// Your routes
+app.post("/orders", async (request, reply) => {
+  await request.bus.publish({
+    type: "CreateOrder",
+    payload: request.body,
+  });
+  return { correlationId: request.correlationId };
+});
+
+await app.listen({ port: 3000 });
+```
+
+## API Reference
+
+### sagaBusFastifyPlugin
+
+Fastify plugin that integrates saga-bus.
+
+```typescript
+interface SagaBusFastifyOptions {
+  /** The bus instance to register */
+  bus: Bus;
+
+  /** Whether to start bus when Fastify starts (default: true) */
+  autoStart?: boolean;
+
+  /** Whether to stop bus when Fastify closes (default: true) */
+  autoStop?: boolean;
+
+  /** 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;
+
+  /** Enable health check route */
+  healthCheck?: boolean | HealthCheckConfig;
+}
+
+interface HealthCheckConfig {
+  /** Route path for health check (default: "/health") */
+  path?: string;
+
+  /** Additional health checks */
+  checks?: Array<{
+    name: string;
+    check: () => Promise<boolean>;
+  }>;
+}
+```
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import Fastify from "fastify";
+import { createBus } from "@saga-bus/core";
+import { sagaBusFastifyPlugin } from "@saga-bus/fastify";
+
+const bus = createBus({ /* config */ });
+const app = Fastify();
+
+await app.register(sagaBusFastifyPlugin, { bus });
+
+app.post("/messages", async (request) => {
+  await request.bus.publish({
+    type: request.body.type,
+    payload: request.body.payload,
+  });
+  return { success: true, correlationId: request.correlationId };
+});
+
+await app.listen({ port: 3000 });
+```
+
+### With Health Check
+
+```typescript
+await app.register(sagaBusFastifyPlugin, {
+  bus,
+  healthCheck: {
+    path: "/health",
+    checks: [
+      {
+        name: "database",
+        check: async () => {
+          await pool.query("SELECT 1");
+          return true;
+        },
+      },
+    ],
+  },
+});
+```
+
+Health check response:
+
+```json
+{
+  "status": "healthy",
+  "timestamp": "2024-01-01T00:00:00.000Z",
+  "checks": {
+    "bus": { "status": "pass" },
+    "database": { "status": "pass" }
+  }
+}
+```
+
+### Custom Correlation ID
+
+```typescript
+await app.register(sagaBusFastifyPlugin, {
+  bus,
+  correlationIdHeader: "x-request-id",
+  correlationIdGenerator: () => `req-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+});
+```
+
+### Manual Lifecycle Control
+
+```typescript
+await app.register(sagaBusFastifyPlugin, {
+  bus,
+  autoStart: false,
+  autoStop: false,
+});
+
+// Start bus manually
+await bus.start();
+
+// Stop bus manually before close
+app.addHook("onClose", async () => {
+  await bus.stop();
+});
+```
+
+## TypeScript Support
+
+The plugin extends Fastify types:
+
+```typescript
+// In your route handlers
+app.get("/", async (request, reply) => {
+  // request.bus is typed as Bus
+  await request.bus.publish(message);
+
+  // request.correlationId is typed as string
+  console.log(`Processing ${request.correlationId}`);
+
+  // fastify.bus is also available
+  await request.server.bus.publish(message);
+});
+```
+
+## Error Handling
+
+The plugin installs a custom error handler for saga-specific errors:
+
+- **SagaTimeoutError**: Returns 408 Request Timeout
+- **ConcurrencyError**: Returns 409 Conflict
+
+```typescript
+app.get("/order/:id", async (request) => {
+  // If this throws a ConcurrencyError, client gets 409
+  await request.bus.publish({ type: "UpdateOrder", payload: { id: request.params.id } });
+});
+```
+
+Response on ConcurrencyError:
+
+```json
+{
+  "error": "Concurrency Conflict",
+  "message": "Expected version 1, but found 2",
+  "correlationId": "abc-123"
+}
+```
+
+## Example: Complete Application
+
+```typescript
+import Fastify from "fastify";
+import { createBus, InMemoryTransport, InMemorySagaStore } from "@saga-bus/core";
+import { sagaBusFastifyPlugin } from "@saga-bus/fastify";
+
+// Create bus
+const bus = createBus({
+  transport: new InMemoryTransport(),
+  store: new InMemorySagaStore(),
+});
+
+// Create Fastify app
+const app = Fastify({ logger: true });
+
+// Register saga-bus plugin
+await app.register(sagaBusFastifyPlugin, {
+  bus,
+  healthCheck: true,
+});
+
+// Routes
+app.post("/orders", async (request) => {
+  await request.bus.publish({
+    type: "CreateOrder",
+    payload: request.body,
+  });
+  return { orderId: "new-order", correlationId: request.correlationId };
+});
+
+app.get("/orders/:id", async (request) => {
+  // Access bus from request
+  const state = await request.bus.getSagaState("OrderSaga", request.params.id);
+  return state;
+});
+
+// Start server
+await app.listen({ port: 3000 });
+console.log("Server running on port 3000");
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,146 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  sagaBusFastifyPlugin: () => sagaBusFastifyPlugin
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/plugin.ts
+var import_fastify_plugin = __toESM(require("fastify-plugin"), 1);
+var import_crypto = require("crypto");
+var sagaBusPlugin = async (fastify, options) => {
+  const {
+    bus,
+    autoStart = true,
+    autoStop = true,
+    correlationIdHeader = "x-correlation-id",
+    generateCorrelationId = true,
+    correlationIdGenerator = import_crypto.randomUUID,
+    healthCheck = false
+  } = options;
+  fastify.decorate("bus", bus);
+  fastify.decorateRequest("bus", null);
+  fastify.decorateRequest("correlationId", "");
+  fastify.addHook("onRequest", async (request, reply) => {
+    request.bus = bus;
+    let correlationId = request.headers[correlationIdHeader.toLowerCase()];
+    if (!correlationId && generateCorrelationId) {
+      correlationId = correlationIdGenerator();
+    }
+    if (correlationId) {
+      request.correlationId = correlationId;
+      reply.header(correlationIdHeader, correlationId);
+    }
+  });
+  if (autoStart) {
+    fastify.addHook("onReady", async () => {
+      await bus.start();
+      fastify.log.info("Saga bus started");
+    });
+  }
+  if (autoStop) {
+    fastify.addHook("onClose", async () => {
+      await bus.stop();
+      fastify.log.info("Saga bus stopped");
+    });
+  }
+  if (healthCheck) {
+    const config = typeof healthCheck === "boolean" ? { path: "/health", checks: [] } : { path: "/health", checks: [], ...healthCheck };
+    fastify.get(config.path, async (_request, reply) => {
+      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 config.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;
+      reply.code(statusCode).send(healthStatus);
+    });
+  }
+  fastify.setErrorHandler((error, request, reply) => {
+    if (error.name === "SagaTimeoutError") {
+      reply.code(408).send({
+        error: "Saga Timeout",
+        message: error.message,
+        correlationId: request.correlationId
+      });
+      return;
+    }
+    if (error.name === "ConcurrencyError") {
+      reply.code(409).send({
+        error: "Concurrency Conflict",
+        message: error.message,
+        correlationId: request.correlationId
+      });
+      return;
+    }
+    reply.send(error);
+  });
+};
+var sagaBusFastifyPlugin = (0, import_fastify_plugin.default)(sagaBusPlugin, {
+  fastify: ">=4.0.0",
+  name: "@saga-bus/fastify"
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  sagaBusFastifyPlugin
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/plugin.ts"],"sourcesContent":["export { sagaBusFastifyPlugin } from \"./plugin.js\";\nexport type {\n  SagaBusFastifyOptions,\n  HealthCheckConfig,\n  HealthStatus,\n} from \"./types.js\";\n","import type { FastifyPluginAsync, FastifyError } from \"fastify\";\nimport fp from \"fastify-plugin\";\nimport { randomUUID } from \"crypto\";\nimport type { SagaBusFastifyOptions, HealthCheckConfig, HealthStatus } from \"./types.js\";\n\nconst sagaBusPlugin: FastifyPluginAsync<SagaBusFastifyOptions> = async (\n  fastify,\n  options\n) => {\n  const {\n    bus,\n    autoStart = true,\n    autoStop = true,\n    correlationIdHeader = \"x-correlation-id\",\n    generateCorrelationId = true,\n    correlationIdGenerator = randomUUID,\n    healthCheck = false,\n  } = options;\n\n  // Decorate fastify instance with bus\n  fastify.decorate(\"bus\", bus);\n\n  // Decorate request with bus and correlationId\n  // @ts-expect-error - Fastify decorateRequest typing is complex, null is valid for initial decoration\n  fastify.decorateRequest(\"bus\", null);\n  fastify.decorateRequest(\"correlationId\", \"\");\n\n  // Add hook to set bus and correlation ID on request\n  fastify.addHook(\"onRequest\", async (request, reply) => {\n    request.bus = bus;\n\n    // Extract or generate correlation ID\n    let correlationId = request.headers[correlationIdHeader.toLowerCase()] as string | undefined;\n\n    if (!correlationId && generateCorrelationId) {\n      correlationId = correlationIdGenerator();\n    }\n\n    if (correlationId) {\n      request.correlationId = correlationId;\n      reply.header(correlationIdHeader, correlationId);\n    }\n  });\n\n  // Auto-start bus\n  if (autoStart) {\n    fastify.addHook(\"onReady\", async () => {\n      await bus.start();\n      fastify.log.info(\"Saga bus started\");\n    });\n  }\n\n  // Auto-stop bus\n  if (autoStop) {\n    fastify.addHook(\"onClose\", async () => {\n      await bus.stop();\n      fastify.log.info(\"Saga bus stopped\");\n    });\n  }\n\n  // Register health check route\n  if (healthCheck) {\n    const config: HealthCheckConfig = typeof healthCheck === \"boolean\"\n      ? { path: \"/health\", checks: [] }\n      : { path: \"/health\", checks: [], ...healthCheck };\n\n    fastify.get(config.path!, async (_request, reply) => {\n      const healthStatus: HealthStatus = {\n        status: \"healthy\",\n        timestamp: new Date().toISOString(),\n        checks: {},\n      };\n\n      // Check bus\n      try {\n        if (bus) {\n          healthStatus.checks.bus = { status: \"pass\" };\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 config.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      reply.code(statusCode).send(healthStatus);\n    });\n  }\n\n  // Error handler for saga errors\n  fastify.setErrorHandler((error: FastifyError, request, reply) => {\n    if (error.name === \"SagaTimeoutError\") {\n      reply.code(408).send({\n        error: \"Saga Timeout\",\n        message: error.message,\n        correlationId: request.correlationId,\n      });\n      return;\n    }\n\n    if (error.name === \"ConcurrencyError\") {\n      reply.code(409).send({\n        error: \"Concurrency Conflict\",\n        message: error.message,\n        correlationId: request.correlationId,\n      });\n      return;\n    }\n\n    // Default error handling\n    reply.send(error);\n  });\n};\n\nexport const sagaBusFastifyPlugin = fp(sagaBusPlugin, {\n  fastify: \">=4.0.0\",\n  name: \"@saga-bus/fastify\",\n});\n"],"mappings":"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","names":["fp"]}

package/dist/index.d.cts

@@ -0,0 +1,49 @@
+import { FastifyPluginAsync } from 'fastify';
+import { Bus } from '@saga-bus/core';
+
+declare module "fastify" {
+    interface FastifyRequest {
+        bus: Bus;
+        correlationId: string;
+    }
+    interface FastifyInstance {
+        bus: Bus;
+    }
+}
+interface SagaBusFastifyOptions {
+    /** The bus instance to register */
+    bus: Bus;
+    /** Whether to start bus when Fastify starts */
+    autoStart?: boolean;
+    /** Whether to stop bus when Fastify closes */
+    autoStop?: boolean;
+    /** Header name for correlation ID */
+    correlationIdHeader?: string;
+    /** Whether to generate correlation ID if not present */
+    generateCorrelationId?: boolean;
+    /** Custom correlation ID generator */
+    correlationIdGenerator?: () => string;
+    /** Enable health check route */
+    healthCheck?: boolean | HealthCheckConfig;
+}
+interface HealthCheckConfig {
+    /** Route path for health check */
+    path?: string;
+    /** Additional health checks */
+    checks?: Array<{
+        name: string;
+        check: () => Promise<boolean>;
+    }>;
+}
+interface HealthStatus {
+    status: "healthy" | "unhealthy";
+    timestamp: string;
+    checks: Record<string, {
+        status: "pass" | "fail";
+        message?: string;
+    }>;
+}
+
+declare const sagaBusFastifyPlugin: FastifyPluginAsync<SagaBusFastifyOptions>;
+
+export { type HealthCheckConfig, type HealthStatus, type SagaBusFastifyOptions, sagaBusFastifyPlugin };

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import { FastifyPluginAsync } from 'fastify';
+import { Bus } from '@saga-bus/core';
+
+declare module "fastify" {
+    interface FastifyRequest {
+        bus: Bus;
+        correlationId: string;
+    }
+    interface FastifyInstance {
+        bus: Bus;
+    }
+}
+interface SagaBusFastifyOptions {
+    /** The bus instance to register */
+    bus: Bus;
+    /** Whether to start bus when Fastify starts */
+    autoStart?: boolean;
+    /** Whether to stop bus when Fastify closes */
+    autoStop?: boolean;
+    /** Header name for correlation ID */
+    correlationIdHeader?: string;
+    /** Whether to generate correlation ID if not present */
+    generateCorrelationId?: boolean;
+    /** Custom correlation ID generator */
+    correlationIdGenerator?: () => string;
+    /** Enable health check route */
+    healthCheck?: boolean | HealthCheckConfig;
+}
+interface HealthCheckConfig {
+    /** Route path for health check */
+    path?: string;
+    /** Additional health checks */
+    checks?: Array<{
+        name: string;
+        check: () => Promise<boolean>;
+    }>;
+}
+interface HealthStatus {
+    status: "healthy" | "unhealthy";
+    timestamp: string;
+    checks: Record<string, {
+        status: "pass" | "fail";
+        message?: string;
+    }>;
+}
+
+declare const sagaBusFastifyPlugin: FastifyPluginAsync<SagaBusFastifyOptions>;
+
+export { type HealthCheckConfig, type HealthStatus, type SagaBusFastifyOptions, sagaBusFastifyPlugin };

package/dist/index.js

@@ -0,0 +1,109 @@
+// src/plugin.ts
+import fp from "fastify-plugin";
+import { randomUUID } from "crypto";
+var sagaBusPlugin = async (fastify, options) => {
+  const {
+    bus,
+    autoStart = true,
+    autoStop = true,
+    correlationIdHeader = "x-correlation-id",
+    generateCorrelationId = true,
+    correlationIdGenerator = randomUUID,
+    healthCheck = false
+  } = options;
+  fastify.decorate("bus", bus);
+  fastify.decorateRequest("bus", null);
+  fastify.decorateRequest("correlationId", "");
+  fastify.addHook("onRequest", async (request, reply) => {
+    request.bus = bus;
+    let correlationId = request.headers[correlationIdHeader.toLowerCase()];
+    if (!correlationId && generateCorrelationId) {
+      correlationId = correlationIdGenerator();
+    }
+    if (correlationId) {
+      request.correlationId = correlationId;
+      reply.header(correlationIdHeader, correlationId);
+    }
+  });
+  if (autoStart) {
+    fastify.addHook("onReady", async () => {
+      await bus.start();
+      fastify.log.info("Saga bus started");
+    });
+  }
+  if (autoStop) {
+    fastify.addHook("onClose", async () => {
+      await bus.stop();
+      fastify.log.info("Saga bus stopped");
+    });
+  }
+  if (healthCheck) {
+    const config = typeof healthCheck === "boolean" ? { path: "/health", checks: [] } : { path: "/health", checks: [], ...healthCheck };
+    fastify.get(config.path, async (_request, reply) => {
+      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 config.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;
+      reply.code(statusCode).send(healthStatus);
+    });
+  }
+  fastify.setErrorHandler((error, request, reply) => {
+    if (error.name === "SagaTimeoutError") {
+      reply.code(408).send({
+        error: "Saga Timeout",
+        message: error.message,
+        correlationId: request.correlationId
+      });
+      return;
+    }
+    if (error.name === "ConcurrencyError") {
+      reply.code(409).send({
+        error: "Concurrency Conflict",
+        message: error.message,
+        correlationId: request.correlationId
+      });
+      return;
+    }
+    reply.send(error);
+  });
+};
+var sagaBusFastifyPlugin = fp(sagaBusPlugin, {
+  fastify: ">=4.0.0",
+  name: "@saga-bus/fastify"
+});
+export {
+  sagaBusFastifyPlugin
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugin.ts"],"sourcesContent":["import type { FastifyPluginAsync, FastifyError } from \"fastify\";\nimport fp from \"fastify-plugin\";\nimport { randomUUID } from \"crypto\";\nimport type { SagaBusFastifyOptions, HealthCheckConfig, HealthStatus } from \"./types.js\";\n\nconst sagaBusPlugin: FastifyPluginAsync<SagaBusFastifyOptions> = async (\n  fastify,\n  options\n) => {\n  const {\n    bus,\n    autoStart = true,\n    autoStop = true,\n    correlationIdHeader = \"x-correlation-id\",\n    generateCorrelationId = true,\n    correlationIdGenerator = randomUUID,\n    healthCheck = false,\n  } = options;\n\n  // Decorate fastify instance with bus\n  fastify.decorate(\"bus\", bus);\n\n  // Decorate request with bus and correlationId\n  // @ts-expect-error - Fastify decorateRequest typing is complex, null is valid for initial decoration\n  fastify.decorateRequest(\"bus\", null);\n  fastify.decorateRequest(\"correlationId\", \"\");\n\n  // Add hook to set bus and correlation ID on request\n  fastify.addHook(\"onRequest\", async (request, reply) => {\n    request.bus = bus;\n\n    // Extract or generate correlation ID\n    let correlationId = request.headers[correlationIdHeader.toLowerCase()] as string | undefined;\n\n    if (!correlationId && generateCorrelationId) {\n      correlationId = correlationIdGenerator();\n    }\n\n    if (correlationId) {\n      request.correlationId = correlationId;\n      reply.header(correlationIdHeader, correlationId);\n    }\n  });\n\n  // Auto-start bus\n  if (autoStart) {\n    fastify.addHook(\"onReady\", async () => {\n      await bus.start();\n      fastify.log.info(\"Saga bus started\");\n    });\n  }\n\n  // Auto-stop bus\n  if (autoStop) {\n    fastify.addHook(\"onClose\", async () => {\n      await bus.stop();\n      fastify.log.info(\"Saga bus stopped\");\n    });\n  }\n\n  // Register health check route\n  if (healthCheck) {\n    const config: HealthCheckConfig = typeof healthCheck === \"boolean\"\n      ? { path: \"/health\", checks: [] }\n      : { path: \"/health\", checks: [], ...healthCheck };\n\n    fastify.get(config.path!, async (_request, reply) => {\n      const healthStatus: HealthStatus = {\n        status: \"healthy\",\n        timestamp: new Date().toISOString(),\n        checks: {},\n      };\n\n      // Check bus\n      try {\n        if (bus) {\n          healthStatus.checks.bus = { status: \"pass\" };\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 config.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      reply.code(statusCode).send(healthStatus);\n    });\n  }\n\n  // Error handler for saga errors\n  fastify.setErrorHandler((error: FastifyError, request, reply) => {\n    if (error.name === \"SagaTimeoutError\") {\n      reply.code(408).send({\n        error: \"Saga Timeout\",\n        message: error.message,\n        correlationId: request.correlationId,\n      });\n      return;\n    }\n\n    if (error.name === \"ConcurrencyError\") {\n      reply.code(409).send({\n        error: \"Concurrency Conflict\",\n        message: error.message,\n        correlationId: request.correlationId,\n      });\n      return;\n    }\n\n    // Default error handling\n    reply.send(error);\n  });\n};\n\nexport const sagaBusFastifyPlugin = fp(sagaBusPlugin, {\n  fastify: \">=4.0.0\",\n  name: \"@saga-bus/fastify\",\n});\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@saga-bus/fastify",
+  "version": "1.0.0",
+  "description": "Fastify 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/fastify"
+  },
+  "bugs": {
+    "url": "https://github.com/deanforan/saga-bus/issues"
+  },
+  "homepage": "https://github.com/deanforan/saga-bus#readme",
+  "keywords": [
+    "saga",
+    "message-bus",
+    "fastify",
+    "plugin",
+    "integration"
+  ],
+  "dependencies": {
+    "fastify-plugin": "^5.0.0",
+    "@saga-bus/core": "0.1.0"
+  },
+  "devDependencies": {
+    "fastify": "^5.0.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",
+    "fastify": ">=4.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}