@stacksjs/bun-router 0.0.2

package/dist/routing/subdomain-routing.d.ts

@@ -0,0 +1,159 @@
+import type { MiddlewareHandler, RouteHandler } from '../types';
+/**
+ * Create subdomain routing middleware
+ */
+export declare function createSubdomainMiddleware(subdomainRouter: SubdomainRouter): void;
+/**
+ * Utility functions for subdomain routing
+ */
+export declare const SubdomainUtils: {
+  /**
+   * Extract subdomain from request
+   */
+  getSubdomain: (req: EnhancedRequest) => any;
+  /**
+   * Get domain parameters from request
+   */
+  getDomainParams: (req: EnhancedRequest) => unknown;
+  /**
+   * Check if request matches domain pattern
+   */
+  matchesDomain: (req: EnhancedRequest, pattern: string) => any;
+  /**
+   * Get full subdomain info from request
+   */
+  getSubdomainInfo: (req: EnhancedRequest) => any
+};
+/**
+ * Factory functions for common subdomain patterns
+ */
+export declare const SubdomainPatterns: {
+  /**
+   * Single subdomain pattern (e.g., api.example.com)
+   */
+  single: (subdomain: string, domain: string) => any;
+  /**
+   * Wildcard subdomain pattern (e.g., {account}.example.com)
+   */
+  wildcard: (domain: string, paramName: string?) => any;
+  /**
+   * Multi-level subdomain (e.g., {service}.{env}.example.com)
+   */
+  multiLevel: (domain: string, ...paramNames: string[]) => any;
+  /**
+   * API versioning pattern (e.g., v1.api.example.com)
+   */
+  apiVersion: (domain: string) => any;
+  /**
+   * Tenant pattern (e.g., {tenant}.app.example.com)
+   */
+  tenant: (domain: string) => any;
+  /**
+   * Environment pattern (e.g., {env}.example.com)
+   */
+  environment: (domain: string) => any
+};
+/**
+ * Domain pattern configuration
+ */
+export declare interface DomainPattern {
+  pattern: string
+  parameters: string[]
+  regex: RegExp
+}
+/**
+ * Domain group configuration
+ */
+export declare interface DomainGroupConfig {
+  domain: string
+  middleware?: MiddlewareHandler[]
+  prefix?: string
+  name?: string
+}
+/**
+ * Subdomain route information
+ */
+export declare interface SubdomainRouteInfo {
+  domain: string
+  parameters: Record<string, string>
+  subdomain?: string
+  rootDomain?: string
+}
+/**
+ * Domain pattern parser and matcher
+ */
+export declare class DomainMatcher {
+  static parseDomainPattern(pattern: string): DomainPattern;
+  static matchDomain(domain: string, pattern: DomainPattern): Record<string, string> | null;
+  static extractSubdomainInfo(domain: string): SubdomainRouteInfo;
+}
+/**
+ * Domain group for organizing routes by domain patterns
+ */
+export declare class DomainGroup {
+  private routes: Array<{
+    method: string
+    path: string
+    handler: RouteHandler
+    middleware: MiddlewareHandler[]
+    name?: string
+  }>;
+  public pattern: DomainPattern;
+  public config: DomainGroupConfig;
+  constructor(pattern: DomainPattern, config: DomainGroupConfig);
+  addRoute(method: string, path: string, handler: RouteHandler, middleware?: MiddlewareHandler[], name?: string): void;
+  getRoutes(): Array<{ method: string, path: string, handler: RouteHandler, middleware: MiddlewareHandler[] }>;
+  matchesDomain(domain: string): Record<string, string> | null;
+}
+/**
+ * Subdomain router for managing domain-based routing
+ */
+export declare class SubdomainRouter {
+  private domainGroups: DomainGroup[];
+  private wildcardGroup?: DomainGroup;
+  domain(pattern: string): DomainGroupBuilder;
+  addDomainGroup(group: DomainGroup): void;
+  findDomainGroup(domain: string): { group: DomainGroup, parameters: Record<string, string> } | null;
+  getAllRoutes(): Array<{
+    domainPattern: string
+    domainParameters: Record<string, string>
+    method: string
+    path: string
+    handler: RouteHandler
+    middleware: MiddlewareHandler[]
+    name?: string
+  }>;
+}
+/**
+ * Domain group builder for fluent API
+ */
+export declare class DomainGroupBuilder {
+  private group: DomainGroup;
+  private router: SubdomainRouter;
+  private pattern: DomainPattern;
+  constructor(router: SubdomainRouter, pattern: DomainPattern);
+  middleware(middleware: MiddlewareHandler[]): this;
+  prefix(prefix: string): this;
+  name(name: string): this;
+  routes(callback: (builder: RouteGroupBuilder) => void): void;
+  get(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[]): void;
+  post(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[]): void;
+  put(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[]): void;
+  delete(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[]): void;
+  patch(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[]): void;
+}
+/**
+ * Route group builder for defining routes within domain groups
+ */
+export declare class RouteGroupBuilder {
+  private group: DomainGroup;
+  constructor(group: DomainGroup);
+  get(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[], name?: string): void;
+  post(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[], name?: string): void;
+  put(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[], name?: string): void;
+  delete(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[], name?: string): void;
+  patch(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[], name?: string): void;
+  options(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[], name?: string): void;
+  head(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[], name?: string): void;
+  any(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[], name?: string): void;
+}

