@onebun/core 0.1.1 → 0.1.2

package/src/ws-pattern-matcher.ts

@@ -0,0 +1,240 @@
+/**
+ * WebSocket Pattern Matcher
+ *
+ * Provides pattern matching for WebSocket events and room names.
+ * Supports wildcards (*) and named parameters ({paramName}).
+ *
+ * @example
+ * // Wildcard patterns
+ * matchPattern('chat:*', 'chat:general')         // { matched: true, params: {} }
+ * matchPattern('user:*:action', 'user:123:action') // { matched: true, params: {} }
+ *
+ * // Parameter patterns
+ * matchPattern('chat:{roomId}', 'chat:general')  // { matched: true, params: { roomId: 'general' } }
+ * matchPattern('user:{id}:message', 'user:123:message') // { matched: true, params: { id: '123' } }
+ *
+ * // Combined patterns
+ * matchPattern('service:{service}:*', 'service:auth:login') // { matched: true, params: { service: 'auth' } }
+ */
+
+import type { PatternMatch } from './ws.types';
+
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Parse a pattern into a regex and extract parameter names
+ *
+ * @param pattern - Pattern string with wildcards and/or parameters
+ * @returns Object with regex and parameter names
+ */
+export function parsePattern(pattern: string): {
+  regex: RegExp;
+  paramNames: string[];
+} {
+  const paramNames: string[] = [];
+  let regexStr = '^';
+  let i = 0;
+
+  while (i < pattern.length) {
+    const char = pattern[i];
+
+    if (char === '*') {
+      // Wildcard: matches any characters except the separator
+      regexStr += '[^:]*';
+      i++;
+    } else if (char === '{') {
+      // Named parameter: {paramName}
+      const endIndex = pattern.indexOf('}', i);
+      if (endIndex === -1) {
+        // Invalid pattern, treat as literal
+        regexStr += escapeRegex(char);
+        i++;
+      } else {
+        const paramName = pattern.substring(i + 1, endIndex);
+        paramNames.push(paramName);
+        // Match any characters except the separator
+        regexStr += '([^:]+)';
+        i = endIndex + 1;
+      }
+    } else if (char === ':') {
+      // Separator
+      regexStr += ':';
+      i++;
+    } else {
+      // Literal character
+      regexStr += escapeRegex(char);
+      i++;
+    }
+  }
+
+  regexStr += '$';
+
+  return {
+    regex: new RegExp(regexStr),
+    paramNames,
+  };
+}
+
+/**
+ * Match a value against a pattern
+ *
+ * @param pattern - Pattern string with wildcards and/or parameters
+ * @param value - Value to match
+ * @returns Match result with extracted parameters
+ *
+ * @example
+ * matchPattern('chat:*', 'chat:general')
+ * // Returns: { matched: true, params: {} }
+ *
+ * matchPattern('chat:{roomId}:message', 'chat:general:message')
+ * // Returns: { matched: true, params: { roomId: 'general' } }
+ *
+ * matchPattern('chat:private', 'chat:public')
+ * // Returns: { matched: false, params: {} }
+ */
+export function matchPattern(pattern: string, value: string): PatternMatch {
+  // Exact match fast path
+  if (pattern === value) {
+    return { matched: true, params: {} };
+  }
+
+  // Check if pattern has any special characters
+  if (!pattern.includes('*') && !pattern.includes('{')) {
+    // No wildcards or parameters, must be exact match
+    return { matched: false, params: {} };
+  }
+
+  const { regex, paramNames } = parsePattern(pattern);
+  const match = value.match(regex);
+
+  if (!match) {
+    return { matched: false, params: {} };
+  }
+
+  // Extract parameters
+  const params: Record<string, string> = {};
+  for (let i = 0; i < paramNames.length; i++) {
+    params[paramNames[i]] = match[i + 1];
+  }
+
+  return { matched: true, params };
+}
+
+/**
+ * Check if a pattern matches a value (without extracting parameters)
+ *
+ * @param pattern - Pattern string
+ * @param value - Value to match
+ * @returns Whether the pattern matches
+ */
+export function isPatternMatch(pattern: string, value: string): boolean {
+  return matchPattern(pattern, value).matched;
+}
+
+/**
+ * Find all values that match a pattern
+ *
+ * @param pattern - Pattern string
+ * @param values - Array of values to check
+ * @returns Array of matching values
+ */
+export function findMatchingValues(pattern: string, values: string[]): string[] {
+  return values.filter((value) => isPatternMatch(pattern, value));
+}
+
+/**
+ * Create a pattern matcher function for a specific pattern
+ *
+ * @param pattern - Pattern string
+ * @returns Function that matches values against the pattern
+ *
+ * @example
+ * const matcher = createPatternMatcher('chat:{roomId}:message');
+ * matcher('chat:general:message') // { matched: true, params: { roomId: 'general' } }
+ * matcher('chat:private:action')  // { matched: false, params: {} }
+ */
+export function createPatternMatcher(pattern: string): (value: string) => PatternMatch {
+  const { regex, paramNames } = parsePattern(pattern);
+
+  return (value: string): PatternMatch => {
+    // Exact match fast path
+    if (pattern === value) {
+      return { matched: true, params: {} };
+    }
+
+    const match = value.match(regex);
+
+    if (!match) {
+      return { matched: false, params: {} };
+    }
+
+    const params: Record<string, string> = {};
+    for (let i = 0; i < paramNames.length; i++) {
+      params[paramNames[i]] = match[i + 1];
+    }
+
+    return { matched: true, params };
+  };
+}
+
+/**
+ * Check if a string is a pattern (contains wildcards or parameters)
+ *
+ * @param value - String to check
+ * @returns Whether the string is a pattern
+ */
+export function isPattern(value: string): boolean {
+  return value.includes('*') || value.includes('{');
+}
+
+/**
+ * Extract parameter names from a pattern
+ *
+ * @param pattern - Pattern string
+ * @returns Array of parameter names
+ *
+ * @example
+ * getPatternParams('chat:{roomId}:user:{userId}')
+ * // Returns: ['roomId', 'userId']
+ */
+export function getPatternParams(pattern: string): string[] {
+  const params: string[] = [];
+  const regex = /\{([^}]+)\}/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(pattern)) !== null) {
+    params.push(match[1]);
+  }
+
+  return params;
+}
+
+/**
+ * Build a value from a pattern and parameters
+ *
+ * @param pattern - Pattern string
+ * @param params - Parameter values
+ * @returns Built value string
+ *
+ * @example
+ * buildFromPattern('chat:{roomId}:message', { roomId: 'general' })
+ * // Returns: 'chat:general:message'
+ */
+export function buildFromPattern(pattern: string, params: Record<string, string>): string {
+  let result = pattern;
+
+  // Replace wildcards with empty string (or you could throw an error)
+  result = result.replace(/\*/g, '');
+
+  // Replace parameters with values
+  for (const [key, value] of Object.entries(params)) {
+    result = result.replace(`{${key}}`, value);
+  }
+
+  return result;
+}

