@cosmneo/onion-lasagna 0.2.0 → 0.3.0

package/dist/events/asyncapi/index.d.ts

@@ -0,0 +1,184 @@
+import { c as EventRouterConfig, e as EventRouterDefinition } from '../../event-router-definition.type-D8CG-kjZ.js';
+import { JsonSchema } from '../../http/schema/types.js';
+
+/**
+ * @fileoverview AsyncAPI types for specification generation.
+ *
+ * @module events/asyncapi/types
+ */
+
+/**
+ * AsyncAPI specification configuration.
+ */
+interface AsyncAPIConfig {
+    /**
+     * AsyncAPI specification version.
+     * @default '3.0.0'
+     */
+    readonly asyncapi?: '3.0.0';
+    /**
+     * API information.
+     */
+    readonly info: AsyncAPIInfo;
+    /**
+     * Server configurations (e.g., message broker details).
+     */
+    readonly servers?: Record<string, AsyncAPIServer>;
+    /**
+     * Default content type for messages.
+     * @default 'application/json'
+     */
+    readonly defaultContentType?: string;
+    /**
+     * Custom tags with descriptions.
+     */
+    readonly tags?: readonly AsyncAPITag[];
+    /**
+     * External documentation.
+     */
+    readonly externalDocs?: AsyncAPIExternalDocs;
+}
+/**
+ * API information.
+ */
+interface AsyncAPIInfo {
+    readonly title: string;
+    readonly version: string;
+    readonly description?: string;
+    readonly termsOfService?: string;
+    readonly contact?: {
+        readonly name?: string;
+        readonly url?: string;
+        readonly email?: string;
+    };
+    readonly license?: {
+        readonly name: string;
+        readonly url?: string;
+    };
+    readonly tags?: readonly AsyncAPITag[];
+}
+/**
+ * Server configuration (message broker).
+ */
+interface AsyncAPIServer {
+    readonly host: string;
+    readonly protocol: string;
+    readonly protocolVersion?: string;
+    readonly pathname?: string;
+    readonly description?: string;
+    readonly tags?: readonly AsyncAPITag[];
+}
+/**
+ * Tag definition.
+ */
+interface AsyncAPITag {
+    readonly name: string;
+    readonly description?: string;
+    readonly externalDocs?: AsyncAPIExternalDocs;
+}
+/**
+ * External documentation.
+ */
+interface AsyncAPIExternalDocs {
+    readonly url: string;
+    readonly description?: string;
+}
+/**
+ * Complete AsyncAPI 3.0 specification.
+ */
+interface AsyncAPISpec {
+    readonly asyncapi: string;
+    readonly info: AsyncAPIInfo;
+    readonly servers?: Record<string, AsyncAPIServer>;
+    readonly defaultContentType?: string;
+    readonly channels?: Record<string, AsyncAPIChannel>;
+    readonly operations?: Record<string, AsyncAPIOperation>;
+    readonly components?: AsyncAPIComponents;
+    readonly externalDocs?: AsyncAPIExternalDocs;
+}
+/**
+ * Channel definition (represents an event type).
+ */
+interface AsyncAPIChannel {
+    readonly address?: string;
+    readonly messages?: Record<string, AsyncAPIMessage>;
+    readonly description?: string;
+    readonly tags?: readonly AsyncAPITag[];
+}
+/**
+ * Message definition (event payload).
+ */
+interface AsyncAPIMessage {
+    readonly name?: string;
+    readonly title?: string;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly contentType?: string;
+    readonly payload?: JsonSchema;
+    readonly tags?: readonly AsyncAPITag[];
+    readonly deprecated?: boolean;
+}
+/**
+ * Operation definition (subscribe action).
+ */
+interface AsyncAPIOperation {
+    readonly action: 'send' | 'receive';
+    readonly channel: {
+        readonly $ref: string;
+    };
+    readonly summary?: string;
+    readonly description?: string;
+    readonly tags?: readonly AsyncAPITag[];
+    readonly deprecated?: boolean;
+    readonly messages?: readonly {
+        readonly $ref: string;
+    }[];
+}
+/**
+ * Components object for reusable definitions.
+ */
+interface AsyncAPIComponents {
+    readonly schemas?: Record<string, JsonSchema>;
+    readonly messages?: Record<string, AsyncAPIMessage>;
+    readonly channels?: Record<string, AsyncAPIChannel>;
+}
+
+/**
+ * @fileoverview AsyncAPI specification generation from event router definitions.
+ *
+ * The `generateAsyncAPI` function creates a complete AsyncAPI 3.0 specification
+ * from an event router definition. All handler payload schemas are converted to
+ * JSON Schema and included in the specification.
+ *
+ * @module events/asyncapi/generate
+ */
+
+/**
+ * Generates an AsyncAPI 3.0 specification from an event router definition.
+ *
+ * This function walks the event router structure, extracts JSON schemas from
+ * all handler payload definitions, and builds a complete AsyncAPI 3.0 specification.
+ *
+ * @param router - Event router definition or raw config
+ * @param config - AsyncAPI configuration (info, servers, tags, etc.)
+ * @returns Complete AsyncAPI specification
+ *
+ * @example
+ * ```typescript
+ * import { generateAsyncAPI } from '@cosmneo/onion-lasagna/events/asyncapi';
+ * import { notificationEventRouter } from './events/router';
+ *
+ * const spec = generateAsyncAPI(notificationEventRouter, {
+ *   info: {
+ *     title: 'My Event API',
+ *     version: '1.0.0',
+ *     description: 'Domain events for the application',
+ *   },
+ * });
+ *
+ * app.get('/asyncapi.json', (c) => c.json(spec));
+ * ```
+ */
+declare function generateAsyncAPI<T extends EventRouterConfig>(router: T | EventRouterDefinition<T>, config: AsyncAPIConfig): AsyncAPISpec;
+
+export { type AsyncAPIChannel, type AsyncAPIComponents, type AsyncAPIConfig, type AsyncAPIExternalDocs, type AsyncAPIInfo, type AsyncAPIMessage, type AsyncAPIOperation, type AsyncAPIServer, type AsyncAPISpec, type AsyncAPITag, generateAsyncAPI };

