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

package/README.md

@@ -2,6 +2,17 @@
 
 Express.js utilities for Emmett applications that want OpenAPI 3.x validation without pulling the whole Emmett core. This package wires [`express-openapi-validator`](https://github.com/cdimascio/express-openapi-validator) into the Emmett application builder so you can validate requests, responses, security handlers, file uploads, and formats from a single OpenAPI document.
 
+[![npm version](https://img.shields.io/npm/v/@emmett-community/emmett-expressjs-with-openapi.svg)](https://www.npmjs.com/package/@emmett-community/emmett-expressjs-with-openapi) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Build and test](https://github.com/emmett-community/emmett-expressjs-with-openapi/actions/workflows/build_and_test.yml/badge.svg)](https://github.com/emmett-community/emmett-expressjs-with-openapi/actions/workflows/build_and_test.yml)
+
+## Features
+
+- ✅ **OpenAPI 3.x validation** - Validate requests, responses, security, and file uploads.
+- ✅ **Operation handlers** - Auto-wire handlers from `operationId` or `x-eov-operation-handler`.
+- ✅ **Problem Details middleware** - RFC 7807 error responses out of the box.
+- ✅ **ETag helpers** - Built-in optimistic concurrency utilities.
+- ✅ **Testing helpers** - `ApiSpecification` and `ApiE2ESpecification` for tests.
+- ✅ **Optional add-ons** - Firebase Auth security handlers and Pino HTTP logging.
+
 ## Why this package?
 
 - Built as a standalone module extracted from the original `@event-driven-io/emmett` repo so it can evolve independently.
@@ -12,10 +23,33 @@ Express.js utilities for Emmett applications that want OpenAPI 3.x validation wi
 
 ```bash
 npm install @emmett-community/emmett-expressjs-with-openapi
-npm install express-openapi-validator   # optional peer dependency
+npm install express-openapi-validator            # optional: OpenAPI validation
+npm install pino-http                            # optional: HTTP logging
+npm install @my-f-startup/firebase-auth-express  # optional: Firebase Auth handlers
 ```
 
-Other peer requirements (`express`, `@event-driven-io/emmett`, etc.) follow the versions listed in `package.json`.
+### Peer Dependencies
+
+Required:
+
+- `@event-driven-io/emmett` ^0.39.1
+- `express` ^4.19.2
+- `express-async-errors` ^3.1.1
+- `http-problem-details` ^0.1.5
+
+TypeScript types:
+
+- `@types/express` ^4.17.21
+- `@types/supertest` ^6.0.2 (if using testing helpers)
+
+Optional (feature-gated):
+
+- `express-openapi-validator` ^5.3.7 (OpenAPI validation)
+- `pino-http` ^9.0.0 (HTTP logging)
+- `@my-f-startup/firebase-auth-express` 0.1.0 (Firebase Auth handlers)
+- `supertest` ^7.0.0 (required by testing helpers)
+
+Versions follow what is listed in `package.json`.
 
 ## Quick start
 
@@ -23,15 +57,33 @@ Other peer requirements (`express`, `@event-driven-io/emmett`, etc.) follow the
 import {
   getApplication,
   createOpenApiValidatorOptions,
+  startAPI,
 } from '@emmett-community/emmett-expressjs-with-openapi';
 
-const app = getApplication({
+const app = await getApplication({
   apis: [myApi],
   openApiValidator: createOpenApiValidatorOptions('./openapi.yaml', {
     validateRequests: true,
     validateResponses: process.env.NODE_ENV === 'development',
   }),
 });
+
+startAPI(app, { port: 3000 });
+```
+
+## Configuration
+
+### OpenAPI validation
+
+```typescript
+const app = await getApplication({
+  apis: [myApi],
+  openApiValidator: createOpenApiValidatorOptions('./openapi.yaml', {
+    validateRequests: true,
+    validateResponses: true,
+    operationHandlers: './handlers',
+  }),
+});
 ```
 
 Prefer to parse the spec once and share it? Load the `.yml` document manually and reuse it for routing, validation, and automatic `operationHandlers`.
@@ -41,9 +93,11 @@ import path from 'node:path';
 import { readFileSync } from 'node:fs';
 import { parse } from 'yaml';
 
-const spec = parse(readFileSync(new URL('./openapi.yml', import.meta.url), 'utf-8'));
+const spec = parse(
+  readFileSync(new URL('./openapi.yml', import.meta.url), 'utf-8'),
+);
 
-const app = getApplication({
+const app = await getApplication({
   apis: [usersApi],
   openApiValidator: createOpenApiValidatorOptions(spec, {
     operationHandlers: path.join(path.dirname(import.meta.url), './handlers'),
@@ -51,16 +105,32 @@ const app = getApplication({
 });
 ```
 
-## Configuration highlights
-
-`createOpenApiValidatorOptions` forwards every option from `express-openapi-validator`, so you can:
+Highlights:
 
 - Enable/disable request or response validation, including per-field tweaks (coercion, unknown query params, removing additional fields, etc.).
 - Register custom security handlers with `validateSecurity.handlers`.
 - Serve the parsed spec via `serveSpec`, configure file upload limits, ignore health-check routes, or validate the spec itself.
 - Reuse `$ref` parsing, custom formats, and file upload middleware exactly as in the upstream validator.
 
-## Firebase Auth (optional)
+### Logging (optional)
+
+Install the optional peer to enable HTTP request/response logging:
+
+```bash
+npm install pino-http
+```
+
+```typescript
+const app = await getApplication({
+  pinoHttp: true, // defaults
+  // or:
+  pinoHttp: { autoLogging: false },
+});
+```
+
+See the full options in the [`pino-http` docs](https://github.com/pinojs/pino-http).
+
+### Firebase Auth (optional)
 
 If you use Firebase Authentication, install the optional peer and plug it into OpenAPI security handlers:
 
@@ -78,7 +148,7 @@ import {
 
 admin.initializeApp();
 
-const app = getApplication({
+const app = await getApplication({
   apis: [myApi],
   openApiValidator: createOpenApiValidatorOptions('./openapi.yaml', {
     validateSecurity: {
@@ -90,20 +160,73 @@ const app = getApplication({
 
 `@my-f-startup/firebase-auth-express` relies on `firebase-admin`. Make sure the Admin SDK is installed, initialized, and configured for your environment (credentials or emulator).
 
-Head to [`docs/openapi-validation.md`](docs/openapi-validation.md) for the full matrix of options, extended explanations, and complete examples. Keeping that document allows us to document advanced scenarios without bloating the README.
+## Observability
 
-## Examples
+This package supports optional logging and tracing.
 
-Working examples live under `examples/`:
+### Logging
 
-- `examples/shopping-cart` – feature-complete Emmett sample (business logic, memory store/publisher, security handlers, OpenAPI file, unit/int/e2e tests, `.http` scripts).
-- Legacy quick starts:
-  - `examples/basic` – manual routes + validation (minimal scaffolding).
-  - `examples/with-security` – standalone security handler demo.
-  - `examples/operation-handlers` – barebones `operationHandlers` showcase.
-  - `examples/firebase-auth` – Firebase Auth security handlers with operation handlers.
+Inject a Pino-compatible logger:
+
+```typescript
+import pino from 'pino';
+
+const logger = pino();
+
+const app = await getApplication({
+  observability: { logger },
+});
+
+startAPI(app, { port: 3000, logger });
+```
+
+No logs are emitted when logger is not provided.
+
+### Tracing
+
+If your application initializes OpenTelemetry, this package will emit spans automatically. Tracing is passive - spans are no-ops when OpenTelemetry is not configured.
+
+```typescript
+import { tracedOn, OK } from '@emmett-community/emmett-expressjs-with-openapi';
+
+router.post('/carts', tracedOn(async (req) => {
+  // Your handler logic
+  return OK({ body: { success: true } });
+}));
+```
+
+This package never initializes OpenTelemetry - configure your tracer provider in your application.
+
+## API Reference
+
+### Application
+
+- `getApplication(options)` - Creates and configures the Express app.
+- `startAPI(app, options)` - Starts the HTTP server.
+
+### OpenAPI
+
+- `createOpenApiValidatorOptions(apiSpec, options)` - Helper to assemble OpenAPI validator config.
+- `isOpenApiValidatorAvailable()` - Type guard for optional validator dependency.
+- `createFirebaseAuthSecurityHandlers(options)` - Firebase Auth security handlers.
+- `registerHandlerModule(handlersPath, module)` - Manual registration for operation handlers.
+
+### HTTP helpers
+
+- `send`, `sendCreated`, `sendAccepted`, `sendProblem` - Standard HTTP responses.
+
+### ETag helpers
+
+- `toWeakETag`, `getETagFromIfMatch`, `getETagFromIfNotMatch`, `getETagValueFromIfMatch`, `setETag`.
 
-## Tests
+### Testing helpers
+
+- `ApiSpecification`, `ApiE2ESpecification`
+- `expect`, `expectNewEvents`, `expectResponse`, `expectError`
+
+See [`docs/openapi-validation.md`](docs/openapi-validation.md) for the full matrix of options and extended examples.
+
+## Testing
 
 The package includes comprehensive test coverage:
 
@@ -111,21 +234,96 @@ The package includes comprehensive test coverage:
 - **Integration tests** (`test/integration/`) - Basic routing, OpenAPI validation, operation handlers, optimistic concurrency
 - **E2E tests** (`test/e2e/`) - End-to-end workflows for all features
 
-Run `npm test` to execute the whole suite (unit + integration + e2e) or use:
+### Running tests
 
-- `npm run test:unit` - Unit tests only
-- `npm run test:int` - Integration tests only
-- `npm run test:e2e` - E2E tests only
+```bash
+# Unit tests
+npm run test:unit
+
+# Integration tests
+npm run test:int
+
+# E2E tests
+npm run test:e2e
+
+# All tests
+npm test
+```
+
+## Examples
+
+Working examples live under `examples/`:
+
+- `examples/shopping-cart` – feature-complete Emmett sample (business logic, memory store/publisher, security handlers, OpenAPI file, unit/int/e2e tests, `.http` scripts).
+- Legacy quick starts:
+  - `examples/basic` – manual routes + validation (minimal scaffolding).
+  - `examples/with-security` – standalone security handler demo.
+  - `examples/operation-handlers` – barebones `operationHandlers` showcase.
+  - `examples/firebase-auth` – Firebase Auth security handlers with operation handlers.
 
 ## Documentation
 
 - **Guide:** [`docs/openapi-validation.md`](docs/openapi-validation.md) – authoritative reference for configuration, advanced usage, and troubleshooting.
 - **Emmett docs:** <https://event-driven-io.github.io/emmett/>
 
+## Compatibility
+
+- **Node.js**: tested in CI with 24.x
+- **Emmett**: ^0.39.1
+- **Express**: ^4.19.2
+
 ## Contributing
 
-Issues and PRs are welcome! Please open a discussion or ticket if you are unsure about the direction of a change before coding.
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Type-check
+npm run build:ts
+
+# Run tests
+npm test
+
+# Run unit tests only
+npm run test:unit
+
+# Run integration tests
+npm run test:int
+
+# Run E2E tests
+npm run test:e2e
+```
 
 ## License
 
 MIT
+
+## Related Packages
+
+- [@event-driven-io/emmett](https://github.com/event-driven-io/emmett) - Core Emmett framework
+- [@emmett-community/emmett-google-firestore](https://github.com/emmett-community/emmett-google-firestore) - Firestore event store
+- [@emmett-community/emmett-google-realtime-db](https://github.com/emmett-community/emmett-google-realtime-db) - Realtime Database inline projections
+- [@emmett-community/emmett-google-pubsub](https://github.com/emmett-community/emmett-google-pubsub) - Pub/Sub message bus
+- [@event-driven-io/emmett-mongodb](https://github.com/event-driven-io/emmett/tree/main/src/packages/emmett-mongodb) - MongoDB event store
+
+## Support
+
+- [GitHub Issues](https://github.com/emmett-community/emmett-expressjs-with-openapi/issues)
+- [Emmett Documentation](https://event-driven-io.github.io/emmett/)
+
+---
+
+Made with ❤️ by the Emmett Community

package/dist/chunk-BY65ZALY.cjs

@@ -0,0 +1,12 @@
+"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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,12 @@
+// 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

@@ -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 * 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":[]}

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

@@ -1,18 +1,37 @@
 import {
   registerHandlerModule
 } from "./chunk-5TC7YUZR.js";
+import {
+  safeLog
+} from "./chunk-I46UH36B.js";
 
 // src/internal/handler-importer.ts
 import { pathToFileURL } from "url";
-async function importAndRegisterHandlers(modules) {
+async function importAndRegisterHandlers(modules, logger) {
+  safeLog.debug(logger, "Importing handler modules", {
+    count: modules.length,
+    modules: modules.map((m) => m.moduleName)
+  });
   const importedHandlers = {};
   for (const module of modules) {
     try {
+      safeLog.debug(logger, "Importing handler module", {
+        moduleName: module.moduleName,
+        absolutePath: module.absolutePath
+      });
       const fileUrl = pathToFileURL(module.absolutePath).href;
       const importedModule = await import(fileUrl);
       registerHandlerModule(module.absolutePath, importedModule);
       importedHandlers[module.moduleName] = importedModule;
+      safeLog.debug(logger, "Handler module imported successfully", {
+        moduleName: module.moduleName
+      });
     } catch (error) {
+      safeLog.error(
+        logger,
+        `Failed to import handler module "${module.moduleName}"`,
+        error
+      );
       throw new Error(
         `Failed to import handler module "${module.moduleName}" from ${module.absolutePath}: ${error.message}`
       );
@@ -23,4 +42,4 @@ async function importAndRegisterHandlers(modules) {
 export {
   importAndRegisterHandlers
 };
-//# sourceMappingURL=handler-importer-OJGFQON5.js.map
+//# sourceMappingURL=handler-importer-6A237UML.js.map

package/dist/handler-importer-6A237UML.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/handler-importer.ts"],"sourcesContent":["/**\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"],"mappings":";;;;;;;;AASA,SAAS,qBAAqB;AAc9B,eAAsB,0BACpB,SACA,QACiC;AACjC,UAAQ,MAAM,QAAQ,6BAA6B;AAAA,IACjD,OAAO,QAAQ;AAAA,IACf,SAAS,QAAQ,IAAI,CAAC,MAAM,EAAE,UAAU;AAAA,EAC1C,CAAC;AAED,QAAM,mBAA2C,CAAC;AAElD,aAAW,UAAU,SAAS;AAC5B,QAAI;AACF,cAAQ,MAAM,QAAQ,4BAA4B;AAAA,QAChD,YAAY,OAAO;AAAA,QACnB,cAAc,OAAO;AAAA,MACvB,CAAC;AAGD,YAAM,UAAU,cAAc,OAAO,YAAY,EAAE;AAGnD,YAAM,iBAAiB,MAAM,OAAO;AAGpC,4BAAsB,OAAO,cAAc,cAAc;AAGzD,uBAAiB,OAAO,UAAU,IAAI;AAEtC,cAAQ,MAAM,QAAQ,wCAAwC;AAAA,QAC5D,YAAY,OAAO;AAAA,MACrB,CAAC;AAAA,IACH,SAAS,OAAO;AACd,cAAQ;AAAA,QACN;AAAA,QACA,oCAAoC,OAAO,UAAU;AAAA,QACrD;AAAA,MACF;AACA,YAAM,IAAI;AAAA,QACR,oCAAoC,OAAO,UAAU,UAAU,OAAO,YAAY,KAC/E,MAAgB,OACnB;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;","names":[]}

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

@@ -1,19 +1,38 @@
 "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; } }
 
 var _chunkMRSGTROWcjs = require('./chunk-MRSGTROW.cjs');
+
+
+var _chunkBY65ZALYcjs = require('./chunk-BY65ZALY.cjs');
 require('./chunk-GS7T56RP.cjs');
 
 // src/internal/handler-importer.ts
 var _url = require('url');
-async function importAndRegisterHandlers(modules) {
+async function importAndRegisterHandlers(modules, logger) {
+  _chunkBY65ZALYcjs.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", {
+        moduleName: module.moduleName,
+        absolutePath: module.absolutePath
+      });
       const fileUrl = _url.pathToFileURL.call(void 0, module.absolutePath).href;
       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", {
+        moduleName: module.moduleName
+      });
     } catch (error) {
+      _chunkBY65ZALYcjs.safeLog.error(
+        logger,
+        `Failed to import handler module "${module.moduleName}"`,
+        error
+      );
       throw new Error(
         `Failed to import handler module "${module.moduleName}" from ${module.absolutePath}: ${error.message}`
       );
@@ -24,4 +43,4 @@ async function importAndRegisterHandlers(modules) {
 
 
 exports.importAndRegisterHandlers = importAndRegisterHandlers;
-//# sourceMappingURL=handler-importer-4BVBIZX3.cjs.map
+//# sourceMappingURL=handler-importer-UFV7TKBN.cjs.map

package/dist/handler-importer-UFV7TKBN.cjs.map

@@ -0,0 +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"]}