@cosmneo/onion-lasagna 0.2.0 → 0.3.0

package/dist/events/server/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/presentation/events/server/index.ts","../../../src/presentation/events/handler/types/event-router-definition.type.ts","../../../src/presentation/events/handler/utils.ts","../../../src/presentation/http/shared/error-mapping.ts","../../../src/presentation/events/shared/error-mapping.ts","../../../src/presentation/events/server/types.ts","../../../src/presentation/events/server/create-event-routes.ts","../../../src/presentation/events/server/event-routes-builder.ts"],"sourcesContent":["export { eventRoutes } from './event-routes-builder';\nexport type {\n  EventRoutesBuilder,\n  MissingHandlersError,\n  BuilderEventHandlerConfig,\n} from './event-routes-builder';\n\nexport type {\n  RawEvent,\n  EventMetadata,\n  ValidatedEvent,\n  TypedEventContext,\n  EventHandlerConfig,\n  SimpleEventHandlerFn,\n  SimpleEventHandlerConfig,\n  AnyEventHandlerConfig,\n  EventMiddlewareFunction,\n  EventRoutesConfig,\n  CreateEventRoutesOptions,\n  UnifiedEventInput,\n  UseCasePort,\n} from './types';\n\nexport { isSimpleEventHandlerConfig } from './types';\n","/**\n * @fileoverview Event router definition types for grouping event handlers.\n *\n * Mirrors the HTTP router definition pattern with hierarchical grouping,\n * dotted-key access, and deep merge support.\n *\n * @module events/handler/types/event-router-definition\n */\n\nimport type { EventHandlerDefinition } from './event-handler-definition.type';\nimport type { SchemaAdapter } from '../../../http/schema/types';\n\n// ============================================================================\n// Router Types\n// ============================================================================\n\n/**\n * A router entry can be an event handler definition, a nested config, or a router definition.\n */\nexport type EventRouterEntry =\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  EventHandlerDefinition<string, any, any> | EventRouterConfig | EventRouterDefinition;\n\n/**\n * Configuration for an event router (group of event handlers).\n */\nexport interface EventRouterConfig {\n  readonly [key: string]: EventRouterEntry;\n}\n\n/**\n * Router-level defaults applied to all child event handlers.\n */\nexport interface EventRouterDefaults {\n  /** Default tags for all handlers. Merged with handler-specific tags. */\n  readonly tags?: readonly string[];\n\n  /** Default context schema. Applied to handlers that don't define their own. */\n  readonly context?: SchemaAdapter;\n}\n\n/**\n * A fully defined event router.\n */\nexport interface EventRouterDefinition<T extends EventRouterConfig = EventRouterConfig> {\n  /** The handlers and nested routers in this router. */\n  readonly handlers: T;\n\n  /** Default values applied to all child handlers. */\n  readonly defaults?: EventRouterDefaults;\n\n  /**\n   * Marker to identify this as an event router.\n   * @internal\n   */\n  readonly _isEventRouter: true;\n}\n\n// ============================================================================\n// Type Guards\n// ============================================================================\n\n/**\n * Checks if a value is an EventHandlerDefinition.\n */\nexport function isEventHandlerDefinition(value: unknown): value is EventHandlerDefinition {\n  return typeof value === 'object' && value !== null && 'eventType' in value && '_types' in value;\n}\n\n/**\n * Checks if a value is an EventRouterDefinition.\n */\nexport function isEventRouterDefinition(value: unknown): value is EventRouterDefinition {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    '_isEventRouter' in value &&\n    (value as EventRouterDefinition)._isEventRouter === true\n  );\n}\n\n// ============================================================================\n// Utility Types\n// ============================================================================\n\n/**\n * Flattens an event router into a map of dotted keys to handler definitions.\n */\nexport type FlattenEventRouter<\n  T extends EventRouterConfig,\n  Prefix extends string = '',\n> = T extends EventRouterConfig\n  ? {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      [K in keyof T]: T[K] extends EventHandlerDefinition<any, any, any>\n        ? { [P in `${Prefix}${K & string}`]: T[K] }\n        : T[K] extends EventRouterConfig\n          ? FlattenEventRouter<T[K], `${Prefix}${K & string}.`>\n          : never;\n    }[keyof T] extends infer U\n    ? // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      U extends Record<string, EventHandlerDefinition<any, any, any>>\n      ? U\n      : never\n    : never\n  : never;\n\n/**\n * Gets all handler keys from an event router.\n */\nexport type EventRouterKeys<\n  T extends EventRouterConfig,\n  Prefix extends string = '',\n> = T extends EventRouterConfig\n  ? {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      [K in keyof T]: T[K] extends EventHandlerDefinition<any, any, any>\n        ? `${Prefix}${K & string}`\n        : T[K] extends EventRouterConfig\n          ? EventRouterKeys<T[K], `${Prefix}${K & string}.`>\n          : never;\n    }[keyof T]\n  : never;\n\n/**\n * Gets an event handler by its dotted key path.\n */\nexport type GetEventHandler<\n  T extends EventRouterConfig,\n  K extends string,\n> = K extends `${infer Head}.${infer Tail}`\n  ? Head extends keyof T\n    ? T[Head] extends EventRouterConfig\n      ? GetEventHandler<T[Head], Tail>\n      : never\n    : never\n  : K extends keyof T\n    ? // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      T[K] extends EventHandlerDefinition<any, any, any>\n      ? T[K]\n      : never\n    : never;\n\n// ============================================================================\n// Deep Merge Types\n// ============================================================================\n\n/**\n * Deep-merges two event router configs at the type level.\n */\nexport type DeepMergeTwo<A extends EventRouterConfig, B extends EventRouterConfig> = {\n  readonly [K in keyof A | keyof B]: K extends keyof A\n    ? K extends keyof B\n      ? A[K] extends EventRouterConfig\n        ? B[K] extends EventRouterConfig\n          ? DeepMergeTwo<A[K], B[K]>\n          : B[K]\n        : B[K]\n      : A[K]\n    : K extends keyof B\n      ? B[K]\n      : never;\n};\n\n/**\n * Recursively deep-merges N event router configs left-to-right.\n */\nexport type DeepMergeAll<T extends readonly EventRouterConfig[]> = T extends readonly [\n  infer Only extends EventRouterConfig,\n]\n  ? Only\n  : T extends readonly [\n        infer First extends EventRouterConfig,\n        infer Second extends EventRouterConfig,\n        ...infer Rest extends readonly EventRouterConfig[],\n      ]\n    ? DeepMergeAll<[DeepMergeTwo<First, Second>, ...Rest]>\n    : EventRouterConfig;\n\n// ============================================================================\n// Runtime Utilities\n// ============================================================================\n\n/**\n * Collects all event handlers from a router into a flat array.\n */\nexport function collectEventHandlers(\n  config: EventRouterConfig,\n  basePath = '',\n): { key: string; handler: EventHandlerDefinition }[] {\n  const handlers: { key: string; handler: EventHandlerDefinition }[] = [];\n\n  for (const [key, value] of Object.entries(config)) {\n    const fullKey = basePath ? `${basePath}.${key}` : key;\n\n    if (isEventHandlerDefinition(value)) {\n      handlers.push({ key: fullKey, handler: value });\n    } else if (isEventRouterDefinition(value)) {\n      handlers.push(...collectEventHandlers(value.handlers, fullKey));\n    } else if (typeof value === 'object' && value !== null) {\n      handlers.push(...collectEventHandlers(value as EventRouterConfig, fullKey));\n    }\n  }\n\n  return handlers;\n}\n","/**\n * @fileoverview Utility functions for event handler routing.\n *\n * @module events/handler/utils\n */\n\n/**\n * Generates a handler ID from a dotted key path.\n *\n * Converts dot-separated keys to camelCase:\n * - `\"ticket.created\"` → `\"ticketCreated\"`\n * - `\"ecosystem.member.added\"` → `\"ecosystemMemberAdded\"`\n *\n * @param key - The dotted key path\n * @returns A camelCase handler ID\n */\nexport function generateHandlerId(key: string): string {\n  return key.replace(/\\.(\\w)/g, (_, char: string) => char.toUpperCase());\n}\n","/**\n * @fileoverview Centralized error mapping for HTTP frameworks.\n *\n * Provides a single source of truth for mapping onion-lasagna errors\n * to HTTP status codes and response bodies.\n *\n * @module http/shared/error-mapping\n */\n\nimport { CodedError } from '../../../global/exceptions/coded-error.error';\nimport { ObjectValidationError } from '../../../global/exceptions/object-validation.error';\nimport { DomainError } from '../../../domain/exceptions/domain.error';\nimport { UseCaseError } from '../../../app/exceptions/use-case.error';\nimport { NotFoundError } from '../../../app/exceptions/not-found.error';\nimport { ConflictError } from '../../../app/exceptions/conflict.error';\nimport { UnprocessableError } from '../../../app/exceptions/unprocessable.error';\nimport { ForbiddenError } from '../../../app/exceptions/forbidden.error';\nimport { UnauthorizedError } from '../../../app/exceptions/unauthorized.error';\nimport { InfraError } from '../../../infra/exceptions/infra.error';\nimport { ControllerError } from '../../exceptions/controller.error';\nimport { AccessDeniedError } from '../../exceptions/access-denied.error';\nimport { InvalidRequestError } from '../../exceptions/invalid-request.error';\nimport type { ErrorResponseBody, MappedErrorResponse } from './types';\n\n// ============================================================================\n// Constants and Interfaces\n// ============================================================================\n\n/**\n * Default masked error response for internal errors.\n */\nconst MASKED_ERROR_BODY: ErrorResponseBody = {\n  message: 'An unexpected error occurred',\n  errorCode: 'INTERNAL_ERROR',\n};\n\n/**\n * Known internal error type names that should be masked.\n */\nconst INTERNAL_ERROR_TYPES = [\n  'DomainError',\n  'InfraError',\n  'ControllerError',\n  'NetworkError',\n  'PersistenceError',\n  'ExternalServiceError',\n  'InvariantViolationError',\n];\n\n/**\n * Validation error item structure.\n */\ninterface ValidationErrorInput {\n  field: string;\n  message: string;\n}\n\n/**\n * Validation error structure for string-based checking.\n */\ninterface ValidationErrorItem {\n  field: string;\n  message: string;\n}\n\n/**\n * Interface for errors with validation items.\n */\ninterface ErrorWithValidation {\n  message: string;\n  code: string;\n  validationErrors: ValidationErrorItem[];\n}\n\n/**\n * Interface for coded errors.\n */\ninterface CodedErrorLike {\n  message: string;\n  code: string;\n}\n\n// ============================================================================\n// String-based type checking helpers (for bundled code compatibility)\n// ============================================================================\n\n/**\n * Checks if error matches a specific error type by checking its constructor name.\n * This approach avoids issues with multiple class instances in bundled code.\n * Handles both original names and tsup's mangled names (prefixed with _).\n *\n * @param error - The error to check\n * @param typeName - The error type name to match\n * @returns True if error matches the type name\n */\nexport function isErrorType(error: unknown, typeName: string): error is CodedErrorLike {\n  if (!error || typeof error !== 'object') return false;\n  // Guard against objects without constructor (e.g., Object.create(null))\n  const constructor = Object.prototype.hasOwnProperty.call(error, 'constructor')\n    ? (error as { constructor?: { name?: string } }).constructor\n    : Object.getPrototypeOf(error)?.constructor;\n  if (!constructor) return false;\n  const name = constructor.name;\n  // Check both the original name and the mangled name (tsup prefixes with _)\n  return name === typeName || name === `_${typeName}`;\n}\n\n/**\n * Checks if error has validation errors array.\n *\n * @param error - The error to check\n * @returns True if error has validationErrors property\n */\nexport function hasValidationErrors(error: unknown): error is ErrorWithValidation {\n  if (!error || typeof error !== 'object') return false;\n  return (\n    'validationErrors' in error && Array.isArray((error as ErrorWithValidation).validationErrors)\n  );\n}\n\n// ============================================================================\n// Response body builders\n// ============================================================================\n\n/**\n * Builds a validation error response body from error details.\n *\n * @param message - The error message\n * @param code - The error code\n * @param validationErrors - Array of field validation errors\n * @returns Error response body with errorItems\n */\nfunction buildValidationErrorBody(\n  message: string,\n  code: string,\n  validationErrors: readonly ValidationErrorInput[],\n): ErrorResponseBody {\n  return {\n    message,\n    errorCode: code,\n    errorItems: validationErrors.map((e) => ({\n      item: e.field,\n      message: e.message,\n    })),\n  };\n}\n\n/**\n * Builds a simple error response body from error details.\n *\n * @param message - The error message\n * @param code - The error code\n * @returns Error response body\n */\nfunction buildSimpleErrorBody(message: string, code: string): ErrorResponseBody {\n  return {\n    message,\n    errorCode: code,\n  };\n}\n\n// ============================================================================\n// Primary error mapping functions (with bundled code fallback)\n// ============================================================================\n\n/**\n * Maps an error to the appropriate HTTP status code.\n * Uses instanceof first, then falls back to name-based checking for bundled code.\n *\n * @param error - The error to map\n * @returns HTTP status code\n */\nexport function getHttpStatusCode(error: unknown): number {\n  // Try instanceof first (faster)\n  if (error instanceof ObjectValidationError) return 400;\n  if (error instanceof InvalidRequestError) return 400;\n  if (error instanceof UnauthorizedError) return 401;\n  if (error instanceof ForbiddenError) return 403;\n  if (error instanceof AccessDeniedError) return 403;\n  if (error instanceof NotFoundError) return 404;\n  if (error instanceof ConflictError) return 409;\n  if (error instanceof UnprocessableError) return 422;\n  if (error instanceof UseCaseError) return 400;\n\n  // Fall back to name-based checking for bundled code (e.g., _NotFoundError)\n  if (isErrorType(error, 'ObjectValidationError')) return 400;\n  if (isErrorType(error, 'InvalidRequestError')) return 400;\n  if (isErrorType(error, 'UnauthorizedError')) return 401;\n  if (isErrorType(error, 'ForbiddenError')) return 403;\n  if (isErrorType(error, 'AccessDeniedError')) return 403;\n  if (isErrorType(error, 'NotFoundError')) return 404;\n  if (isErrorType(error, 'ConflictError')) return 409;\n  if (isErrorType(error, 'UnprocessableError')) return 422;\n  if (isErrorType(error, 'UseCaseError')) return 400;\n\n  return 500;\n}\n\n/**\n * Checks if an error should have its details masked in the response.\n *\n * Security-sensitive errors (domain, infrastructure, controller) are masked\n * to prevent leaking implementation details.\n * Uses instanceof first, then falls back to name-based checking for bundled code.\n *\n * @param error - The error to check\n * @returns True if error details should be hidden\n */\nexport function shouldMaskError(error: unknown): boolean {\n  // Try instanceof first (faster)\n  if (\n    error instanceof DomainError ||\n    error instanceof InfraError ||\n    error instanceof ControllerError\n  ) {\n    return true;\n  }\n\n  // Fall back to name-based checking for bundled code\n  for (const errorType of INTERNAL_ERROR_TYPES) {\n    if (isErrorType(error, errorType)) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Creates the response body for an error.\n * Uses instanceof first, then falls back to name-based checking for bundled code.\n *\n * @param error - The error to create body for\n * @returns Error response body\n */\nexport function createErrorResponseBody(error: unknown): ErrorResponseBody {\n  // Masked errors - hide internal details\n  if (shouldMaskError(error)) {\n    return MASKED_ERROR_BODY;\n  }\n\n  // Validation errors - include field details (try instanceof first)\n  if (error instanceof ObjectValidationError) {\n    return buildValidationErrorBody(error.message, error.code, error.validationErrors);\n  }\n  if (error instanceof InvalidRequestError) {\n    return buildValidationErrorBody(error.message, error.code, error.validationErrors);\n  }\n\n  // Validation errors - fall back to name-based checking for bundled code\n  if (isErrorType(error, 'ObjectValidationError') && hasValidationErrors(error)) {\n    return buildValidationErrorBody(error.message, error.code, error.validationErrors);\n  }\n  if (isErrorType(error, 'InvalidRequestError') && hasValidationErrors(error)) {\n    return buildValidationErrorBody(error.message, error.code, error.validationErrors);\n  }\n\n  // Other coded errors - expose message and code (try instanceof first)\n  if (error instanceof CodedError) {\n    return buildSimpleErrorBody(error.message, error.code);\n  }\n\n  // Other coded errors - fall back to name-based checking\n  if (isErrorType(error, 'CodedError')) {\n    return buildSimpleErrorBody(error.message, error.code);\n  }\n\n  // Check for any error with message and code properties\n  if (\n    error &&\n    typeof error === 'object' &&\n    'message' in error &&\n    'code' in error &&\n    typeof (error as CodedErrorLike).message === 'string' &&\n    typeof (error as CodedErrorLike).code === 'string'\n  ) {\n    return buildSimpleErrorBody((error as CodedErrorLike).message, (error as CodedErrorLike).code);\n  }\n\n  // Unknown errors - mask\n  return MASKED_ERROR_BODY;\n}\n\n/**\n * Maps an error to a complete HTTP response structure.\n *\n * Mapping strategy (checked in order):\n * 1. `ObjectValidationError` / `InvalidRequestError` → 400 Bad Request (with field errors)\n * 2. `UseCaseError` → 400 Bad Request\n * 3. `UnauthorizedError` → 401 Unauthorized\n * 4. `ForbiddenError` / `AccessDeniedError` → 403 Forbidden\n * 5. `NotFoundError` → 404 Not Found\n * 6. `ConflictError` → 409 Conflict\n * 7. `UnprocessableError` → 422 Unprocessable Entity\n * 8. `DomainError` / `InfraError` / `ControllerError` → 500 Internal Server Error (masked)\n * 9. Unknown → 500 Internal Server Error (masked)\n *\n * @param error - The error to map\n * @returns Mapped error response with status and body\n */\nexport function mapErrorToHttpResponse(error: unknown): MappedErrorResponse {\n  return {\n    status: getHttpStatusCode(error),\n    body: createErrorResponseBody(error),\n  };\n}\n","/**\n * @fileoverview Error-to-EventResult mapping for event handlers.\n *\n * Maps caught errors to event processing outcomes (ack/retry/dlq).\n * Uses the same name-based type checking as the HTTP error mapper\n * for compatibility with bundled/minified code.\n *\n * @module events/shared/error-mapping\n */\n\nimport { isErrorType } from '../../http/shared/error-mapping';\nimport type { EventResult } from './types';\n\n// ============================================================================\n// Error Type Classifications\n// ============================================================================\n\n/**\n * Error types that indicate permanent failures (send to DLQ).\n * These errors will not resolve on retry.\n */\nconst DLQ_ERROR_TYPES = [\n  'ObjectValidationError',\n  'InvalidRequestError',\n  'UseCaseError',\n  'DomainError',\n  'UnprocessableError',\n  'AccessDeniedError',\n  'ForbiddenError',\n  'UnauthorizedError',\n  'InvariantViolationError',\n];\n\n/**\n * Error types that indicate transient failures (retry).\n * These errors may resolve on subsequent attempts.\n */\nconst RETRY_ERROR_TYPES = [\n  'NotFoundError',\n  'ConflictError',\n  'InfraError',\n  'DbError',\n  'NetworkError',\n  'TimeoutError',\n  'ExternalServiceError',\n  'PersistenceError',\n];\n\n// ============================================================================\n// Mapping Function\n// ============================================================================\n\n/**\n * Maps a caught error to an EventResult.\n *\n * Default mapping strategy:\n *\n * | Error Type                                     | Outcome | Rationale                              |\n * |------------------------------------------------|---------|----------------------------------------|\n * | ObjectValidationError, InvalidRequestError      | dlq     | Bad payload — retrying won't help      |\n * | UseCaseError                                    | dlq     | Business rule rejection — permanent    |\n * | DomainError, InvariantViolationError            | dlq     | Domain invariant — permanent           |\n * | UnprocessableError                              | dlq     | Valid but not processable — permanent  |\n * | AccessDeniedError, ForbiddenError, Unauthorized | dlq     | Permission — permanent                 |\n * | NotFoundError                                   | retry   | Entity might not exist yet             |\n * | ConflictError                                   | retry   | Concurrent write — may resolve         |\n * | InfraError, DbError, NetworkError, TimeoutError | retry   | Infrastructure/transient               |\n * | Unknown                                         | retry   | Conservative — don't lose messages     |\n *\n * @param error - The caught error\n * @returns An EventResult indicating how the message should be handled\n */\nexport function mapErrorToEventResult(error: unknown): EventResult {\n  // Check DLQ errors first (permanent failures)\n  for (const typeName of DLQ_ERROR_TYPES) {\n    if (isErrorType(error, typeName)) {\n      return {\n        outcome: 'dlq',\n        reason: (error as { message: string }).message,\n      };\n    }\n  }\n\n  // Check retry errors (transient failures)\n  for (const typeName of RETRY_ERROR_TYPES) {\n    if (isErrorType(error, typeName)) {\n      return {\n        outcome: 'retry',\n        reason: (error as { message: string }).message,\n      };\n    }\n  }\n\n  // Unknown errors — retry conservatively to avoid losing messages\n  const message =\n    error instanceof Error ? error.message : 'Unknown error occurred during event processing';\n\n  return {\n    outcome: 'retry',\n    reason: message,\n  };\n}\n","/**\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/events/server/index.d.cts