package/dist/events/asyncapi/index.js

@@ -0,0 +1,8 @@
+import {
+  generateAsyncAPI
+} from "../../chunk-KJ4JGZOE.js";
+import "../../chunk-CBTICRSM.js";
+export {
+  generateAsyncAPI
+};
+//# sourceMappingURL=index.js.map

package/dist/events/asyncapi/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/events/handler/index.cjs

@@ -0,0 +1,171 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/presentation/events/handler/index.ts
+var handler_exports = {};
+__export(handler_exports, {
+  collectEventHandlers: () => collectEventHandlers,
+  defineEventHandler: () => defineEventHandler,
+  defineEventRouter: () => defineEventRouter,
+  generateHandlerId: () => generateHandlerId,
+  isEventHandlerDefinition: () => isEventHandlerDefinition,
+  isEventRouterDefinition: () => isEventRouterDefinition,
+  mergeEventRouters: () => mergeEventRouters
+});
+module.exports = __toCommonJS(handler_exports);
+
+// src/presentation/events/handler/define-event-handler.ts
+function defineEventHandler(input) {
+  const definition = {
+    eventType: input.eventType,
+    payload: input.payload ?? void 0,
+    context: input.context ?? void 0,
+    docs: {
+      summary: input.docs?.summary,
+      description: input.docs?.description,
+      tags: input.docs?.tags,
+      deprecated: input.docs?.deprecated ?? false
+    },
+    _types: void 0
+  };
+  return Object.freeze(definition);
+}
+
+// src/presentation/events/handler/types/event-router-definition.type.ts
+function isEventHandlerDefinition(value) {
+  return typeof value === "object" && value !== null && "eventType" in value && "_types" in value;
+}
+function isEventRouterDefinition(value) {
+  return typeof value === "object" && value !== null && "_isEventRouter" in value && value._isEventRouter === true;
+}
+function collectEventHandlers(config, basePath = "") {
+  const handlers = [];
+  for (const [key, value] of Object.entries(config)) {
+    const fullKey = basePath ? `${basePath}.${key}` : key;
+    if (isEventHandlerDefinition(value)) {
+      handlers.push({ key: fullKey, handler: value });
+    } else if (isEventRouterDefinition(value)) {
+      handlers.push(...collectEventHandlers(value.handlers, fullKey));
+    } else if (typeof value === "object" && value !== null) {
+      handlers.push(...collectEventHandlers(value, fullKey));
+    }
+  }
+  return handlers;
+}
+
+// src/presentation/events/handler/define-event-router.ts
+function defineEventRouter(handlers, options) {
+  const defaults = options?.defaults;
+  const processedHandlers = defaults?.context || defaults?.tags ? applyEventRouterDefaults(handlers, defaults) : handlers;
+  const definition = {
+    handlers: processedHandlers,
+    defaults,
+    _isEventRouter: true
+  };
+  return deepFreeze(definition);
+}
+function applyEventRouterDefaults(handlers, defaults) {
+  const result = {};
+  for (const [key, value] of Object.entries(handlers)) {
+    if (isEventHandlerDefinition(value)) {
+      result[key] = applyDefaultsToEventHandler(value, defaults);
+    } else if (isEventRouterDefinition(value)) {
+      result[key] = {
+        ...value,
+        handlers: applyEventRouterDefaults(value.handlers, defaults)
+      };
+    } else if (typeof value === "object" && value !== null) {
+      result[key] = applyEventRouterDefaults(value, defaults);
+    }
+  }
+  return result;
+}
+function applyDefaultsToEventHandler(handler, defaults) {
+  const needsContext = defaults.context && !handler.context;
+  const needsTags = defaults.tags && defaults.tags.length > 0;
+  if (!needsContext && !needsTags) return handler;
+  return Object.freeze({
+    ...handler,
+    context: handler.context ?? defaults.context ?? void 0,
+    docs: {
+      ...handler.docs,
+      tags: mergeTags(defaults.tags, handler.docs.tags)
+    }
+  });
+}
+function mergeTags(routerTags, handlerTags) {
+  if (!routerTags || routerTags.length === 0) return handlerTags;
+  if (!handlerTags || handlerTags.length === 0) return routerTags;
+  const merged = [...routerTags];
+  for (const tag of handlerTags) {
+    if (!merged.includes(tag)) {
+      merged.push(tag);
+    }
+  }
+  return merged;
+}
+function deepFreeze(obj) {
+  const propNames = Object.getOwnPropertyNames(obj);
+  for (const name of propNames) {
+    const value = obj[name];
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+      deepFreeze(value);
+    }
+  }
+  return Object.freeze(obj);
+}
+function extractHandlers(input) {
+  return isEventRouterDefinition(input) ? input.handlers : input;
+}
+function isSubRouter(value) {
+  return typeof value === "object" && value !== null && !isEventHandlerDefinition(value) && !isEventRouterDefinition(value);
+}
+function deepMergeConfigs(a, b) {
+  const result = { ...a };
+  for (const key of Object.keys(b)) {
+    const aVal = result[key];
+    const bVal = b[key];
+    if (isSubRouter(aVal) && isSubRouter(bVal)) {
+      result[key] = deepMergeConfigs(aVal, bVal);
+    } else {
+      result[key] = bVal;
+    }
+  }
+  return result;
+}
+function mergeEventRouters(...routers) {
+  const merged = routers.map(extractHandlers).reduce(deepMergeConfigs);
+  return defineEventRouter(merged);
+}
+
+// src/presentation/events/handler/utils.ts
+function generateHandlerId(key) {
+  return key.replace(/\.(\w)/g, (_, char) => char.toUpperCase());
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  collectEventHandlers,
+  defineEventHandler,
+  defineEventRouter,
+  generateHandlerId,
+  isEventHandlerDefinition,
+  isEventRouterDefinition,
+  mergeEventRouters
+});
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/presentation/events/handler/index.ts","../../../src/presentation/events/handler/define-event-handler.ts","../../../src/presentation/events/handler/types/event-router-definition.type.ts","../../../src/presentation/events/handler/define-event-router.ts","../../../src/presentation/events/handler/utils.ts"],"sourcesContent":["export { defineEventHandler } from './define-event-handler';\nexport { defineEventRouter, mergeEventRouters } from './define-event-router';\nexport type { DefineEventRouterOptions } from './define-event-router';\nexport { generateHandlerId } from './utils';\nexport * from './types';\n","/**\n * @fileoverview Factory function for creating event handler definitions.\n *\n * The `defineEventHandler` function is the main entry point for defining\n * event handlers. It mirrors `defineRoute` from the HTTP layer but is\n * tailored for asynchronous event processing.\n *\n * @module events/handler/define-event-handler\n */\n\nimport type { SchemaAdapter, InferOutput } from '../../http/schema/types';\nimport type { EventHandlerDefinition } from './types';\n\n// ============================================================================\n// Input Types\n// ============================================================================\n\n/**\n * Input for defineEventHandler.\n *\n * @example Basic handler with payload schema\n * ```typescript\n * defineEventHandler({\n *   eventType: 'ticket.created',\n *   payload: zodSchema(z.object({ ticketId: z.string() })),\n *   docs: { summary: 'Handle ticket creation', tags: ['ticket'] },\n * })\n * ```\n *\n * @example With context schema\n * ```typescript\n * defineEventHandler({\n *   eventType: 'order.shipped',\n *   payload: zodSchema(orderShippedSchema),\n *   context: zodSchema(eventMetadataSchema),\n * })\n * ```\n */\ninterface DefineEventHandlerInput<\n  TEventType extends string,\n  TPayload extends SchemaAdapter | undefined = undefined,\n  TContext extends SchemaAdapter | undefined = undefined,\n> {\n  /** Event type string used for routing (e.g., 'ticket.created'). */\n  readonly eventType: TEventType;\n\n  /** Payload validation schema. */\n  readonly payload?: TPayload;\n\n  /** Context validation schema (validates event metadata). */\n  readonly context?: TContext;\n\n  /** Handler documentation. */\n  readonly docs?: {\n    readonly summary?: string;\n    readonly description?: string;\n    readonly tags?: readonly string[];\n    readonly deprecated?: boolean;\n  };\n}\n\n// ============================================================================\n// Return type helpers\n// ============================================================================\n\ntype ResolvePayload<T> = T extends SchemaAdapter ? InferOutput<T> : undefined;\ntype ResolveContext<T> = T extends SchemaAdapter ? InferOutput<T> : undefined;\n\n// ============================================================================\n// Factory Function\n// ============================================================================\n\n/**\n * Creates an event handler definition from the provided configuration.\n *\n * This is the main entry point for defining event handlers. The resulting\n * definition can be used for type-safe handler registration, payload\n * validation, and documentation generation.\n *\n * @param input - Event handler configuration with optional schemas\n * @returns A frozen EventHandlerDefinition object with full type information\n */\nexport function defineEventHandler<\n  TEventType extends string,\n  TPayload extends SchemaAdapter | undefined = undefined,\n  TContext extends SchemaAdapter | undefined = undefined,\n>(\n  input: DefineEventHandlerInput<TEventType, TPayload, TContext>,\n): EventHandlerDefinition<TEventType, ResolvePayload<TPayload>, ResolveContext<TContext>> {\n  const definition = {\n    eventType: input.eventType,\n    payload: input.payload ?? undefined,\n    context: input.context ?? undefined,\n    docs: {\n      summary: input.docs?.summary,\n      description: input.docs?.description,\n      tags: input.docs?.tags,\n      deprecated: input.docs?.deprecated ?? false,\n    },\n    _types: undefined as unknown,\n  };\n\n  return Object.freeze(definition) as EventHandlerDefinition<\n    TEventType,\n    ResolvePayload<TPayload>,\n    ResolveContext<TContext>\n  >;\n}\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 Factory function for creating event router definitions.\n *\n * The `defineEventRouter` function groups event handlers into a hierarchical\n * structure with optional router-level defaults for context and tags.\n *\n * @module events/handler/define-event-router\n */\n\nimport type {\n  EventRouterConfig,\n  EventRouterDefaults,\n  EventRouterDefinition,\n  EventHandlerDefinition,\n  DeepMergeTwo,\n  DeepMergeAll,\n} from './types';\nimport { isEventHandlerDefinition, isEventRouterDefinition } from './types';\n\n/**\n * Options for event router definition.\n */\nexport interface DefineEventRouterOptions {\n  /**\n   * Default values applied to all child handlers.\n   *\n   * @example\n   * ```typescript\n   * defineEventRouter({\n   *   created: onTicketCreated,\n   *   assigned: onTicketAssigned,\n   * }, {\n   *   defaults: {\n   *     context: zodSchema(eventMetadataSchema),\n   *     tags: ['ticket'],\n   *   },\n   * })\n   * ```\n   */\n  readonly defaults?: EventRouterDefaults;\n}\n\n/**\n * Creates an event router definition from a configuration object.\n *\n * @param handlers - Object containing event handlers and nested routers\n * @param options - Optional router configuration\n * @returns A frozen EventRouterDefinition object\n *\n * @example Basic router\n * ```typescript\n * const ticketEvents = defineEventRouter({\n *   created: onTicketCreated,\n *   assigned: onTicketAssigned,\n *   transferred: onTicketTransferred,\n * });\n * ```\n *\n * @example Nested router\n * ```typescript\n * const events = defineEventRouter({\n *   ticket: {\n *     created: onTicketCreated,\n *     assigned: onTicketAssigned,\n *   },\n *   ecosystem: {\n *     memberAdded: onMemberAdded,\n *   },\n * });\n * ```\n */\nexport function defineEventRouter<T extends EventRouterConfig>(\n  handlers: T,\n  options?: DefineEventRouterOptions,\n): EventRouterDefinition<T> {\n  const defaults = options?.defaults;\n\n  const processedHandlers =\n    defaults?.context || defaults?.tags\n      ? (applyEventRouterDefaults(handlers, defaults) as T)\n      : handlers;\n\n  const definition: EventRouterDefinition<T> = {\n    handlers: processedHandlers,\n    defaults,\n    _isEventRouter: true,\n  };\n\n  return deepFreeze(definition);\n}\n\n/**\n * Recursively applies router-level defaults to all handlers in the tree.\n */\nfunction applyEventRouterDefaults(\n  handlers: EventRouterConfig,\n  defaults: EventRouterDefaults,\n): EventRouterConfig {\n  const result: Record<string, unknown> = {};\n\n  for (const [key, value] of Object.entries(handlers)) {\n    if (isEventHandlerDefinition(value)) {\n      result[key] = applyDefaultsToEventHandler(value, defaults);\n    } else if (isEventRouterDefinition(value)) {\n      result[key] = {\n        ...value,\n        handlers: applyEventRouterDefaults(value.handlers, defaults),\n      };\n    } else if (typeof value === 'object' && value !== null) {\n      result[key] = applyEventRouterDefaults(value as EventRouterConfig, defaults);\n    }\n  }\n\n  return result as EventRouterConfig;\n}\n\n/**\n * Applies router-level defaults to a single event handler definition.\n */\nfunction applyDefaultsToEventHandler(\n  handler: EventHandlerDefinition,\n  defaults: EventRouterDefaults,\n): EventHandlerDefinition {\n  const needsContext = defaults.context && !handler.context;\n  const needsTags = defaults.tags && defaults.tags.length > 0;\n\n  if (!needsContext && !needsTags) return handler;\n\n  return Object.freeze({\n    ...handler,\n    context: handler.context ?? defaults.context ?? undefined,\n    docs: {\n      ...handler.docs,\n      tags: mergeTags(defaults.tags, handler.docs.tags),\n    },\n  }) as EventHandlerDefinition;\n}\n\n/**\n * Merges router-level tags with handler-level tags, avoiding duplicates.\n */\nfunction mergeTags(\n  routerTags?: readonly string[],\n  handlerTags?: readonly string[],\n): readonly string[] | undefined {\n  if (!routerTags || routerTags.length === 0) return handlerTags;\n  if (!handlerTags || handlerTags.length === 0) return routerTags;\n\n  const merged = [...routerTags];\n  for (const tag of handlerTags) {\n    if (!merged.includes(tag)) {\n      merged.push(tag);\n    }\n  }\n  return merged;\n}\n\n/**\n * Deep freezes an object and all its nested objects.\n */\nfunction deepFreeze<T extends object>(obj: T): T {\n  const propNames = Object.getOwnPropertyNames(obj) as (keyof T)[];\n\n  for (const name of propNames) {\n    const value = obj[name];\n    if (value && typeof value === 'object' && !Object.isFrozen(value)) {\n      deepFreeze(value);\n    }\n  }\n\n  return Object.freeze(obj);\n}\n\n// ============================================================================\n// mergeEventRouters — variadic deep merge\n// ============================================================================\n\ntype EventRouterInput<T extends EventRouterConfig> = T | EventRouterDefinition<T>;\n\n/** Extracts the raw EventRouterConfig from either a plain config or an EventRouterDefinition. */\nfunction extractHandlers<T extends EventRouterConfig>(input: EventRouterInput<T>): T {\n  return isEventRouterDefinition(input) ? input.handlers : input;\n}\n\n/** Returns true if `value` is a plain sub-router object. */\nfunction isSubRouter(value: unknown): value is EventRouterConfig {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    !isEventHandlerDefinition(value) &&\n    !isEventRouterDefinition(value)\n  );\n}\n\n/** Recursively deep-merges two router configs. Sub-routers are merged; leaves are overwritten. */\nfunction deepMergeConfigs(a: EventRouterConfig, b: EventRouterConfig): EventRouterConfig {\n  const result: Record<string, unknown> = { ...a };\n\n  for (const key of Object.keys(b)) {\n    const aVal = result[key];\n    const bVal = b[key];\n\n    if (isSubRouter(aVal) && isSubRouter(bVal)) {\n      result[key] = deepMergeConfigs(aVal, bVal);\n    } else {\n      result[key] = bVal;\n    }\n  }\n\n  return result as EventRouterConfig;\n}\n\n// Overloads for 2–8 routers\nexport function mergeEventRouters<T1 extends EventRouterConfig, T2 extends EventRouterConfig>(\n  r1: EventRouterInput<T1>,\n  r2: EventRouterInput<T2>,\n): EventRouterDefinition<DeepMergeTwo<T1, T2>>;\nexport function mergeEventRouters<\n  T1 extends EventRouterConfig,\n  T2 extends EventRouterConfig,\n  T3 extends EventRouterConfig,\n>(\n  r1: EventRouterInput<T1>,\n  r2: EventRouterInput<T2>,\n  r3: EventRouterInput<T3>,\n): EventRouterDefinition<DeepMergeAll<[T1, T2, T3]>>;\nexport function mergeEventRouters<\n  T1 extends EventRouterConfig,\n  T2 extends EventRouterConfig,\n  T3 extends EventRouterConfig,\n  T4 extends EventRouterConfig,\n>(\n  r1: EventRouterInput<T1>,\n  r2: EventRouterInput<T2>,\n  r3: EventRouterInput<T3>,\n  r4: EventRouterInput<T4>,\n): EventRouterDefinition<DeepMergeAll<[T1, T2, T3, T4]>>;\nexport function mergeEventRouters<\n  T1 extends EventRouterConfig,\n  T2 extends EventRouterConfig,\n  T3 extends EventRouterConfig,\n  T4 extends EventRouterConfig,\n  T5 extends EventRouterConfig,\n>(\n  r1: EventRouterInput<T1>,\n  r2: EventRouterInput<T2>,\n  r3: EventRouterInput<T3>,\n  r4: EventRouterInput<T4>,\n  r5: EventRouterInput<T5>,\n): EventRouterDefinition<DeepMergeAll<[T1, T2, T3, T4, T5]>>;\nexport function mergeEventRouters<\n  T1 extends EventRouterConfig,\n  T2 extends EventRouterConfig,\n  T3 extends EventRouterConfig,\n  T4 extends EventRouterConfig,\n  T5 extends EventRouterConfig,\n  T6 extends EventRouterConfig,\n>(\n  r1: EventRouterInput<T1>,\n  r2: EventRouterInput<T2>,\n  r3: EventRouterInput<T3>,\n  r4: EventRouterInput<T4>,\n  r5: EventRouterInput<T5>,\n  r6: EventRouterInput<T6>,\n): EventRouterDefinition<DeepMergeAll<[T1, T2, T3, T4, T5, T6]>>;\nexport function mergeEventRouters<\n  T1 extends EventRouterConfig,\n  T2 extends EventRouterConfig,\n  T3 extends EventRouterConfig,\n  T4 extends EventRouterConfig,\n  T5 extends EventRouterConfig,\n  T6 extends EventRouterConfig,\n  T7 extends EventRouterConfig,\n>(\n  r1: EventRouterInput<T1>,\n  r2: EventRouterInput<T2>,\n  r3: EventRouterInput<T3>,\n  r4: EventRouterInput<T4>,\n  r5: EventRouterInput<T5>,\n  r6: EventRouterInput<T6>,\n  r7: EventRouterInput<T7>,\n): EventRouterDefinition<DeepMergeAll<[T1, T2, T3, T4, T5, T6, T7]>>;\nexport function mergeEventRouters<\n  T1 extends EventRouterConfig,\n  T2 extends EventRouterConfig,\n  T3 extends EventRouterConfig,\n  T4 extends EventRouterConfig,\n  T5 extends EventRouterConfig,\n  T6 extends EventRouterConfig,\n  T7 extends EventRouterConfig,\n  T8 extends EventRouterConfig,\n>(\n  r1: EventRouterInput<T1>,\n  r2: EventRouterInput<T2>,\n  r3: EventRouterInput<T3>,\n  r4: EventRouterInput<T4>,\n  r5: EventRouterInput<T5>,\n  r6: EventRouterInput<T6>,\n  r7: EventRouterInput<T7>,\n  r8: EventRouterInput<T8>,\n): EventRouterDefinition<DeepMergeAll<[T1, T2, T3, T4, T5, T6, T7, T8]>>;\n\n// Variadic fallback for 9+\nexport function mergeEventRouters(\n  ...routers: EventRouterInput<EventRouterConfig>[]\n): EventRouterDefinition<EventRouterConfig>;\n\n// Implementation\nexport function mergeEventRouters(\n  ...routers: EventRouterInput<EventRouterConfig>[]\n): EventRouterDefinition<EventRouterConfig> {\n  const merged = routers.map(extractHandlers).reduce(deepMergeConfigs);\n  return defineEventRouter(merged);\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"],"mappings":"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","names":[]}

