@cosmneo/onion-lasagna 0.2.1 → 0.3.1

package/dist/chunk-XWKHOLIP.js

@@ -0,0 +1,191 @@
+import {
+  mapErrorToEventResult
+} from "./chunk-4BVOLXDJ.js";
+import {
+  collectEventHandlers,
+  generateHandlerId,
+  isEventRouterDefinition
+} from "./chunk-CBTICRSM.js";
+
+// src/presentation/events/server/types.ts
+function isSimpleEventHandlerConfig(config) {
+  return "handler" in config && typeof config.handler === "function";
+}
+
+// src/presentation/events/server/create-event-routes.ts
+function createEventRoutesInternal(router, handlers, options) {
+  const config = isEventRouterDefinition(router) ? router.handlers : router;
+  const collectedHandlers = collectEventHandlers(config);
+  const result = [];
+  const resolvedOptions = {
+    ...options,
+    validatePayload: options?.validatePayload ?? true,
+    allowPartial: options?.allowPartial ?? false
+  };
+  for (const { key, handler: handlerDef } of collectedHandlers) {
+    const handlerConfig = handlers[key];
+    if (!handlerConfig) {
+      if (resolvedOptions.allowPartial) {
+        continue;
+      }
+      throw new Error(
+        `Missing handler for event "${key}". All event handlers must have a handler configuration.`
+      );
+    }
+    result.push(createEventHandler(key, handlerDef, handlerConfig, resolvedOptions));
+  }
+  return result;
+}
+function createEventHandler(key, handlerDef, config, options) {
+  const middleware = config.middleware ?? [];
+  const globalMiddleware = options?.middleware ?? [];
+  const allMiddleware = [...globalMiddleware, ...middleware];
+  const shouldValidatePayload = options.validatePayload ?? true;
+  const errorMapper = options.errorMapper ?? mapErrorToEventResult;
+  return {
+    eventType: handlerDef.eventType,
+    metadata: {
+      handlerId: generateHandlerId(key),
+      summary: handlerDef.docs.summary,
+      description: handlerDef.docs.description,
+      tags: handlerDef.docs.tags,
+      deprecated: handlerDef.docs.deprecated
+    },
+    handler: async (rawEvent) => {
+      try {
+        let validatedContext = rawEvent.metadata;
+        if (handlerDef.context) {
+          const contextResult = validateContextData(handlerDef, rawEvent.metadata);
+          if (!contextResult.success) {
+            const errors = contextResult.errors ?? [];
+            return {
+              outcome: "dlq",
+              reason: `Context validation failed: ${errors.map((e) => `${e.path.join(".")}: ${e.message}`).join("; ")}`
+            };
+          }
+          validatedContext = contextResult.data;
+        }
+        let validatedPayload = rawEvent.payload;
+        if (shouldValidatePayload && handlerDef.payload) {
+          const payloadResult = validatePayloadData(handlerDef, rawEvent.payload);
+          if (!payloadResult.success) {
+            const errors = payloadResult.errors ?? [];
+            return {
+              outcome: "dlq",
+              reason: `Payload validation failed: ${errors.map((e) => `${e.path.join(".")}: ${e.message}`).join("; ")}`
+            };
+          }
+          validatedPayload = payloadResult.data;
+        }
+        const validatedEvent = {
+          payload: validatedPayload,
+          raw: rawEvent
+        };
+        const executePipeline = async () => {
+          if (isSimpleEventHandlerConfig(config)) {
+            return config.handler(
+              validatedEvent,
+              validatedContext
+            );
+          } else {
+            const { payloadMapper, useCase, resultMapper } = config;
+            const input = payloadMapper(
+              validatedEvent,
+              validatedContext
+            );
+            const output = await useCase.execute(input);
+            return resultMapper ? resultMapper(output) : { outcome: "ack" };
+          }
+        };
+        if (allMiddleware.length === 0) {
+          return await executePipeline();
+        }
+        let index = 0;
+        const next = async () => {
+          if (index >= allMiddleware.length) {
+            return executePipeline();
+          }
+          const mw = allMiddleware[index++];
+          return mw(rawEvent, next);
+        };
+        return await next();
+      } catch (error) {
+        return errorMapper(error);
+      }
+    }
+  };
+}
+function validatePayloadData(handler, payload) {
+  const schema = handler.payload;
+  if (!schema) return { success: true, data: payload };
+  const result = schema.validate(payload);
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+  const errors = result.issues.map((issue) => ({
+    ...issue,
+    path: ["payload", ...issue.path]
+  }));
+  return { success: false, errors };
+}
+function validateContextData(handler, metadata) {
+  const schema = handler.context;
+  if (!schema) return { success: true, data: metadata };
+  const result = schema.validate(metadata);
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+  const errors = result.issues.map((issue) => ({
+    ...issue,
+    path: ["context", ...issue.path]
+  }));
+  return { success: false, errors };
+}
+
+// src/presentation/events/server/event-routes-builder.ts
+var EventRoutesBuilderImpl = class _EventRoutesBuilderImpl {
+  router;
+  handlers;
+  constructor(router, handlers) {
+    this.router = router;
+    this.handlers = handlers ?? /* @__PURE__ */ new Map();
+  }
+  handle(key, handlerOrConfig) {
+    const config = typeof handlerOrConfig === "function" ? { handler: handlerOrConfig } : handlerOrConfig;
+    const newHandlers = new Map(this.handlers);
+    newHandlers.set(key, config);
+    return new _EventRoutesBuilderImpl(
+      this.router,
+      newHandlers
+    );
+  }
+  handleWithUseCase(key, config) {
+    const newHandlers = new Map(this.handlers);
+    newHandlers.set(
+      key,
+      config
+    );
+    return new _EventRoutesBuilderImpl(
+      this.router,
+      newHandlers
+    );
+  }
+  build(options) {
+    return createEventRoutesInternal(this.router, Object.fromEntries(this.handlers), options);
+  }
+  buildPartial(options) {
+    return createEventRoutesInternal(this.router, Object.fromEntries(this.handlers), {
+      ...options,
+      allowPartial: true
+    });
+  }
+};
+function eventRoutes(router) {
+  return new EventRoutesBuilderImpl(router);
+}
+
+export {
+  isSimpleEventHandlerConfig,
+  eventRoutes
+};
+//# sourceMappingURL=chunk-XWKHOLIP.js.map