package/dist/streaming/index.d.ts

@@ -0,0 +1,15 @@
+export type { SSEConfig, SSEEvent } from '../types';
+export {
+  createSSEMiddleware,
+  SSEConnectionManager,
+  SSEHandler,
+  sseManager,
+  SSEUtils,
+} from './sse-handler';
+export {
+  type BaseStreamConfig,
+  FileStreamHandler,
+  StreamHandler,
+  StreamResponse,
+  StreamUtils,
+} from './stream-handler';

package/dist/streaming/sse-handler.d.ts

@@ -0,0 +1,81 @@
+import type { SSEConfig, SSEEvent,  } from '../types';
+/**
+ * SSE middleware for route handlers
+ */
+export declare function createSSEMiddleware(config?: SSEConfig): void;
+/**
+ * Global SSE connection manager instance
+ */
+export declare const sseManager: SSEConnectionManager;
+/**
+ * SSE utility functions
+ */
+export declare const SSEUtils: {
+  /**
+   * Create a simple SSE route handler
+   */
+  createHandler<TPath extends string>(
+    handler: SSERouteHandler<TPath>,
+  ): (req: EnhancedRequest & { params: ExtractRouteParams<TPath> }) => unknown;
+  /**
+   * Create SSE event from object
+   */
+  createEvent(data: any, options: Partial<SSEEvent> = {}): unknown;
+  /**
+   * Validate SSE event
+   */
+  validateEvent(event: SSEEvent): unknown;
+  /**
+   * Create periodic SSE sender
+   */
+  createPeriodicSender(
+    sse: SSEHandler,
+    dataFn: () => any | Promise<any>,
+    intervalMs: number,
+  ): () => unknown;
+  /**
+   * Create SSE from async iterable
+   */
+  async fromAsyncIterable<T>(
+    sse: SSEHandler,
+    iterable: AsyncIterable<T>,
+    transform?: (item: T) => SSEEvent,
+  ): unknown
+};
+/**
+ * Server-Sent Events handler
+ */
+export declare class SSEHandler {
+  private config: Required<SSEConfig>;
+  private controller?: ReadableStreamDefaultController<Uint8Array>;
+  private encoder: any;
+  private isConnected: any;
+  private heartbeatInterval?: Timer;
+  constructor(config?: SSEConfig);
+  createStream(): Response;
+  send(event: SSEEvent): boolean;
+  sendBatch(events: SSEEvent[]): number;
+  message(data: any, id?: string): boolean;
+  event(type: string, data: any, id?: string): boolean;
+  comment(text: string): boolean;
+  close(): void;
+  private formatEvent(event: SSEEvent): string;
+  private setupHeartbeat(): void;
+  private clearHeartbeat(): void;
+  private sendRetryDelay(): void;
+  private disconnect(): void;
+}
+/**
+ * SSE connection manager
+ */
+export declare class SSEConnectionManager {
+  private connections: any;
+  private connectionCounts: any;
+  createConnection(connectionId: string, config?: SSEConfig): SSEHandler;
+  getConnection(connectionId: string): SSEHandler | undefined;
+  closeConnection(connectionId: string): boolean;
+  broadcast(event: SSEEvent): number;
+  broadcastToConnections(connectionIds: string[], event: SSEEvent): number;
+  getStats(): { totalConnections: number, connectionsByUser: Record<string, number>, activeConnections: string[] };
+  cleanup(): void;
+}

