@stacksjs/bun-router 0.0.4 → 0.0.6

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

@@ -0,0 +1,138 @@
+import type { EnhancedRequest, MiddlewareHandler, NextFunction } from '../types';
+import type { MiddlewareTestContext } from './types';
+import { mock, spyOn } from 'bun:test';
+/**
+ * Middleware testing utilities
+ */
+export declare class MiddlewareTester {
+    private middleware;
+    private context;
+    constructor(middleware: MiddlewareHandler);
+    private createContext;
+    /**
+     * Set up the test request
+     */
+    withRequest(request: EnhancedRequest): MiddlewareTester;
+    /**
+     * Set up a custom next function
+     */
+    withNext(nextFn: NextFunction): MiddlewareTester;
+    /**
+     * Set up an error context
+     */
+    withError(error: Error): MiddlewareTester;
+    /**
+     * Execute the middleware and return the result
+     */
+    execute(): Promise<Response | null>;
+    /**
+     * Assert that next was called
+     */
+    expectNextCalled(times?: number): MiddlewareTester;
+    /**
+     * Assert that next was not called
+     */
+    expectNextNotCalled(): MiddlewareTester;
+    /**
+     * Assert that middleware threw an error
+     */
+    expectError(errorMessage?: string): MiddlewareTester;
+    /**
+     * Get the test context
+     */
+    getContext(): MiddlewareTestContext;
+    /**
+     * Reset the middleware tester
+     */
+    reset(): MiddlewareTester;
+}
+/**
+ * Create a middleware tester
+ */
+export declare function testMiddleware(middleware: MiddlewareHandler): MiddlewareTester;
+/**
+ * Mock middleware factory
+ */
+export declare const mockMiddleware: {
+    /**
+     * Create a middleware that always calls next
+     */
+    passthrough: () => MiddlewareHandler;
+    /**
+     * Create a middleware that returns a response without calling next
+     */
+    response: (status?: number, body?: any) => MiddlewareHandler;
+    /**
+     * Create a middleware that throws an error
+     */
+    error: (message?: string) => MiddlewareHandler;
+    /**
+     * Create a middleware that modifies the request
+     */
+    modifyRequest: (modifier: (req: EnhancedRequest) => void) => MiddlewareHandler;
+    /**
+     * Create a middleware that adds context
+     */
+    addContext: (key: string, value: any) => MiddlewareHandler;
+    /**
+     * Create an authentication middleware mock
+     */
+    auth: (user?: any) => MiddlewareHandler;
+    /**
+     * Create a rate limiting middleware mock
+     */
+    rateLimit: (shouldLimit?: boolean) => MiddlewareHandler;
+    /**
+     * Create a CORS middleware mock
+     */
+    cors: (origin?: string) => MiddlewareHandler;
+};
+/**
+ * Middleware chain tester
+ */
+export declare class MiddlewareChainTester {
+    private middlewares;
+    private request;
+    private finalHandler;
+    constructor(middlewares: MiddlewareHandler[]);
+    /**
+     * Set the request for the chain
+     */
+    withRequest(request: EnhancedRequest): MiddlewareChainTester;
+    /**
+     * Set the final handler
+     */
+    withFinalHandler(handler: () => Promise<Response>): MiddlewareChainTester;
+    /**
+     * Execute the middleware chain
+     */
+    execute(): Promise<Response | null>;
+    /**
+     * Get execution order of middlewares
+     */
+    getExecutionOrder(): number[];
+}
+/**
+ * Create a middleware chain tester
+ */
+export declare function testMiddlewareChain(middlewares: MiddlewareHandler[]): MiddlewareChainTester;
+/**
+ * Spy on middleware execution
+ */
+export declare function spyOnMiddleware(middleware: MiddlewareHandler): ReturnType<typeof spyOn>;
+/**
+ * Create a middleware spy that tracks calls
+ */
+export declare function createMiddlewareSpy(): {
+    middleware: MiddlewareHandler;
+    spy: ReturnType<typeof mock>;
+};
+/**
+ * Test middleware performance
+ */
+export declare function benchmarkMiddleware(middleware: MiddlewareHandler, iterations?: number): Promise<{
+    averageTime: number;
+    minTime: number;
+    maxTime: number;
+    totalTime: number;
+}>;

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

