@stacksjs/bun-router 0.0.2

package/dist/testing/websocket-testing.d.ts

@@ -0,0 +1,170 @@
+import type { WSTestClient, WSTestMessage } from './types';
+/**
+ * Factory functions
+ */
+export declare function createWebSocketTester(): WebSocketTester;
+export declare function createMockServerWebSocket(data?: any): MockServerWebSocket;
+/**
+ * WebSocket handler testing utilities
+ */
+export declare const wsHandlerMocks: {
+  /**
+   * Mock WebSocket open handler
+   */
+  onOpen: () => any;
+  /**
+   * Mock WebSocket message handler
+   */
+  onMessage: (response?: string | ArrayBuffer | Uint8Array) => any;
+  /**
+   * Mock WebSocket close handler
+   */
+  onClose: () => any;
+  /**
+   * Mock WebSocket error handler
+   */
+  onError: () => any;
+  /**
+   * Mock echo handler
+   */
+  echo: () => any;
+  /**
+   * Mock broadcast handler
+   */
+  broadcast: (clients: ServerWebSocket<any>[]) => any;
+  /**
+   * Mock chat room handler
+   */
+  chatRoom: (room: string) => any
+};
+/**
+ * WebSocket test scenarios
+ */
+export declare const wsTestScenarios: {
+  /**
+   * Test basic connection and message exchange
+   */
+  basicConnection: () => any;
+  /**
+   * Test connection failure
+   */
+  connectionFailure: () => any;
+  /**
+   * Test message broadcasting
+   */
+  messageBroadcast: (clientCount: number?) => any;
+  /**
+   * Test ping/pong mechanism
+   */
+  pingPong: () => any;
+  /**
+   * Test connection timeout
+   */
+  connectionTimeout: () => any
+};
+/**
+ * WebSocket assertion helpers
+ */
+export declare const wsAssertions: {
+  /**
+   * Assert WebSocket is connected
+   */
+  isConnected: (tester: WebSocketTester) => any;
+  /**
+   * Assert WebSocket is disconnected
+   */
+  isDisconnected: (tester: WebSocketTester) => any;
+  /**
+   * Assert message was sent
+   */
+  messageSent: (tester: WebSocketTester, expectedMessage: string | ArrayBuffer | Uint8Array) => any;
+  /**
+   * Assert number of messages sent
+   */
+  messageCount: (tester: WebSocketTester, expectedCount: number) => any;
+  /**
+   * Assert message type
+   */
+  messageType: (tester: WebSocketTester, index: number, expectedType: 'text' | 'binary') => any;
+  /**
+   * Assert ready state
+   */
+  readyState: (tester: WebSocketTester, expectedState: number) => any
+};
+/**
+ * WebSocket performance testing
+ */
+export declare const wsPerformance: {
+  /**
+   * Test message throughput
+   */
+  testThroughput: ( messageCount: number?, messageSize: number?, ) => Promise<{ messagesPerSecond: number totalTime: number averageLatency: number }>;
+  /**
+   * Test concurrent connections
+   */
+  testConcurrentConnections: ( connectionCount: number?, ) => Promise<{ successfulConnections: number failedConnections: number averageConnectionTime: number }>
+};
+/**
+ * WebSocket test utilities
+ */
+export declare const wsTestUtils: {
+  /**
+   * Create multiple connected clients
+   */
+  createClients: (count: number) => any;
+  /**
+   * Simulate network latency
+   */
+  withLatency: (tester: WebSocketTester, latencyMs: number) => any;
+  /**
+   * Simulate packet loss
+   */
+  withPacketLoss: (tester: WebSocketTester, lossRate: number) => any;
+  /**
+   * Create message generator
+   */
+  * messageGenerator(count: number, prefix: string = 'Message'): unknown
+};
+/**
+ * WebSocket testing utilities
+ */
+export declare class WebSocketTester {
+  private messages: WSTestMessage[];
+  private isConnected: boolean;
+  private readyState: number;
+  private eventHandlers: Map<string, ((...args: any[]) => any)[]>;
+  constructor();
+  private setupEventHandlers(): void;
+  connect(): WebSocketTester;
+  disconnect(code?: number, reason?: string): WebSocketTester;
+  send(data: string | ArrayBuffer | Uint8Array): WebSocketTester;
+  receive(data: string | ArrayBuffer | Uint8Array): WebSocketTester;
+  ping(data?: Uint8Array): WebSocketTester;
+  pong(data?: Uint8Array): WebSocketTester;
+  on(event: string, handler: (...args: any[]) => any): WebSocketTester;
+  off(event: string, handler: (...args: any[]) => any): WebSocketTester;
+  private emit(event: string, data: any): void;
+  getSentMessages(): WSTestMessage[];
+  getMessagesByType(type: 'text' | 'binary'): WSTestMessage[];
+  clearMessages(): WebSocketTester;
+  getState(): { isConnected: boolean, readyState: number };
+  getTestClient(): WSTestClient;
+}
+/**
+ * Mock ServerWebSocket for testing
+ */
+export declare class MockServerWebSocket {
+  private tester: WebSocketTester;
+  private _data: any;
+  constructor(data?: any);
+  send(message: string | ArrayBuffer | Uint8Array): void;
+  close(code?: number, reason?: string): void;
+  ping(data?: Uint8Array): void;
+  pong(data?: Uint8Array): void;
+  publish(topic: string, message: string | ArrayBuffer | Uint8Array): void;
+  subscribe(_topic: string): void;
+  unsubscribe(_topic: string): void;
+  isSubscribed(_topic: string): boolean;
+  cork(callback: () => void): void;
+  getTester(): WebSocketTester;
+}