package/dist/chunk-XWKHOLIP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/presentation/events/server/types.ts","../src/presentation/events/server/create-event-routes.ts","../src/presentation/events/server/event-routes-builder.ts"],"sourcesContent":["/**\n * @fileoverview Server types for the event handler system.\n *\n * @module events/server/types\n */\n\nimport type { EventHandlerDefinition, EventRouterConfig, EventRouterKeys } from '../handler/types';\nimport type { EventResult } from '../shared/types';\n\n// Re-export UseCasePort from HTTP — same interface, no duplication\nexport type { UseCasePort } from '../../http/server/types';\n\n// ============================================================================\n// Raw Event (from messaging system)\n// ============================================================================\n\n/**\n * Event metadata provided by the messaging system.\n */\nexport interface EventMetadata {\n  /** Unique event identifier for idempotency checks. */\n  readonly eventId: string;\n\n  /** ISO 8601 timestamp of when the event occurred. */\n  readonly timestamp: string;\n\n  /** Correlation ID for distributed tracing. */\n  readonly correlationId?: string;\n\n  /** Source system or bounded context that emitted the event. */\n  readonly source?: string;\n\n  /** Number of delivery attempts (1-based). */\n  readonly attemptCount?: number;\n\n  /** Additional metadata from the messaging system. */\n  readonly [key: string]: unknown;\n}\n\n/**\n * Raw event from the messaging system.\n * This is the input to event handlers before validation.\n */\nexport interface RawEvent {\n  /** Event type string for routing. */\n  readonly type: string;\n\n  /** Event payload (unvalidated). */\n  readonly payload: unknown;\n\n  /** Event metadata from the messaging system. */\n  readonly metadata: EventMetadata;\n}\n\n// ============================================================================\n// Validated Event\n// ============================================================================\n\n/**\n * A validated event with typed payload.\n * This is what handlers receive after validation passes.\n */\nexport interface ValidatedEvent<THandler extends EventHandlerDefinition> {\n  /** Validated event payload. */\n  readonly payload: THandler['_types']['payload'];\n\n  /** Raw event object for advanced use cases. */\n  readonly raw: RawEvent;\n}\n\n/**\n * Typed event context based on handler definition.\n * If the handler defines a context schema, this will be the validated type.\n * Otherwise, it falls back to the generic EventMetadata.\n */\nexport type TypedEventContext<THandler extends EventHandlerDefinition> =\n  THandler['_types']['context'] extends undefined ? EventMetadata : THandler['_types']['context'];\n\n// ============================================================================\n// Handler Types\n// ============================================================================\n\n/**\n * Handler configuration using the use case pattern.\n *\n * @typeParam THandler - The event handler definition type\n * @typeParam TInput - Use case input type\n * @typeParam TOutput - Use case output type\n */\nexport interface EventHandlerConfig<\n  THandler extends EventHandlerDefinition,\n  TInput = void,\n  TOutput = void,\n> {\n  /**\n   * Maps the validated event payload to use case input.\n   * Both `event` and `ctx` are fully typed based on handler schemas.\n   */\n  readonly payloadMapper: (\n    event: ValidatedEvent<THandler>,\n    ctx: TypedEventContext<THandler>,\n  ) => TInput;\n\n  /** The use case to execute. */\n  readonly useCase: { execute(input?: TInput): Promise<TOutput> };\n\n  /**\n   * Maps the use case output to an EventResult.\n   * If omitted, defaults to `{ outcome: 'ack' }`.\n   */\n  readonly resultMapper?: (output: TOutput) => EventResult;\n\n  /** Middleware to run before the handler. */\n  readonly middleware?: readonly EventMiddlewareFunction[];\n}\n\n/**\n * Simple handler function that directly returns an EventResult.\n */\nexport type SimpleEventHandlerFn<THandler extends EventHandlerDefinition> = (\n  event: ValidatedEvent<THandler>,\n  ctx: TypedEventContext<THandler>,\n) => Promise<EventResult> | EventResult;\n\n/**\n * Configuration for a simple handler (no use case).\n */\nexport interface SimpleEventHandlerConfig<THandler extends EventHandlerDefinition> {\n  readonly handler: SimpleEventHandlerFn<THandler>;\n  readonly middleware?: readonly EventMiddlewareFunction[];\n}\n\n/**\n * Union of all event handler config types.\n * Used internally to store handlers in the builder.\n */\nexport type AnyEventHandlerConfig<\n  THandler extends EventHandlerDefinition,\n  TInput = unknown,\n  TOutput = unknown,\n> = EventHandlerConfig<THandler, TInput, TOutput> | SimpleEventHandlerConfig<THandler>;\n\n/**\n * Type guard to check if config is a simple event handler.\n */\nexport function isSimpleEventHandlerConfig(\n  config: AnyEventHandlerConfig<EventHandlerDefinition, unknown, unknown>,\n): config is SimpleEventHandlerConfig<EventHandlerDefinition> {\n  return 'handler' in config && typeof config.handler === 'function';\n}\n\n/**\n * Event middleware function type.\n */\nexport type EventMiddlewareFunction = (\n  event: RawEvent,\n  next: () => Promise<EventResult>,\n) => Promise<EventResult>;\n\n// ============================================================================\n// Server Configuration\n// ============================================================================\n\n/**\n * Configuration mapping handler keys to handler configs.\n */\n// TInput/TOutput are user-defined per handler - any is required for heterogeneous configs\nexport type EventRoutesConfig<T extends EventRouterConfig> = Record<\n  EventRouterKeys<T>,\n  EventHandlerConfig<any, any, any>\n>;\n\n/**\n * Options for creating event routes.\n */\nexport interface CreateEventRoutesOptions {\n  /** Global middleware to run before all handlers. */\n  readonly middleware?: readonly EventMiddlewareFunction[];\n\n  /**\n   * Whether to validate incoming event payloads against handler schemas.\n   * When enabled, invalid payloads result in a `dlq` outcome.\n   * @default true\n   */\n  readonly validatePayload?: boolean;\n\n  /**\n   * Custom error mapper to override default error-to-EventResult mapping.\n   * If not provided, uses the built-in `mapErrorToEventResult`.\n   */\n  readonly errorMapper?: (error: unknown) => EventResult;\n\n  /**\n   * Allow partial handler configuration (not all handlers need to be wired).\n   * @default false\n   * @internal Used by builder pattern's buildPartial()\n   */\n  readonly allowPartial?: boolean;\n}\n\n// ============================================================================\n// Unified Event Input (for messaging adapters)\n// ============================================================================\n\n/**\n * Event input compatible with messaging adapters.\n * This is the output of eventRoutes().build().\n */\nexport interface UnifiedEventInput {\n  /** Event type string for routing. */\n  readonly eventType: string;\n\n  /** Handler function. */\n  readonly handler: (rawEvent: RawEvent) => Promise<EventResult>;\n\n  /** Handler metadata for documentation. */\n  readonly metadata: {\n    readonly handlerId?: string;\n    readonly summary?: string;\n    readonly description?: string;\n    readonly tags?: readonly string[];\n    readonly deprecated?: boolean;\n  };\n}\n","/**\n * @fileoverview Internal implementation for creating event routes with auto-validation.\n *\n * Generates event handlers from an event router definition.\n * Each handler automatically validates incoming event payloads and context\n * against the handler's schemas.\n *\n * @module events/server/create-event-routes\n * @internal\n */\n\nimport type { SchemaAdapter, ValidationIssue } from '../../http/schema/types';\nimport type {\n  EventRouterConfig,\n  EventRouterDefinition,\n  EventHandlerDefinition,\n} from '../handler/types';\nimport { isEventRouterDefinition, collectEventHandlers } from '../handler/types';\nimport { generateHandlerId } from '../handler/utils';\nimport { mapErrorToEventResult } from '../shared/error-mapping';\nimport type { EventResult } from '../shared/types';\nimport type {\n  AnyEventHandlerConfig,\n  CreateEventRoutesOptions,\n  EventMetadata,\n  RawEvent,\n  UnifiedEventInput,\n  ValidatedEvent,\n} from './types';\nimport { isSimpleEventHandlerConfig } from './types';\n\n/**\n * Internal implementation for creating event routes.\n * Used by the builder pattern (eventRoutes).\n *\n * @internal\n */\nexport function createEventRoutesInternal<T extends EventRouterConfig>(\n  router: T | EventRouterDefinition<T>,\n  handlers: Record<string, AnyEventHandlerConfig<EventHandlerDefinition, unknown, unknown>>,\n  options?: CreateEventRoutesOptions,\n): UnifiedEventInput[] {\n  const config = isEventRouterDefinition(router) ? router.handlers : router;\n  const collectedHandlers = collectEventHandlers(config);\n\n  const result: UnifiedEventInput[] = [];\n\n  const resolvedOptions: CreateEventRoutesOptions = {\n    ...options,\n    validatePayload: options?.validatePayload ?? true,\n    allowPartial: options?.allowPartial ?? false,\n  };\n\n  for (const { key, handler: handlerDef } of collectedHandlers) {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    const handlerConfig = handlers[key] as\n      | AnyEventHandlerConfig<EventHandlerDefinition, any, any>\n      | undefined;\n\n    if (!handlerConfig) {\n      if (resolvedOptions.allowPartial) {\n        continue;\n      }\n      throw new Error(\n        `Missing handler for event \"${key}\". All event handlers must have a handler configuration.`,\n      );\n    }\n\n    result.push(createEventHandler(key, handlerDef, handlerConfig, resolvedOptions));\n  }\n\n  return result;\n}\n\n/**\n * Creates a single event handler with validation and error mapping.\n */\nfunction createEventHandler(\n  key: string,\n  handlerDef: EventHandlerDefinition,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  config: AnyEventHandlerConfig<EventHandlerDefinition, any, any>,\n  options: CreateEventRoutesOptions,\n): UnifiedEventInput {\n  const middleware = config.middleware ?? [];\n  const globalMiddleware = options?.middleware ?? [];\n  const allMiddleware = [...globalMiddleware, ...middleware];\n  const shouldValidatePayload = options.validatePayload ?? true;\n  const errorMapper = options.errorMapper ?? mapErrorToEventResult;\n\n  return {\n    eventType: handlerDef.eventType,\n    metadata: {\n      handlerId: generateHandlerId(key),\n      summary: handlerDef.docs.summary,\n      description: handlerDef.docs.description,\n      tags: handlerDef.docs.tags as string[],\n      deprecated: handlerDef.docs.deprecated,\n    },\n    handler: async (rawEvent: RawEvent): Promise<EventResult> => {\n      try {\n        // Validate context (if schema defined)\n        let validatedContext: unknown = rawEvent.metadata;\n        if (handlerDef.context) {\n          const contextResult = validateContextData(handlerDef, rawEvent.metadata);\n          if (!contextResult.success) {\n            const errors = contextResult.errors ?? [];\n            return {\n              outcome: 'dlq',\n              reason: `Context validation failed: ${errors.map((e) => `${e.path.join('.')}: ${e.message}`).join('; ')}`,\n            };\n          }\n          validatedContext = contextResult.data;\n        }\n\n        // Validate payload (if enabled and schema defined)\n        let validatedPayload: unknown = rawEvent.payload;\n        if (shouldValidatePayload && handlerDef.payload) {\n          const payloadResult = validatePayloadData(handlerDef, rawEvent.payload);\n          if (!payloadResult.success) {\n            const errors = payloadResult.errors ?? [];\n            return {\n              outcome: 'dlq',\n              reason: `Payload validation failed: ${errors.map((e) => `${e.path.join('.')}: ${e.message}`).join('; ')}`,\n            };\n          }\n          validatedPayload = payloadResult.data;\n        }\n\n        const validatedEvent: ValidatedEventInternal = {\n          payload: validatedPayload,\n          raw: rawEvent,\n        };\n\n        // Execute the pipeline\n        const executePipeline = async (): Promise<EventResult> => {\n          if (isSimpleEventHandlerConfig(config)) {\n            return config.handler(\n              validatedEvent as unknown as ValidatedEvent<EventHandlerDefinition>,\n              validatedContext as EventMetadata,\n            );\n          } else {\n            const { payloadMapper, useCase, resultMapper } = config;\n\n            const input = payloadMapper(\n              validatedEvent as unknown as ValidatedEvent<EventHandlerDefinition>,\n              validatedContext as EventMetadata,\n            );\n\n            const output = await useCase.execute(input);\n\n            return resultMapper ? resultMapper(output) : { outcome: 'ack' };\n          }\n        };\n\n        if (allMiddleware.length === 0) {\n          return await executePipeline();\n        }\n\n        // Build middleware chain\n        let index = 0;\n        const next = async (): Promise<EventResult> => {\n          if (index >= allMiddleware.length) {\n            return executePipeline();\n          }\n          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- index bounds checked above\n          const mw = allMiddleware[index++]!;\n          return mw(rawEvent, next);\n        };\n\n        return await next();\n      } catch (error) {\n        return errorMapper(error);\n      }\n    },\n  };\n}\n\n// ============================================================================\n// Validation Helpers\n// ============================================================================\n\ninterface ValidationResultInternal {\n  success: boolean;\n  errors?: ValidationIssue[];\n  data?: unknown;\n}\n\n/**\n * Validates event payload against the handler's payload schema.\n */\nfunction validatePayloadData(\n  handler: EventHandlerDefinition,\n  payload: unknown,\n): ValidationResultInternal {\n  const schema = handler.payload as SchemaAdapter | undefined;\n  if (!schema) return { success: true, data: payload };\n\n  const result = schema.validate(payload);\n  if (result.success) {\n    return { success: true, data: result.data };\n  }\n\n  const errors = result.issues.map((issue) => ({\n    ...issue,\n    path: ['payload', ...issue.path],\n  }));\n\n  return { success: false, errors };\n}\n\n/**\n * Validates event metadata against the handler's context schema.\n */\nfunction validateContextData(\n  handler: EventHandlerDefinition,\n  metadata: EventMetadata,\n): ValidationResultInternal {\n  const schema = handler.context as SchemaAdapter | undefined;\n  if (!schema) return { success: true, data: metadata };\n\n  const result = schema.validate(metadata);\n  if (result.success) {\n    return { success: true, data: result.data };\n  }\n\n  const errors = result.issues.map((issue) => ({\n    ...issue,\n    path: ['context', ...issue.path],\n  }));\n\n  return { success: false, errors };\n}\n\n/**\n * Internal validated event type with unknown fields.\n * Used inside createEventHandler where specific types are erased.\n */\ninterface ValidatedEventInternal {\n  readonly payload: unknown;\n  readonly raw: RawEvent;\n}\n","/**\n * @fileoverview Builder pattern for creating type-safe event routes.\n *\n * The `eventRoutes` function returns a builder that provides 100% type inference\n * for all handler parameters — no manual type annotations required.\n *\n * @module events/server/event-routes-builder\n */\n\nimport type {\n  EventRouterConfig,\n  EventRouterDefinition,\n  GetEventHandler,\n  EventRouterKeys,\n  EventHandlerDefinition,\n} from '../handler/types';\nimport type { EventResult } from '../shared/types';\nimport type {\n  AnyEventHandlerConfig,\n  CreateEventRoutesOptions,\n  EventHandlerConfig,\n  EventMiddlewareFunction,\n  SimpleEventHandlerConfig,\n  SimpleEventHandlerFn,\n  TypedEventContext,\n  UnifiedEventInput,\n  ValidatedEvent,\n} from './types';\nimport { createEventRoutesInternal } from './create-event-routes';\n\n// ============================================================================\n// Builder Types\n// ============================================================================\n\n/**\n * Error type displayed when attempting to build() with missing handlers.\n * The `___missingHandlers` property shows which handlers are missing.\n */\nexport interface MissingHandlersError<TMissing extends string> {\n  /**\n   * This error indicates that not all event handlers have been wired.\n   * Use buildPartial() to build with only the defined handlers,\n   * or add handlers for the missing events.\n   */\n  (options?: never): never;\n  /** Event handlers that are missing. */\n  readonly ___missingHandlers: TMissing;\n}\n\n/**\n * Handler configuration for the builder pattern.\n */\nexport interface BuilderEventHandlerConfig<\n  THandler extends EventHandlerDefinition,\n  TInput,\n  TOutput,\n> {\n  /**\n   * Maps the validated event payload to use case input.\n   * Both `event` and `ctx` are fully typed based on handler schemas.\n   */\n  readonly payloadMapper: (\n    event: ValidatedEvent<THandler>,\n    ctx: TypedEventContext<THandler>,\n  ) => TInput;\n\n  /** The use case to execute. */\n  readonly useCase: { execute(input?: TInput): Promise<TOutput> };\n\n  /**\n   * Maps the use case output to an EventResult.\n   * If omitted, defaults to `{ outcome: 'ack' }`.\n   */\n  readonly resultMapper?: (output: TOutput) => EventResult;\n\n  /** Middleware to run before the handler. */\n  readonly middleware?: readonly EventMiddlewareFunction[];\n}\n\n/**\n * Builder interface for creating type-safe event routes.\n *\n * Each `.handle()` call captures the specific handler type and provides\n * full type inference for payloadMapper and useCase.\n *\n * @typeParam T - The event router configuration type\n * @typeParam THandled - Union of handler keys that have been wired (accumulates)\n *\n * @example\n * ```typescript\n * const routes = eventRoutes(ticketEvents)\n *   .handleWithUseCase('created', {\n *     payloadMapper: (event, ctx) => ({\n *       ticketId: event.payload.ticketId,  // Fully typed!\n *       correlationId: ctx.correlationId,  // Fully typed!\n *     }),\n *     useCase: sendNotificationUseCase,\n *   })\n *   .handle('assigned', async (event) => {\n *     await notifyAssignee(event.payload);\n *     return { outcome: 'ack' as const };\n *   })\n *   .build();\n * ```\n */\nexport interface EventRoutesBuilder<T extends EventRouterConfig, THandled extends string = never> {\n  /**\n   * Register a simple handler for an event.\n   * The handler receives validated event and context, returns EventResult directly.\n   */\n  handle<K extends Exclude<EventRouterKeys<T>, THandled>>(\n    key: K,\n    handlerOrConfig:\n      | SimpleEventHandlerFn<GetEventHandler<T, K>>\n      | SimpleEventHandlerConfig<GetEventHandler<T, K>>,\n  ): EventRoutesBuilder<T, THandled | K>;\n\n  /**\n   * Register a handler using the use case pattern.\n   * Follows: payloadMapper → useCase.execute() → resultMapper (or ack)\n   */\n  handleWithUseCase<K extends Exclude<EventRouterKeys<T>, THandled>, TInput, TOutput>(\n    key: K,\n    config: BuilderEventHandlerConfig<GetEventHandler<T, K>, TInput, TOutput>,\n  ): EventRoutesBuilder<T, THandled | K>;\n\n  /**\n   * Build the event routes array for messaging adapter registration.\n   *\n   * This method is only available when ALL handlers have been wired.\n   * If some handlers are missing, use `buildPartial()` instead.\n   */\n  build: [Exclude<EventRouterKeys<T>, THandled>] extends [never]\n    ? (options?: CreateEventRoutesOptions) => UnifiedEventInput[]\n    : MissingHandlersError<Exclude<EventRouterKeys<T>, THandled>>;\n\n  /**\n   * Build event routes for only the defined handlers.\n   * No compile-time enforcement of completeness.\n   */\n  buildPartial(options?: CreateEventRoutesOptions): UnifiedEventInput[];\n}\n\n// ============================================================================\n// Builder Implementation\n// ============================================================================\n\n/**\n * Internal builder implementation.\n *\n * Uses an immutable pattern where each handle() call returns a new\n * builder instance with the updated handlers map.\n */\nclass EventRoutesBuilderImpl<T extends EventRouterConfig, THandled extends string = never> {\n  private readonly router: T | EventRouterDefinition<T>;\n  private readonly handlers: Map<\n    string,\n    AnyEventHandlerConfig<EventHandlerDefinition, unknown, unknown>\n  >;\n\n  constructor(\n    router: T | EventRouterDefinition<T>,\n    handlers?: Map<string, AnyEventHandlerConfig<EventHandlerDefinition, unknown, unknown>>,\n  ) {\n    this.router = router;\n    this.handlers = handlers ?? new Map();\n  }\n\n  handle<K extends Exclude<EventRouterKeys<T>, THandled>>(\n    key: K,\n    handlerOrConfig:\n      | SimpleEventHandlerFn<GetEventHandler<T, K>>\n      | SimpleEventHandlerConfig<GetEventHandler<T, K>>,\n  ): EventRoutesBuilder<T, THandled | K> {\n    const config: SimpleEventHandlerConfig<EventHandlerDefinition> =\n      typeof handlerOrConfig === 'function'\n        ? { handler: handlerOrConfig as SimpleEventHandlerFn<EventHandlerDefinition> }\n        : (handlerOrConfig as SimpleEventHandlerConfig<EventHandlerDefinition>);\n\n    const newHandlers = new Map(this.handlers);\n    newHandlers.set(key as string, config);\n\n    return new EventRoutesBuilderImpl<T, THandled | K>(\n      this.router,\n      newHandlers,\n    ) as unknown as EventRoutesBuilder<T, THandled | K>;\n  }\n\n  handleWithUseCase<K extends Exclude<EventRouterKeys<T>, THandled>, TInput, TOutput>(\n    key: K,\n    config: BuilderEventHandlerConfig<GetEventHandler<T, K>, TInput, TOutput>,\n  ): EventRoutesBuilder<T, THandled | K> {\n    const newHandlers = new Map(this.handlers);\n    newHandlers.set(\n      key as string,\n      config as EventHandlerConfig<EventHandlerDefinition, unknown, unknown>,\n    );\n\n    return new EventRoutesBuilderImpl<T, THandled | K>(\n      this.router,\n      newHandlers,\n    ) as unknown as EventRoutesBuilder<T, THandled | K>;\n  }\n\n  build(options?: CreateEventRoutesOptions): UnifiedEventInput[] {\n    return createEventRoutesInternal(this.router, Object.fromEntries(this.handlers), options);\n  }\n\n  buildPartial(options?: CreateEventRoutesOptions): UnifiedEventInput[] {\n    return createEventRoutesInternal(this.router, Object.fromEntries(this.handlers), {\n      ...options,\n      allowPartial: true,\n    });\n  }\n}\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Creates a type-safe event routes builder for an event router.\n *\n * The builder pattern provides 100% type inference for all handler parameters:\n * - `event.payload` is typed from the handler's payload schema\n * - `ctx` is typed from the handler's context schema (or EventMetadata)\n * - `output` in resultMapper is typed from the use case\n *\n * @param router - Event router definition or event router config\n * @returns Builder for registering handlers\n *\n * @example Basic usage\n * ```typescript\n * import { eventRoutes } from '@cosmneo/onion-lasagna/events/server';\n * import { ticketEvents } from './router';\n *\n * const routes = eventRoutes(ticketEvents)\n *   .handleWithUseCase('created', {\n *     payloadMapper: (event, ctx) => ({\n *       ticketId: event.payload.ticketId,\n *       correlationId: ctx.correlationId,\n *     }),\n *     useCase: sendNotificationUseCase,\n *   })\n *   .handle('assigned', async (event) => {\n *     await notifyAssignee(event.payload);\n *     return { outcome: 'ack' as const };\n *   })\n *   .build();\n * ```\n */\nexport function eventRoutes<T extends EventRouterConfig>(\n  router: T | EventRouterDefinition<T>,\n): EventRoutesBuilder<T, never> {\n  return new EventRoutesBuilderImpl(router) as unknown as EventRoutesBuilder<T, never>;\n}\n"],"mappings":"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","names":[]}

