@cosmneo/onion-lasagna 0.2.1 → 0.3.0

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

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

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

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

package/dist/events/asyncapi/index.cjs

@@ -0,0 +1,143 @@
+"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/asyncapi/index.ts
+var asyncapi_exports = {};
+__export(asyncapi_exports, {
+  generateAsyncAPI: () => generateAsyncAPI
+});
+module.exports = __toCommonJS(asyncapi_exports);
+
+// 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/utils.ts
+function generateHandlerId(key) {
+  return key.replace(/\.(\w)/g, (_, char) => char.toUpperCase());
+}
+
+// src/presentation/events/asyncapi/generate.ts
+function generateAsyncAPI(router, config) {
+  const routerConfig = isEventRouterDefinition(router) ? router.handlers : router;
+  const handlers = collectEventHandlers(routerConfig);
+  const channels = {};
+  const operations = {};
+  const allTags = /* @__PURE__ */ new Set();
+  for (const { key, handler } of handlers) {
+    const handlerId = generateHandlerId(key);
+    const channelId = handler.eventType;
+    const message = buildMessage(handler.eventType, handler.payload, handler.docs);
+    if (!channels[channelId]) {
+      channels[channelId] = {
+        address: handler.eventType,
+        messages: {}
+      };
+    }
+    const channelMessages = { ...channels[channelId].messages ?? {} };
+    channelMessages[handlerId] = message;
+    channels[channelId] = { ...channels[channelId], messages: channelMessages };
+    const operation = {
+      action: "receive",
+      channel: { $ref: `#/channels/${channelId}` },
+      messages: [{ $ref: `#/channels/${channelId}/messages/${handlerId}` }]
+    };
+    if (handler.docs.summary) {
+      operation.summary = handler.docs.summary;
+    }
+    if (handler.docs.description) {
+      operation.description = handler.docs.description;
+    }
+    if (handler.docs.deprecated) {
+      operation.deprecated = true;
+    }
+    if (handler.docs.tags && handler.docs.tags.length > 0) {
+      operation.tags = handler.docs.tags.map((t) => ({
+        name: t
+      }));
+      for (const tag of handler.docs.tags) {
+        allTags.add(tag);
+      }
+    }
+    operations[handlerId] = operation;
+  }
+  const tags = config.tags ? [...config.tags] : [];
+  for (const tagName of allTags) {
+    if (!tags.some((t) => t.name === tagName)) {
+      tags.push({ name: tagName });
+    }
+  }
+  const info = tags.length > 0 ? { ...config.info, tags } : config.info;
+  const spec = {
+    asyncapi: config.asyncapi ?? "3.0.0",
+    info,
+    defaultContentType: config.defaultContentType ?? "application/json",
+    channels,
+    operations
+  };
+  if (config.servers && Object.keys(config.servers).length > 0) {
+    spec.servers = config.servers;
+  }
+  if (config.externalDocs) {
+    spec.externalDocs = config.externalDocs;
+  }
+  return spec;
+}
+function buildMessage(eventType, payload, docs) {
+  const message = {
+    name: eventType
+  };
+  if (docs.summary) {
+    message.summary = docs.summary;
+  }
+  if (docs.description) {
+    message.description = docs.description;
+  }
+  if (docs.deprecated) {
+    message.deprecated = true;
+  }
+  if (payload) {
+    const schema = payload.toJsonSchema();
+    message.payload = schema;
+  }
+  return message;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  generateAsyncAPI
+});
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/presentation/events/asyncapi/index.ts","../../../src/presentation/events/handler/types/event-router-definition.type.ts","../../../src/presentation/events/handler/utils.ts","../../../src/presentation/events/asyncapi/generate.ts"],"sourcesContent":["export { generateAsyncAPI } from './generate';\nexport type {\n  AsyncAPIConfig,\n  AsyncAPIInfo,\n  AsyncAPIServer,\n  AsyncAPITag,\n  AsyncAPIExternalDocs,\n  AsyncAPISpec,\n  AsyncAPIChannel,\n  AsyncAPIMessage,\n  AsyncAPIOperation,\n  AsyncAPIComponents,\n} 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 AsyncAPI specification generation from event router definitions.\n *\n * The `generateAsyncAPI` function creates a complete AsyncAPI 3.0 specification\n * from an event router definition. All handler payload schemas are converted to\n * JSON Schema and included in the specification.\n *\n * @module events/asyncapi/generate\n */\n\nimport type { SchemaAdapter } from '../../http/schema/types';\nimport type { EventRouterConfig, EventRouterDefinition } from '../handler/types';\nimport { isEventRouterDefinition, collectEventHandlers } from '../handler/types';\nimport { generateHandlerId } from '../handler/utils';\nimport type {\n  AsyncAPIConfig,\n  AsyncAPISpec,\n  AsyncAPIChannel,\n  AsyncAPIOperation,\n  AsyncAPIMessage,\n  AsyncAPITag,\n} from './types';\n\n/**\n * Generates an AsyncAPI 3.0 specification from an event router definition.\n *\n * This function walks the event router structure, extracts JSON schemas from\n * all handler payload definitions, and builds a complete AsyncAPI 3.0 specification.\n *\n * @param router - Event router definition or raw config\n * @param config - AsyncAPI configuration (info, servers, tags, etc.)\n * @returns Complete AsyncAPI specification\n *\n * @example\n * ```typescript\n * import { generateAsyncAPI } from '@cosmneo/onion-lasagna/events/asyncapi';\n * import { notificationEventRouter } from './events/router';\n *\n * const spec = generateAsyncAPI(notificationEventRouter, {\n *   info: {\n *     title: 'My Event API',\n *     version: '1.0.0',\n *     description: 'Domain events for the application',\n *   },\n * });\n *\n * app.get('/asyncapi.json', (c) => c.json(spec));\n * ```\n */\nexport function generateAsyncAPI<T extends EventRouterConfig>(\n  router: T | EventRouterDefinition<T>,\n  config: AsyncAPIConfig,\n): AsyncAPISpec {\n  const routerConfig = isEventRouterDefinition(router) ? router.handlers : router;\n  const handlers = collectEventHandlers(routerConfig);\n\n  const channels: Record<string, AsyncAPIChannel> = {};\n  const operations: Record<string, AsyncAPIOperation> = {};\n  const allTags = new Set<string>();\n\n  for (const { key, handler } of handlers) {\n    const handlerId = generateHandlerId(key);\n    const channelId = handler.eventType;\n\n    // Build message\n    const message = buildMessage(handler.eventType, handler.payload, handler.docs);\n\n    // Build channel (group by eventType — multiple handlers may share a channel)\n    if (!channels[channelId]) {\n      channels[channelId] = {\n        address: handler.eventType,\n        messages: {},\n      };\n    }\n    const channelMessages = { ...(channels[channelId]!.messages ?? {}) };\n    channelMessages[handlerId] = message;\n    channels[channelId] = { ...channels[channelId]!, messages: channelMessages };\n\n    // Build operation (one per handler)\n    const operation: AsyncAPIOperation = {\n      action: 'receive',\n      channel: { $ref: `#/channels/${channelId}` },\n      messages: [{ $ref: `#/channels/${channelId}/messages/${handlerId}` }],\n    };\n\n    if (handler.docs.summary) {\n      (operation as { summary: string }).summary = handler.docs.summary;\n    }\n    if (handler.docs.description) {\n      (operation as { description: string }).description = handler.docs.description;\n    }\n    if (handler.docs.deprecated) {\n      (operation as { deprecated: boolean }).deprecated = true;\n    }\n    if (handler.docs.tags && handler.docs.tags.length > 0) {\n      (operation as { tags: readonly AsyncAPITag[] }).tags = handler.docs.tags.map((t) => ({\n        name: t,\n      }));\n      for (const tag of handler.docs.tags) {\n        allTags.add(tag);\n      }\n    }\n\n    operations[handlerId] = operation;\n  }\n\n  // Merge custom tags with collected tags (AsyncAPI 3.0: tags live inside info)\n  const tags: AsyncAPITag[] = config.tags ? [...config.tags] : [];\n  for (const tagName of allTags) {\n    if (!tags.some((t) => t.name === tagName)) {\n      tags.push({ name: tagName });\n    }\n  }\n\n  const info = tags.length > 0 ? { ...config.info, tags } : config.info;\n\n  // Build the specification\n  const spec: AsyncAPISpec = {\n    asyncapi: config.asyncapi ?? '3.0.0',\n    info,\n    defaultContentType: config.defaultContentType ?? 'application/json',\n    channels,\n    operations,\n  };\n\n  if (config.servers && Object.keys(config.servers).length > 0) {\n    (spec as { servers: typeof config.servers }).servers = config.servers;\n  }\n\n  if (config.externalDocs) {\n    (spec as { externalDocs: typeof config.externalDocs }).externalDocs = config.externalDocs;\n  }\n\n  return spec;\n}\n\n/**\n * Builds an AsyncAPI message from a handler definition.\n */\nfunction buildMessage(\n  eventType: string,\n  payload: unknown,\n  docs: {\n    readonly summary?: string;\n    readonly description?: string;\n    readonly tags?: readonly string[];\n    readonly deprecated?: boolean;\n  },\n): AsyncAPIMessage {\n  const message: AsyncAPIMessage = {\n    name: eventType,\n  };\n\n  if (docs.summary) {\n    (message as { summary: string }).summary = docs.summary;\n  }\n  if (docs.description) {\n    (message as { description: string }).description = docs.description;\n  }\n  if (docs.deprecated) {\n    (message as { deprecated: boolean }).deprecated = true;\n  }\n\n  if (payload) {\n    const schema = (payload as SchemaAdapter).toJsonSchema();\n    (message as { payload: typeof schema }).payload = schema;\n  }\n\n  return message;\n}\n"],"mappings":"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","names":[]}

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

@@ -0,0 +1,184 @@
+import { c as EventRouterConfig, e as EventRouterDefinition } from '../../event-router-definition.type-CP9uTlux.cjs';
+import { JsonSchema } from '../../http/schema/types.cjs';
+
+/**
+ * @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 };