@@ -0,0 +1,186 @@
+import type { EnhancedRequest } from '../types';
+import type { ModelBindingTestOptions } from './types';
+/**
+ * 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;
+    private options;
+    constructor(options?: ModelBindingTestOptions);
+    /**
+     * Set the request for testing
+     */
+    withRequest(request: EnhancedRequest): ModelBindingTester;
+    /**
+     * Set route parameters
+     */
+    withParams(params: Record<string, string>): ModelBindingTester;
+    /**
+     * Set the model class to test
+     */
+    withModel(modelClass: any): ModelBindingTester;
+    /**
+     * Set the route key for model binding
+     */
+    withRouteKey(routeKey: string): ModelBindingTester;
+    /**
+     * Set constraints for model binding
+     */
+    withConstraints(constraints: Record<string, any>): ModelBindingTester;
+    /**
+     * Set a custom resolver function
+     */
+    withResolver(resolver: (value: string) => Promise<any>): ModelBindingTester;
+    /**
+     * Test model resolution
+     */
+    testResolution(paramValue: string): Promise<any>;
+    /**
+     * Test model not found scenario
+     */
+    testNotFound(paramValue: string): Promise<void>;
+    /**
+     * Get the configured request
+     */
+    getRequest(): EnhancedRequest;
+}
+/**
+ * Mock model factories
+ */
+export declare const modelMocks: {
+    /**
+     * Create a mock model class
+     */
+    createModel: (name: string, attributes?: Record<string, any>) => typeof GenericMockModel;
+    /**
+     * Create a User model mock
+     */
+    User: typeof MockUserClass;
+    /**
+     * Create a Post model mock
+     */
+    Post: typeof MockPostClass;
+};
+/** 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>;
+/**
+ * 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;
+};
+/**
+ * Model resolver factory for testing
+ */
+export declare class ModelResolverTester {
+    private resolvers;
+    /**
+     * Register a model resolver
+     */
+    register(key: string, resolver: (value: string) => Promise<any>): ModelResolverTester;
+    /**
+     * Register a model class resolver
+     */
+    registerModel(key: string, modelClass: any): ModelResolverTester;
+    /**
+     * Test model resolution
+     */
+    resolve(key: string, value: string): Promise<any>;
+    /**
+     * Test all registered resolvers
+     */
+    testAll(testValue?: string): Promise<Record<string, any>>;
+    /**
+     * Get all registered resolver keys
+     */
+    getKeys(): string[];
+    /**
+     * Clear all resolvers
+     */
+    clear(): ModelResolverTester;
+}
+/** 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>;
+/**
+ * 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;
+};
+/**
+ * Factory functions
+ */
+export declare function createModelBindingTester(options?: ModelBindingTestOptions): ModelBindingTester;
+export declare function createModelResolverTester(): ModelResolverTester;
+/** User scope constraint function */
+export type UserScopeConstraint = (_model: any, _user: any) => Promise<boolean>;
+/**
+ * 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>;
+};

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

@@ -0,0 +1,235 @@
+import type { EnhancedRequest } from '../types';
+import type { TestClient } from './test-client';
+import type { LoadTestConfig, PerformanceMetrics } from './types';
+/** Route handler benchmark result */
+export interface RouteHandlerBenchmarkResult {
+    averageTime: number;
+    minTime: number;
+    maxTime: number;
+    totalTime: number;
+    throughput: number;
+}
+/** Middleware benchmark result */
+export interface MiddlewareBenchmarkResult {
+    averageTime: number;
+    minTime: number;
+    maxTime: number;
+    totalTime: number;
+}
+/** JSON serialization benchmark result */
+export interface JsonBenchmarkResult {
+    averageTime: number;
+    minTime: number;
+    maxTime: number;
+    totalTime: number;
+    dataSize: number;
+}
+/** URL parsing benchmark result */
+export interface UrlParsingBenchmarkResult {
+    averageTime: number;
+    minTime: number;
+    maxTime: number;
+    totalTime: number;
+}
+/** Memory test result */
+export interface MemoryTestResult {
+    heapUsedBefore: number;
+    heapUsedAfter: number;
+    heapUsedDelta: number;
+    rssBefore: number;
+    rssAfter: number;
+    rssDelta: number;
+}
+/** Memory usage result */
+export interface MemoryUsageResult<T> {
+    averageHeapUsed: number;
+    maxHeapUsed: number;
+    memoryLeakDetected: boolean;
+    results: T[];
+}
+/** Route handler memory leak result */
+export interface RouteHandlerMemoryLeakResult {
+    memoryLeakDetected: boolean;
+    initialMemory: number;
+    finalMemory: number;
+    memoryGrowth: number;
+}
+/** Ramp up test options */
+export interface RampUpTestOptions {
+    startConcurrency: number;
+    endConcurrency: number;
+    rampUpTime: number;
+    testDuration: number;
+}
+/** Ramp up test result */
+export interface RampUpTestResult {
+    concurrency: number;
+    requestsPerSecond: number;
+    averageResponseTime: number;
+    errorRate: number;
+}
+/** Spike test options */
+export interface SpikeTestOptions {
+    normalLoad: number;
+    spikeLoad: number;
+    spikeDuration: number;
+}
+/** Spike test result */
+export interface SpikeTestResult {
+    normalPhase: any;
+    spikePhase: any;
+    recoveryPhase: any;
+}
+/**
+ * Performance testing utilities
+ */
+export declare class PerformanceTester {
+    private metrics;
+    private startTime;
+    private endTime;
+    /**
+     * Start performance measurement
+     */
+    start(): PerformanceTester;
+    /**
+     * End performance measurement
+     */
+    end(): PerformanceTester;
+    /**
+     * Record a performance metric
+     */
+    recordMetric(metric: PerformanceMetrics): PerformanceTester;
+    /**
+     * Get elapsed time
+     */
+    getElapsedTime(): number;
+    /**
+     * Get all recorded metrics
+     */
+    getMetrics(): PerformanceMetrics[];
+    /**
+     * Get average response time
+     */
+    getAverageResponseTime(): number;
+    /**
+     * Get memory usage statistics
+     */
+    getMemoryStats(): {
+        averageHeapUsed: number;
+        maxHeapUsed: number;
+        averageRSS: number;
+        maxRSS: number;
+    };
+    /**
+     * Clear all metrics
+     */
+    clear(): PerformanceTester;
+}
+/**
+ * Load testing utilities
+ */
+export declare class LoadTester {
+    private client;
+    private config;
+    constructor(client: TestClient, config: LoadTestConfig);
+    /**
+     * Run load test
+     */
+    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;
+}
+/** Route matching benchmark result */
+export interface RouteMatchingBenchmarkResult {
+    averageTime: number;
+    minTime: number;
+    maxTime: number;
+    totalTime: number;
+    matchRate: number;
+}
+/**
+ * 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) => void;
+    /**
+     * Assert throughput meets minimum requirements
+     */
+    throughputAtLeast: (actualThroughput: number, minThroughput: number) => void;
+    /**
+     * Assert error rate is acceptable
+     */
+    errorRateBelow: (errorRate: number, maxErrorRate: number) => void;
+    /**
+     * Assert memory usage is within limits
+     */
+    memoryUsageWithin: (actualUsage: number, maxUsage: number) => void;
+    /**
+     * Assert no memory leaks detected
+     */
+    noMemoryLeaks: (memoryGrowth: number, threshold?: number) => void;
+};
+/**
+ * Factory functions
+ */
+export declare function createPerformanceTester(): PerformanceTester;
+export declare function createLoadTester(client: TestClient, config: LoadTestConfig): LoadTester;
+/**
+ * Performance test utilities
+ */
+export declare const performanceUtils: {
+    /**
+     * Get current memory usage
+     */
+    getCurrentMemoryUsage: () => PerformanceMetrics["memoryUsage"];
+    /**
+     * Get CPU usage
+     */
+    getCPUUsage: () => PerformanceMetrics["cpuUsage"];
+    /**
+     * Create performance metric snapshot
+     */
+    createMetricSnapshot: (responseTime: number) => PerformanceMetrics;
+    /**
+     * Format performance results for display
+     */
+    formatResults: (results: any) => string;
+};

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

