@emmett-community/emmett-expressjs-with-openapi 0.4.0 → 0.5.0

package/README.md

@@ -182,6 +182,51 @@ startAPI(app, { port: 3000, logger });
 
 No logs are emitted when logger is not provided.
 
+#### Logger Contract
+
+This package defines the canonical Logger interface for the Emmett ecosystem. Implementations (Pino, Winston, etc.) MUST adapt to this contract.
+
+```typescript
+interface Logger {
+  debug(context: Record<string, unknown>, message?: string): void;
+  info(context: Record<string, unknown>, message?: string): void;
+  warn(context: Record<string, unknown>, message?: string): void;
+  error(context: Record<string, unknown>, message?: string): void;
+}
+```
+
+**Semantic Rules:**
+
+- `context` (first parameter): Structured data for the log entry
+- `message` (second parameter): Human-readable message
+- The order is never inverted
+
+Pino implements this contract natively. For other loggers like Winston, you need to create an adapter.
+
+> **Note**: The adapter example below is for demonstration purposes only. It is NOT part of the public API and NOT an official recommendation. Users must implement their own adapters for non-Pino loggers.
+
+```typescript
+import winston from 'winston';
+import type { Logger } from '@emmett-community/emmett-expressjs-with-openapi';
+
+const winstonLogger = winston.createLogger({ /* config */ });
+
+const logger: Logger = {
+  debug(context, message) {
+    winstonLogger.debug(message ?? '', context);
+  },
+  info(context, message) {
+    winstonLogger.info(message ?? '', context);
+  },
+  warn(context, message) {
+    winstonLogger.warn(message ?? '', context);
+  },
+  error(context, message) {
+    winstonLogger.error(message ?? '', context);
+  },
+};
+```
+
 ### Tracing
 
 If your application initializes OpenTelemetry, this package will emit spans automatically. Tracing is passive - spans are no-ops when OpenTelemetry is not configured.

package/dist/chunk-FSPH5TRT.cjs

@@ -0,0 +1,45 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/observability.ts
+var safeLog = {
+  debug: (logger, msg, data) => {
+    if (!logger) return;
+    logger.debug(normalizeContext(data), msg);
+  },
+  info: (logger, msg, data) => {
+    if (!logger) return;
+    logger.info(normalizeContext(data), msg);
+  },
+  warn: (logger, msg, data) => {
+    if (!logger) return;
+    logger.warn(normalizeContext(data), msg);
+  },
+  error: (logger, msg, error) => {
+    if (!logger) return;
+    logger.error(normalizeErrorContext(error), msg);
+  }
+};
+function normalizeContext(data) {
+  if (data === void 0 || data === null) {
+    return {};
+  }
+  if (typeof data === "object" && !Array.isArray(data)) {
+    return { ...data };
+  }
+  return { data };
+}
+function normalizeErrorContext(error) {
+  if (error === void 0 || error === null) {
+    return {};
+  }
+  if (error instanceof Error) {
+    return { err: error };
+  }
+  if (typeof error === "object" && !Array.isArray(error)) {
+    return { ...error };
+  }
+  return { err: error };
+}
+
+
+
+exports.safeLog = safeLog;
+//# sourceMappingURL=chunk-FSPH5TRT.cjs.map

package/dist/chunk-FSPH5TRT.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/emmett-expressjs-with-openapi/emmett-expressjs-with-openapi/dist/chunk-FSPH5TRT.cjs","../src/observability.ts"],"names":[],"mappings":"AAAA;AC+FO,IAAM,QAAA,EAAU;AAAA,EACrB,KAAA,EAAO,CAAC,MAAA,EAA4B,GAAA,EAAa,IAAA,EAAA,GAAmB;AAClE,IAAA,GAAA,CAAI,CAAC,MAAA,EAAQ,MAAA;AACb,IAAA,MAAA,CAAO,KAAA,CAAM,gBAAA,CAAiB,IAAI,CAAA,EAAG,GAAG,CAAA;AAAA,EAC1C,CAAA;AAAA,EACA,IAAA,EAAM,CAAC,MAAA,EAA4B,GAAA,EAAa,IAAA,EAAA,GAAmB;AACjE,IAAA,GAAA,CAAI,CAAC,MAAA,EAAQ,MAAA;AACb,IAAA,MAAA,CAAO,IAAA,CAAK,gBAAA,CAAiB,IAAI,CAAA,EAAG,GAAG,CAAA;AAAA,EACzC,CAAA;AAAA,EACA,IAAA,EAAM,CAAC,MAAA,EAA4B,GAAA,EAAa,IAAA,EAAA,GAAmB;AACjE,IAAA,GAAA,CAAI,CAAC,MAAA,EAAQ,MAAA;AACb,IAAA,MAAA,CAAO,IAAA,CAAK,gBAAA,CAAiB,IAAI,CAAA,EAAG,GAAG,CAAA;AAAA,EACzC,CAAA;AAAA,EACA,KAAA,EAAO,CAAC,MAAA,EAA4B,GAAA,EAAa,KAAA,EAAA,GAAoB;AACnE,IAAA,GAAA,CAAI,CAAC,MAAA,EAAQ,MAAA;AACb,IAAA,MAAA,CAAO,KAAA,CAAM,qBAAA,CAAsB,KAAK,CAAA,EAAG,GAAG,CAAA;AAAA,EAChD;AACF,CAAA;AAMA,SAAS,gBAAA,CAAiB,IAAA,EAAwC;AAChE,EAAA,GAAA,CAAI,KAAA,IAAS,KAAA,EAAA,GAAa,KAAA,IAAS,IAAA,EAAM;AACvC,IAAA,OAAO,CAAC,CAAA;AAAA,EACV;AACA,EAAA,GAAA,CAAI,OAAO,KAAA,IAAS,SAAA,GAAY,CAAC,KAAA,CAAM,OAAA,CAAQ,IAAI,CAAA,EAAG;AACpD,IAAA,OAAO,EAAE,GAAI,KAAiC,CAAA;AAAA,EAChD;AACA,EAAA,OAAO,EAAE,KAAK,CAAA;AAChB;AAOA,SAAS,qBAAA,CAAsB,KAAA,EAAyC;AACtE,EAAA,GAAA,CAAI,MAAA,IAAU,KAAA,EAAA,GAAa,MAAA,IAAU,IAAA,EAAM;AACzC,IAAA,OAAO,CAAC,CAAA;AAAA,EACV;AACA,EAAA,GAAA,CAAI,MAAA,WAAiB,KAAA,EAAO;AAC1B,IAAA,OAAO,EAAE,GAAA,EAAK,MAAM,CAAA;AAAA,EACtB;AACA,EAAA,GAAA,CAAI,OAAO,MAAA,IAAU,SAAA,GAAY,CAAC,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG;AACtD,IAAA,OAAO,EAAE,GAAI,MAAkC,CAAA;AAAA,EACjD;AACA,EAAA,OAAO,EAAE,GAAA,EAAK,MAAM,CAAA;AACtB;ADxGA;AACA;AACE;AACF,0BAAC","file":"/home/runner/work/emmett-expressjs-with-openapi/emmett-expressjs-with-openapi/dist/chunk-FSPH5TRT.cjs","sourcesContent":[null,"/**\n * Observability types for emmett-expressjs-with-openapi.\n *\n * This module provides optional logging integration\n * following a \"silent by default\" philosophy.\n */\n\n/**\n * Canonical Logger contract for the Emmett ecosystem.\n *\n * This package defines the canonical Logger interface.\n * Implementations (Pino, Winston, etc.) MUST adapt to this contract.\n * This contract MUST NOT adapt to any specific implementation.\n *\n * Semantic Rules:\n * - context (first parameter): ALWAYS structured data as Record<string, unknown>\n * - message (second parameter): ALWAYS the human-readable log message\n * - The order is NEVER inverted\n * - The (message, data) form is NOT valid for this contract\n *\n * @example\n * ```typescript\n * // Pino - native compatibility\n * import pino from 'pino';\n * const logger = pino();\n * // logger.info({ orderId }, 'Order created') matches our contract\n * ```\n */\nexport interface Logger {\n  /**\n   * Log debug-level message with structured context.\n   * @param context - Structured data to include in the log entry\n   * @param message - Optional human-readable message\n   */\n  debug(context: Record<string, unknown>, message?: string): void;\n\n  /**\n   * Log info-level message with structured context.\n   * @param context - Structured data to include in the log entry\n   * @param message - Optional human-readable message\n   */\n  info(context: Record<string, unknown>, message?: string): void;\n\n  /**\n   * Log warn-level message with structured context.\n   * @param context - Structured data to include in the log entry\n   * @param message - Optional human-readable message\n   */\n  warn(context: Record<string, unknown>, message?: string): void;\n\n  /**\n   * Log error-level message with structured context.\n   * @param context - Structured data to include in the log entry (may include 'err' key)\n   * @param message - Optional human-readable message\n   */\n  error(context: Record<string, unknown>, message?: string): void;\n}\n\n/**\n * Observability configuration options.\n */\nexport type ObservabilityOptions = {\n  /**\n   * Optional logger instance for diagnostic output.\n   * When not provided, the library operates silently.\n   *\n   * @example\n   * ```typescript\n   * import pino from 'pino';\n   *\n   * const logger = pino();\n   *\n   * const app = await getApplication({\n   *   observability: { logger },\n   * });\n   * ```\n   */\n  logger?: Logger;\n};\n\n/**\n * Internal helper to safely call logger methods.\n *\n * IMPORTANT: safeLog is the ONLY translation point between internal usage\n * and the Logger contract.\n *\n * Internal Usage Pattern:\n *   safeLog.info(logger, 'Order created', { orderId: 123 })\n *\n * Translation to Logger Contract:\n *   logger.info({ orderId: 123 }, 'Order created')\n *\n * This allows ergonomic internal usage while ensuring all injected loggers\n * receive calls in the canonical (context, message) format.\n */\nexport const safeLog = {\n  debug: (logger: Logger | undefined, msg: string, data?: unknown) => {\n    if (!logger) return;\n    logger.debug(normalizeContext(data), msg);\n  },\n  info: (logger: Logger | undefined, msg: string, data?: unknown) => {\n    if (!logger) return;\n    logger.info(normalizeContext(data), msg);\n  },\n  warn: (logger: Logger | undefined, msg: string, data?: unknown) => {\n    if (!logger) return;\n    logger.warn(normalizeContext(data), msg);\n  },\n  error: (logger: Logger | undefined, msg: string, error?: unknown) => {\n    if (!logger) return;\n    logger.error(normalizeErrorContext(error), msg);\n  },\n};\n\n/**\n * Normalize data to context object for regular log methods.\n * Creates a shallow copy to avoid accidental mutation of the original object.\n */\nfunction normalizeContext(data: unknown): Record<string, unknown> {\n  if (data === undefined || data === null) {\n    return {};\n  }\n  if (typeof data === 'object' && !Array.isArray(data)) {\n    return { ...(data as Record<string, unknown>) };\n  }\n  return { data };\n}\n\n/**\n * Normalize error to context object for error log method.\n * Uses 'err' key for Pino compatibility (Pino serializes Error objects on 'err' key).\n * Creates a shallow copy to avoid accidental mutation of the original object.\n */\nfunction normalizeErrorContext(error: unknown): Record<string, unknown> {\n  if (error === undefined || error === null) {\n    return {};\n  }\n  if (error instanceof Error) {\n    return { err: error };\n  }\n  if (typeof error === 'object' && !Array.isArray(error)) {\n    return { ...(error as Record<string, unknown>) };\n  }\n  return { err: error };\n}\n"]}