package/dist/streaming/stream-handler.d.ts

@@ -0,0 +1,81 @@
+import type { BunFile } from 'bun';
+import type { BufferedStreamConfig, ContentType, DirectStreamConfig, EnhancedRequest, ResponseStatus, StreamingCompression, StreamingFormat,  } from '../types';
+/**
+ * Stream utilities
+ */
+export declare const StreamUtils: {
+  U>(
+    transformFn: (chunk: T) => U | Promise<U>,
+  ): unknown;
+  /**
+   * Create a filter stream
+   */
+  filter<T>(
+    filterFn: (chunk: T) => boolean | Promise<boolean>,
+  ): unknown;
+  /**
+   * Create a batch stream
+   */
+  batch<T>(batchSize: number): unknown;
+  /**
+   * Create a delay stream
+   */
+  delay<T>(ms: number): unknown;
+  /**
+   * Create a rate limit stream
+   */
+  rateLimit<T>(itemsPerSecond: number): unknown
+};
+/**
+ * Base streaming configuration
+ */
+export declare interface BaseStreamConfig {
+  contentType?: ContentType
+  headers?: Record<string, string>
+  status?: ResponseStatus
+  bufferSize?: number
+  enableCompression?: boolean
+  compressionType?: StreamingCompression
+}
+/**
+ * Stream response wrapper
+ */
+export declare class StreamResponse {
+  private stream: ReadableStream;
+  private headers: Headers;
+  private status: ResponseStatus;
+  constructor(stream: ReadableStream, options?: {
+      headers?: Headers | Record<string, string>
+      status?: ResponseStatus
+      contentType?: ContentType
+    });
+  toResponse(): Response;
+  addHeader(name: string, value: string): this;
+  setContentType(contentType: ContentType): this;
+  setStatus(status: ResponseStatus): this;
+}
+/**
+ * Generic streaming handler
+ */
+export declare class StreamHandler {
+  static direct<T>(data: T[] | AsyncIterable<T>, config?: DirectStreamConfig): StreamResponse;
+  static buffered<T>(data: T[] | AsyncIterable<T>, config?: BufferedStreamConfig): StreamResponse;
+  static json<T>(data: T[] | AsyncIterable<T>, config?: BaseStreamConfig): StreamResponse;
+  static text(data: string[] | AsyncIterable<string>, config?: BaseStreamConfig): StreamResponse;
+  static csv<T extends Record<string, any>>(data: T[] | AsyncIterable<T>, config?: BaseStreamConfig & { csvHeaders?: string[] }): StreamResponse;
+  static private formatData<T>(data: T, format: StreamingFormat): string;
+  static private objectToCsvRow(obj: Record<string, any>, headers?: string[]): string;
+  static private getContentTypeForFormat(format: StreamingFormat): ContentType;
+}
+/**
+ * File streaming utilities
+ */
+export declare class FileStreamHandler {
+  static streamFile(filePath: string, request: EnhancedRequest, options?: {
+      contentType?: ContentType
+      enableRanges?: boolean
+      chunkSize?: number
+    }): Promise<Response>;
+  static private handleRangeRequest(file: BunFile, rangeHeader: string, contentType?: ContentType): Promise<Response>;
+  static private parseRangeHeader(rangeHeader: string, fileSize: number): [number, number][] | null;
+}

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