package/src/ws-service-definition.ts

@@ -0,0 +1,223 @@
+/**
+ * WebSocket Service Definition
+ *
+ * Collects metadata from WebSocket gateways for generating typed clients.
+ */
+
+import type { WsHandlerType, WsParamMetadata } from './ws.types';
+
+import { getModuleMetadata } from './decorators';
+import { getGatewayMetadata, isWebSocketGateway } from './ws-decorators';
+
+/**
+ * Metadata for a single WebSocket endpoint/event
+ */
+export interface WsEndpointMetadata {
+  /** Gateway class name */
+  gateway: string;
+  /** Event pattern */
+  event: string;
+  /** Handler method name */
+  handler: string;
+  /** Handler type (message, connect, etc.) */
+  type: WsHandlerType;
+  /** Parameter metadata */
+  params?: WsParamMetadata[];
+}
+
+/**
+ * Definition of a WebSocket gateway with its events
+ */
+export interface WsGatewayDefinition {
+  /** Gateway class name */
+  name: string;
+  /** WebSocket path */
+  path: string;
+  /** Namespace (if any) */
+  namespace?: string;
+  /** Map of event patterns to endpoint metadata */
+  events: Map<string, WsEndpointMetadata>;
+}
+
+/**
+ * Service definition containing all WebSocket gateways and events.
+ * Used for generating typed WebSocket clients.
+ */
+export interface WsServiceDefinition<TModule = unknown> {
+  /** Reference to the module class */
+  readonly _module: TModule;
+  /** Flat list of all endpoints */
+  readonly _endpoints: WsEndpointMetadata[];
+  /** Gateways grouped by name */
+  readonly _gateways: Map<string, WsGatewayDefinition>;
+}
+
+/**
+ * Module metadata structure
+ */
+interface ModuleMetadata {
+  imports?: Function[];
+  controllers?: Function[];
+  providers?: unknown[];
+  exports?: unknown[];
+}
+
+/**
+ * Collect WebSocket endpoints recursively from a module and its imports
+ */
+function collectWsEndpointsRecursively(metadata: ModuleMetadata): WsEndpointMetadata[] {
+  const endpoints: WsEndpointMetadata[] = [];
+
+  // Collect from controllers (gateways are in controllers)
+  for (const controller of metadata.controllers || []) {
+    // Check if it's a WebSocket gateway
+    if (!isWebSocketGateway(controller)) {
+      continue;
+    }
+
+    const gatewayMeta = getGatewayMetadata(controller);
+    if (!gatewayMeta) {
+      continue;
+    }
+
+    // Add each handler as an endpoint
+    for (const handler of gatewayMeta.handlers) {
+      endpoints.push({
+        gateway: controller.name,
+        event: handler.pattern || handler.type,
+        handler: handler.handler,
+        type: handler.type,
+        params: handler.params,
+      });
+    }
+  }
+
+  // Recursively collect from imported modules
+  for (const importedModule of metadata.imports || []) {
+    const importedMeta = getModuleMetadata(importedModule);
+    if (importedMeta) {
+      endpoints.push(...collectWsEndpointsRecursively(importedMeta));
+    }
+  }
+
+  return endpoints;
+}
+
+/**
+ * Group endpoints by gateway
+ */
+function groupByGateway(
+  endpoints: WsEndpointMetadata[],
+  moduleClass: Function,
+): Map<string, WsGatewayDefinition> {
+  const gateways = new Map<string, WsGatewayDefinition>();
+  const metadata = getModuleMetadata(moduleClass);
+
+  if (!metadata) {
+    return gateways;
+  }
+
+  // First, collect gateway metadata
+  const gatewayPaths = new Map<string, { path: string; namespace?: string }>();
+
+  for (const controller of metadata.controllers || []) {
+    if (isWebSocketGateway(controller)) {
+      const gatewayMeta = getGatewayMetadata(controller);
+      if (gatewayMeta) {
+        gatewayPaths.set(controller.name, {
+          path: gatewayMeta.path,
+          namespace: gatewayMeta.namespace,
+        });
+      }
+    }
+  }
+
+  // Group endpoints by gateway
+  for (const endpoint of endpoints) {
+    if (!gateways.has(endpoint.gateway)) {
+      const pathInfo = gatewayPaths.get(endpoint.gateway) || { path: '/' };
+      gateways.set(endpoint.gateway, {
+        name: endpoint.gateway,
+        path: pathInfo.path,
+        namespace: pathInfo.namespace,
+        events: new Map(),
+      });
+    }
+
+    gateways.get(endpoint.gateway)!.events.set(endpoint.event, endpoint);
+  }
+
+  return gateways;
+}
+
+/**
+ * Create a WebSocket service definition from a module class.
+ * Collects all endpoint metadata from gateways and imported modules.
+ *
+ * @param moduleClass - The root module class decorated with @Module
+ * @returns Service definition containing all WebSocket endpoints
+ *
+ * @example
+ * ```typescript
+ * import { createWsServiceDefinition } from '@onebun/core';
+ * import { ChatModule } from './chat.module';
+ *
+ * export const chatWsDefinition = createWsServiceDefinition(ChatModule);
+ *
+ * // Use with createWsClient
+ * const client = createWsClient(chatWsDefinition, {
+ *   url: 'ws://localhost:3000',
+ * });
+ * ```
+ */
+export function createWsServiceDefinition<TModule>(
+  moduleClass: new (...args: unknown[]) => TModule,
+): WsServiceDefinition<TModule> {
+  const metadata = getModuleMetadata(moduleClass);
+  if (!metadata) {
+    throw new Error(`${moduleClass.name} is not decorated with @Module`);
+  }
+
+  const endpoints = collectWsEndpointsRecursively(metadata);
+  const gateways = groupByGateway(endpoints, moduleClass);
+
+  return {
+    _module: moduleClass as unknown as TModule,
+    _endpoints: endpoints,
+    _gateways: gateways,
+  };
+}
+
+/**
+ * Get gateway names from a service definition
+ */
+export function getWsGatewayNames<TDef extends WsServiceDefinition>(
+  definition: TDef,
+): string[] {
+  return Array.from(definition._gateways.keys());
+}
+
+/**
+ * Get event names for a gateway
+ */
+export function getWsEventNames<TDef extends WsServiceDefinition>(
+  definition: TDef,
+  gatewayName: string,
+): string[] {
+  const gateway = definition._gateways.get(gatewayName);
+
+  return gateway ? Array.from(gateway.events.keys()) : [];
+}
+
+/**
+ * Get endpoint metadata by gateway and event
+ */
+export function getWsEndpoint<TDef extends WsServiceDefinition>(
+  definition: TDef,
+  gatewayName: string,
+  event: string,
+): WsEndpointMetadata | undefined {
+  const gateway = definition._gateways.get(gatewayName);
+
+  return gateway?.events.get(event);
+}