package/dist/event-router-definition.type-CP9uTlux.d.cts

@@ -0,0 +1,150 @@
+import { SchemaAdapter } from './http/schema/types.cjs';
+
+/**
+ * @fileoverview Core event handler definition types.
+ *
+ * An event handler definition captures all information needed for:
+ * - Type-safe event payload validation
+ * - Server-side event routing and dispatching
+ * - AsyncAPI / documentation generation
+ *
+ * @module events/handler/types/event-handler-definition
+ */
+
+/**
+ * Event handler documentation for AsyncAPI / docs generation.
+ */
+interface EventHandlerDocumentation {
+    /** Short summary of the handler. */
+    readonly summary?: string;
+    /** Detailed description. Supports Markdown. */
+    readonly description?: string;
+    /** Tags for grouping event handlers. */
+    readonly tags?: readonly string[];
+    /** Whether this handler is deprecated. @default false */
+    readonly deprecated?: boolean;
+}
+/**
+ * A fully defined event handler with computed types.
+ * This is the output of `defineEventHandler()`.
+ */
+interface EventHandlerDefinition<TEventType extends string = string, TPayload = undefined, TContext = undefined> {
+    /** Event type string used for routing (e.g., 'ticket.created'). */
+    readonly eventType: TEventType;
+    /** Payload validation schema. */
+    readonly payload: SchemaAdapter | undefined;
+    /** Context validation schema (validates event metadata). */
+    readonly context: SchemaAdapter | undefined;
+    /** Handler documentation. */
+    readonly docs: EventHandlerDocumentation;
+    /**
+     * Phantom types for TypeScript inference.
+     * Never accessed at runtime.
+     * @internal
+     */
+    readonly _types: {
+        readonly eventType: TEventType;
+        readonly payload: TPayload;
+        readonly context: TContext;
+    };
+}
+/** Infers the event type string from a handler definition. */
+type InferEventType<T> = T extends EventHandlerDefinition<infer TEventType, unknown, unknown> ? TEventType : never;
+/** Infers the payload type from a handler definition. */
+type InferEventPayload<T> = T extends EventHandlerDefinition<string, infer TPayload, unknown> ? TPayload : never;
+/** Infers the context type from a handler definition. */
+type InferEventContext<T> = T extends EventHandlerDefinition<string, unknown, infer TContext> ? TContext : never;
+
+/**
+ * @fileoverview Event router definition types for grouping event handlers.
+ *
+ * Mirrors the HTTP router definition pattern with hierarchical grouping,
+ * dotted-key access, and deep merge support.
+ *
+ * @module events/handler/types/event-router-definition
+ */
+
+/**
+ * A router entry can be an event handler definition, a nested config, or a router definition.
+ */
+type EventRouterEntry = EventHandlerDefinition<string, any, any> | EventRouterConfig | EventRouterDefinition;
+/**
+ * Configuration for an event router (group of event handlers).
+ */
+interface EventRouterConfig {
+    readonly [key: string]: EventRouterEntry;
+}
+/**
+ * Router-level defaults applied to all child event handlers.
+ */
+interface EventRouterDefaults {
+    /** Default tags for all handlers. Merged with handler-specific tags. */
+    readonly tags?: readonly string[];
+    /** Default context schema. Applied to handlers that don't define their own. */
+    readonly context?: SchemaAdapter;
+}
+/**
+ * A fully defined event router.
+ */
+interface EventRouterDefinition<T extends EventRouterConfig = EventRouterConfig> {
+    /** The handlers and nested routers in this router. */
+    readonly handlers: T;
+    /** Default values applied to all child handlers. */
+    readonly defaults?: EventRouterDefaults;
+    /**
+     * Marker to identify this as an event router.
+     * @internal
+     */
+    readonly _isEventRouter: true;
+}
+/**
+ * Checks if a value is an EventHandlerDefinition.
+ */
+declare function isEventHandlerDefinition(value: unknown): value is EventHandlerDefinition;
+/**
+ * Checks if a value is an EventRouterDefinition.
+ */
+declare function isEventRouterDefinition(value: unknown): value is EventRouterDefinition;
+/**
+ * Flattens an event router into a map of dotted keys to handler definitions.
+ */
+type FlattenEventRouter<T extends EventRouterConfig, Prefix extends string = ''> = T extends EventRouterConfig ? {
+    [K in keyof T]: T[K] extends EventHandlerDefinition<any, any, any> ? {
+        [P in `${Prefix}${K & string}`]: T[K];
+    } : T[K] extends EventRouterConfig ? FlattenEventRouter<T[K], `${Prefix}${K & string}.`> : never;
+}[keyof T] extends infer U ? U extends Record<string, EventHandlerDefinition<any, any, any>> ? U : never : never : never;
+/**
+ * Gets all handler keys from an event router.
+ */
+type EventRouterKeys<T extends EventRouterConfig, Prefix extends string = ''> = T extends EventRouterConfig ? {
+    [K in keyof T]: T[K] extends EventHandlerDefinition<any, any, any> ? `${Prefix}${K & string}` : T[K] extends EventRouterConfig ? EventRouterKeys<T[K], `${Prefix}${K & string}.`> : never;
+}[keyof T] : never;
+/**
+ * Gets an event handler by its dotted key path.
+ */
+type GetEventHandler<T extends EventRouterConfig, K extends string> = K extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? T[Head] extends EventRouterConfig ? GetEventHandler<T[Head], Tail> : never : never : K extends keyof T ? T[K] extends EventHandlerDefinition<any, any, any> ? T[K] : never : never;
+/**
+ * Deep-merges two event router configs at the type level.
+ */
+type DeepMergeTwo<A extends EventRouterConfig, B extends EventRouterConfig> = {
+    readonly [K in keyof A | keyof B]: K extends keyof A ? K extends keyof B ? A[K] extends EventRouterConfig ? B[K] extends EventRouterConfig ? DeepMergeTwo<A[K], B[K]> : B[K] : B[K] : A[K] : K extends keyof B ? B[K] : never;
+};
+/**
+ * Recursively deep-merges N event router configs left-to-right.
+ */
+type DeepMergeAll<T extends readonly EventRouterConfig[]> = T extends readonly [
+    infer Only extends EventRouterConfig
+] ? Only : T extends readonly [
+    infer First extends EventRouterConfig,
+    infer Second extends EventRouterConfig,
+    ...infer Rest extends readonly EventRouterConfig[]
+] ? DeepMergeAll<[DeepMergeTwo<First, Second>, ...Rest]> : EventRouterConfig;
+/**
+ * Collects all event handlers from a router into a flat array.
+ */
+declare function collectEventHandlers(config: EventRouterConfig, basePath?: string): {
+    key: string;
+    handler: EventHandlerDefinition;
+}[];
+
+export { type DeepMergeTwo as D, type EventHandlerDefinition as E, type FlattenEventRouter as F, type GetEventHandler as G, type InferEventType as I, type EventHandlerDocumentation as a, type EventRouterEntry as b, type EventRouterConfig as c, type EventRouterDefaults as d, type EventRouterDefinition as e, type EventRouterKeys as f, type InferEventPayload as g, type InferEventContext as h, isEventHandlerDefinition as i, isEventRouterDefinition as j, collectEventHandlers as k, type DeepMergeAll as l };