@@ -0,0 +1,107 @@
+import type { EnhancedRequest } from '../types';
+import type { JWTTestOptions, SessionTestOptions, TestUser } from './types';
+/**
+ * Factory functions
+ */
+export declare function createAuthTester(request?: EnhancedRequest): AuthTester;
+export declare function createJWTTester(options?: JWTTestOptions): JWTTester;
+export declare function createSessionTester(options?: SessionTestOptions): SessionTester;
+/**
+ * Authentication mock factories
+ */
+export declare const authMocks: {
+  /**
+   * Create a mock user
+   */
+  user: (overrides: Partial<TestUser> = {}) => any;
+  /**
+   * Create an admin user
+   */
+  adminUser: (overrides: Partial<TestUser> = {}) => any;
+  /**
+   * Create a guest user
+   */
+  guestUser: () => any;
+  /**
+   * Mock authentication middleware
+   */
+  authMiddleware: (user?: TestUser) => any;
+  /**
+   * Mock role-based middleware
+   */
+  roleMiddleware: (requiredRoles: string[]) => any;
+  /**
+   * Mock permission-based middleware
+   */
+  permissionMiddleware: (requiredPermissions: string[]) => any
+};
+/**
+ * Helper functions
+ */
+export declare const authHelpers: {
+  /**
+   * Create an authenticated request
+   */
+  authenticatedRequest: (user: TestUser, request?: EnhancedRequest) => any;
+  /**
+   * Create a request with JWT
+   */
+  jwtRequest: (payload: Record<string, any> = {}, request?: EnhancedRequest) => any;
+  /**
+   * Create a request with session
+   */
+  sessionRequest: (sessionData: Record<string, any> = {}, request?: EnhancedRequest) => any;
+  /**
+   * Verify JWT token structure
+   */
+  verifyJWTStructure: (token: string) => any;
+  /**
+   * Extract payload from JWT (for testing)
+   */
+  extractJWTPayload: (token: string) => any
+};
+/**
+ * Authentication testing utilities
+ */
+export declare class AuthTester {
+  private request: EnhancedRequest;
+  constructor(request?: EnhancedRequest);
+  as(user: TestUser): AuthTester;
+  withJWT(token: string, type?: 'Bearer' | 'Basic'): AuthTester;
+  withSession(sessionData: any): AuthTester;
+  withApiKey(apiKey: string, headerName?: string): AuthTester;
+  withBasicAuth(username: string, password: string): AuthTester;
+  withAuthCookies(cookies: Record<string, string>): AuthTester;
+  unauthenticated(): AuthTester;
+  getRequest(): EnhancedRequest;
+}
+/**
+ * JWT testing utilities
+ */
+export declare class JWTTester {
+  private options: JWTTestOptions;
+  constructor(options?: JWTTestOptions);
+  generateToken(payload?: Record<string, any>): string;
+  generateExpiredToken(payload?: Record<string, any>): string;
+  generateInvalidToken(): string;
+  decodeToken(token: string): { header: any, payload: any, signature: string };
+  private parseExpiresIn(expiresIn: string): number;
+}
+/**
+ * Session testing utilities
+ */
+export declare class SessionTester {
+  private options: SessionTestOptions;
+  constructor(options?: SessionTestOptions);
+  createSession(data?: Record<string, any>): {
+    sessionId: string
+    data: Record<string, any>
+    cookie: string
+  };
+  generateSessionCookie(name?: string): string;
+  createExpiredSession(): {
+    sessionId: string
+    data: Record<string, any>
+    cookie: string
+  };
+}

package/dist/testing/file-upload-testing.d.ts

