@stacksjs/bun-router 0.0.2

package/dist/testing/model-binding-testing.d.ts

@@ -0,0 +1,132 @@
+import type { EnhancedRequest } from '../types';
+import type { ModelBindingTestOptions } from './types';
+/**
+ * Factory functions
+ */
+export declare function createModelBindingTester(options?: ModelBindingTestOptions): ModelBindingTester;
+export declare function createModelResolverTester(): ModelResolverTester;
+/**
+ * Mock model factories
+ */
+export declare const modelMocks: {
+  /**
+   * Create a mock model class
+   */
+  createModel: (name: string, attributes: Record<string, any> = {}) => any;
+  /**
+   * Create a User model mock
+   */
+  User: () => unknown;
+  /**
+   * Create a Post model mock
+   */
+  Post: () => unknown
+};
+/**
+ * Model binding constraint helpers
+ */
+export declare const constraintHelpers: {
+  belongsTo: (userIdField?: string) => ModelConstraintFn
+  belongsToUser: () => ModelConstraintFn
+  published: () => SimpleModelConstraintFn
+  visible: () => SimpleModelConstraintFn
+  custom: (constraintFn: ModelConstraintFn) => ModelConstraintFn
+  combine: (...constraints: ModelConstraintFn[]) => ModelConstraintFn
+};
+/**
+ * Route model binding test helpers
+ */
+export declare const routeModelHelpers: {
+  testRoute: (path: string, params: Record<string, string>, modelBindings: Record<string, any>) => Promise<EnhancedRequest>
+  createHandler: (expectedModels: string[]) => RouteHandlerFn
+  testBindingMiddleware: (bindings: Record<string, any>) => BindingMiddlewareFn
+};
+/**
+ * Test utilities for scoped model binding
+ */
+export declare const scopedBindingHelpers: {
+  testUserScoped: (model: any, user: any, constraint?: UserScopeConstraint) => Promise<boolean>
+  testRoleAccess: (model: any, user: any, requiredRoles: string[]) => Promise<boolean>
+  testPermissionAccess: (model: any, user: any, requiredPermissions: string[]) => Promise<boolean>
+};
+/** Model constraint function type */
+export type ModelConstraintFn = (model: any, request: EnhancedRequest) => Promise<boolean>
+/** Simple model constraint function type (no request) */
+export type SimpleModelConstraintFn = (model: any) => Promise<boolean>
+/** Route handler function type */
+export type RouteHandlerFn = (request: EnhancedRequest) => Promise<Response>
+/** Binding middleware function type */
+export type BindingMiddlewareFn = (request: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>
+/** User scope constraint function */
+export type UserScopeConstraint = (model: any, user: any) => Promise<boolean>
+/**
+ * Generic mock model base class for type annotations
+ */
+export declare class GenericMockModel {
+  id: any;
+  attributes: Record<string, any>;
+  constructor(data?: Record<string, any>);
+  static modelName: string;
+  static find(_id: any): Promise<GenericMockModel | null>;
+  static findOrFail(_id: any): Promise<GenericMockModel>;
+  static where(_conditions: Record<string, any>): Promise<GenericMockModel[]>;
+  static create(_data: Record<string, any>): Promise<GenericMockModel>;
+  save(): Promise<GenericMockModel>;
+  delete(): Promise<void>;
+  toJSON(): Record<string, any>;
+}
+/**
+ * Mock User class for type annotations
+ */
+export declare class MockUserClass {
+  id: number;
+  email: string;
+  name: string;
+  constructor(data?: { id: number, email?: string, name?: string });
+  static find(_id: any): Promise<MockUserClass | null>;
+  static findOrFail(_id: any): Promise<MockUserClass>;
+  toJSON(): Record<string, any>;
+}
+/**
+ * Mock Post class for type annotations
+ */
+export declare class MockPostClass {
+  id: number;
+  title: string;
+  content: string;
+  userId: number;
+  constructor(data?: { id: number, title?: string, content?: string, userId?: number });
+  static find(_id: any): Promise<MockPostClass | null>;
+  static findOrFail(_id: any): Promise<MockPostClass>;
+  belongsTo(_userId: number): Promise<boolean>;
+  toJSON(): Record<string, any>;
+}
+/**
+ * Model binding testing utilities
+ */
+export declare class ModelBindingTester {
+  private request: EnhancedRequest;
+  private options: ModelBindingTestOptions;
+  constructor(options?: ModelBindingTestOptions);
+  withRequest(request: EnhancedRequest): ModelBindingTester;
+  withParams(params: Record<string, string>): ModelBindingTester;
+  withModel(modelClass: any): ModelBindingTester;
+  withRouteKey(routeKey: string): ModelBindingTester;
+  withConstraints(constraints: Record<string, any>): ModelBindingTester;
+  withResolver(resolver: (value: string) => Promise<any>): ModelBindingTester;
+  testResolution(paramValue: string): Promise<any>;
+  testNotFound(paramValue: string): Promise<void>;
+  getRequest(): EnhancedRequest;
+}
+/**
+ * Model resolver factory for testing
+ */
+export declare class ModelResolverTester {
+  private resolvers: Map<string, (value: string) => Promise<any>>;
+  register(key: string, resolver: (value: string) => Promise<any>): ModelResolverTester;
+  registerModel(key: string, modelClass: any): ModelResolverTester;
+  resolve(key: string, value: string): Promise<any>;
+  testAll(testValue?: string): Promise<Record<string, any>>;
+  getKeys(): string[];
+  clear(): ModelResolverTester;
+}

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

@@ -0,0 +1,202 @@
+import type { EnhancedRequest } from '../types';
+import type { LoadTestConfig, PerformanceMetrics } from './types';
+import type { TestClient } from './test-client';
+/**
+ * Factory functions
+ */
+export declare function createPerformanceTester(): PerformanceTester;
+export declare function createLoadTester(client: TestClient, config: LoadTestConfig): LoadTester;
+/**
+ * Benchmark testing utilities
+ */
+export declare const benchmarkTests: {
+  routeHandler: (handler: (req: EnhancedRequest) => Promise<Response>, iterations?: number) => Promise<RouteHandlerBenchmarkResult>
+  middleware: (middleware: (req: EnhancedRequest, next: () => Promise<Response | null>) => Promise<Response | null>, iterations?: number) => Promise<MiddlewareBenchmarkResult>
+  jsonSerialization: (data: any, iterations?: number) => Promise<JsonBenchmarkResult>
+  routeMatching: (routes: Array<{ path: string, handler: any }>, testPaths: string[], iterations?: number) => Promise<RouteMatchingBenchmarkResult>
+};
+/**
+ * Memory testing utilities
+ */
+export declare const memoryTests: {
+  measureMemoryUsage: <T>(fn: () => Promise<T> | T, iterations?: number) => Promise<MemoryUsageResult<T>>
+  testRouteHandlerMemoryLeaks: (handler: (req: EnhancedRequest) => Promise<Response>, iterations?: number) => Promise<RouteHandlerMemoryLeakResult>
+};
+/**
+ * Stress testing utilities
+ */
+export declare const stressTests: {
+  rampUpTest: (client: TestClient, path: string, options: RampUpTestOptions) => Promise<RampUpTestResult[]>
+  spikeTest: (client: TestClient, path: string, options: SpikeTestOptions) => Promise<SpikeTestResult>
+};
+/**
+ * Performance assertion helpers
+ */
+export declare const performanceAssertions: {
+  /**
+   * Assert response time is within acceptable range
+   */
+  responseTimeWithin: (actualTime: number, maxTime: number) => any;
+  /**
+   * Assert throughput meets minimum requirements
+   */
+  throughputAtLeast: (actualThroughput: number, minThroughput: number) => any;
+  /**
+   * Assert error rate is acceptable
+   */
+  errorRateBelow: (errorRate: number, maxErrorRate: number) => any;
+  /**
+   * Assert memory usage is within limits
+   */
+  memoryUsageWithin: (actualUsage: number, maxUsage: number) => any;
+  /**
+   * Assert no memory leaks detected
+   */
+  noMemoryLeaks: (memoryGrowth: number, threshold: number?) => any
+};
+/**
+ * Performance test utilities
+ */
+export declare const performanceUtils: {
+  /**
+   * Get current memory usage
+   */
+  getCurrentMemoryUsage: () => any;
+  /**
+   * Get CPU usage
+   */
+  getCPUUsage: () => any;
+  /**
+   * Create performance metric snapshot
+   */
+  createMetricSnapshot: (responseTime: number) => any;
+  /**
+   * Format performance results for display
+   */
+  formatResults: (results: any) => any
+};
+/** Route handler benchmark result */
+export declare interface RouteHandlerBenchmarkResult {
+  averageTime: number
+  minTime: number
+  maxTime: number
+  totalTime: number
+  throughput: number
+}
+/** Middleware benchmark result */
+export declare interface MiddlewareBenchmarkResult {
+  averageTime: number
+  minTime: number
+  maxTime: number
+  totalTime: number
+}
+/** JSON serialization benchmark result */
+export declare interface JsonBenchmarkResult {
+  averageTime: number
+  minTime: number
+  maxTime: number
+  totalTime: number
+  dataSize: number
+}
+/** URL parsing benchmark result */
+export declare interface UrlParsingBenchmarkResult {
+  averageTime: number
+  minTime: number
+  maxTime: number
+  totalTime: number
+}
+/** Memory test result */
+export declare interface MemoryTestResult {
+  heapUsedBefore: number
+  heapUsedAfter: number
+  heapUsedDelta: number
+  rssBefore: number
+  rssAfter: number
+  rssDelta: number
+}
+/** Memory usage result */
+export declare interface MemoryUsageResult<T> {
+  averageHeapUsed: number
+  maxHeapUsed: number
+  memoryLeakDetected: boolean
+  results: T[]
+}
+/** Route handler memory leak result */
+export declare interface RouteHandlerMemoryLeakResult {
+  memoryLeakDetected: boolean
+  initialMemory: number
+  finalMemory: number
+  memoryGrowth: number
+}
+/** Ramp up test options */
+export declare interface RampUpTestOptions {
+  startConcurrency: number
+  endConcurrency: number
+  rampUpTime: number
+  testDuration: number
+}
+/** Ramp up test result */
+export declare interface RampUpTestResult {
+  concurrency: number
+  requestsPerSecond: number
+  averageResponseTime: number
+  errorRate: number
+}
+/** Spike test options */
+export declare interface SpikeTestOptions {
+  normalLoad: number
+  spikeLoad: number
+  spikeDuration: number
+}
+/** Spike test result */
+export declare interface SpikeTestResult {
+  normalPhase: any
+  spikePhase: any
+  recoveryPhase: any
+}
+/** Route matching benchmark result */
+export declare interface RouteMatchingBenchmarkResult {
+  averageTime: number
+  minTime: number
+  maxTime: number
+  totalTime: number
+  matchRate: number
+}
+/**
+ * Performance testing utilities
+ */
+export declare class PerformanceTester {
+  private metrics: PerformanceMetrics[];
+  private startTime: number;
+  private endTime: number;
+  start(): PerformanceTester;
+  end(): PerformanceTester;
+  recordMetric(metric: PerformanceMetrics): PerformanceTester;
+  getElapsedTime(): number;
+  getMetrics(): PerformanceMetrics[];
+  getAverageResponseTime(): number;
+  getMemoryStats(): {
+    averageHeapUsed: number
+    maxHeapUsed: number
+    averageRSS: number
+    maxRSS: number
+  };
+  clear(): PerformanceTester;
+}
+/**
+ * Load testing utilities
+ */
+export declare class LoadTester {
+  private client: TestClient;
+  private config: LoadTestConfig;
+  constructor(client: TestClient, config: LoadTestConfig);
+  run(path: string, method?: 'GET' | 'POST' | 'PUT' | 'DELETE', requestOptions?: any): Promise<{
+      totalRequests: number
+      successfulRequests: number
+      failedRequests: number
+      averageResponseTime: number
+      requestsPerSecond: number
+      errors: Array<{ error: string, count: number }>
+    }>;
+  private makeRequest(path: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE', options: any): Promise<number>;
+}

package/dist/testing/test-client.d.ts

@@ -0,0 +1,58 @@
+import type { EnhancedRequest } from '../types';
+import type { Router } from '../router/router';
+import type { TestClientConfig, TestRequestOptions } from './types';
+import type { TestResponseWrapper } from './test-response';
+/**
+ * Create a test client for a router
+ */
+export declare function createTestClient(router: Router, config?: TestClientConfig): TestClient;
+/**
+ * Test client factory with fluent API
+ */
+export declare const testClient: {
+  /**
+   * Create a test client for a router
+   */
+  for: (router: Router, config?: TestClientConfig) => any;
+  /**
+   * Create a test client with specific configuration
+   */
+  withConfig: (config: TestClientConfig) => (router: Router) => any;
+  /**
+   * Create a test client with authentication
+   */
+  withAuth: (token: string, type: 'Bearer' | 'Basic' = 'Bearer') => (router: Router) => any;
+  /**
+   * Create a test client with custom headers
+   */
+  withHeaders: (headers: Record<string, string>) => (router: Router) => any
+};
+/**
+ * Test client for making HTTP requests to router instances
+ */
+export declare class TestClient {
+  private router: Router;
+  private config: TestClientConfig;
+  private defaultHeaders: Record<string, string>;
+  constructor(router: Router, config?: TestClientConfig);
+  get(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+  post(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+  put(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+  patch(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+  delete(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+  options(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+  head(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+  request(method: string, path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+  private handleRequest(request: EnhancedRequest): Promise<Response>;
+  private findMatchingRoute(method: string, pathname: string): { route: any, params: Record<string, string> } | null;
+  private matchPath(pattern: string, pathname: string): Record<string, string> | null;
+  private executeMiddlewareChain(request: EnhancedRequest, route: any): Promise<Response>;
+  private executeHandler(handler: any, request: EnhancedRequest): Promise<Response>;
+  setDefaultHeaders(headers: Record<string, string>): TestClient;
+  auth(token: string, type?: 'Bearer' | 'Basic'): TestClient;
+  userAgent(userAgent: string): TestClient;
+  withConfig(config: Partial<TestClientConfig>): TestClient;
+  withHeaders(headers: Record<string, string>): TestClient;
+  getRouter(): Router;
+  getConfig(): TestClientConfig;
+}

package/dist/testing/test-request.d.ts

@@ -0,0 +1,43 @@
+import type { EnhancedRequest, UploadedFile } from '../types';
+import type { TestFile, TestRequestOptions } from './types';
+/**
+ * Create a mock request with minimal setup
+ */
+export declare function createMockRequest(method?: string, path?: string, options?: TestRequestOptions): EnhancedRequest;
+/**
+ * Helper functions for creating test requests
+ */
+export declare const testRequest: {
+  get: (path: string, options?: TestRequestOptions) => any;
+  post: (path: string, options?: TestRequestOptions) => any;
+  put: (path: string, options?: TestRequestOptions) => any;
+  patch: (path: string, options?: TestRequestOptions) => any;
+  delete: (path: string, options?: TestRequestOptions) => any;
+  options: (path: string, options?: TestRequestOptions) => any;
+  head: (path: string, options?: TestRequestOptions) => any
+};
+/**
+ * Creates a mock EnhancedRequest for testing
+ */
+export declare class TestRequestBuilder {
+  private request: Partial<EnhancedRequest>;
+  private url: URL;
+  constructor(method: string, path: string, options?: TestRequestOptions);
+  private parseQuery(searchParams: URLSearchParams): Record<string, string | string[]>;
+  private convertTestFiles(testFiles: TestFile[]): UploadedFile[];
+  private handleBody(body: any): void;
+  params(params: Record<string, string>): TestRequestBuilder;
+  headers(headers: Record<string, string>): TestRequestBuilder;
+  auth(token: string, type?: 'Bearer' | 'Basic'): TestRequestBuilder;
+  user(user: any): TestRequestBuilder;
+  session(session: any): TestRequestBuilder;
+  cookies(cookies: Record<string, string>): TestRequestBuilder;
+  context(context: Record<string, any>): TestRequestBuilder;
+  json(data: any): TestRequestBuilder;
+  form(data: Record<string, any>): TestRequestBuilder;
+  files(files: TestFile[]): TestRequestBuilder;
+  ip(ip: string): TestRequestBuilder;
+  userAgent(userAgent: string): TestRequestBuilder;
+  csrf(token: string): TestRequestBuilder;
+  build(): EnhancedRequest;
+}

package/dist/testing/test-response.d.ts

@@ -0,0 +1,45 @@
+import type { TestResponse } from './types';
+/**
+ * Create a test response from a Response object
+ */
+export declare function createTestResponse(response: Response): Promise<TestResponseWrapper>;
+/**
+ * Create a mock response for testing
+ */
+export declare function createMockResponse(status?: number, body?: any, headers?: Record<string, string>): TestResponseWrapper;
+/**
+ * Test response wrapper with assertion helpers
+ */
+export declare class TestResponseWrapper implements TestResponse {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  body: any;
+  text: string;
+  json: any;
+  cookies: Record<string, string>;
+  redirected: boolean;
+  url: string;
+  ok: boolean;
+  type: string;
+  private originalResponse: Response;
+  constructor(response: Response, body?: any);
+  private parseHeaders(headers: Headers): Record<string, string>;
+  private parseCookies(cookieHeader: string | null): Record<string, string>;
+  expectStatus(status: number): TestResponseWrapper;
+  expectSuccess(): TestResponseWrapper;
+  expectHeader(name: string, value?: string): TestResponseWrapper;
+  expectBody(expectedBody: any): TestResponseWrapper;
+  expectJson(expectedJson: any): TestResponseWrapper;
+  expectJsonContains(properties: Record<string, any>): TestResponseWrapper;
+  expectCookie(name: string, value?: string): TestResponseWrapper;
+  expectRedirect(url?: string): TestResponseWrapper;
+  expectValidationError(field?: string, message?: string): TestResponseWrapper;
+  expectContentType(contentType: string): TestResponseWrapper;
+  expectBodyContains(text: string): TestResponseWrapper;
+  expectBodyMatches(pattern: RegExp): TestResponseWrapper;
+  expectJsonStructure(structure: any): TestResponseWrapper;
+  private validateStructure(data: any, structure: any, path: string): void;
+  getOriginalResponse(): Response;
+  toJSON(): any;
+}

package/dist/testing/types.d.ts

@@ -0,0 +1,206 @@
+import type { EnhancedRequest, MiddlewareHandler } from '../types';
+/**
+ * Test client configuration options
+ */
+export declare interface TestClientConfig {
+  baseUrl?: string
+  defaultHeaders?: Record<string, string>
+  timeout?: number
+  followRedirects?: boolean
+  validateStatus?: (status: number) => boolean
+}
+/**
+ * Test request options
+ */
+export declare interface TestRequestOptions {
+  headers?: Record<string, string>
+  query?: Record<string, string | string[]>
+  body?: any
+  files?: TestFile[]
+  cookies?: Record<string, string>
+  session?: any
+  user?: any
+  context?: Record<string, any>
+  timeout?: number
+  followRedirects?: boolean
+}
+/**
+ * Test file for upload testing
+ */
+export declare interface TestFile {
+  fieldName: string
+  filename: string
+  content: string | ArrayBuffer | Uint8Array
+  mimetype?: string
+}
+/**
+ * Test response interface
+ */
+export declare interface TestResponse {
+  status: number
+  statusText: string
+  headers: Record<string, string>
+  body: any
+  text: string
+  json: any
+  cookies: Record<string, string>
+  redirected: boolean
+  url: string
+  ok: boolean
+  type: string
+}
+/**
+ * Middleware test context
+ */
+export declare interface MiddlewareTestContext {
+  request: EnhancedRequest
+  response?: Response
+  next: ReturnType<typeof import('bun:test').mock<() => Promise<Response | null>>>
+  error?: Error
+}
+/**
+ * Authentication test user
+ */
+export declare interface TestUser {
+  id: string | number
+  email?: string
+  username?: string
+  roles?: string[]
+  permissions?: string[]
+}
+/**
+ * JWT test options
+ */
+export declare interface JWTTestOptions {
+  secret?: string
+  expiresIn?: string
+  algorithm?: 'HS256' | 'HS384' | 'HS512' | 'RS256'
+  payload?: Record<string, any>
+  headers?: Record<string, any>
+}
+/**
+ * Session test options
+ */
+export declare interface SessionTestOptions {
+  sessionId?: string
+  data?: Record<string, any>
+  maxAge?: number
+  secure?: boolean
+  httpOnly?: boolean
+}
+/**
+ * Model binding test options
+ */
+export declare interface ModelBindingTestOptions {
+  modelClass?: any
+  routeKey?: string
+  constraints?: Record<string, any>
+  customResolver?: (value: string) => Promise<any>
+}
+/**
+ * Performance test metrics
+ */
+export declare interface PerformanceMetrics {
+  responseTime: number
+  memoryUsage: {
+    heapUsed: number
+    heapTotal: number
+    external: number
+    rss: number
+  }
+  cpuUsage: {
+    user: number
+    system: number
+  }
+  requestsPerSecond?: number
+  concurrentRequests?: number
+}
+/**
+ * Load test configuration
+ */
+export declare interface LoadTestConfig {
+  duration: number
+  concurrency: number
+  rampUp?: number
+  rampDown?: number
+  requestsPerSecond?: number
+  maxRequests?: number
+}
+/**
+ * WebSocket test message
+ */
+export declare interface WSTestMessage {
+  type: 'text' | 'binary'
+  data: string | ArrayBuffer | Uint8Array
+  timestamp?: number
+}
+/**
+ * WebSocket test client
+ */
+export declare interface WSTestClient {
+  send: (message: string | ArrayBuffer | Uint8Array) => void
+  close: (code?: number, reason?: string) => void
+  ping: (data?: Uint8Array) => void
+  pong: (data?: Uint8Array) => void
+  messages: WSTestMessage[]
+  isConnected: boolean
+  readyState: number
+}
+/**
+ * Test assertion helpers
+ */
+export declare interface TestAssertions {
+  toHaveStatus: (status: number) => void
+  toHaveHeader: (name: string, value?: string) => void
+  toHaveBody: (body: any) => void
+  toHaveJson: (json: any) => void
+  toHaveCookie: (name: string, value?: string) => void
+  toBeRedirected: (url?: string) => void
+  toHaveValidationError: (field?: string, message?: string) => void
+  toBeAuthenticated: (user?: any) => void
+  toBeUnauthenticated: () => void
+  toHaveMiddleware: (middleware: string | MiddlewareHandler) => void
+  toHaveModel: (model: any) => void
+  toHaveUploadedFile: (fieldName: string, filename?: string) => void
+  toRespondWithin: (milliseconds: number) => void
+}
+/**
+ * Mock factory options
+ */
+export declare interface MockFactoryOptions {
+  count?: number
+  overrides?: Record<string, any>
+  relations?: Record<string, any>
+}
+/**
+ * Database test helpers
+ */
+export declare interface DatabaseTestHelpers {
+  seed: (data: any[]) => Promise<void>
+  truncate: (tables?: string[]) => Promise<void>
+  factory: <T>(model: string, options?: MockFactoryOptions) => T[]
+  create: <T>(model: string, data?: Partial<T>) => Promise<T>
+  transaction: <T>(callback: () => Promise<T>) => Promise<T>
+}
+/**
+ * Test environment configuration
+ */
+export declare interface TestEnvironment {
+  database?: DatabaseTestHelpers
+  cache?: {
+    clear: () => Promise<void>
+    get: (key: string) => Promise<any>
+    set: (key: string, value: any, ttl?: number) => Promise<void>
+  }
+  storage?: {
+    clear: () => Promise<void>
+    put: (path: string, content: string | ArrayBuffer) => Promise<void>
+    get: (path: string) => Promise<string | ArrayBuffer | null>
+    delete: (path: string) => Promise<void>
+  }
+  queue?: {
+    clear: () => Promise<void>
+    push: (job: any) => Promise<void>
+    process: () => Promise<void>
+  }
+}