package/dist/events/handler/index.d.cts

@@ -0,0 +1,153 @@
+import { SchemaAdapter, InferOutput } from '../../http/schema/types.cjs';
+import { E as EventHandlerDefinition, c as EventRouterConfig, d as EventRouterDefaults, e as EventRouterDefinition, D as DeepMergeTwo, l as DeepMergeAll } from '../../event-router-definition.type-CP9uTlux.cjs';
+export { a as EventHandlerDocumentation, b as EventRouterEntry, f as EventRouterKeys, F as FlattenEventRouter, G as GetEventHandler, h as InferEventContext, g as InferEventPayload, I as InferEventType, k as collectEventHandlers, i as isEventHandlerDefinition, j as isEventRouterDefinition } from '../../event-router-definition.type-CP9uTlux.cjs';
+
+/**
+ * @fileoverview Factory function for creating event handler definitions.
+ *
+ * The `defineEventHandler` function is the main entry point for defining
+ * event handlers. It mirrors `defineRoute` from the HTTP layer but is
+ * tailored for asynchronous event processing.
+ *
+ * @module events/handler/define-event-handler
+ */
+
+/**
+ * Input for defineEventHandler.
+ *
+ * @example Basic handler with payload schema
+ * ```typescript
+ * defineEventHandler({
+ *   eventType: 'ticket.created',
+ *   payload: zodSchema(z.object({ ticketId: z.string() })),
+ *   docs: { summary: 'Handle ticket creation', tags: ['ticket'] },
+ * })
+ * ```
+ *
+ * @example With context schema
+ * ```typescript
+ * defineEventHandler({
+ *   eventType: 'order.shipped',
+ *   payload: zodSchema(orderShippedSchema),
+ *   context: zodSchema(eventMetadataSchema),
+ * })
+ * ```
+ */
+interface DefineEventHandlerInput<TEventType extends string, TPayload extends SchemaAdapter | undefined = undefined, TContext extends SchemaAdapter | undefined = undefined> {
+    /** Event type string used for routing (e.g., 'ticket.created'). */
+    readonly eventType: TEventType;
+    /** Payload validation schema. */
+    readonly payload?: TPayload;
+    /** Context validation schema (validates event metadata). */
+    readonly context?: TContext;
+    /** Handler documentation. */
+    readonly docs?: {
+        readonly summary?: string;
+        readonly description?: string;
+        readonly tags?: readonly string[];
+        readonly deprecated?: boolean;
+    };
+}
+type ResolvePayload<T> = T extends SchemaAdapter ? InferOutput<T> : undefined;
+type ResolveContext<T> = T extends SchemaAdapter ? InferOutput<T> : undefined;
+/**
+ * Creates an event handler definition from the provided configuration.
+ *
+ * This is the main entry point for defining event handlers. The resulting
+ * definition can be used for type-safe handler registration, payload
+ * validation, and documentation generation.
+ *
+ * @param input - Event handler configuration with optional schemas
+ * @returns A frozen EventHandlerDefinition object with full type information
+ */
+declare function defineEventHandler<TEventType extends string, TPayload extends SchemaAdapter | undefined = undefined, TContext extends SchemaAdapter | undefined = undefined>(input: DefineEventHandlerInput<TEventType, TPayload, TContext>): EventHandlerDefinition<TEventType, ResolvePayload<TPayload>, ResolveContext<TContext>>;
+
+/**
+ * @fileoverview Factory function for creating event router definitions.
+ *
+ * The `defineEventRouter` function groups event handlers into a hierarchical
+ * structure with optional router-level defaults for context and tags.
+ *
+ * @module events/handler/define-event-router
+ */
+
+/**
+ * Options for event router definition.
+ */
+interface DefineEventRouterOptions {
+    /**
+     * Default values applied to all child handlers.
+     *
+     * @example
+     * ```typescript
+     * defineEventRouter({
+     *   created: onTicketCreated,
+     *   assigned: onTicketAssigned,
+     * }, {
+     *   defaults: {
+     *     context: zodSchema(eventMetadataSchema),
+     *     tags: ['ticket'],
+     *   },
+     * })
+     * ```
+     */
+    readonly defaults?: EventRouterDefaults;
+}
+/**
+ * Creates an event router definition from a configuration object.
+ *
+ * @param handlers - Object containing event handlers and nested routers
+ * @param options - Optional router configuration
+ * @returns A frozen EventRouterDefinition object
+ *
+ * @example Basic router
+ * ```typescript
+ * const ticketEvents = defineEventRouter({
+ *   created: onTicketCreated,
+ *   assigned: onTicketAssigned,
+ *   transferred: onTicketTransferred,
+ * });
+ * ```
+ *
+ * @example Nested router
+ * ```typescript
+ * const events = defineEventRouter({
+ *   ticket: {
+ *     created: onTicketCreated,
+ *     assigned: onTicketAssigned,
+ *   },
+ *   ecosystem: {
+ *     memberAdded: onMemberAdded,
+ *   },
+ * });
+ * ```
+ */
+declare function defineEventRouter<T extends EventRouterConfig>(handlers: T, options?: DefineEventRouterOptions): EventRouterDefinition<T>;
+type EventRouterInput<T extends EventRouterConfig> = T | EventRouterDefinition<T>;
+declare function mergeEventRouters<T1 extends EventRouterConfig, T2 extends EventRouterConfig>(r1: EventRouterInput<T1>, r2: EventRouterInput<T2>): EventRouterDefinition<DeepMergeTwo<T1, T2>>;
+declare function mergeEventRouters<T1 extends EventRouterConfig, T2 extends EventRouterConfig, T3 extends EventRouterConfig>(r1: EventRouterInput<T1>, r2: EventRouterInput<T2>, r3: EventRouterInput<T3>): EventRouterDefinition<DeepMergeAll<[T1, T2, T3]>>;
+declare function mergeEventRouters<T1 extends EventRouterConfig, T2 extends EventRouterConfig, T3 extends EventRouterConfig, T4 extends EventRouterConfig>(r1: EventRouterInput<T1>, r2: EventRouterInput<T2>, r3: EventRouterInput<T3>, r4: EventRouterInput<T4>): EventRouterDefinition<DeepMergeAll<[T1, T2, T3, T4]>>;
+declare function mergeEventRouters<T1 extends EventRouterConfig, T2 extends EventRouterConfig, T3 extends EventRouterConfig, T4 extends EventRouterConfig, T5 extends EventRouterConfig>(r1: EventRouterInput<T1>, r2: EventRouterInput<T2>, r3: EventRouterInput<T3>, r4: EventRouterInput<T4>, r5: EventRouterInput<T5>): EventRouterDefinition<DeepMergeAll<[T1, T2, T3, T4, T5]>>;
+declare function mergeEventRouters<T1 extends EventRouterConfig, T2 extends EventRouterConfig, T3 extends EventRouterConfig, T4 extends EventRouterConfig, T5 extends EventRouterConfig, T6 extends EventRouterConfig>(r1: EventRouterInput<T1>, r2: EventRouterInput<T2>, r3: EventRouterInput<T3>, r4: EventRouterInput<T4>, r5: EventRouterInput<T5>, r6: EventRouterInput<T6>): EventRouterDefinition<DeepMergeAll<[T1, T2, T3, T4, T5, T6]>>;
+declare function mergeEventRouters<T1 extends EventRouterConfig, T2 extends EventRouterConfig, T3 extends EventRouterConfig, T4 extends EventRouterConfig, T5 extends EventRouterConfig, T6 extends EventRouterConfig, T7 extends EventRouterConfig>(r1: EventRouterInput<T1>, r2: EventRouterInput<T2>, r3: EventRouterInput<T3>, r4: EventRouterInput<T4>, r5: EventRouterInput<T5>, r6: EventRouterInput<T6>, r7: EventRouterInput<T7>): EventRouterDefinition<DeepMergeAll<[T1, T2, T3, T4, T5, T6, T7]>>;
+declare function mergeEventRouters<T1 extends EventRouterConfig, T2 extends EventRouterConfig, T3 extends EventRouterConfig, T4 extends EventRouterConfig, T5 extends EventRouterConfig, T6 extends EventRouterConfig, T7 extends EventRouterConfig, T8 extends EventRouterConfig>(r1: EventRouterInput<T1>, r2: EventRouterInput<T2>, r3: EventRouterInput<T3>, r4: EventRouterInput<T4>, r5: EventRouterInput<T5>, r6: EventRouterInput<T6>, r7: EventRouterInput<T7>, r8: EventRouterInput<T8>): EventRouterDefinition<DeepMergeAll<[T1, T2, T3, T4, T5, T6, T7, T8]>>;
+declare function mergeEventRouters(...routers: EventRouterInput<EventRouterConfig>[]): EventRouterDefinition<EventRouterConfig>;
+
+/**
+ * @fileoverview Utility functions for event handler routing.
+ *
+ * @module events/handler/utils
+ */
+/**
+ * Generates a handler ID from a dotted key path.
+ *
+ * Converts dot-separated keys to camelCase:
+ * - `"ticket.created"` → `"ticketCreated"`
+ * - `"ecosystem.member.added"` → `"ecosystemMemberAdded"`
+ *
+ * @param key - The dotted key path
+ * @returns A camelCase handler ID
+ */
+declare function generateHandlerId(key: string): string;
+
+export { DeepMergeAll, DeepMergeTwo, type DefineEventRouterOptions, EventHandlerDefinition, EventRouterConfig, EventRouterDefaults, EventRouterDefinition, defineEventHandler, defineEventRouter, generateHandlerId, mergeEventRouters };