@saga-bus/middleware-logging 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,50 @@
+# @saga-bus/middleware-logging
+
+Structured logging middleware for saga-bus.
+
+## Installation
+
+```bash
+pnpm add @saga-bus/middleware-logging
+```
+
+## Usage
+
+```typescript
+import { createLoggingMiddleware } from "@saga-bus/middleware-logging";
+import { createBus } from "@saga-bus/core";
+
+const loggingMiddleware = createLoggingMiddleware({
+  logger: console,
+  level: "info",
+});
+
+const bus = createBus({
+  middleware: [loggingMiddleware],
+  sagas: [...],
+  transport,
+});
+```
+
+## Log Events
+
+| Event | Level | Description |
+|-------|-------|-------------|
+| `saga.message.received` | info | Message received for processing |
+| `saga.handler.start` | debug | Handler execution started |
+| `saga.handler.success` | info | Handler completed successfully |
+| `saga.handler.error` | error | Handler threw an error |
+| `saga.state.created` | info | New saga instance created |
+| `saga.state.completed` | info | Saga marked as complete |
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `logger` | `Logger` | `console` | Logger instance |
+| `level` | `string` | `"info"` | Minimum log level |
+| `includeState` | `boolean` | `false` | Include state in logs |
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,143 @@
+"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, {
+  createLoggingMiddleware: () => createLoggingMiddleware
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/createLoggingMiddleware.ts
+var LOG_LEVEL_PRIORITY = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+var defaultLogger = {
+  debug: (message, meta) => console.debug(`[saga-bus] ${message}`, meta ?? ""),
+  info: (message, meta) => console.info(`[saga-bus] ${message}`, meta ?? ""),
+  warn: (message, meta) => console.warn(`[saga-bus] ${message}`, meta ?? ""),
+  error: (message, meta) => console.error(`[saga-bus] ${message}`, meta ?? "")
+};
+function createLoggingMiddleware(options = {}) {
+  const {
+    logger = defaultLogger,
+    level = "info",
+    logPayload = false,
+    logState = false,
+    filter,
+    enrichMeta
+  } = options;
+  const minPriority = LOG_LEVEL_PRIORITY[level];
+  function log(eventLevel, eventType, message, meta) {
+    if (LOG_LEVEL_PRIORITY[eventLevel] < minPriority) {
+      return;
+    }
+    if (filter && !filter(eventType, meta)) {
+      return;
+    }
+    const enrichedMeta = enrichMeta ? enrichMeta(meta) : meta;
+    const finalMeta = { ...enrichedMeta, event: eventType };
+    switch (eventLevel) {
+      case "debug":
+        logger.debug(message, finalMeta);
+        break;
+      case "info":
+        logger.info(message, finalMeta);
+        break;
+      case "warn":
+        logger.warn(message, finalMeta);
+        break;
+      case "error":
+        logger.error(message, finalMeta);
+        break;
+    }
+  }
+  function baseMeta(ctx) {
+    const meta = {
+      sagaName: ctx.sagaName,
+      correlationId: ctx.correlationId,
+      messageId: ctx.envelope.id,
+      messageType: ctx.envelope.type
+    };
+    if (ctx.sagaId) {
+      meta.sagaId = ctx.sagaId;
+    }
+    if (logPayload) {
+      meta.payload = ctx.envelope.payload;
+    }
+    return meta;
+  }
+  return async (ctx, next) => {
+    const startTime = Date.now();
+    log("debug", "saga.message.received", "Message received", {
+      ...baseMeta(ctx),
+      headers: ctx.envelope.headers
+    });
+    log("debug", "saga.handler.start", "Handler starting", baseMeta(ctx));
+    try {
+      await next();
+      const duration = Date.now() - startTime;
+      const isNew = ctx.preState === void 0 && ctx.postState !== void 0;
+      const isCompleted = ctx.postState?.metadata?.isCompleted === true;
+      const wasAlreadyCompleted = ctx.preState?.metadata?.isCompleted === true;
+      const resultMeta = {
+        ...baseMeta(ctx),
+        durationMs: duration
+      };
+      if (ctx.sagaId) {
+        resultMeta.sagaId = ctx.sagaId;
+      }
+      if (logState && ctx.postState) {
+        resultMeta.state = ctx.postState;
+      }
+      if (ctx.postState) {
+        resultMeta.version = ctx.postState.metadata.version;
+      }
+      if (isNew) {
+        log("info", "saga.state.created", "Saga instance created", resultMeta);
+      } else if (isCompleted && !wasAlreadyCompleted) {
+        log("info", "saga.state.completed", "Saga completed", resultMeta);
+      } else if (ctx.postState) {
+        log("debug", "saga.state.updated", "Saga state updated", resultMeta);
+      }
+      log("debug", "saga.handler.success", "Handler completed successfully", {
+        ...baseMeta(ctx),
+        durationMs: duration
+      });
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      log("error", "saga.handler.error", "Handler failed", {
+        ...baseMeta(ctx),
+        durationMs: duration,
+        error: error instanceof Error ? error.message : String(error),
+        errorType: error instanceof Error ? error.name : "UnknownError",
+        stack: error instanceof Error ? error.stack : void 0
+      });
+      throw error;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createLoggingMiddleware
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/createLoggingMiddleware.ts"],"sourcesContent":["export { createLoggingMiddleware } from \"./createLoggingMiddleware.js\";\nexport type {\n  LoggingMiddlewareOptions,\n  LogLevel,\n  LogEventType,\n} from \"./types.js\";\n","import type { SagaMiddleware, SagaPipelineContext, Logger } from \"@saga-bus/core\";\nimport type { LoggingMiddlewareOptions, LogLevel, LogEventType } from \"./types.js\";\n\n/**\n * Log level priorities for filtering.\n */\nconst LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {\n  debug: 0,\n  info: 1,\n  warn: 2,\n  error: 3,\n};\n\n/**\n * Default console-based logger.\n */\nconst defaultLogger: Logger = {\n  debug: (message, meta) => console.debug(`[saga-bus] ${message}`, meta ?? \"\"),\n  info: (message, meta) => console.info(`[saga-bus] ${message}`, meta ?? \"\"),\n  warn: (message, meta) => console.warn(`[saga-bus] ${message}`, meta ?? \"\"),\n  error: (message, meta) => console.error(`[saga-bus] ${message}`, meta ?? \"\"),\n};\n\n/**\n * Create a logging middleware for saga execution.\n *\n * @example\n * ```typescript\n * const loggingMiddleware = createLoggingMiddleware({\n *   level: \"debug\",\n *   logPayload: true,\n * });\n *\n * const bus = createBus({\n *   transport,\n *   sagas: [...],\n *   middleware: [loggingMiddleware],\n * });\n * ```\n */\nexport function createLoggingMiddleware(\n  options: LoggingMiddlewareOptions = {}\n): SagaMiddleware {\n  const {\n    logger = defaultLogger,\n    level = \"info\",\n    logPayload = false,\n    logState = false,\n    filter,\n    enrichMeta,\n  } = options;\n\n  const minPriority = LOG_LEVEL_PRIORITY[level];\n\n  /**\n   * Log an event if it meets the level threshold.\n   */\n  function log(\n    eventLevel: LogLevel,\n    eventType: LogEventType,\n    message: string,\n    meta: Record<string, unknown>\n  ): void {\n    if (LOG_LEVEL_PRIORITY[eventLevel] < minPriority) {\n      return;\n    }\n\n    if (filter && !filter(eventType, meta)) {\n      return;\n    }\n\n    const enrichedMeta = enrichMeta ? enrichMeta(meta) : meta;\n    const finalMeta = { ...enrichedMeta, event: eventType };\n\n    switch (eventLevel) {\n      case \"debug\":\n        logger.debug(message, finalMeta);\n        break;\n      case \"info\":\n        logger.info(message, finalMeta);\n        break;\n      case \"warn\":\n        logger.warn(message, finalMeta);\n        break;\n      case \"error\":\n        logger.error(message, finalMeta);\n        break;\n    }\n  }\n\n  /**\n   * Build base metadata from pipeline context.\n   */\n  function baseMeta(ctx: SagaPipelineContext): Record<string, unknown> {\n    const meta: Record<string, unknown> = {\n      sagaName: ctx.sagaName,\n      correlationId: ctx.correlationId,\n      messageId: ctx.envelope.id,\n      messageType: ctx.envelope.type,\n    };\n\n    if (ctx.sagaId) {\n      meta.sagaId = ctx.sagaId;\n    }\n\n    if (logPayload) {\n      meta.payload = ctx.envelope.payload;\n    }\n\n    return meta;\n  }\n\n  return async (ctx: SagaPipelineContext, next: () => Promise<void>) => {\n    const startTime = Date.now();\n\n    // Log message received\n    log(\"debug\", \"saga.message.received\", \"Message received\", {\n      ...baseMeta(ctx),\n      headers: ctx.envelope.headers,\n    });\n\n    // Log handler start\n    log(\"debug\", \"saga.handler.start\", \"Handler starting\", baseMeta(ctx));\n\n    try {\n      await next();\n\n      const duration = Date.now() - startTime;\n\n      // Determine what happened\n      const isNew = ctx.preState === undefined && ctx.postState !== undefined;\n      const isCompleted = ctx.postState?.metadata?.isCompleted === true;\n      const wasAlreadyCompleted = ctx.preState?.metadata?.isCompleted === true;\n\n      // Build result metadata\n      const resultMeta: Record<string, unknown> = {\n        ...baseMeta(ctx),\n        durationMs: duration,\n      };\n\n      if (ctx.sagaId) {\n        resultMeta.sagaId = ctx.sagaId;\n      }\n\n      if (logState && ctx.postState) {\n        resultMeta.state = ctx.postState;\n      }\n\n      if (ctx.postState) {\n        resultMeta.version = ctx.postState.metadata.version;\n      }\n\n      // Log appropriate event\n      if (isNew) {\n        log(\"info\", \"saga.state.created\", \"Saga instance created\", resultMeta);\n      } else if (isCompleted && !wasAlreadyCompleted) {\n        log(\"info\", \"saga.state.completed\", \"Saga completed\", resultMeta);\n      } else if (ctx.postState) {\n        log(\"debug\", \"saga.state.updated\", \"Saga state updated\", resultMeta);\n      }\n\n      // Log handler success\n      log(\"debug\", \"saga.handler.success\", \"Handler completed successfully\", {\n        ...baseMeta(ctx),\n        durationMs: duration,\n      });\n    } catch (error) {\n      const duration = Date.now() - startTime;\n\n      // Log handler error\n      log(\"error\", \"saga.handler.error\", \"Handler failed\", {\n        ...baseMeta(ctx),\n        durationMs: duration,\n        error: error instanceof Error ? error.message : String(error),\n        errorType: error instanceof Error ? error.name : \"UnknownError\",\n        stack: error instanceof Error ? error.stack : undefined,\n      });\n\n      // Re-throw to let error handling proceed\n      throw error;\n    }\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,61 @@
+import { Logger, SagaMiddleware } from '@saga-bus/core';
+
+/**
+ * Log level for filtering.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Log event types emitted by the middleware.
+ */
+type LogEventType = "saga.message.received" | "saga.handler.start" | "saga.handler.success" | "saga.handler.error" | "saga.state.created" | "saga.state.updated" | "saga.state.completed";
+/**
+ * Options for the logging middleware.
+ */
+interface LoggingMiddlewareOptions {
+    /**
+     * Logger instance to use. Defaults to console-based logger.
+     */
+    logger?: Logger;
+    /**
+     * Minimum log level. Events below this level are not logged.
+     * Default: "info"
+     */
+    level?: LogLevel;
+    /**
+     * Whether to log message payload. Default: false (for security/privacy).
+     */
+    logPayload?: boolean;
+    /**
+     * Whether to log full state. Default: false (can be large).
+     */
+    logState?: boolean;
+    /**
+     * Custom event filter. Return false to skip logging an event.
+     */
+    filter?: (eventType: LogEventType, meta: Record<string, unknown>) => boolean;
+    /**
+     * Custom metadata enricher. Add extra fields to all log events.
+     */
+    enrichMeta?: (meta: Record<string, unknown>) => Record<string, unknown>;
+}
+
+/**
+ * Create a logging middleware for saga execution.
+ *
+ * @example
+ * ```typescript
+ * const loggingMiddleware = createLoggingMiddleware({
+ *   level: "debug",
+ *   logPayload: true,
+ * });
+ *
+ * const bus = createBus({
+ *   transport,
+ *   sagas: [...],
+ *   middleware: [loggingMiddleware],
+ * });
+ * ```
+ */
+declare function createLoggingMiddleware(options?: LoggingMiddlewareOptions): SagaMiddleware;
+
+export { type LogEventType, type LogLevel, type LoggingMiddlewareOptions, createLoggingMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import { Logger, SagaMiddleware } from '@saga-bus/core';
+
+/**
+ * Log level for filtering.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Log event types emitted by the middleware.
+ */
+type LogEventType = "saga.message.received" | "saga.handler.start" | "saga.handler.success" | "saga.handler.error" | "saga.state.created" | "saga.state.updated" | "saga.state.completed";
+/**
+ * Options for the logging middleware.
+ */
+interface LoggingMiddlewareOptions {
+    /**
+     * Logger instance to use. Defaults to console-based logger.
+     */
+    logger?: Logger;
+    /**
+     * Minimum log level. Events below this level are not logged.
+     * Default: "info"
+     */
+    level?: LogLevel;
+    /**
+     * Whether to log message payload. Default: false (for security/privacy).
+     */
+    logPayload?: boolean;
+    /**
+     * Whether to log full state. Default: false (can be large).
+     */
+    logState?: boolean;
+    /**
+     * Custom event filter. Return false to skip logging an event.
+     */
+    filter?: (eventType: LogEventType, meta: Record<string, unknown>) => boolean;
+    /**
+     * Custom metadata enricher. Add extra fields to all log events.
+     */
+    enrichMeta?: (meta: Record<string, unknown>) => Record<string, unknown>;
+}
+
+/**
+ * Create a logging middleware for saga execution.
+ *
+ * @example
+ * ```typescript
+ * const loggingMiddleware = createLoggingMiddleware({
+ *   level: "debug",
+ *   logPayload: true,
+ * });
+ *
+ * const bus = createBus({
+ *   transport,
+ *   sagas: [...],
+ *   middleware: [loggingMiddleware],
+ * });
+ * ```
+ */
+declare function createLoggingMiddleware(options?: LoggingMiddlewareOptions): SagaMiddleware;
+
+export { type LogEventType, type LogLevel, type LoggingMiddlewareOptions, createLoggingMiddleware };

package/dist/index.js

@@ -0,0 +1,116 @@
+// src/createLoggingMiddleware.ts
+var LOG_LEVEL_PRIORITY = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+var defaultLogger = {
+  debug: (message, meta) => console.debug(`[saga-bus] ${message}`, meta ?? ""),
+  info: (message, meta) => console.info(`[saga-bus] ${message}`, meta ?? ""),
+  warn: (message, meta) => console.warn(`[saga-bus] ${message}`, meta ?? ""),
+  error: (message, meta) => console.error(`[saga-bus] ${message}`, meta ?? "")
+};
+function createLoggingMiddleware(options = {}) {
+  const {
+    logger = defaultLogger,
+    level = "info",
+    logPayload = false,
+    logState = false,
+    filter,
+    enrichMeta
+  } = options;
+  const minPriority = LOG_LEVEL_PRIORITY[level];
+  function log(eventLevel, eventType, message, meta) {
+    if (LOG_LEVEL_PRIORITY[eventLevel] < minPriority) {
+      return;
+    }
+    if (filter && !filter(eventType, meta)) {
+      return;
+    }
+    const enrichedMeta = enrichMeta ? enrichMeta(meta) : meta;
+    const finalMeta = { ...enrichedMeta, event: eventType };
+    switch (eventLevel) {
+      case "debug":
+        logger.debug(message, finalMeta);
+        break;
+      case "info":
+        logger.info(message, finalMeta);
+        break;
+      case "warn":
+        logger.warn(message, finalMeta);
+        break;
+      case "error":
+        logger.error(message, finalMeta);
+        break;
+    }
+  }
+  function baseMeta(ctx) {
+    const meta = {
+      sagaName: ctx.sagaName,
+      correlationId: ctx.correlationId,
+      messageId: ctx.envelope.id,
+      messageType: ctx.envelope.type
+    };
+    if (ctx.sagaId) {
+      meta.sagaId = ctx.sagaId;
+    }
+    if (logPayload) {
+      meta.payload = ctx.envelope.payload;
+    }
+    return meta;
+  }
+  return async (ctx, next) => {
+    const startTime = Date.now();
+    log("debug", "saga.message.received", "Message received", {
+      ...baseMeta(ctx),
+      headers: ctx.envelope.headers
+    });
+    log("debug", "saga.handler.start", "Handler starting", baseMeta(ctx));
+    try {
+      await next();
+      const duration = Date.now() - startTime;
+      const isNew = ctx.preState === void 0 && ctx.postState !== void 0;
+      const isCompleted = ctx.postState?.metadata?.isCompleted === true;
+      const wasAlreadyCompleted = ctx.preState?.metadata?.isCompleted === true;
+      const resultMeta = {
+        ...baseMeta(ctx),
+        durationMs: duration
+      };
+      if (ctx.sagaId) {
+        resultMeta.sagaId = ctx.sagaId;
+      }
+      if (logState && ctx.postState) {
+        resultMeta.state = ctx.postState;
+      }
+      if (ctx.postState) {
+        resultMeta.version = ctx.postState.metadata.version;
+      }
+      if (isNew) {
+        log("info", "saga.state.created", "Saga instance created", resultMeta);
+      } else if (isCompleted && !wasAlreadyCompleted) {
+        log("info", "saga.state.completed", "Saga completed", resultMeta);
+      } else if (ctx.postState) {
+        log("debug", "saga.state.updated", "Saga state updated", resultMeta);
+      }
+      log("debug", "saga.handler.success", "Handler completed successfully", {
+        ...baseMeta(ctx),
+        durationMs: duration
+      });
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      log("error", "saga.handler.error", "Handler failed", {
+        ...baseMeta(ctx),
+        durationMs: duration,
+        error: error instanceof Error ? error.message : String(error),
+        errorType: error instanceof Error ? error.name : "UnknownError",
+        stack: error instanceof Error ? error.stack : void 0
+      });
+      throw error;
+    }
+  };
+}
+export {
+  createLoggingMiddleware
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/createLoggingMiddleware.ts"],"sourcesContent":["import type { SagaMiddleware, SagaPipelineContext, Logger } from \"@saga-bus/core\";\nimport type { LoggingMiddlewareOptions, LogLevel, LogEventType } from \"./types.js\";\n\n/**\n * Log level priorities for filtering.\n */\nconst LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {\n  debug: 0,\n  info: 1,\n  warn: 2,\n  error: 3,\n};\n\n/**\n * Default console-based logger.\n */\nconst defaultLogger: Logger = {\n  debug: (message, meta) => console.debug(`[saga-bus] ${message}`, meta ?? \"\"),\n  info: (message, meta) => console.info(`[saga-bus] ${message}`, meta ?? \"\"),\n  warn: (message, meta) => console.warn(`[saga-bus] ${message}`, meta ?? \"\"),\n  error: (message, meta) => console.error(`[saga-bus] ${message}`, meta ?? \"\"),\n};\n\n/**\n * Create a logging middleware for saga execution.\n *\n * @example\n * ```typescript\n * const loggingMiddleware = createLoggingMiddleware({\n *   level: \"debug\",\n *   logPayload: true,\n * });\n *\n * const bus = createBus({\n *   transport,\n *   sagas: [...],\n *   middleware: [loggingMiddleware],\n * });\n * ```\n */\nexport function createLoggingMiddleware(\n  options: LoggingMiddlewareOptions = {}\n): SagaMiddleware {\n  const {\n    logger = defaultLogger,\n    level = \"info\",\n    logPayload = false,\n    logState = false,\n    filter,\n    enrichMeta,\n  } = options;\n\n  const minPriority = LOG_LEVEL_PRIORITY[level];\n\n  /**\n   * Log an event if it meets the level threshold.\n   */\n  function log(\n    eventLevel: LogLevel,\n    eventType: LogEventType,\n    message: string,\n    meta: Record<string, unknown>\n  ): void {\n    if (LOG_LEVEL_PRIORITY[eventLevel] < minPriority) {\n      return;\n    }\n\n    if (filter && !filter(eventType, meta)) {\n      return;\n    }\n\n    const enrichedMeta = enrichMeta ? enrichMeta(meta) : meta;\n    const finalMeta = { ...enrichedMeta, event: eventType };\n\n    switch (eventLevel) {\n      case \"debug\":\n        logger.debug(message, finalMeta);\n        break;\n      case \"info\":\n        logger.info(message, finalMeta);\n        break;\n      case \"warn\":\n        logger.warn(message, finalMeta);\n        break;\n      case \"error\":\n        logger.error(message, finalMeta);\n        break;\n    }\n  }\n\n  /**\n   * Build base metadata from pipeline context.\n   */\n  function baseMeta(ctx: SagaPipelineContext): Record<string, unknown> {\n    const meta: Record<string, unknown> = {\n      sagaName: ctx.sagaName,\n      correlationId: ctx.correlationId,\n      messageId: ctx.envelope.id,\n      messageType: ctx.envelope.type,\n    };\n\n    if (ctx.sagaId) {\n      meta.sagaId = ctx.sagaId;\n    }\n\n    if (logPayload) {\n      meta.payload = ctx.envelope.payload;\n    }\n\n    return meta;\n  }\n\n  return async (ctx: SagaPipelineContext, next: () => Promise<void>) => {\n    const startTime = Date.now();\n\n    // Log message received\n    log(\"debug\", \"saga.message.received\", \"Message received\", {\n      ...baseMeta(ctx),\n      headers: ctx.envelope.headers,\n    });\n\n    // Log handler start\n    log(\"debug\", \"saga.handler.start\", \"Handler starting\", baseMeta(ctx));\n\n    try {\n      await next();\n\n      const duration = Date.now() - startTime;\n\n      // Determine what happened\n      const isNew = ctx.preState === undefined && ctx.postState !== undefined;\n      const isCompleted = ctx.postState?.metadata?.isCompleted === true;\n      const wasAlreadyCompleted = ctx.preState?.metadata?.isCompleted === true;\n\n      // Build result metadata\n      const resultMeta: Record<string, unknown> = {\n        ...baseMeta(ctx),\n        durationMs: duration,\n      };\n\n      if (ctx.sagaId) {\n        resultMeta.sagaId = ctx.sagaId;\n      }\n\n      if (logState && ctx.postState) {\n        resultMeta.state = ctx.postState;\n      }\n\n      if (ctx.postState) {\n        resultMeta.version = ctx.postState.metadata.version;\n      }\n\n      // Log appropriate event\n      if (isNew) {\n        log(\"info\", \"saga.state.created\", \"Saga instance created\", resultMeta);\n      } else if (isCompleted && !wasAlreadyCompleted) {\n        log(\"info\", \"saga.state.completed\", \"Saga completed\", resultMeta);\n      } else if (ctx.postState) {\n        log(\"debug\", \"saga.state.updated\", \"Saga state updated\", resultMeta);\n      }\n\n      // Log handler success\n      log(\"debug\", \"saga.handler.success\", \"Handler completed successfully\", {\n        ...baseMeta(ctx),\n        durationMs: duration,\n      });\n    } catch (error) {\n      const duration = Date.now() - startTime;\n\n      // Log handler error\n      log(\"error\", \"saga.handler.error\", \"Handler failed\", {\n        ...baseMeta(ctx),\n        durationMs: duration,\n        error: error instanceof Error ? error.message : String(error),\n        errorType: error instanceof Error ? error.name : \"UnknownError\",\n        stack: error instanceof Error ? error.stack : undefined,\n      });\n\n      // Re-throw to let error handling proceed\n      throw error;\n    }\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@saga-bus/middleware-logging",
+  "version": "1.0.0",
+  "description": "Structured logging middleware 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/middleware-logging"
+  },
+  "bugs": {
+    "url": "https://github.com/deanforan/saga-bus/issues"
+  },
+  "homepage": "https://github.com/deanforan/saga-bus#readme",
+  "keywords": [
+    "saga",
+    "message-bus",
+    "middleware",
+    "logging",
+    "observability"
+  ],
+  "dependencies": {
+    "@saga-bus/core": "0.1.0"
+  },
+  "devDependencies": {
+    "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"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}