package/dist/chunk-PZBLPYJH.js

@@ -0,0 +1,45 @@
+// src/observability.ts
+var safeLog = {
+  debug: (logger, msg, data) => {
+    if (!logger) return;
+    logger.debug(normalizeContext(data), msg);
+  },
+  info: (logger, msg, data) => {
+    if (!logger) return;
+    logger.info(normalizeContext(data), msg);
+  },
+  warn: (logger, msg, data) => {
+    if (!logger) return;
+    logger.warn(normalizeContext(data), msg);
+  },
+  error: (logger, msg, error) => {
+    if (!logger) return;
+    logger.error(normalizeErrorContext(error), msg);
+  }
+};
+function normalizeContext(data) {
+  if (data === void 0 || data === null) {
+    return {};
+  }
+  if (typeof data === "object" && !Array.isArray(data)) {
+    return { ...data };
+  }
+  return { data };
+}
+function normalizeErrorContext(error) {
+  if (error === void 0 || error === null) {
+    return {};
+  }
+  if (error instanceof Error) {
+    return { err: error };
+  }
+  if (typeof error === "object" && !Array.isArray(error)) {
+    return { ...error };
+  }
+  return { err: error };
+}
+
+export {
+  safeLog
+};
+//# sourceMappingURL=chunk-PZBLPYJH.js.map

package/dist/chunk-PZBLPYJH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/observability.ts"],"sourcesContent":["/**\n * Observability types for emmett-expressjs-with-openapi.\n *\n * This module provides optional logging integration\n * following a \"silent by default\" philosophy.\n */\n\n/**\n * Canonical Logger contract for the Emmett ecosystem.\n *\n * This package defines the canonical Logger interface.\n * Implementations (Pino, Winston, etc.) MUST adapt to this contract.\n * This contract MUST NOT adapt to any specific implementation.\n *\n * Semantic Rules:\n * - context (first parameter): ALWAYS structured data as Record<string, unknown>\n * - message (second parameter): ALWAYS the human-readable log message\n * - The order is NEVER inverted\n * - The (message, data) form is NOT valid for this contract\n *\n * @example\n * ```typescript\n * // Pino - native compatibility\n * import pino from 'pino';\n * const logger = pino();\n * // logger.info({ orderId }, 'Order created') matches our contract\n * ```\n */\nexport interface Logger {\n  /**\n   * Log debug-level message with structured context.\n   * @param context - Structured data to include in the log entry\n   * @param message - Optional human-readable message\n   */\n  debug(context: Record<string, unknown>, message?: string): void;\n\n  /**\n   * Log info-level message with structured context.\n   * @param context - Structured data to include in the log entry\n   * @param message - Optional human-readable message\n   */\n  info(context: Record<string, unknown>, message?: string): void;\n\n  /**\n   * Log warn-level message with structured context.\n   * @param context - Structured data to include in the log entry\n   * @param message - Optional human-readable message\n   */\n  warn(context: Record<string, unknown>, message?: string): void;\n\n  /**\n   * Log error-level message with structured context.\n   * @param context - Structured data to include in the log entry (may include 'err' key)\n   * @param message - Optional human-readable message\n   */\n  error(context: Record<string, unknown>, message?: string): void;\n}\n\n/**\n * Observability configuration options.\n */\nexport type ObservabilityOptions = {\n  /**\n   * Optional logger instance for diagnostic output.\n   * When not provided, the library operates silently.\n   *\n   * @example\n   * ```typescript\n   * import pino from 'pino';\n   *\n   * const logger = pino();\n   *\n   * const app = await getApplication({\n   *   observability: { logger },\n   * });\n   * ```\n   */\n  logger?: Logger;\n};\n\n/**\n * Internal helper to safely call logger methods.\n *\n * IMPORTANT: safeLog is the ONLY translation point between internal usage\n * and the Logger contract.\n *\n * Internal Usage Pattern:\n *   safeLog.info(logger, 'Order created', { orderId: 123 })\n *\n * Translation to Logger Contract:\n *   logger.info({ orderId: 123 }, 'Order created')\n *\n * This allows ergonomic internal usage while ensuring all injected loggers\n * receive calls in the canonical (context, message) format.\n */\nexport const safeLog = {\n  debug: (logger: Logger | undefined, msg: string, data?: unknown) => {\n    if (!logger) return;\n    logger.debug(normalizeContext(data), msg);\n  },\n  info: (logger: Logger | undefined, msg: string, data?: unknown) => {\n    if (!logger) return;\n    logger.info(normalizeContext(data), msg);\n  },\n  warn: (logger: Logger | undefined, msg: string, data?: unknown) => {\n    if (!logger) return;\n    logger.warn(normalizeContext(data), msg);\n  },\n  error: (logger: Logger | undefined, msg: string, error?: unknown) => {\n    if (!logger) return;\n    logger.error(normalizeErrorContext(error), msg);\n  },\n};\n\n/**\n * Normalize data to context object for regular log methods.\n * Creates a shallow copy to avoid accidental mutation of the original object.\n */\nfunction normalizeContext(data: unknown): Record<string, unknown> {\n  if (data === undefined || data === null) {\n    return {};\n  }\n  if (typeof data === 'object' && !Array.isArray(data)) {\n    return { ...(data as Record<string, unknown>) };\n  }\n  return { data };\n}\n\n/**\n * Normalize error to context object for error log method.\n * Uses 'err' key for Pino compatibility (Pino serializes Error objects on 'err' key).\n * Creates a shallow copy to avoid accidental mutation of the original object.\n */\nfunction normalizeErrorContext(error: unknown): Record<string, unknown> {\n  if (error === undefined || error === null) {\n    return {};\n  }\n  if (error instanceof Error) {\n    return { err: error };\n  }\n  if (typeof error === 'object' && !Array.isArray(error)) {\n    return { ...(error as Record<string, unknown>) };\n  }\n  return { err: error };\n}\n"],"mappings":";AA+FO,IAAM,UAAU;AAAA,EACrB,OAAO,CAAC,QAA4B,KAAa,SAAmB;AAClE,QAAI,CAAC,OAAQ;AACb,WAAO,MAAM,iBAAiB,IAAI,GAAG,GAAG;AAAA,EAC1C;AAAA,EACA,MAAM,CAAC,QAA4B,KAAa,SAAmB;AACjE,QAAI,CAAC,OAAQ;AACb,WAAO,KAAK,iBAAiB,IAAI,GAAG,GAAG;AAAA,EACzC;AAAA,EACA,MAAM,CAAC,QAA4B,KAAa,SAAmB;AACjE,QAAI,CAAC,OAAQ;AACb,WAAO,KAAK,iBAAiB,IAAI,GAAG,GAAG;AAAA,EACzC;AAAA,EACA,OAAO,CAAC,QAA4B,KAAa,UAAoB;AACnE,QAAI,CAAC,OAAQ;AACb,WAAO,MAAM,sBAAsB,KAAK,GAAG,GAAG;AAAA,EAChD;AACF;AAMA,SAAS,iBAAiB,MAAwC;AAChE,MAAI,SAAS,UAAa,SAAS,MAAM;AACvC,WAAO,CAAC;AAAA,EACV;AACA,MAAI,OAAO,SAAS,YAAY,CAAC,MAAM,QAAQ,IAAI,GAAG;AACpD,WAAO,EAAE,GAAI,KAAiC;AAAA,EAChD;AACA,SAAO,EAAE,KAAK;AAChB;AAOA,SAAS,sBAAsB,OAAyC;AACtE,MAAI,UAAU,UAAa,UAAU,MAAM;AACzC,WAAO,CAAC;AAAA,EACV;AACA,MAAI,iBAAiB,OAAO;AAC1B,WAAO,EAAE,KAAK,MAAM;AAAA,EACtB;AACA,MAAI,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK,GAAG;AACtD,WAAO,EAAE,GAAI,MAAkC;AAAA,EACjD;AACA,SAAO,EAAE,KAAK,MAAM;AACtB;","names":[]}