@@ -0,0 +1,117 @@
+import type { Router } from '../router/router';
+import type { TestResponseWrapper } from './test-response';
+import type { TestClientConfig, TestRequestOptions } from './types';
+/**
+ * Test client for making HTTP requests to router instances
+ */
+export declare class TestClient {
+    private router;
+    private config;
+    private defaultHeaders;
+    constructor(router: Router, config?: TestClientConfig);
+    /**
+     * Make a GET request
+     */
+    get(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+    /**
+     * Make a POST request
+     */
+    post(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+    /**
+     * Make a PUT request
+     */
+    put(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+    /**
+     * Make a PATCH request
+     */
+    patch(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+    /**
+     * Make a DELETE request
+     */
+    delete(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+    /**
+     * Make an OPTIONS request
+     */
+    options(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+    /**
+     * Make a HEAD request
+     */
+    head(path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+    /**
+     * Make a request with custom method
+     */
+    request(method: string, path: string, options?: TestRequestOptions): Promise<TestResponseWrapper>;
+    /**
+     * Handle request through the router
+     */
+    private handleRequest;
+    /**
+     * Find matching route for the request
+     */
+    private findMatchingRoute;
+    /**
+     * Simple path matching with parameter extraction
+     */
+    private matchPath;
+    /**
+     * Execute middleware chain and route handler
+     */
+    private executeMiddlewareChain;
+    /**
+     * Execute route handler
+     */
+    private executeHandler;
+    /**
+     * Set default headers for all requests
+     */
+    setDefaultHeaders(headers: Record<string, string>): TestClient;
+    /**
+     * Set authorization header for all requests
+     */
+    auth(token: string, type?: 'Bearer' | 'Basic'): TestClient;
+    /**
+     * Set user agent for all requests
+     */
+    userAgent(userAgent: string): TestClient;
+    /**
+     * Create a new test client with additional configuration
+     */
+    withConfig(config: Partial<TestClientConfig>): TestClient;
+    /**
+     * Create a new test client with additional headers
+     */
+    withHeaders(headers: Record<string, string>): TestClient;
+    /**
+     * Get the router instance
+     */
+    getRouter(): Router;
+    /**
+     * Get client configuration
+     */
+    getConfig(): TestClientConfig;
+}
+/**
+ * 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) => TestClient;
+    /**
+     * Create a test client with specific configuration
+     */
+    withConfig: (config: TestClientConfig) => (router: Router) => TestClient;
+    /**
+     * Create a test client with authentication
+     */
+    withAuth: (token: string, type?: "Bearer" | "Basic") => (router: Router) => TestClient;
+    /**
+     * Create a test client with custom headers
+     */
+    withHeaders: (headers: Record<string, string>) => (router: Router) => TestClient;
+};