@@ -0,0 +1,281 @@
+import { E as EventHandlerDefinition, c as EventRouterConfig, f as EventRouterKeys, e as EventRouterDefinition, G as GetEventHandler } from '../../event-router-definition.type-CP9uTlux.cjs';
+import { E as EventResult } from '../../types-cke61juH.cjs';
+export { U as UseCasePort } from '../../types-afYpL7Ap.cjs';
+import '../../http/schema/types.cjs';
+import '../../router-definition.type-BElX-Pl4.cjs';
+
+/**
+ * @fileoverview Server types for the event handler system.
+ *
+ * @module events/server/types
+ */
+
+/**
+ * Event metadata provided by the messaging system.
+ */
+interface EventMetadata {
+    /** Unique event identifier for idempotency checks. */
+    readonly eventId: string;
+    /** ISO 8601 timestamp of when the event occurred. */
+    readonly timestamp: string;
+    /** Correlation ID for distributed tracing. */
+    readonly correlationId?: string;
+    /** Source system or bounded context that emitted the event. */
+    readonly source?: string;
+    /** Number of delivery attempts (1-based). */
+    readonly attemptCount?: number;
+    /** Additional metadata from the messaging system. */
+    readonly [key: string]: unknown;
+}
+/**
+ * Raw event from the messaging system.
+ * This is the input to event handlers before validation.
+ */
+interface RawEvent {
+    /** Event type string for routing. */
+    readonly type: string;
+    /** Event payload (unvalidated). */
+    readonly payload: unknown;
+    /** Event metadata from the messaging system. */
+    readonly metadata: EventMetadata;
+}
+/**
+ * A validated event with typed payload.
+ * This is what handlers receive after validation passes.
+ */
+interface ValidatedEvent<THandler extends EventHandlerDefinition> {
+    /** Validated event payload. */
+    readonly payload: THandler['_types']['payload'];
+    /** Raw event object for advanced use cases. */
+    readonly raw: RawEvent;
+}
+/**
+ * Typed event context based on handler definition.
+ * If the handler defines a context schema, this will be the validated type.
+ * Otherwise, it falls back to the generic EventMetadata.
+ */
+type TypedEventContext<THandler extends EventHandlerDefinition> = THandler['_types']['context'] extends undefined ? EventMetadata : THandler['_types']['context'];
+/**
+ * Handler configuration using the use case pattern.
+ *
+ * @typeParam THandler - The event handler definition type
+ * @typeParam TInput - Use case input type
+ * @typeParam TOutput - Use case output type
+ */
+interface EventHandlerConfig<THandler extends EventHandlerDefinition, TInput = void, TOutput = void> {
+    /**
+     * Maps the validated event payload to use case input.
+     * Both `event` and `ctx` are fully typed based on handler schemas.
+     */
+    readonly payloadMapper: (event: ValidatedEvent<THandler>, ctx: TypedEventContext<THandler>) => TInput;
+    /** The use case to execute. */
+    readonly useCase: {
+        execute(input?: TInput): Promise<TOutput>;
+    };
+    /**
+     * Maps the use case output to an EventResult.
+     * If omitted, defaults to `{ outcome: 'ack' }`.
+     */
+    readonly resultMapper?: (output: TOutput) => EventResult;
+    /** Middleware to run before the handler. */
+    readonly middleware?: readonly EventMiddlewareFunction[];
+}
+/**
+ * Simple handler function that directly returns an EventResult.
+ */
+type SimpleEventHandlerFn<THandler extends EventHandlerDefinition> = (event: ValidatedEvent<THandler>, ctx: TypedEventContext<THandler>) => Promise<EventResult> | EventResult;
+/**
+ * Configuration for a simple handler (no use case).
+ */
+interface SimpleEventHandlerConfig<THandler extends EventHandlerDefinition> {
+    readonly handler: SimpleEventHandlerFn<THandler>;
+    readonly middleware?: readonly EventMiddlewareFunction[];
+}
+/**
+ * Union of all event handler config types.
+ * Used internally to store handlers in the builder.
+ */
+type AnyEventHandlerConfig<THandler extends EventHandlerDefinition, TInput = unknown, TOutput = unknown> = EventHandlerConfig<THandler, TInput, TOutput> | SimpleEventHandlerConfig<THandler>;
+/**
+ * Type guard to check if config is a simple event handler.
+ */
+declare function isSimpleEventHandlerConfig(config: AnyEventHandlerConfig<EventHandlerDefinition, unknown, unknown>): config is SimpleEventHandlerConfig<EventHandlerDefinition>;
+/**
+ * Event middleware function type.
+ */
+type EventMiddlewareFunction = (event: RawEvent, next: () => Promise<EventResult>) => Promise<EventResult>;
+/**
+ * Configuration mapping handler keys to handler configs.
+ */
+type EventRoutesConfig<T extends EventRouterConfig> = Record<EventRouterKeys<T>, EventHandlerConfig<any, any, any>>;
+/**
+ * Options for creating event routes.
+ */
+interface CreateEventRoutesOptions {
+    /** Global middleware to run before all handlers. */
+    readonly middleware?: readonly EventMiddlewareFunction[];
+    /**
+     * Whether to validate incoming event payloads against handler schemas.
+     * When enabled, invalid payloads result in a `dlq` outcome.
+     * @default true
+     */
+    readonly validatePayload?: boolean;
+    /**
+     * Custom error mapper to override default error-to-EventResult mapping.
+     * If not provided, uses the built-in `mapErrorToEventResult`.
+     */
+    readonly errorMapper?: (error: unknown) => EventResult;
+    /**
+     * Allow partial handler configuration (not all handlers need to be wired).
+     * @default false
+     * @internal Used by builder pattern's buildPartial()
+     */
+    readonly allowPartial?: boolean;
+}
+/**
+ * Event input compatible with messaging adapters.
+ * This is the output of eventRoutes().build().
+ */
+interface UnifiedEventInput {
+    /** Event type string for routing. */
+    readonly eventType: string;
+    /** Handler function. */
+    readonly handler: (rawEvent: RawEvent) => Promise<EventResult>;
+    /** Handler metadata for documentation. */
+    readonly metadata: {
+        readonly handlerId?: string;
+        readonly summary?: string;
+        readonly description?: string;
+        readonly tags?: readonly string[];
+        readonly deprecated?: boolean;
+    };
+}
+
+/**
+ * @fileoverview Builder pattern for creating type-safe event routes.
+ *
+ * The `eventRoutes` function returns a builder that provides 100% type inference
+ * for all handler parameters — no manual type annotations required.
+ *
+ * @module events/server/event-routes-builder
+ */
+
+/**
+ * Error type displayed when attempting to build() with missing handlers.
+ * The `___missingHandlers` property shows which handlers are missing.
+ */
+interface MissingHandlersError<TMissing extends string> {
+    /**
+     * This error indicates that not all event handlers have been wired.
+     * Use buildPartial() to build with only the defined handlers,
+     * or add handlers for the missing events.
+     */
+    (options?: never): never;
+    /** Event handlers that are missing. */
+    readonly ___missingHandlers: TMissing;
+}
+/**
+ * Handler configuration for the builder pattern.
+ */
+interface BuilderEventHandlerConfig<THandler extends EventHandlerDefinition, TInput, TOutput> {
+    /**
+     * Maps the validated event payload to use case input.
+     * Both `event` and `ctx` are fully typed based on handler schemas.
+     */
+    readonly payloadMapper: (event: ValidatedEvent<THandler>, ctx: TypedEventContext<THandler>) => TInput;
+    /** The use case to execute. */
+    readonly useCase: {
+        execute(input?: TInput): Promise<TOutput>;
+    };
+    /**
+     * Maps the use case output to an EventResult.
+     * If omitted, defaults to `{ outcome: 'ack' }`.
+     */
+    readonly resultMapper?: (output: TOutput) => EventResult;
+    /** Middleware to run before the handler. */
+    readonly middleware?: readonly EventMiddlewareFunction[];
+}
+/**
+ * Builder interface for creating type-safe event routes.
+ *
+ * Each `.handle()` call captures the specific handler type and provides
+ * full type inference for payloadMapper and useCase.
+ *
+ * @typeParam T - The event router configuration type
+ * @typeParam THandled - Union of handler keys that have been wired (accumulates)
+ *
+ * @example
+ * ```typescript
+ * const routes = eventRoutes(ticketEvents)
+ *   .handleWithUseCase('created', {
+ *     payloadMapper: (event, ctx) => ({
+ *       ticketId: event.payload.ticketId,  // Fully typed!
+ *       correlationId: ctx.correlationId,  // Fully typed!
+ *     }),
+ *     useCase: sendNotificationUseCase,
+ *   })
+ *   .handle('assigned', async (event) => {
+ *     await notifyAssignee(event.payload);
+ *     return { outcome: 'ack' as const };
+ *   })
+ *   .build();
+ * ```
+ */
+interface EventRoutesBuilder<T extends EventRouterConfig, THandled extends string = never> {
+    /**
+     * Register a simple handler for an event.
+     * The handler receives validated event and context, returns EventResult directly.
+     */
+    handle<K extends Exclude<EventRouterKeys<T>, THandled>>(key: K, handlerOrConfig: SimpleEventHandlerFn<GetEventHandler<T, K>> | SimpleEventHandlerConfig<GetEventHandler<T, K>>): EventRoutesBuilder<T, THandled | K>;
+    /**
+     * Register a handler using the use case pattern.
+     * Follows: payloadMapper → useCase.execute() → resultMapper (or ack)
+     */
+    handleWithUseCase<K extends Exclude<EventRouterKeys<T>, THandled>, TInput, TOutput>(key: K, config: BuilderEventHandlerConfig<GetEventHandler<T, K>, TInput, TOutput>): EventRoutesBuilder<T, THandled | K>;
+    /**
+     * Build the event routes array for messaging adapter registration.
+     *
+     * This method is only available when ALL handlers have been wired.
+     * If some handlers are missing, use `buildPartial()` instead.
+     */
+    build: [Exclude<EventRouterKeys<T>, THandled>] extends [never] ? (options?: CreateEventRoutesOptions) => UnifiedEventInput[] : MissingHandlersError<Exclude<EventRouterKeys<T>, THandled>>;
+    /**
+     * Build event routes for only the defined handlers.
+     * No compile-time enforcement of completeness.
+     */
+    buildPartial(options?: CreateEventRoutesOptions): UnifiedEventInput[];
+}
+/**
+ * Creates a type-safe event routes builder for an event router.
+ *
+ * The builder pattern provides 100% type inference for all handler parameters:
+ * - `event.payload` is typed from the handler's payload schema
+ * - `ctx` is typed from the handler's context schema (or EventMetadata)
+ * - `output` in resultMapper is typed from the use case
+ *
+ * @param router - Event router definition or event router config
+ * @returns Builder for registering handlers
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { eventRoutes } from '@cosmneo/onion-lasagna/events/server';
+ * import { ticketEvents } from './router';
+ *
+ * const routes = eventRoutes(ticketEvents)
+ *   .handleWithUseCase('created', {
+ *     payloadMapper: (event, ctx) => ({
+ *       ticketId: event.payload.ticketId,
+ *       correlationId: ctx.correlationId,
+ *     }),
+ *     useCase: sendNotificationUseCase,
+ *   })
+ *   .handle('assigned', async (event) => {
+ *     await notifyAssignee(event.payload);
+ *     return { outcome: 'ack' as const };
+ *   })
+ *   .build();
+ * ```
+ */
+declare function eventRoutes<T extends EventRouterConfig>(router: T | EventRouterDefinition<T>): EventRoutesBuilder<T, never>;
+
+export { type AnyEventHandlerConfig, type BuilderEventHandlerConfig, type CreateEventRoutesOptions, type EventHandlerConfig, type EventMetadata, type EventMiddlewareFunction, type EventRoutesBuilder, type EventRoutesConfig, type MissingHandlersError, type RawEvent, type SimpleEventHandlerConfig, type SimpleEventHandlerFn, type TypedEventContext, type UnifiedEventInput, type ValidatedEvent, eventRoutes, isSimpleEventHandlerConfig };