package/dist/event-router-definition.type-D8CG-kjZ.d.ts

@@ -0,0 +1,150 @@
+import { SchemaAdapter } from './http/schema/types.js';
+
+/**
+ * @fileoverview Core event handler definition types.
+ *
+ * An event handler definition captures all information needed for:
+ * - Type-safe event payload validation
+ * - Server-side event routing and dispatching
+ * - AsyncAPI / documentation generation
+ *
+ * @module events/handler/types/event-handler-definition
+ */
+
+/**
+ * Event handler documentation for AsyncAPI / docs generation.
+ */
+interface EventHandlerDocumentation {
+    /** Short summary of the handler. */
+    readonly summary?: string;
+    /** Detailed description. Supports Markdown. */
+    readonly description?: string;
+    /** Tags for grouping event handlers. */
+    readonly tags?: readonly string[];
+    /** Whether this handler is deprecated. @default false */
+    readonly deprecated?: boolean;
+}
+/**
+ * A fully defined event handler with computed types.
+ * This is the output of `defineEventHandler()`.
+ */
+interface EventHandlerDefinition<TEventType extends string = string, TPayload = undefined, TContext = undefined> {
+    /** Event type string used for routing (e.g., 'ticket.created'). */
+    readonly eventType: TEventType;
+    /** Payload validation schema. */
+    readonly payload: SchemaAdapter | undefined;
+    /** Context validation schema (validates event metadata). */
+    readonly context: SchemaAdapter | undefined;
+    /** Handler documentation. */
+    readonly docs: EventHandlerDocumentation;
+    /**
+     * Phantom types for TypeScript inference.
+     * Never accessed at runtime.
+     * @internal
+     */
+    readonly _types: {
+        readonly eventType: TEventType;
+        readonly payload: TPayload;
+        readonly context: TContext;
+    };
+}
+/** Infers the event type string from a handler definition. */
+type InferEventType<T> = T extends EventHandlerDefinition<infer TEventType, unknown, unknown> ? TEventType : never;
+/** Infers the payload type from a handler definition. */
+type InferEventPayload<T> = T extends EventHandlerDefinition<string, infer TPayload, unknown> ? TPayload : never;
+/** Infers the context type from a handler definition. */
+type InferEventContext<T> = T extends EventHandlerDefinition<string, unknown, infer TContext> ? TContext : never;
+
+/**
+ * @fileoverview Event router definition types for grouping event handlers.
+ *
+ * Mirrors the HTTP router definition pattern with hierarchical grouping,
+ * dotted-key access, and deep merge support.
+ *
+ * @module events/handler/types/event-router-definition
+ */
+
+/**
+ * A router entry can be an event handler definition, a nested config, or a router definition.
+ */
+type EventRouterEntry = EventHandlerDefinition<string, any, any> | EventRouterConfig | EventRouterDefinition;
+/**
+ * Configuration for an event router (group of event handlers).
+ */
+interface EventRouterConfig {
+    readonly [key: string]: EventRouterEntry;
+}
+/**
+ * Router-level defaults applied to all child event handlers.
+ */
+interface EventRouterDefaults {
+    /** Default tags for all handlers. Merged with handler-specific tags. */
+    readonly tags?: readonly string[];
+    /** Default context schema. Applied to handlers that don't define their own. */
+    readonly context?: SchemaAdapter;
+}
+/**
+ * A fully defined event router.
+ */
+interface EventRouterDefinition<T extends EventRouterConfig = EventRouterConfig> {
+    /** The handlers and nested routers in this router. */
+    readonly handlers: T;
+    /** Default values applied to all child handlers. */
+    readonly defaults?: EventRouterDefaults;
+    /**
+     * Marker to identify this as an event router.
+     * @internal
+     */
+    readonly _isEventRouter: true;
+}
+/**
+ * Checks if a value is an EventHandlerDefinition.
+ */
+declare function isEventHandlerDefinition(value: unknown): value is EventHandlerDefinition;
+/**
+ * Checks if a value is an EventRouterDefinition.
+ */
+declare function isEventRouterDefinition(value: unknown): value is EventRouterDefinition;
+/**
+ * Flattens an event router into a map of dotted keys to handler definitions.
+ */
+type FlattenEventRouter<T extends EventRouterConfig, Prefix extends string = ''> = T extends EventRouterConfig ? {
+    [K in keyof T]: T[K] extends EventHandlerDefinition<any, any, any> ? {
+        [P in `${Prefix}${K & string}`]: T[K];
+    } : T[K] extends EventRouterConfig ? FlattenEventRouter<T[K], `${Prefix}${K & string}.`> : never;
+}[keyof T] extends infer U ? U extends Record<string, EventHandlerDefinition<any, any, any>> ? U : never : never : never;
+/**
+ * Gets all handler keys from an event router.
+ */
+type EventRouterKeys<T extends EventRouterConfig, Prefix extends string = ''> = T extends EventRouterConfig ? {
+    [K in keyof T]: T[K] extends EventHandlerDefinition<any, any, any> ? `${Prefix}${K & string}` : T[K] extends EventRouterConfig ? EventRouterKeys<T[K], `${Prefix}${K & string}.`> : never;
+}[keyof T] : never;
+/**
+ * Gets an event handler by its dotted key path.
+ */
+type GetEventHandler<T extends EventRouterConfig, K extends string> = K extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? T[Head] extends EventRouterConfig ? GetEventHandler<T[Head], Tail> : never : never : K extends keyof T ? T[K] extends EventHandlerDefinition<any, any, any> ? T[K] : never : never;
+/**
+ * Deep-merges two event router configs at the type level.
+ */
+type DeepMergeTwo<A extends EventRouterConfig, B extends EventRouterConfig> = {
+    readonly [K in keyof A | keyof B]: K extends keyof A ? K extends keyof B ? A[K] extends EventRouterConfig ? B[K] extends EventRouterConfig ? DeepMergeTwo<A[K], B[K]> : B[K] : B[K] : A[K] : K extends keyof B ? B[K] : never;
+};
+/**
+ * Recursively deep-merges N event router configs left-to-right.
+ */
+type DeepMergeAll<T extends readonly EventRouterConfig[]> = T extends readonly [
+    infer Only extends EventRouterConfig
+] ? Only : T extends readonly [
+    infer First extends EventRouterConfig,
+    infer Second extends EventRouterConfig,
+    ...infer Rest extends readonly EventRouterConfig[]
+] ? DeepMergeAll<[DeepMergeTwo<First, Second>, ...Rest]> : EventRouterConfig;
+/**
+ * Collects all event handlers from a router into a flat array.
+ */
+declare function collectEventHandlers(config: EventRouterConfig, basePath?: string): {
+    key: string;
+    handler: EventHandlerDefinition;
+}[];
+
+export { type DeepMergeTwo as D, type EventHandlerDefinition as E, type FlattenEventRouter as F, type GetEventHandler as G, type InferEventType as I, type EventHandlerDocumentation as a, type EventRouterEntry as b, type EventRouterConfig as c, type EventRouterDefaults as d, type EventRouterDefinition as e, type EventRouterKeys as f, type InferEventPayload as g, type InferEventContext as h, isEventHandlerDefinition as i, isEventRouterDefinition as j, collectEventHandlers as k, type DeepMergeAll as l };