package/dist/{handler-importer-UFV7TKBN.cjs → handler-importer-BRJVJNST.cjs}

@@ -3,20 +3,20 @@
 var _chunkMRSGTROWcjs = require('./chunk-MRSGTROW.cjs');
 
 
-var _chunkBY65ZALYcjs = require('./chunk-BY65ZALY.cjs');
+var _chunkFSPH5TRTcjs = require('./chunk-FSPH5TRT.cjs');
 require('./chunk-GS7T56RP.cjs');
 
 // src/internal/handler-importer.ts
 var _url = require('url');
 async function importAndRegisterHandlers(modules, logger) {
-  _chunkBY65ZALYcjs.safeLog.debug(logger, "Importing handler modules", {
+  _chunkFSPH5TRTcjs.safeLog.debug(logger, "Importing handler modules", {
     count: modules.length,
     modules: modules.map((m) => m.moduleName)
   });
   const importedHandlers = {};
   for (const module of modules) {
     try {
-      _chunkBY65ZALYcjs.safeLog.debug(logger, "Importing handler module", {
+      _chunkFSPH5TRTcjs.safeLog.debug(logger, "Importing handler module", {
         moduleName: module.moduleName,
         absolutePath: module.absolutePath
       });
@@ -24,11 +24,11 @@ async function importAndRegisterHandlers(modules, logger) {
       const importedModule = await Promise.resolve().then(() => _interopRequireWildcard(require(fileUrl)));
       _chunkMRSGTROWcjs.registerHandlerModule.call(void 0, module.absolutePath, importedModule);
       importedHandlers[module.moduleName] = importedModule;
-      _chunkBY65ZALYcjs.safeLog.debug(logger, "Handler module imported successfully", {
+      _chunkFSPH5TRTcjs.safeLog.debug(logger, "Handler module imported successfully", {
         moduleName: module.moduleName
       });
     } catch (error) {
-      _chunkBY65ZALYcjs.safeLog.error(
+      _chunkFSPH5TRTcjs.safeLog.error(
         logger,
         `Failed to import handler module "${module.moduleName}"`,
         error
@@ -43,4 +43,4 @@ async function importAndRegisterHandlers(modules, logger) {
 
 
 exports.importAndRegisterHandlers = importAndRegisterHandlers;
-//# sourceMappingURL=handler-importer-UFV7TKBN.cjs.map
+//# sourceMappingURL=handler-importer-BRJVJNST.cjs.map

package/dist/{handler-importer-UFV7TKBN.cjs.map → handler-importer-BRJVJNST.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/emmett-expressjs-with-openapi/emmett-expressjs-with-openapi/dist/handler-importer-UFV7TKBN.cjs","../src/internal/handler-importer.ts"],"names":[],"mappings":"AAAA;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B,gCAA6B;AAC7B;AACA;ACCA,0BAA8B;AAc9B,MAAA,SAAsB,yBAAA,CACpB,OAAA,EACA,MAAA,EACiC;AACjC,EAAA,yBAAA,CAAQ,KAAA,CAAM,MAAA,EAAQ,2BAAA,EAA6B;AAAA,IACjD,KAAA,EAAO,OAAA,CAAQ,MAAA;AAAA,IACf,OAAA,EAAS,OAAA,CAAQ,GAAA,CAAI,CAAC,CAAA,EAAA,GAAM,CAAA,CAAE,UAAU;AAAA,EAC1C,CAAC,CAAA;AAED,EAAA,MAAM,iBAAA,EAA2C,CAAC,CAAA;AAElD,EAAA,IAAA,CAAA,MAAW,OAAA,GAAU,OAAA,EAAS;AAC5B,IAAA,IAAI;AACF,MAAA,yBAAA,CAAQ,KAAA,CAAM,MAAA,EAAQ,0BAAA,EAA4B;AAAA,QAChD,UAAA,EAAY,MAAA,CAAO,UAAA;AAAA,QACnB,YAAA,EAAc,MAAA,CAAO;AAAA,MACvB,CAAC,CAAA;AAGD,MAAA,MAAM,QAAA,EAAU,gCAAA,MAAc,CAAO,YAAY,CAAA,CAAE,IAAA;AAGnD,MAAA,MAAM,eAAA,EAAiB,MAAM,4DAAA,CAAO,OAAA,GAAA;AAGpC,MAAA,qDAAA,MAAsB,CAAO,YAAA,EAAc,cAAc,CAAA;AAGzD,MAAA,gBAAA,CAAiB,MAAA,CAAO,UAAU,EAAA,EAAI,cAAA;AAEtC,MAAA,yBAAA,CAAQ,KAAA,CAAM,MAAA,EAAQ,sCAAA,EAAwC;AAAA,QAC5D,UAAA,EAAY,MAAA,CAAO;AAAA,MACrB,CAAC,CAAA;AAAA,IACH,EAAA,MAAA,CAAS,KAAA,EAAO;AACd,MAAA,yBAAA,CAAQ,KAAA;AAAA,QACN,MAAA;AAAA,QACA,CAAA,iCAAA,EAAoC,MAAA,CAAO,UAAU,CAAA,CAAA,CAAA;AAAA,QACrD;AAAA,MACF,CAAA;AACA,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,iCAAA,EAAoC,MAAA,CAAO,UAAU,CAAA,OAAA,EAAU,MAAA,CAAO,YAAY,CAAA,EAAA,EAC/E,KAAA,CAAgB,OACnB,CAAA;AAAA,MAAA;AACF,IAAA;AACF,EAAA;AAGF,EAAA;AACF;AD7BA;AACA;AACA","file":"/home/runner/work/emmett-expressjs-with-openapi/emmett-expressjs-with-openapi/dist/handler-importer-UFV7TKBN.cjs","sourcesContent":[null,"/**\n * Handler module importer.\n *\n * INTERNAL MODULE - Not part of public API.\n *\n * Dynamically imports handler modules and registers them in the ESM resolver cache,\n * enabling automatic handler discovery without manual registration.\n */\n\nimport { pathToFileURL } from 'node:url';\nimport { type Logger, safeLog } from '../observability';\nimport { registerHandlerModule } from './esm-resolver.js';\nimport type { HandlerModuleInfo } from './openapi-parser.js';\n\nexport type ImportedHandlerModules = Record<string, any>;\n\n/**\n * Dynamically import and register all handler modules.\n *\n * @param modules - Handler module information from OpenAPI parser\n * @param logger - Optional logger for debug output\n * @returns Object containing all imported modules, keyed by module name\n */\nexport async function importAndRegisterHandlers(\n  modules: HandlerModuleInfo[],\n  logger?: Logger,\n): Promise<ImportedHandlerModules> {\n  safeLog.debug(logger, 'Importing handler modules', {\n    count: modules.length,\n    modules: modules.map((m) => m.moduleName),\n  });\n\n  const importedHandlers: ImportedHandlerModules = {};\n\n  for (const module of modules) {\n    try {\n      safeLog.debug(logger, 'Importing handler module', {\n        moduleName: module.moduleName,\n        absolutePath: module.absolutePath,\n      });\n\n      // Convert to file:// URL for dynamic import\n      const fileUrl = pathToFileURL(module.absolutePath).href;\n\n      // Dynamically import the handler module\n      const importedModule = await import(fileUrl);\n\n      // Register in ESM resolver cache\n      registerHandlerModule(module.absolutePath, importedModule);\n\n      // Store in result object keyed by module name\n      importedHandlers[module.moduleName] = importedModule;\n\n      safeLog.debug(logger, 'Handler module imported successfully', {\n        moduleName: module.moduleName,\n      });\n    } catch (error) {\n      safeLog.error(\n        logger,\n        `Failed to import handler module \"${module.moduleName}\"`,\n        error,\n      );\n      throw new Error(\n        `Failed to import handler module \"${module.moduleName}\" from ${module.absolutePath}: ${\n          (error as Error).message\n        }`,\n      );\n    }\n  }\n\n  return importedHandlers;\n}\n"]}
+{"version":3,"sources":["/home/runner/work/emmett-expressjs-with-openapi/emmett-expressjs-with-openapi/dist/handler-importer-BRJVJNST.cjs","../src/internal/handler-importer.ts"],"names":[],"mappings":"AAAA;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B,gCAA6B;AAC7B;AACA;ACCA,0BAA8B;AAc9B,MAAA,SAAsB,yBAAA,CACpB,OAAA,EACA,MAAA,EACiC;AACjC,EAAA,yBAAA,CAAQ,KAAA,CAAM,MAAA,EAAQ,2BAAA,EAA6B;AAAA,IACjD,KAAA,EAAO,OAAA,CAAQ,MAAA;AAAA,IACf,OAAA,EAAS,OAAA,CAAQ,GAAA,CAAI,CAAC,CAAA,EAAA,GAAM,CAAA,CAAE,UAAU;AAAA,EAC1C,CAAC,CAAA;AAED,EAAA,MAAM,iBAAA,EAA2C,CAAC,CAAA;AAElD,EAAA,IAAA,CAAA,MAAW,OAAA,GAAU,OAAA,EAAS;AAC5B,IAAA,IAAI;AACF,MAAA,yBAAA,CAAQ,KAAA,CAAM,MAAA,EAAQ,0BAAA,EAA4B;AAAA,QAChD,UAAA,EAAY,MAAA,CAAO,UAAA;AAAA,QACnB,YAAA,EAAc,MAAA,CAAO;AAAA,MACvB,CAAC,CAAA;AAGD,MAAA,MAAM,QAAA,EAAU,gCAAA,MAAc,CAAO,YAAY,CAAA,CAAE,IAAA;AAGnD,MAAA,MAAM,eAAA,EAAiB,MAAM,4DAAA,CAAO,OAAA,GAAA;AAGpC,MAAA,qDAAA,MAAsB,CAAO,YAAA,EAAc,cAAc,CAAA;AAGzD,MAAA,gBAAA,CAAiB,MAAA,CAAO,UAAU,EAAA,EAAI,cAAA;AAEtC,MAAA,yBAAA,CAAQ,KAAA,CAAM,MAAA,EAAQ,sCAAA,EAAwC;AAAA,QAC5D,UAAA,EAAY,MAAA,CAAO;AAAA,MACrB,CAAC,CAAA;AAAA,IACH,EAAA,MAAA,CAAS,KAAA,EAAO;AACd,MAAA,yBAAA,CAAQ,KAAA;AAAA,QACN,MAAA;AAAA,QACA,CAAA,iCAAA,EAAoC,MAAA,CAAO,UAAU,CAAA,CAAA,CAAA;AAAA,QACrD;AAAA,MACF,CAAA;AACA,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,iCAAA,EAAoC,MAAA,CAAO,UAAU,CAAA,OAAA,EAAU,MAAA,CAAO,YAAY,CAAA,EAAA,EAC/E,KAAA,CAAgB,OACnB,CAAA;AAAA,MAAA;AACF,IAAA;AACF,EAAA;AAGF,EAAA;AACF;AD7BA;AACA;AACA","file":"/home/runner/work/emmett-expressjs-with-openapi/emmett-expressjs-with-openapi/dist/handler-importer-BRJVJNST.cjs","sourcesContent":[null,"/**\n * Handler module importer.\n *\n * INTERNAL MODULE - Not part of public API.\n *\n * Dynamically imports handler modules and registers them in the ESM resolver cache,\n * enabling automatic handler discovery without manual registration.\n */\n\nimport { pathToFileURL } from 'node:url';\nimport { type Logger, safeLog } from '../observability';\nimport { registerHandlerModule } from './esm-resolver.js';\nimport type { HandlerModuleInfo } from './openapi-parser.js';\n\nexport type ImportedHandlerModules = Record<string, any>;\n\n/**\n * Dynamically import and register all handler modules.\n *\n * @param modules - Handler module information from OpenAPI parser\n * @param logger - Optional logger for debug output\n * @returns Object containing all imported modules, keyed by module name\n */\nexport async function importAndRegisterHandlers(\n  modules: HandlerModuleInfo[],\n  logger?: Logger,\n): Promise<ImportedHandlerModules> {\n  safeLog.debug(logger, 'Importing handler modules', {\n    count: modules.length,\n    modules: modules.map((m) => m.moduleName),\n  });\n\n  const importedHandlers: ImportedHandlerModules = {};\n\n  for (const module of modules) {\n    try {\n      safeLog.debug(logger, 'Importing handler module', {\n        moduleName: module.moduleName,\n        absolutePath: module.absolutePath,\n      });\n\n      // Convert to file:// URL for dynamic import\n      const fileUrl = pathToFileURL(module.absolutePath).href;\n\n      // Dynamically import the handler module\n      const importedModule = await import(fileUrl);\n\n      // Register in ESM resolver cache\n      registerHandlerModule(module.absolutePath, importedModule);\n\n      // Store in result object keyed by module name\n      importedHandlers[module.moduleName] = importedModule;\n\n      safeLog.debug(logger, 'Handler module imported successfully', {\n        moduleName: module.moduleName,\n      });\n    } catch (error) {\n      safeLog.error(\n        logger,\n        `Failed to import handler module \"${module.moduleName}\"`,\n        error,\n      );\n      throw new Error(\n        `Failed to import handler module \"${module.moduleName}\" from ${module.absolutePath}: ${\n          (error as Error).message\n        }`,\n      );\n    }\n  }\n\n  return importedHandlers;\n}\n"]}

package/dist/{handler-importer-6A237UML.js → handler-importer-V4EJZ2DG.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-5TC7YUZR.js";
 import {
   safeLog
-} from "./chunk-I46UH36B.js";
+} from "./chunk-PZBLPYJH.js";
 
 // src/internal/handler-importer.ts
 import { pathToFileURL } from "url";
@@ -42,4 +42,4 @@ async function importAndRegisterHandlers(modules, logger) {
 export {
   importAndRegisterHandlers
 };
-//# sourceMappingURL=handler-importer-6A237UML.js.map
+//# sourceMappingURL=handler-importer-V4EJZ2DG.js.map

package/dist/index.cjs

@@ -3,7 +3,7 @@
 var _chunkMRSGTROWcjs = require('./chunk-MRSGTROW.cjs');
 
 
-var _chunkBY65ZALYcjs = require('./chunk-BY65ZALY.cjs');
+var _chunkFSPH5TRTcjs = require('./chunk-FSPH5TRT.cjs');
 
 
 var _chunkGS7T56RPcjs = require('./chunk-GS7T56RP.cjs');
@@ -23,7 +23,7 @@ var _module = require('module');
 // src/middlewares/problemDetailsMiddleware.ts
 var _httpproblemdetails = require('http-problem-details');
 var problemDetailsMiddleware = (mapError, logger) => (error, request, response, _next) => {
-  _chunkBY65ZALYcjs.safeLog.error(logger, "Request error", error);
+  _chunkFSPH5TRTcjs.safeLog.error(logger, "Request error", error);
   let problemDetails;
   if (mapError) problemDetails = mapError(error, request);
   problemDetails = _nullishCoalesce(problemDetails, () => ( defaultErrorToProblemDetailsMapping(error)));
@@ -62,7 +62,7 @@ var getApplication = async (options) => {
     observability
   } = options;
   const logger = _optionalChain([observability, 'optionalAccess', _ => _.logger]);
-  _chunkBY65ZALYcjs.safeLog.debug(logger, "Initializing Express application", {
+  _chunkFSPH5TRTcjs.safeLog.debug(logger, "Initializing Express application", {
     hasApis: !!_optionalChain([apis, 'optionalAccess', _2 => _2.length]),
     hasOpenApiValidator: !!openApiValidator,
     hasPinoHttp: !!pinoHttp
@@ -81,7 +81,7 @@ var getApplication = async (options) => {
       const middleware = provider(options2);
       app.use(middleware);
     } catch (error) {
-      _chunkBY65ZALYcjs.safeLog.warn(
+      _chunkFSPH5TRTcjs.safeLog.warn(
         logger,
         "Pino HTTP configuration provided but pino-http package is not installed. Install it with: npm install pino-http"
       );
@@ -103,8 +103,8 @@ var getApplication = async (options) => {
       activateESMResolver();
       const handlersBasePath = typeof openApiValidator.operationHandlers === "string" ? openApiValidator.operationHandlers : openApiValidator.operationHandlers.basePath;
       if (handlersBasePath) {
-        const { extractHandlerModules } = await Promise.resolve().then(() => _interopRequireWildcard(require("./openapi-parser-PW5USNZ4.cjs")));
-        const { importAndRegisterHandlers } = await Promise.resolve().then(() => _interopRequireWildcard(require("./handler-importer-UFV7TKBN.cjs")));
+        const { extractHandlerModules } = await Promise.resolve().then(() => _interopRequireWildcard(require("./openapi-parser-HMWO3IPV.cjs")));
+        const { importAndRegisterHandlers } = await Promise.resolve().then(() => _interopRequireWildcard(require("./handler-importer-BRJVJNST.cjs")));
         const modules = await tracer.startActiveSpan(
           "emmett.openapi.parse_spec",
           async (span) => {
@@ -138,7 +138,7 @@ var getApplication = async (options) => {
               span.setStatus({ code: _api.SpanStatusCode.OK });
               return result;
             } catch (error) {
-              _chunkBY65ZALYcjs.safeLog.error(logger, "Failed to auto-import handler modules", error);
+              _chunkFSPH5TRTcjs.safeLog.error(logger, "Failed to auto-import handler modules", error);
               span.recordException(error);
               span.setStatus({ code: _api.SpanStatusCode.ERROR });
               throw error;
@@ -185,7 +185,7 @@ var getApplication = async (options) => {
         app.use(middleware);
       }
     } catch (error) {
-      _chunkBY65ZALYcjs.safeLog.warn(
+      _chunkFSPH5TRTcjs.safeLog.warn(
         logger,
         "OpenAPI validator configuration provided but express-openapi-validator package is not installed. Install it with: npm install express-openapi-validator"
       );
@@ -202,14 +202,14 @@ var getApplication = async (options) => {
   }
   if (!disableProblemDetailsMiddleware)
     app.use(problemDetailsMiddleware(mapError, logger));
-  _chunkBY65ZALYcjs.safeLog.info(logger, "Express application initialized");
+  _chunkFSPH5TRTcjs.safeLog.info(logger, "Express application initialized");
   return app;
 };
 var startAPI = (app, options = { port: 3e3 }) => {
   const { port, logger } = options;
   const server = _http2.default.createServer(app);
   server.on("listening", () => {
-    _chunkBY65ZALYcjs.safeLog.info(logger, "Server up listening", { port });
+    _chunkFSPH5TRTcjs.safeLog.info(logger, "Server up listening", { port });
   });
   return server.listen(port);
 };
@@ -578,5 +578,5 @@ var ApiSpecification = {
 
 
 
-exports.Accepted = Accepted; exports.ApiE2ESpecification = ApiE2ESpecification; exports.ApiSpecification = ApiSpecification; exports.BadRequest = BadRequest; exports.Conflict = Conflict; exports.Created = Created; exports.DefaultHttpProblemResponseOptions = DefaultHttpProblemResponseOptions; exports.DefaultHttpResponseOptions = DefaultHttpResponseOptions; exports.ETagErrors = ETagErrors; exports.Forbidden = Forbidden; exports.HeaderNames = HeaderNames; exports.HttpProblem = HttpProblem; exports.HttpResponse = HttpResponse; exports.NoContent = NoContent; exports.NotFound = NotFound; exports.OK = OK; exports.PreconditionFailed = PreconditionFailed; exports.WeakETagRegex = WeakETagRegex; exports.createFirebaseAuthSecurityHandlers = createFirebaseAuthSecurityHandlers; exports.createOpenApiValidatorOptions = createOpenApiValidatorOptions; exports.existingStream = existingStream; exports.expect = expect; exports.expectError = expectError; exports.expectNewEvents = expectNewEvents; exports.expectResponse = expectResponse; exports.getApplication = getApplication; exports.getETagFromIfMatch = getETagFromIfMatch; exports.getETagFromIfNotMatch = getETagFromIfNotMatch; exports.getETagValueFromIfMatch = getETagValueFromIfMatch; exports.getWeakETagValue = getWeakETagValue; exports.isOpenApiValidatorAvailable = isOpenApiValidatorAvailable; exports.isWeakETag = isWeakETag; exports.on = on; exports.registerHandlerModule = _chunkMRSGTROWcjs.registerHandlerModule; exports.safeLog = _chunkBY65ZALYcjs.safeLog; exports.send = send; exports.sendAccepted = sendAccepted; exports.sendCreated = sendCreated; exports.sendProblem = sendProblem; exports.setETag = setETag; exports.startAPI = startAPI; exports.toWeakETag = toWeakETag; exports.tracedOn = tracedOn;
+exports.Accepted = Accepted; exports.ApiE2ESpecification = ApiE2ESpecification; exports.ApiSpecification = ApiSpecification; exports.BadRequest = BadRequest; exports.Conflict = Conflict; exports.Created = Created; exports.DefaultHttpProblemResponseOptions = DefaultHttpProblemResponseOptions; exports.DefaultHttpResponseOptions = DefaultHttpResponseOptions; exports.ETagErrors = ETagErrors; exports.Forbidden = Forbidden; exports.HeaderNames = HeaderNames; exports.HttpProblem = HttpProblem; exports.HttpResponse = HttpResponse; exports.NoContent = NoContent; exports.NotFound = NotFound; exports.OK = OK; exports.PreconditionFailed = PreconditionFailed; exports.WeakETagRegex = WeakETagRegex; exports.createFirebaseAuthSecurityHandlers = createFirebaseAuthSecurityHandlers; exports.createOpenApiValidatorOptions = createOpenApiValidatorOptions; exports.existingStream = existingStream; exports.expect = expect; exports.expectError = expectError; exports.expectNewEvents = expectNewEvents; exports.expectResponse = expectResponse; exports.getApplication = getApplication; exports.getETagFromIfMatch = getETagFromIfMatch; exports.getETagFromIfNotMatch = getETagFromIfNotMatch; exports.getETagValueFromIfMatch = getETagValueFromIfMatch; exports.getWeakETagValue = getWeakETagValue; exports.isOpenApiValidatorAvailable = isOpenApiValidatorAvailable; exports.isWeakETag = isWeakETag; exports.on = on; exports.registerHandlerModule = _chunkMRSGTROWcjs.registerHandlerModule; exports.safeLog = _chunkFSPH5TRTcjs.safeLog; exports.send = send; exports.sendAccepted = sendAccepted; exports.sendCreated = sendCreated; exports.sendProblem = sendProblem; exports.setETag = setETag; exports.startAPI = startAPI; exports.toWeakETag = toWeakETag; exports.tracedOn = tracedOn;
 //# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -13,14 +13,51 @@ import TestAgent from 'supertest/lib/agent';
  * following a "silent by default" philosophy.
  */
 /**
- * Minimal logger interface compatible with Pino, Winston, console, and similar loggers.
- * All methods are optional to support partial implementations.
+ * Canonical Logger contract for the Emmett ecosystem.
+ *
+ * This package defines the canonical Logger interface.
+ * Implementations (Pino, Winston, etc.) MUST adapt to this contract.
+ * This contract MUST NOT adapt to any specific implementation.
+ *
+ * Semantic Rules:
+ * - context (first parameter): ALWAYS structured data as Record<string, unknown>
+ * - message (second parameter): ALWAYS the human-readable log message
+ * - The order is NEVER inverted
+ * - The (message, data) form is NOT valid for this contract
+ *
+ * @example
+ * ```typescript
+ * // Pino - native compatibility
+ * import pino from 'pino';
+ * const logger = pino();
+ * // logger.info({ orderId }, 'Order created') matches our contract
+ * ```
  */
 interface Logger {
-    debug?(msg: string, data?: unknown): void;
-    info?(msg: string, data?: unknown): void;
-    warn?(msg: string, data?: unknown): void;
-    error?(msg: string, err?: unknown): void;
+    /**
+     * Log debug-level message with structured context.
+     * @param context - Structured data to include in the log entry
+     * @param message - Optional human-readable message
+     */
+    debug(context: Record<string, unknown>, message?: string): void;
+    /**
+     * Log info-level message with structured context.
+     * @param context - Structured data to include in the log entry
+     * @param message - Optional human-readable message
+     */
+    info(context: Record<string, unknown>, message?: string): void;
+    /**
+     * Log warn-level message with structured context.
+     * @param context - Structured data to include in the log entry
+     * @param message - Optional human-readable message
+     */
+    warn(context: Record<string, unknown>, message?: string): void;
+    /**
+     * Log error-level message with structured context.
+     * @param context - Structured data to include in the log entry (may include 'err' key)
+     * @param message - Optional human-readable message
+     */
+    error(context: Record<string, unknown>, message?: string): void;
 }
 /**
  * Observability configuration options.
@@ -44,14 +81,25 @@ type ObservabilityOptions = {
     logger?: Logger;
 };
 /**
- * Internal helper to safely call logger methods, handling partial implementations.
- * Always use: safeLog.error(logger, msg, error) - never { error }
+ * Internal helper to safely call logger methods.
+ *
+ * IMPORTANT: safeLog is the ONLY translation point between internal usage
+ * and the Logger contract.
+ *
+ * Internal Usage Pattern:
+ *   safeLog.info(logger, 'Order created', { orderId: 123 })
+ *
+ * Translation to Logger Contract:
+ *   logger.info({ orderId: 123 }, 'Order created')
+ *
+ * This allows ergonomic internal usage while ensuring all injected loggers
+ * receive calls in the canonical (context, message) format.
  */
 declare const safeLog: {
-    debug: (logger: Logger | undefined, msg: string, data?: unknown) => void | undefined;
-    info: (logger: Logger | undefined, msg: string, data?: unknown) => void | undefined;
-    warn: (logger: Logger | undefined, msg: string, data?: unknown) => void | undefined;
-    error: (logger: Logger | undefined, msg: string, error?: unknown) => void | undefined;
+    debug: (logger: Logger | undefined, msg: string, data?: unknown) => void;
+    info: (logger: Logger | undefined, msg: string, data?: unknown) => void;
+    warn: (logger: Logger | undefined, msg: string, data?: unknown) => void;
+    error: (logger: Logger | undefined, msg: string, error?: unknown) => void;
 };
 
 type AuthClient = {

package/dist/index.d.ts

@@ -13,14 +13,51 @@ import TestAgent from 'supertest/lib/agent';
  * following a "silent by default" philosophy.
  */
 /**
- * Minimal logger interface compatible with Pino, Winston, console, and similar loggers.
- * All methods are optional to support partial implementations.
+ * Canonical Logger contract for the Emmett ecosystem.
+ *
+ * This package defines the canonical Logger interface.
+ * Implementations (Pino, Winston, etc.) MUST adapt to this contract.
+ * This contract MUST NOT adapt to any specific implementation.
+ *
+ * Semantic Rules:
+ * - context (first parameter): ALWAYS structured data as Record<string, unknown>
+ * - message (second parameter): ALWAYS the human-readable log message
+ * - The order is NEVER inverted
+ * - The (message, data) form is NOT valid for this contract
+ *
+ * @example
+ * ```typescript
+ * // Pino - native compatibility
+ * import pino from 'pino';
+ * const logger = pino();
+ * // logger.info({ orderId }, 'Order created') matches our contract
+ * ```
  */
 interface Logger {
-    debug?(msg: string, data?: unknown): void;
-    info?(msg: string, data?: unknown): void;
-    warn?(msg: string, data?: unknown): void;
-    error?(msg: string, err?: unknown): void;
+    /**
+     * Log debug-level message with structured context.
+     * @param context - Structured data to include in the log entry
+     * @param message - Optional human-readable message
+     */
+    debug(context: Record<string, unknown>, message?: string): void;
+    /**
+     * Log info-level message with structured context.
+     * @param context - Structured data to include in the log entry
+     * @param message - Optional human-readable message
+     */
+    info(context: Record<string, unknown>, message?: string): void;
+    /**
+     * Log warn-level message with structured context.
+     * @param context - Structured data to include in the log entry
+     * @param message - Optional human-readable message
+     */
+    warn(context: Record<string, unknown>, message?: string): void;
+    /**
+     * Log error-level message with structured context.
+     * @param context - Structured data to include in the log entry (may include 'err' key)
+     * @param message - Optional human-readable message
+     */
+    error(context: Record<string, unknown>, message?: string): void;
 }
 /**
  * Observability configuration options.
@@ -44,14 +81,25 @@ type ObservabilityOptions = {
     logger?: Logger;
 };
 /**
- * Internal helper to safely call logger methods, handling partial implementations.
- * Always use: safeLog.error(logger, msg, error) - never { error }
+ * Internal helper to safely call logger methods.
+ *
+ * IMPORTANT: safeLog is the ONLY translation point between internal usage
+ * and the Logger contract.
+ *
+ * Internal Usage Pattern:
+ *   safeLog.info(logger, 'Order created', { orderId: 123 })
+ *
+ * Translation to Logger Contract:
+ *   logger.info({ orderId: 123 }, 'Order created')
+ *
+ * This allows ergonomic internal usage while ensuring all injected loggers
+ * receive calls in the canonical (context, message) format.
  */
 declare const safeLog: {
-    debug: (logger: Logger | undefined, msg: string, data?: unknown) => void | undefined;
-    info: (logger: Logger | undefined, msg: string, data?: unknown) => void | undefined;
-    warn: (logger: Logger | undefined, msg: string, data?: unknown) => void | undefined;
-    error: (logger: Logger | undefined, msg: string, error?: unknown) => void | undefined;
+    debug: (logger: Logger | undefined, msg: string, data?: unknown) => void;
+    info: (logger: Logger | undefined, msg: string, data?: unknown) => void;
+    warn: (logger: Logger | undefined, msg: string, data?: unknown) => void;
+    error: (logger: Logger | undefined, msg: string, error?: unknown) => void;
 };
 
 type AuthClient = {

package/dist/index.js

@@ -3,7 +3,7 @@ import {
 } from "./chunk-5TC7YUZR.js";
 import {
   safeLog
-} from "./chunk-I46UH36B.js";
+} from "./chunk-PZBLPYJH.js";
 
 // src/index.ts
 import "express-async-errors";
@@ -100,8 +100,8 @@ var getApplication = async (options) => {
       activateESMResolver();
       const handlersBasePath = typeof openApiValidator.operationHandlers === "string" ? openApiValidator.operationHandlers : openApiValidator.operationHandlers.basePath;
       if (handlersBasePath) {
-        const { extractHandlerModules } = await import("./openapi-parser-QYXNHNSZ.js");
-        const { importAndRegisterHandlers } = await import("./handler-importer-6A237UML.js");
+        const { extractHandlerModules } = await import("./openapi-parser-SFYDJEIN.js");
+        const { importAndRegisterHandlers } = await import("./handler-importer-V4EJZ2DG.js");
         const modules = await tracer.startActiveSpan(
           "emmett.openapi.parse_spec",
           async (span) => {

package/dist/{openapi-parser-PW5USNZ4.cjs → openapi-parser-HMWO3IPV.cjs}

@@ -1,13 +1,13 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
-var _chunkBY65ZALYcjs = require('./chunk-BY65ZALY.cjs');
+var _chunkFSPH5TRTcjs = require('./chunk-FSPH5TRT.cjs');
 require('./chunk-GS7T56RP.cjs');
 
 // src/internal/openapi-parser.ts
 var _promises = require('fs/promises');
 var _path = require('path'); var _path2 = _interopRequireDefault(_path);
 async function extractHandlerModules(apiSpec, handlersBasePath, logger) {
-  _chunkBY65ZALYcjs.safeLog.debug(logger, "Extracting handler modules from OpenAPI spec", {
+  _chunkFSPH5TRTcjs.safeLog.debug(logger, "Extracting handler modules from OpenAPI spec", {
     apiSpec: typeof apiSpec === "string" ? apiSpec : "<object>",
     handlersBasePath
   });
@@ -43,14 +43,14 @@ async function extractHandlerModules(apiSpec, handlersBasePath, logger) {
     }
   }
   const modules = Array.from(handlersMap.values());
-  _chunkBY65ZALYcjs.safeLog.debug(logger, "Extracted handler modules", {
+  _chunkFSPH5TRTcjs.safeLog.debug(logger, "Extracted handler modules", {
     count: modules.length,
     modules: modules.map((m) => m.moduleName)
   });
   return modules;
 }
 async function loadOpenApiSpec(filePath, logger) {
-  _chunkBY65ZALYcjs.safeLog.debug(logger, "Loading OpenAPI spec file", { filePath });
+  _chunkFSPH5TRTcjs.safeLog.debug(logger, "Loading OpenAPI spec file", { filePath });
   try {
     const content = await _promises.readFile.call(void 0, filePath, "utf-8");
     const ext = _path2.default.extname(filePath).toLowerCase();
@@ -65,7 +65,7 @@ async function loadOpenApiSpec(filePath, logger) {
         `Unsupported OpenAPI file format: ${ext}. Use .json, .yaml, or .yml`
       );
     }
-    _chunkBY65ZALYcjs.safeLog.debug(logger, "OpenAPI spec loaded successfully", {
+    _chunkFSPH5TRTcjs.safeLog.debug(logger, "OpenAPI spec loaded successfully", {
       filePath,
       format: ext
     });
@@ -91,4 +91,4 @@ function resolveHandlerPath(basePath, relativePath) {
 
 
 exports.extractHandlerModules = extractHandlerModules;
-//# sourceMappingURL=openapi-parser-PW5USNZ4.cjs.map
+//# sourceMappingURL=openapi-parser-HMWO3IPV.cjs.map

package/dist/{openapi-parser-PW5USNZ4.cjs.map → openapi-parser-HMWO3IPV.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/emmett-expressjs-with-openapi/emmett-expressjs-with-openapi/dist/openapi-parser-PW5USNZ4.cjs","../src/internal/openapi-parser.ts"],"names":[],"mappings":"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","file":"/home/runner/work/emmett-expressjs-with-openapi/emmett-expressjs-with-openapi/dist/openapi-parser-PW5USNZ4.cjs","sourcesContent":[null,"/**\n * OpenAPI Parser for handler module discovery.\n *\n * INTERNAL MODULE - Not part of public API.\n *\n * Parses OpenAPI specifications to extract handler module paths from\n * x-eov-operation-handler fields, enabling automatic handler discovery\n * and registration.\n */\n\nimport { readFile } from 'node:fs/promises';\nimport path from 'node:path';\nimport type { OpenAPIV3 } from 'express-openapi-validator/dist/framework/types';\nimport { type Logger, safeLog } from '../observability';\n\ntype OpenApiDocument = OpenAPIV3.DocumentV3 | OpenAPIV3.DocumentV3_1;\n\nexport type HandlerModuleInfo = {\n  moduleName: string; // e.g., \"shoppingCarts\"\n  relativePath: string; // from x-eov-operation-handler\n  absolutePath: string; // resolved full path\n  operationIds: string[]; // operations using this handler\n};\n\n/**\n * Extract handler modules from OpenAPI specification.\n *\n * @param apiSpec - OpenAPI spec (file path or object)\n * @param handlersBasePath - Base path for handler modules\n * @param logger - Optional logger for debug output\n * @returns Array of handler module information\n */\nexport async function extractHandlerModules(\n  apiSpec: string | OpenApiDocument,\n  handlersBasePath: string,\n  logger?: Logger,\n): Promise<HandlerModuleInfo[]> {\n  safeLog.debug(logger, 'Extracting handler modules from OpenAPI spec', {\n    apiSpec: typeof apiSpec === 'string' ? apiSpec : '<object>',\n    handlersBasePath,\n  });\n\n  // Load spec if it's a file path\n  const spec =\n    typeof apiSpec === 'string' ? await loadOpenApiSpec(apiSpec, logger) : apiSpec;\n\n  // Validate spec structure\n  if (!spec.paths || typeof spec.paths !== 'object') {\n    throw new Error('Invalid OpenAPI specification: missing or invalid \"paths\" field');\n  }\n\n  // Extract handler modules from spec\n  const handlersMap = new Map<string, HandlerModuleInfo>();\n\n  for (const [pathKey, pathItem] of Object.entries(spec.paths)) {\n    if (!pathItem || typeof pathItem !== 'object') continue;\n\n    for (const [method, operation] of Object.entries(pathItem)) {\n      if (method === 'parameters' || method === 'servers') continue;\n      if (!operation || typeof operation !== 'object') continue;\n\n      const handlerName = (operation as any)['x-eov-operation-handler'];\n      const operationId =\n        (operation as any)['x-eov-operation-id'] ||\n        (operation as any).operationId;\n\n      if (handlerName && typeof handlerName === 'string') {\n        const absolutePath = resolveHandlerPath(\n          handlersBasePath,\n          handlerName,\n        );\n\n        if (!handlersMap.has(handlerName)) {\n          handlersMap.set(handlerName, {\n            moduleName: handlerName,\n            relativePath: handlerName,\n            absolutePath,\n            operationIds: [],\n          });\n        }\n\n        if (operationId) {\n          handlersMap.get(handlerName)!.operationIds.push(operationId);\n        }\n      }\n    }\n  }\n\n  const modules = Array.from(handlersMap.values());\n\n  safeLog.debug(logger, 'Extracted handler modules', {\n    count: modules.length,\n    modules: modules.map((m) => m.moduleName),\n  });\n\n  return modules;\n}\n\n/**\n * Load OpenAPI specification from file.\n */\nasync function loadOpenApiSpec(\n  filePath: string,\n  logger?: Logger,\n): Promise<OpenApiDocument> {\n  safeLog.debug(logger, 'Loading OpenAPI spec file', { filePath });\n  try {\n    const content = await readFile(filePath, 'utf-8');\n    const ext = path.extname(filePath).toLowerCase();\n\n    let parsed: OpenApiDocument;\n    if (ext === '.json') {\n      parsed = JSON.parse(content);\n    } else if (ext === '.yaml' || ext === '.yml') {\n      // Dynamic import to avoid bundling yaml if not needed\n      const yaml = await import('yaml');\n      parsed = yaml.parse(content);\n    } else {\n      throw new Error(\n        `Unsupported OpenAPI file format: ${ext}. Use .json, .yaml, or .yml`,\n      );\n    }\n\n    safeLog.debug(logger, 'OpenAPI spec loaded successfully', {\n      filePath,\n      format: ext,\n    });\n\n    return parsed;\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n      throw new Error(`OpenAPI specification file not found: ${filePath}`);\n    }\n    throw error;\n  }\n}\n\n/**\n * Resolve handler module path, preventing path traversal attacks.\n */\nfunction resolveHandlerPath(\n  basePath: string,\n  relativePath: string,\n): string {\n  // Normalize to prevent path traversal\n  const normalized = path.normalize(relativePath);\n\n  // Resolve absolute path\n  const absolutePath = path.resolve(basePath, normalized);\n\n  // Ensure path is within basePath (no escape via ../)\n  const resolvedBase = path.resolve(basePath);\n  if (!absolutePath.startsWith(resolvedBase)) {\n    throw new Error(\n      `Invalid handler path: \"${relativePath}\" escapes base directory`,\n    );\n  }\n\n  return absolutePath;\n}\n"]}
+{"version":3,"sources":["/home/runner/work/emmett-expressjs-with-openapi/emmett-expressjs-with-openapi/dist/openapi-parser-HMWO3IPV.cjs","../src/internal/openapi-parser.ts"],"names":[],"mappings":"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","file":"/home/runner/work/emmett-expressjs-with-openapi/emmett-expressjs-with-openapi/dist/openapi-parser-HMWO3IPV.cjs","sourcesContent":[null,"/**\n * OpenAPI Parser for handler module discovery.\n *\n * INTERNAL MODULE - Not part of public API.\n *\n * Parses OpenAPI specifications to extract handler module paths from\n * x-eov-operation-handler fields, enabling automatic handler discovery\n * and registration.\n */\n\nimport { readFile } from 'node:fs/promises';\nimport path from 'node:path';\nimport type { OpenAPIV3 } from 'express-openapi-validator/dist/framework/types';\nimport { type Logger, safeLog } from '../observability';\n\ntype OpenApiDocument = OpenAPIV3.DocumentV3 | OpenAPIV3.DocumentV3_1;\n\nexport type HandlerModuleInfo = {\n  moduleName: string; // e.g., \"shoppingCarts\"\n  relativePath: string; // from x-eov-operation-handler\n  absolutePath: string; // resolved full path\n  operationIds: string[]; // operations using this handler\n};\n\n/**\n * Extract handler modules from OpenAPI specification.\n *\n * @param apiSpec - OpenAPI spec (file path or object)\n * @param handlersBasePath - Base path for handler modules\n * @param logger - Optional logger for debug output\n * @returns Array of handler module information\n */\nexport async function extractHandlerModules(\n  apiSpec: string | OpenApiDocument,\n  handlersBasePath: string,\n  logger?: Logger,\n): Promise<HandlerModuleInfo[]> {\n  safeLog.debug(logger, 'Extracting handler modules from OpenAPI spec', {\n    apiSpec: typeof apiSpec === 'string' ? apiSpec : '<object>',\n    handlersBasePath,\n  });\n\n  // Load spec if it's a file path\n  const spec =\n    typeof apiSpec === 'string' ? await loadOpenApiSpec(apiSpec, logger) : apiSpec;\n\n  // Validate spec structure\n  if (!spec.paths || typeof spec.paths !== 'object') {\n    throw new Error('Invalid OpenAPI specification: missing or invalid \"paths\" field');\n  }\n\n  // Extract handler modules from spec\n  const handlersMap = new Map<string, HandlerModuleInfo>();\n\n  for (const [pathKey, pathItem] of Object.entries(spec.paths)) {\n    if (!pathItem || typeof pathItem !== 'object') continue;\n\n    for (const [method, operation] of Object.entries(pathItem)) {\n      if (method === 'parameters' || method === 'servers') continue;\n      if (!operation || typeof operation !== 'object') continue;\n\n      const handlerName = (operation as any)['x-eov-operation-handler'];\n      const operationId =\n        (operation as any)['x-eov-operation-id'] ||\n        (operation as any).operationId;\n\n      if (handlerName && typeof handlerName === 'string') {\n        const absolutePath = resolveHandlerPath(\n          handlersBasePath,\n          handlerName,\n        );\n\n        if (!handlersMap.has(handlerName)) {\n          handlersMap.set(handlerName, {\n            moduleName: handlerName,\n            relativePath: handlerName,\n            absolutePath,\n            operationIds: [],\n          });\n        }\n\n        if (operationId) {\n          handlersMap.get(handlerName)!.operationIds.push(operationId);\n        }\n      }\n    }\n  }\n\n  const modules = Array.from(handlersMap.values());\n\n  safeLog.debug(logger, 'Extracted handler modules', {\n    count: modules.length,\n    modules: modules.map((m) => m.moduleName),\n  });\n\n  return modules;\n}\n\n/**\n * Load OpenAPI specification from file.\n */\nasync function loadOpenApiSpec(\n  filePath: string,\n  logger?: Logger,\n): Promise<OpenApiDocument> {\n  safeLog.debug(logger, 'Loading OpenAPI spec file', { filePath });\n  try {\n    const content = await readFile(filePath, 'utf-8');\n    const ext = path.extname(filePath).toLowerCase();\n\n    let parsed: OpenApiDocument;\n    if (ext === '.json') {\n      parsed = JSON.parse(content);\n    } else if (ext === '.yaml' || ext === '.yml') {\n      // Dynamic import to avoid bundling yaml if not needed\n      const yaml = await import('yaml');\n      parsed = yaml.parse(content);\n    } else {\n      throw new Error(\n        `Unsupported OpenAPI file format: ${ext}. Use .json, .yaml, or .yml`,\n      );\n    }\n\n    safeLog.debug(logger, 'OpenAPI spec loaded successfully', {\n      filePath,\n      format: ext,\n    });\n\n    return parsed;\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n      throw new Error(`OpenAPI specification file not found: ${filePath}`);\n    }\n    throw error;\n  }\n}\n\n/**\n * Resolve handler module path, preventing path traversal attacks.\n */\nfunction resolveHandlerPath(\n  basePath: string,\n  relativePath: string,\n): string {\n  // Normalize to prevent path traversal\n  const normalized = path.normalize(relativePath);\n\n  // Resolve absolute path\n  const absolutePath = path.resolve(basePath, normalized);\n\n  // Ensure path is within basePath (no escape via ../)\n  const resolvedBase = path.resolve(basePath);\n  if (!absolutePath.startsWith(resolvedBase)) {\n    throw new Error(\n      `Invalid handler path: \"${relativePath}\" escapes base directory`,\n    );\n  }\n\n  return absolutePath;\n}\n"]}

package/dist/{openapi-parser-QYXNHNSZ.js → openapi-parser-SFYDJEIN.js}

@@ -1,6 +1,6 @@
 import {
   safeLog
-} from "./chunk-I46UH36B.js";
+} from "./chunk-PZBLPYJH.js";
 
 // src/internal/openapi-parser.ts
 import { readFile } from "fs/promises";
@@ -90,4 +90,4 @@ function resolveHandlerPath(basePath, relativePath) {
 export {
   extractHandlerModules
 };
-//# sourceMappingURL=openapi-parser-QYXNHNSZ.js.map
+//# sourceMappingURL=openapi-parser-SFYDJEIN.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emmett-community/emmett-expressjs-with-openapi",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "type": "module",
   "description": "Express.js utilities for Emmett applications that want OpenAPI 3.x validation without pulling the whole Emmett core",

package/dist/chunk-BY65ZALY.cjs

@@ -1,12 +0,0 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/observability.ts
-var safeLog = {
-  debug: (logger, msg, data) => _optionalChain([logger, 'optionalAccess', _ => _.debug, 'optionalCall', _2 => _2(msg, data)]),
-  info: (logger, msg, data) => _optionalChain([logger, 'optionalAccess', _3 => _3.info, 'optionalCall', _4 => _4(msg, data)]),
-  warn: (logger, msg, data) => _optionalChain([logger, 'optionalAccess', _5 => _5.warn, 'optionalCall', _6 => _6(msg, data)]),
-  error: (logger, msg, error) => _optionalChain([logger, 'optionalAccess', _7 => _7.error, 'optionalCall', _8 => _8(msg, error)])
-};
-
-
-
-exports.safeLog = safeLog;
-//# sourceMappingURL=chunk-BY65ZALY.cjs.map

package/dist/chunk-BY65ZALY.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/home/runner/work/emmett-expressjs-with-openapi/emmett-expressjs-with-openapi/dist/chunk-BY65ZALY.cjs","../src/observability.ts"],"names":[],"mappings":"AAAA;AC4CO,IAAM,QAAA,EAAU;AAAA,EACrB,KAAA,EAAO,CAAC,MAAA,EAA4B,GAAA,EAAa,IAAA,EAAA,mBAC/C,MAAA,2BAAQ,KAAA,0BAAA,CAAQ,GAAA,EAAK,IAAI,GAAA;AAAA,EAC3B,IAAA,EAAM,CAAC,MAAA,EAA4B,GAAA,EAAa,IAAA,EAAA,mBAC9C,MAAA,6BAAQ,IAAA,0BAAA,CAAO,GAAA,EAAK,IAAI,GAAA;AAAA,EAC1B,IAAA,EAAM,CAAC,MAAA,EAA4B,GAAA,EAAa,IAAA,EAAA,mBAC9C,MAAA,6BAAQ,IAAA,0BAAA,CAAO,GAAA,EAAK,IAAI,GAAA;AAAA,EAC1B,KAAA,EAAO,CAAC,MAAA,EAA4B,GAAA,EAAa,KAAA,EAAA,mBAC/C,MAAA,6BAAQ,KAAA,0BAAA,CAAQ,GAAA,EAAK,KAAK;AAC9B,CAAA;AD9CA;AACA;AACE;AACF,0BAAC","file":"/home/runner/work/emmett-expressjs-with-openapi/emmett-expressjs-with-openapi/dist/chunk-BY65ZALY.cjs","sourcesContent":[null,"/**\n * Observability types for emmett-expressjs-with-openapi.\n *\n * This module provides optional logging integration\n * following a \"silent by default\" philosophy.\n */\n\n/**\n * Minimal logger interface compatible with Pino, Winston, console, and similar loggers.\n * All methods are optional to support partial implementations.\n */\nexport interface Logger {\n  debug?(msg: string, data?: unknown): void;\n  info?(msg: string, data?: unknown): void;\n  warn?(msg: string, data?: unknown): void;\n  error?(msg: string, err?: unknown): void;\n}\n\n/**\n * Observability configuration options.\n */\nexport type ObservabilityOptions = {\n  /**\n   * Optional logger instance for diagnostic output.\n   * When not provided, the library operates silently.\n   *\n   * @example\n   * ```typescript\n   * import pino from 'pino';\n   *\n   * const logger = pino();\n   *\n   * const app = await getApplication({\n   *   observability: { logger },\n   * });\n   * ```\n   */\n  logger?: Logger;\n};\n\n/**\n * Internal helper to safely call logger methods, handling partial implementations.\n * Always use: safeLog.error(logger, msg, error) - never { error }\n */\nexport const safeLog = {\n  debug: (logger: Logger | undefined, msg: string, data?: unknown) =>\n    logger?.debug?.(msg, data),\n  info: (logger: Logger | undefined, msg: string, data?: unknown) =>\n    logger?.info?.(msg, data),\n  warn: (logger: Logger | undefined, msg: string, data?: unknown) =>\n    logger?.warn?.(msg, data),\n  error: (logger: Logger | undefined, msg: string, error?: unknown) =>\n    logger?.error?.(msg, error),\n};\n"]}

package/dist/chunk-I46UH36B.js

@@ -1,12 +0,0 @@
-// src/observability.ts
-var safeLog = {
-  debug: (logger, msg, data) => logger?.debug?.(msg, data),
-  info: (logger, msg, data) => logger?.info?.(msg, data),
-  warn: (logger, msg, data) => logger?.warn?.(msg, data),
-  error: (logger, msg, error) => logger?.error?.(msg, error)
-};
-
-export {
-  safeLog
-};
-//# sourceMappingURL=chunk-I46UH36B.js.map

package/dist/chunk-I46UH36B.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/observability.ts"],"sourcesContent":["/**\n * Observability types for emmett-expressjs-with-openapi.\n *\n * This module provides optional logging integration\n * following a \"silent by default\" philosophy.\n */\n\n/**\n * Minimal logger interface compatible with Pino, Winston, console, and similar loggers.\n * All methods are optional to support partial implementations.\n */\nexport interface Logger {\n  debug?(msg: string, data?: unknown): void;\n  info?(msg: string, data?: unknown): void;\n  warn?(msg: string, data?: unknown): void;\n  error?(msg: string, err?: unknown): void;\n}\n\n/**\n * Observability configuration options.\n */\nexport type ObservabilityOptions = {\n  /**\n   * Optional logger instance for diagnostic output.\n   * When not provided, the library operates silently.\n   *\n   * @example\n   * ```typescript\n   * import pino from 'pino';\n   *\n   * const logger = pino();\n   *\n   * const app = await getApplication({\n   *   observability: { logger },\n   * });\n   * ```\n   */\n  logger?: Logger;\n};\n\n/**\n * Internal helper to safely call logger methods, handling partial implementations.\n * Always use: safeLog.error(logger, msg, error) - never { error }\n */\nexport const safeLog = {\n  debug: (logger: Logger | undefined, msg: string, data?: unknown) =>\n    logger?.debug?.(msg, data),\n  info: (logger: Logger | undefined, msg: string, data?: unknown) =>\n    logger?.info?.(msg, data),\n  warn: (logger: Logger | undefined, msg: string, data?: unknown) =>\n    logger?.warn?.(msg, data),\n  error: (logger: Logger | undefined, msg: string, error?: unknown) =>\n    logger?.error?.(msg, error),\n};\n"],"mappings":";AA4CO,IAAM,UAAU;AAAA,EACrB,OAAO,CAAC,QAA4B,KAAa,SAC/C,QAAQ,QAAQ,KAAK,IAAI;AAAA,EAC3B,MAAM,CAAC,QAA4B,KAAa,SAC9C,QAAQ,OAAO,KAAK,IAAI;AAAA,EAC1B,MAAM,CAAC,QAA4B,KAAa,SAC9C,QAAQ,OAAO,KAAK,IAAI;AAAA,EAC1B,OAAO,CAAC,QAA4B,KAAa,UAC/C,QAAQ,QAAQ,KAAK,KAAK;AAC9B;","names":[]}