@@ -0,0 +1,139 @@
+import type { EnhancedRequest, UploadedFile } from '../types';
+import type { TestFile } from './types';
+/**
+ * Factory functions
+ */
+export declare function createFileUploadTester(request?: EnhancedRequest): FileUploadTester;
+/**
+ * File upload mock factories
+ */
+export declare const fileUploadMocks: {
+  validationMiddleware: (options?: ValidationMiddlewareOptions) => MiddlewareFn
+  imageUploadMiddleware: (options?: ImageUploadMiddlewareOptions) => MiddlewareFn
+  storageService: FileStorageService
+  virusScanner: VirusScanner
+};
+/**
+ * File upload test scenarios
+ */
+export declare const fileUploadScenarios: {
+  /**
+   * Test successful single file upload
+   */
+  singleFileUpload: () => any;
+  /**
+   * Test multiple file upload
+   */
+  multipleFileUpload: () => any;
+  /**
+   * Test file size limit exceeded
+   */
+  fileSizeExceeded: () => any;
+  /**
+   * Test invalid file type
+   */
+  invalidFileType: () => any;
+  /**
+   * Test empty file upload
+   */
+  emptyFileUpload: () => any;
+  /**
+   * Test file with malicious filename
+   */
+  maliciousFilename: () => any
+};
+/**
+ * File upload assertion helpers
+ */
+export declare const fileUploadAssertions: {
+  /**
+   * Assert that request has files
+   */
+  hasFiles: (request: EnhancedRequest, count?: number) => any;
+  /**
+   * Assert that request has file with specific field name
+   */
+  hasFileWithField: (request: EnhancedRequest, fieldName: string) => any;
+  /**
+   * Assert file properties
+   */
+  fileMatches: (file: UploadedFile, expected: Partial<UploadedFile>) => any;
+  /**
+   * Assert file size is within limits
+   */
+  fileSizeWithinLimit: (file: UploadedFile, maxSize: number) => any;
+  /**
+   * Assert file type is allowed
+   */
+  fileTypeAllowed: (file: UploadedFile, allowedTypes: string[]) => any
+};
+/**
+ * Helper to create test files
+ */
+export declare const testFiles: {
+  image: (fieldName: string?, filename: string?) => any;
+  document: (fieldName: string?, filename: string?) => any;
+  text: (fieldName: string?, filename: string?, content: string?) => any;
+  large: (fieldName: string?, sizeInMB: number?) => any;
+  malicious: (fieldName: string?) => any
+};
+/** File storage service interface */
+export declare interface FileStorageService {
+  store: (file: UploadedFile, path?: string) => Promise<string>
+  delete: (path: string) => Promise<void>
+  exists: (path: string) => Promise<boolean>
+  getUrl: (path: string) => string
+}
+/** Virus scanner interface */
+export declare interface VirusScanResult {
+  clean: boolean
+  threat?: string
+}
+export declare interface VirusScanner {
+  scan: (file: UploadedFile) => Promise<VirusScanResult>
+}
+/** Validation middleware options */
+export declare interface ValidationMiddlewareOptions {
+  maxSize?: number
+  allowedTypes?: string[]
+  maxFiles?: number
+}
+/** Image upload middleware options */
+export declare interface ImageUploadMiddlewareOptions {
+  maxSize?: number
+  maxWidth?: number
+  maxHeight?: number
+}
+/** Middleware function type */
+export type MiddlewareFn = (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>
+/**
+ * File upload testing utilities
+ */
+export declare class FileUploadTester {
+  private request: EnhancedRequest;
+  private files: UploadedFile[];
+  constructor(request?: EnhancedRequest);
+  addFile(testFile: TestFile): FileUploadTester;
+  addFiles(testFiles: TestFile[]): FileUploadTester;
+  addImage(fieldName: string, filename?: string, size?: number): FileUploadTester;
+  addDocument(fieldName: string, filename?: string, content?: string): FileUploadTester;
+  addTextFile(fieldName: string, filename?: string, content?: string): FileUploadTester;
+  addLargeFile(fieldName: string, sizeInMB?: number): FileUploadTester;
+  addInvalidFile(fieldName: string, filename?: string): FileUploadTester;
+  withFormData(data: Record<string, any>): FileUploadTester;
+  getRequest(): EnhancedRequest;
+  getFiles(): UploadedFile[];
+  clearFiles(): FileUploadTester;
+  private detectMimeType(filename: string): string;
+}
+/**
+ * File validation testing utilities
+ */
+export declare class FileValidationTester {
+  static testFileSize(file: UploadedFile, maxSize: number): boolean;
+  static testFileType(file: UploadedFile, allowedTypes: string[]): boolean;
+  static testFileExtension(file: UploadedFile, allowedExtensions: string[]): boolean;
+  static testFilename(file: UploadedFile): boolean;
+  static testImageFile(file: UploadedFile): boolean;
+  static testDocumentFile(file: UploadedFile): boolean;
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,10 @@
+export * from './auth-testing';
+export * from './file-upload-testing';
+export * from './middleware-testing';
+export * from './model-binding-testing';
+export * from './performance-testing';
+export * from './test-client';
+export * from './test-request';
+export * from './test-response';
+export * from './types';
+export * from './websocket-testing';

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

@@ -0,0 +1,99 @@
+import { mock, spyOn } from 'bun:test';
+import type { EnhancedRequest, MiddlewareHandler, NextFunction } from '../types';
+import type { MiddlewareTestContext } from './types';
+/**
+ * Create a middleware tester
+ */
+export declare function testMiddleware(middleware: MiddlewareHandler): MiddlewareTester;
+/**
+ * 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
+  }>;
+/**
+ * Mock middleware factory
+ */
+export declare const mockMiddleware: {
+  /**
+   * Create a middleware that always calls next
+   */
+  passthrough: () => any;
+  /**
+   * Create a middleware that returns a response without calling next
+   */
+  response: (status: number?, body?: any) => any;
+  /**
+   * Create a middleware that throws an error
+   */
+  error: (message: string?) => any;
+  /**
+   * Create a middleware that modifies the request
+   */
+  modifyRequest: (modifier: (req: EnhancedRequest) => void) => any;
+  /**
+   * Create a middleware that adds context
+   */
+  addContext: (key: string, value: any) => any;
+  /**
+   * Create an authentication middleware mock
+   */
+  auth: (user?: any) => any;
+  /**
+   * Create a rate limiting middleware mock
+   */
+  rateLimit: (shouldLimit: boolean?) => any;
+  /**
+   * Create a CORS middleware mock
+   */
+  cors: (origin: string?) => any
+};
+/**
+ * Middleware testing utilities
+ */
+export declare class MiddlewareTester {
+  private middleware: MiddlewareHandler;
+  private context: MiddlewareTestContext;
+  constructor(middleware: MiddlewareHandler);
+  private createContext(): MiddlewareTestContext;
+  withRequest(request: EnhancedRequest): MiddlewareTester;
+  withNext(nextFn: NextFunction): MiddlewareTester;
+  withError(error: Error): MiddlewareTester;
+  execute(): Promise<Response | null>;
+  expectNextCalled(times?: number): MiddlewareTester;
+  expectNextNotCalled(): MiddlewareTester;
+  expectError(errorMessage?: string): MiddlewareTester;
+  getContext(): MiddlewareTestContext;
+  reset(): MiddlewareTester;
+}
+/**
+ * Middleware chain tester
+ */
+export declare class MiddlewareChainTester {
+  private middlewares: MiddlewareHandler[];
+  private request: EnhancedRequest;
+  private finalHandler: () => Promise<Response>;
+  constructor(middlewares: MiddlewareHandler[]);
+  withRequest(request: EnhancedRequest): MiddlewareChainTester;
+  withFinalHandler(handler: () => Promise<Response>): MiddlewareChainTester;
+  execute(): Promise<Response | null>;
+  getExecutionOrder(): number[];
+}