package/dist/types/controller-types.d.ts

@@ -0,0 +1,303 @@
+import type { ExtractQueryParams, ExtractTypedParams, RouteHandler, RouteMethod, TypedRequest,  } from './route-inference';
+import type { TypedMiddleware } from './middleware-types';
+// Base controller interface
+export declare interface BaseController {
+
+}
+// Controller method metadata
+export declare interface ControllerMethodMetadata {
+  path: string
+  method: RouteMethod
+  middleware?: TypedMiddleware<any, any, any, any>[]
+  description?: string
+  tags?: string[]
+  deprecated?: boolean
+  operationId?: string
+}
+// Controller method decorator metadata
+export declare interface MethodDecoratorMetadata extends ControllerMethodMetadata {
+  parameterTypes?: any[]
+  returnType?: any
+  target: any
+  propertyKey: string | symbol
+}
+// Controller route registration
+export declare interface ControllerRoute<TPath extends string = string, TQuery extends Record<string, any> = object, TBody = unknown, TContext = object> {
+  method: RouteMethod
+  path: TPath
+  handler: RouteHandler<TPath, TQuery, TBody, TContext>
+  controllerMethod: string
+  middleware?: TypedMiddleware<any, any, any, any>[]
+  metadata?: ControllerMethodMetadata
+}
+// Controller class decorator
+export declare interface ControllerDecorator<TPrefix extends string = ''> {
+  prefix?: TPrefix
+  middleware?: TypedMiddleware<any, any, any, any>[]
+  tags?: string[]
+  description?: string
+}
+// Parameter decorators
+export declare interface ParameterDecorator<_T = any> {
+  (target: TController, propertyKey: keyof TController, parameterIndex: number): void
+}
+// Controller dependency injection
+export declare interface ControllerDependency<T = any> {
+  token: string | symbol | ((...args: any[]) => any)
+  value?: T
+  factory?: () => T
+  singleton?: boolean
+}
+export declare interface DependencyContainer {
+  register: <T>(dependency: ControllerDependency<T>) => void
+  resolve: <T>(token: string | symbol | ((...args: any[]) => any)) => T
+  has: (token: string | symbol | ((...args: any[]) => any)) => boolean
+}
+// Injectable decorator
+export declare interface InjectableDecorator {
+  (constructor: T): T
+}
+// Inject decorator
+export declare interface InjectDecorator<T = any> {
+  (token: string | symbol | ((...args: any[]) => any)): ParameterDecorator<T>
+}
+// Controller factory
+export declare interface ControllerFactory<T extends BaseController> {
+  create: (container?: DependencyContainer) => T
+  getRoutes: () => ControllerRoute[]
+  getMetadata: () => ControllerDecorator
+}
+// Controller registry
+export declare interface ControllerRegistry {
+  register: <T extends BaseController>(
+    controller: new (...args: any[]) => T,
+    metadata?: ControllerDecorator
+  ) => void
+  get: <T extends BaseController>(
+    controller: new (...args: any[]) => T
+  ) => ControllerFactory<T> | undefined
+  getAll: () => Array<{
+    controller: new (...args: any[]) => BaseController
+    factory: ControllerFactory<BaseController>
+  }>
+  resolve: (container?: DependencyContainer) => ControllerRoute[]
+}
+// Controller OpenAPI generation
+export declare interface GenerateControllerOpenAPI<T extends BaseController> {
+  paths: {
+    [K in keyof T]: T[K] extends RouteHandler<infer TPath, infer TQuery, infer TBody, any>
+      ? {
+          [M in RouteMethod]: {
+            operationId: string & K
+            parameters: Array<{
+              name: keyof ExtractTypedParams<TPath>
+              in: 'path'
+              required: true
+              schema: { type: 'string' }
+            }> | Array<{
+              name: keyof ExtractQueryParams<TQuery>
+              in: 'query'
+              required: boolean
+              schema: { type: 'string' }
+            }>
+            requestBody?: TBody extends never ? never : {
+              content: {
+                'application/json': { schema: any }
+              }
+            }
+            responses: {
+              200: {
+                description: 'Success'
+                content: {
+                  'application/json': { schema: any }
+                }
+              }
+            }
+          }
+        }
+      : never
+  }
+}
+// Controller testing utilities
+export declare interface ControllerTestUtils<T extends BaseController> {
+  createInstance: (overrides?: Partial<T>) => T
+  mockMethod: <K extends keyof T>(method: K, implementation: T[K]) => void
+  callMethod: <K extends keyof T>(
+    method: K,
+    ...args: T[K] extends (...args: infer TArgs) => any ? TArgs : never
+  ) => T[K] extends (...args: any[]) => infer TReturn ? TReturn : never
+  getRoutes: () => ControllerRoute[]
+  validateRoutes: () => ControllerValidationError<T>[]
+}
+// Controller performance monitoring
+export declare interface ControllerPerformanceMetrics {
+  controllerName: string
+  methodName: string
+  executionTime: number
+  memoryUsage: number
+  callCount: number
+  errorCount: number
+  lastCalled: Date
+}
+// Controller lifecycle hooks
+export declare interface ControllerLifecycleHooks {
+  onInit?: () => Promise<void> | void
+  onDestroy?: () => Promise<void> | void
+  beforeMethod?: (methodName: string, args: any[]) => Promise<void> | void
+  afterMethod?: (methodName: string, result: any, args: any[]) => Promise<void> | void
+  onError?: (error: Error, methodName: string, args: any[]) => Promise<void> | void
+}
+// Extract controller method names
+export type ControllerMethodNames<T> = {
+  [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never
+}[keyof T]
+// Extract controller methods
+export type ControllerMethods<T> = Pick<T, ControllerMethodNames<T>>
+// Controller method signature validation
+export type ValidateControllerMethod<T> = T extends (
+  request: infer TRequest,
+  ...args: any[]
+) => infer TReturn
+  ? TRequest extends TypedRequest<any, any, any, any>
+    ? TReturn extends Promise<Response> | Response
+      ? T
+      : `Invalid return type: Controller method must return Response or Promise<Response>`
+    : `Invalid parameter type: First parameter must be TypedRequest`
+  : `Invalid method signature: Controller method must be a function`
+// Controller method type inference
+export type InferControllerMethodType<T> = T extends (
+  request: TypedRequest<infer TPath, infer TQuery, infer TBody, infer TContext>,
+  ...args: any[]
+) => Promise<Response> | Response
+  ? {
+      path: TPath
+      query: TQuery
+      body: TBody
+      context: TContext
+      params: ExtractTypedParams<TPath>
+    }
+  : never
+// Route method decorators
+export type RouteDecorator<TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown> = <T extends BaseController>(
+  target: T,
+  propertyKey: keyof T,
+  descriptor: TypedPropertyDescriptor<RouteHandler<TPath, TQuery, TBody, any>>
+) => void
+// HTTP method decorators
+export type GetDecorator<TPath extends string, TQuery extends Record<string, any> = object> = RouteDecorator<TPath, TQuery, never>
+export type PostDecorator<TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown> = RouteDecorator<TPath, TQuery, TBody>
+export type PutDecorator<TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown> = RouteDecorator<TPath, TQuery, TBody>
+export type PatchDecorator<TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown> = RouteDecorator<TPath, TQuery, TBody>
+export type DeleteDecorator<TPath extends string, TQuery extends Record<string, any> = object> = RouteDecorator<TPath, TQuery, never>
+// Parameter extraction types
+export type ParamDecorator<_TName extends string> = ParameterDecorator<string>
+export type QueryDecorator<_TName extends string> = ParameterDecorator<string>
+export type BodyDecorator<T = any> = ParameterDecorator<T>
+export type HeaderDecorator<_TName extends string> = ParameterDecorator<string>
+export type CookieDecorator<_TName extends string> = ParameterDecorator<string>
+export type RequestDecorator = ParameterDecorator<Request>
+export type ResponseDecorator = ParameterDecorator<Response>
+// Controller method parameter types
+export type ControllerMethodParams<T> = T extends (
+  ...args: infer TParams
+) => any
+  ? TParams
+  : never
+// Validate controller method parameters
+export type ValidateControllerParams<T extends any[]> = {
+  [K in keyof T]: T[K] extends TypedRequest<any, any, any, any>
+    ? T[K]
+    : T[K] extends string | number | boolean | object
+      ? T[K]
+      : `Invalid parameter type at index ${K}: ${T[K]}`
+}
+// Controller method validation at compile time
+export type ValidateController<T extends BaseController> = {
+  [K in keyof T]: T[K] extends (...args: any[]) => any
+    ? ValidateControllerMethod<T[K]> extends string
+      ? ValidateControllerMethod<T[K]>
+      : T[K]
+    : T[K]
+}
+// Controller route extraction
+export type ExtractControllerRoutes<T extends BaseController> = {
+  [K in keyof T]: T[K] extends RouteHandler<infer TPath, infer TQuery, infer TBody, infer TContext>
+    ? ControllerRoute<TPath, TQuery, TBody, TContext>
+    : never
+}[keyof T]
+// Controller method binding
+export type BindControllerMethod<TController extends BaseController, TMethod extends keyof TController> = TController[TMethod] extends RouteHandler<infer TPath, infer TQuery, infer TBody, infer TContext>
+  ? (this: TController, request: TypedRequest<TPath, TQuery, TBody, TContext>) => Promise<Response> | Response
+  : never
+// Controller instance type
+export type ControllerInstance<T extends BaseController> = {
+  [K in keyof T]: T[K] extends (...args: any[]) => any
+    ? BindControllerMethod<T, K>
+    : T[K]
+}
+// Controller method metadata extraction
+export type ExtractMethodMetadata<T extends BaseController> = {
+  [K in keyof T]: T[K] extends (...args: any[]) => any
+    ? InferControllerMethodType<T[K]> extends never
+      ? never
+      : {
+          method: K
+          route: InferControllerMethodType<T[K]>
+          metadata?: ControllerMethodMetadata
+        }
+    : never
+}[keyof T]
+// Controller validation errors
+export type ControllerValidationError<T extends BaseController> = {
+  [K in keyof T]: ValidateController<T>[K] extends string
+    ? { method: K, error: ValidateController<T>[K] }
+    : never
+}[keyof T]
+// Controller type guards
+export type IsValidController<T> = T extends BaseController
+  ? ControllerValidationError<T> extends never
+    ? true
+    : false
+  : false
+export type IsValidControllerMethod<T> = ValidateControllerMethod<T> extends string
+  ? false
+  : true
+// Controller composition
+export type ComposeControllers<T extends readonly BaseController[]> = T extends readonly [
+  infer First,
+  ...infer Rest,
+]
+  ? First extends BaseController
+    ? Rest extends readonly BaseController[]
+      ? First & ComposeControllers<Rest>
+      : First
+    : object
+  : object
+// Controller middleware application
+export type ApplyControllerMiddleware<TController extends BaseController, TMiddleware extends TypedMiddleware<any, any, any, any>> = {
+  [K in keyof TController]: TController[K] extends RouteHandler<infer TPath, infer TQuery, infer TBody, infer TContext>
+    ? TMiddleware extends TypedMiddleware<any, any, infer TNewContext, any>
+      ? RouteHandler<TPath, TQuery, TBody, TContext & TNewContext>
+      : TController[K]
+    : TController[K]
+}
+// Controller route conflict detection
+export type DetectControllerConflicts<T extends BaseController> = {
+  [K in keyof T]: {
+    [J in keyof T]: K extends J
+      ? never
+      : T[K] extends RouteHandler<infer Path1, any, any, any>
+        ? T[J] extends RouteHandler<infer Path2, any, any, any>
+          ? Path1 extends Path2
+            ? `Route conflict in controller: methods "${string & K}" and "${string & J}" both handle "${Path1}"`
+            : never
+          : never
+        : never
+  }[keyof T]
+}[keyof T]
+export type PerformanceTrackingController<T extends BaseController> = T & {
+  getPerformanceMetrics: () => ControllerPerformanceMetrics[]
+  resetMetrics: () => void
+}
+// Controller with lifecycle
+export type LifecycleController<T extends BaseController> = T & ControllerLifecycleHooks