@stacksjs/bun-router 0.0.5 → 0.0.7

package/dist/routing/route-throttling.d.ts

@@ -0,0 +1,150 @@
+import type { EnhancedRequest, MiddlewareHandler, ThrottlePattern } from '../types';
+import { LRUCache } from '../cache/lru-cache';
+/**
+ * Throttle configuration for rate limiting
+ */
+export interface ThrottleConfig {
+    maxAttempts: number;
+    windowMs: number;
+    keyGenerator?: (req: EnhancedRequest) => string;
+    skipIf?: (req: EnhancedRequest) => boolean;
+    onLimitReached?: (req: EnhancedRequest, info: RateLimitInfo) => Response;
+    headers?: boolean;
+    maxRequests?: number;
+}
+/**
+ * Rate limit information
+ */
+export interface RateLimitInfo {
+    totalHits: number;
+    totalHits24h?: number;
+    resetTime: Date;
+    remaining: number;
+    limit: number;
+    windowMs: number;
+}
+/**
+ * Rate limit entry stored in cache
+ */
+interface RateLimitEntry {
+    count: number;
+    resetTime: number;
+    firstHit: number;
+}
+/**
+ * Rate limiter implementation
+ */
+export declare class RateLimiter {
+    private cache;
+    private config;
+    constructor(config: ThrottleConfig, cacheSize?: number);
+    /**
+     * Check if request should be rate limited
+     */
+    checkLimit(req: EnhancedRequest): Promise<{
+        allowed: boolean;
+        info: RateLimitInfo;
+    }>;
+    /**
+     * Generate cache key for rate limiting
+     */
+    private generateKey;
+    /**
+     * Extract client IP from request
+     */
+    private getClientIP;
+    /**
+     * Get current statistics
+     */
+    getStats(): ReturnType<LRUCache<RateLimitEntry>['getStats']> & {
+        config: {
+            maxAttempts: number;
+            windowMs: number;
+        };
+    };
+}
+/**
+ * Global rate limiters registry
+ */
+export declare class RateLimitRegistry {
+    private limiters;
+    /**
+     * Register a rate limiter
+     */
+    register(name: string, config: ThrottleConfig): RateLimiter;
+    /**
+     * Get rate limiter by name
+     */
+    get(name: string): RateLimiter | undefined;
+    /**
+     * Create or get rate limiter
+     */
+    getOrCreate(name: string, config: ThrottleConfig): RateLimiter;
+}
+/**
+ * Global rate limit registry instance
+ */
+export declare const rateLimitRegistry: RateLimitRegistry;
+/**
+ * Create rate limiting middleware
+ */
+export declare function createRateLimitMiddleware(config: ThrottleConfig, name?: string): MiddlewareHandler;
+/**
+ * Parse throttle string (Laravel-style) with enhanced time unit support
+ * Examples: '60,1' -> 60 requests per 1 minute
+ *          '100,30s' -> 100 requests per 30 seconds
+ *          '1000,1h' -> 1000 requests per 1 hour
+ *          '60' -> 60 requests per 1 minute (default)
+ */
+export declare function parseThrottleString(throttleStr: ThrottlePattern): ThrottleConfig;
+/**
+ * Factory functions for common rate limiting scenarios
+ */
+export declare const ThrottleFactory: {
+    /**
+     * API rate limiting (60 requests per minute)
+     */
+    api: (maxAttempts?: number, windowMinutes?: number) => ThrottleConfig;
+    /**
+     * Authentication rate limiting (5 attempts per 15 minutes)
+     */
+    auth: () => ThrottleConfig;
+    /**
+     * Upload rate limiting (10 uploads per hour)
+     */
+    upload: () => ThrottleConfig;
+    /**
+     * Search rate limiting (100 searches per 10 minutes)
+     */
+    search: () => ThrottleConfig;
+    /**
+     * Per-user rate limiting
+     */
+    perUser: (maxAttempts: number, windowMinutes: number) => ThrottleConfig;
+    /**
+     * Per-IP rate limiting
+     */
+    perIP: (maxAttempts: number, windowMinutes: number) => ThrottleConfig;
+    /**
+     * Global rate limiting (shared across all users)
+     */
+    global: (maxAttempts: number, windowMinutes: number) => ThrottleConfig;
+};
+/**
+ * Rate limit utilities
+ */
+export declare const RateLimitUtils: {
+    /**
+     * Create throttle middleware from string (Laravel-style)
+     */
+    fromString: (throttleStr: string, name?: string) => MiddlewareHandler;
+    /**
+     * Get rate limit info for a request without incrementing
+     */
+    getInfo: (req: EnhancedRequest, config: ThrottleConfig) => Promise<RateLimitInfo>;
+    /**
+     * Reset rate limit for a specific key
+     */
+    reset: (limiterName: string, key: string) => boolean;
+};
+export {};

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

@@ -0,0 +1,206 @@
+import type { EnhancedRequest, MiddlewareHandler, RouteHandler } from '../types';
+/**
+ * Domain pattern configuration
+ */
+export interface DomainPattern {
+    pattern: string;
+    parameters: string[];
+    regex: RegExp;
+}
+/**
+ * Domain group configuration
+ */
+export interface DomainGroupConfig {
+    domain: string;
+    middleware?: MiddlewareHandler[];
+    prefix?: string;
+    name?: string;
+}
+/**
+ * Subdomain route information
+ */
+export interface SubdomainRouteInfo {
+    domain: string;
+    parameters: Record<string, string>;
+    subdomain?: string;
+    rootDomain?: string;
+}
+/**
+ * Domain pattern parser and matcher
+ */
+export declare class DomainMatcher {
+    /**
+     * Parse domain pattern into regex and parameter names
+     */
+    static parseDomainPattern(pattern: string): DomainPattern;
+    /**
+     * Match domain against pattern and extract parameters
+     */
+    static matchDomain(domain: string, pattern: DomainPattern): Record<string, string> | null;
+    /**
+     * Extract subdomain information from domain
+     */
+    static extractSubdomainInfo(domain: string): SubdomainRouteInfo;
+}
+/**
+ * Domain group for organizing routes by domain patterns
+ */
+export declare class DomainGroup {
+    pattern: DomainPattern;
+    config: DomainGroupConfig;
+    private routes;
+    constructor(pattern: DomainPattern, config: DomainGroupConfig);
+    /**
+     * Add route to domain group
+     */
+    addRoute(method: string, path: string, handler: RouteHandler, middleware?: MiddlewareHandler[], name?: string): void;
+    /**
+     * Get all routes in this domain group
+     */
+    getRoutes(): Array<{
+        method: string;
+        path: string;
+        handler: RouteHandler;
+        middleware: MiddlewareHandler[];
+    }>;
+    /**
+     * Check if domain matches this group's pattern
+     */
+    matchesDomain(domain: string): Record<string, string> | null;
+}
+/**
+ * Subdomain router for managing domain-based routing
+ */
+export declare class SubdomainRouter {
+    private domainGroups;
+    private wildcardGroup?;
+    /**
+     * Create domain group with pattern
+     */
+    domain(pattern: string): DomainGroupBuilder;
+    /**
+     * Add domain group to router
+     */
+    addDomainGroup(group: DomainGroup): void;
+    /**
+     * Find matching domain group and extract parameters
+     */
+    findDomainGroup(domain: string): {
+        group: DomainGroup;
+        parameters: Record<string, string>;
+    } | null;
+    /**
+     * Get all routes from all domain groups
+     */
+    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 router;
+    private pattern;
+    private group;
+    constructor(router: SubdomainRouter, pattern: DomainPattern);
+    /**
+     * Set middleware for domain group
+     */
+    middleware(middleware: MiddlewareHandler[]): this;
+    /**
+     * Set prefix for all routes in group
+     */
+    prefix(prefix: string): this;
+    /**
+     * Set name prefix for routes in group
+     */
+    name(name: string): this;
+    /**
+     * Define routes within domain group
+     */
+    routes(callback: (builder: RouteGroupBuilder) => void): void;
+    /**
+     * Add single route (shorthand)
+     */
+    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;
+    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;
+}
+/**
+ * Create subdomain routing middleware
+ */
+export declare function createSubdomainMiddleware(subdomainRouter: SubdomainRouter): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Utility functions for subdomain routing
+ */
+export declare const SubdomainUtils: {
+    /**
+     * Extract subdomain from request
+     */
+    getSubdomain: (req: EnhancedRequest) => string | null;
+    /**
+     * Get domain parameters from request
+     */
+    getDomainParams: (req: EnhancedRequest) => Record<string, string>;
+    /**
+     * Check if request matches domain pattern
+     */
+    matchesDomain: (req: EnhancedRequest, pattern: string) => boolean;
+    /**
+     * Get full subdomain info from request
+     */
+    getSubdomainInfo: (req: EnhancedRequest) => SubdomainRouteInfo | null;
+};
+/**
+ * Factory functions for common subdomain patterns
+ */
+export declare const SubdomainPatterns: {
+    /**
+     * Single subdomain pattern (e.g., api.example.com)
+     */
+    single: (subdomain: string, domain: string) => string;
+    /**
+     * Wildcard subdomain pattern (e.g., {account}.example.com)
+     */
+    wildcard: (domain: string, paramName?: string) => string;
+    /**
+     * Multi-level subdomain (e.g., {service}.{env}.example.com)
+     */
+    multiLevel: (domain: string, ...paramNames: string[]) => string;
+    /**
+     * API versioning pattern (e.g., v1.api.example.com)
+     */
+    apiVersion: (domain: string) => string;
+    /**
+     * Tenant pattern (e.g., {tenant}.app.example.com)
+     */
+    tenant: (domain: string) => string;
+    /**
+     * Environment pattern (e.g., {env}.example.com)
+     */
+    environment: (domain: string) => string;
+};

package/dist/session/database-store.d.ts

@@ -0,0 +1,51 @@
+import type { SessionData, SessionStore } from '../types/core';
+/**
+ * Minimal database adapter interface for session storage.
+ * Implement this with your ORM (Kysely, Drizzle, etc.).
+ */
+export interface SessionDatabaseAdapter {
+    findSession(sid: string): Promise<{
+        payload: string;
+        last_activity: number;
+    } | null>;
+    upsertSession(sid: string, payload: string, lastActivity: number): Promise<void>;
+    deleteSession(sid: string): Promise<void>;
+    getAllSessions(): Promise<Array<{
+        id: string;
+        payload: string;
+        last_activity: number;
+    }>>;
+    deleteExpiredSessions(maxAge: number): Promise<void>;
+    countSessions(): Promise<number>;
+    clearAllSessions(): Promise<void>;
+}
+/**
+ * Database-backed session store.
+ * Persists sessions in a database table.
+ *
+ * Expected table schema:
+ * ```sql
+ * CREATE TABLE sessions (
+ *   id VARCHAR(255) PRIMARY KEY,
+ *   user_id INTEGER NULL,
+ *   ip_address VARCHAR(45) NULL,
+ *   user_agent TEXT NULL,
+ *   payload TEXT NOT NULL,
+ *   last_activity INTEGER NOT NULL
+ * );
+ * ```
+ */
+export declare class DatabaseSessionStore implements SessionStore<SessionData> {
+    private adapter;
+    private defaultTtl;
+    private cleanupInterval;
+    constructor(adapter: SessionDatabaseAdapter, defaultTtl?: number);
+    get(sid: string): Promise<SessionData | null>;
+    set(sid: string, session: SessionData, _ttl?: number): Promise<void>;
+    destroy(sid: string): Promise<void>;
+    touch(sid: string, session: SessionData, _ttl?: number): Promise<void>;
+    all(): Promise<Record<string, SessionData>>;
+    length(): Promise<number>;
+    clear(): Promise<void>;
+    dispose(): void;
+}

package/dist/session/file-store.d.ts

@@ -0,0 +1,22 @@
+import type { SessionData, SessionStore } from '../types/core';
+/**
+ * File-based session store.
+ * Persists sessions to disk as JSON files.
+ * Suitable for single-server deployments.
+ */
+export declare class FileSessionStore implements SessionStore<SessionData> {
+    private defaultTtl;
+    private dir;
+    private cleanupInterval;
+    constructor(defaultTtl?: number, dir?: string);
+    private filePath;
+    get(sid: string): Promise<SessionData | null>;
+    set(sid: string, session: SessionData, ttl?: number): Promise<void>;
+    destroy(sid: string): Promise<void>;
+    touch(sid: string, session: SessionData, ttl?: number): Promise<void>;
+    all(): Promise<Record<string, SessionData>>;
+    length(): Promise<number>;
+    clear(): Promise<void>;
+    private cleanup;
+    dispose(): void;
+}

package/dist/session/index.d.ts

@@ -0,0 +1,106 @@
+import type { SessionData, SessionStore } from '../types/core';
+import type { RedisClient } from './redis-store';
+import type { SessionDatabaseAdapter } from './database-store';
+export { MemorySessionStore } from './memory-store';
+export { FileSessionStore } from './file-store';
+export { RedisSessionStore } from './redis-store';
+export type { RedisClient } from './redis-store';
+export { DatabaseSessionStore } from './database-store';
+export type { SessionDatabaseAdapter } from './database-store';
+export interface SessionConfig {
+    driver: 'memory' | 'file' | 'redis' | 'database';
+    ttl?: number;
+    cookie?: {
+        name?: string;
+        maxAge?: number;
+        path?: string;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: 'strict' | 'lax' | 'none';
+    };
+    file?: {
+        dir?: string;
+    };
+    redis?: {
+        client: RedisClient;
+        prefix?: string;
+    };
+    database?: {
+        adapter: SessionDatabaseAdapter;
+    };
+}
+/**
+ * Create a session store based on configuration
+ */
+export declare function createSessionStore(config: SessionConfig): SessionStore<SessionData>;
+/**
+ * Session manager for request handling.
+ * Wraps a SessionStore and provides flash data, regeneration, etc.
+ */
+export declare class SessionManager {
+    private sessionId;
+    private data;
+    private store;
+    private flashedKeys;
+    private previousFlash;
+    private dirty;
+    constructor(sessionId: string, data: SessionData, store: SessionStore<SessionData>);
+    get id(): string;
+    /**
+     * Get a value from the session
+     */
+    get<T = unknown>(key: string): T | undefined;
+    /**
+     * Set a value in the session
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Check if a key exists in the session
+     */
+    has(key: string): boolean;
+    /**
+     * Remove a value from the session
+     */
+    forget(key: string): void;
+    /**
+     * Get all session data
+     */
+    all(): Record<string, unknown>;
+    /**
+     * Flash a key-value pair for the next request only
+     */
+    flash(key: string, value: unknown): void;
+    /**
+     * Get a flash value (available for current request)
+     */
+    getFlash<T = unknown>(key: string): T | undefined;
+    /**
+     * Keep specific flash data for another request
+     */
+    keep(keys: string[]): void;
+    /**
+     * Reflash all flash data for another request
+     */
+    reflash(): void;
+    /**
+     * Regenerate session ID (keeps data)
+     */
+    regenerate(): Promise<string>;
+    /**
+     * Invalidate the session (new ID, clear data)
+     */
+    invalidate(): Promise<string>;
+    /**
+     * Save session data to the store.
+     * Call this at the end of the request.
+     */
+    save(): Promise<void>;
+    /**
+     * Destroy the session completely
+     */
+    destroy(): Promise<void>;
+}
+/**
+ * Generate a cryptographically secure session ID
+ */
+export declare function generateSessionId(): string;

package/dist/session/memory-store.d.ts

@@ -0,0 +1,21 @@
+import type { SessionData, SessionStore } from '../types/core';
+/**
+ * In-memory session store.
+ * Fast but data is lost on server restart.
+ * Suitable for development or single-process deployments.
+ */
+export declare class MemorySessionStore implements SessionStore<SessionData> {
+    private defaultTtl;
+    private sessions;
+    private cleanupInterval;
+    constructor(defaultTtl?: number);
+    get(sid: string): Promise<SessionData | null>;
+    set(sid: string, session: SessionData, ttl?: number): Promise<void>;
+    destroy(sid: string): Promise<void>;
+    touch(sid: string, session: SessionData, ttl?: number): Promise<void>;
+    all(): Promise<Record<string, SessionData>>;
+    length(): Promise<number>;
+    clear(): Promise<void>;
+    private cleanup;
+    dispose(): void;
+}

package/dist/session/redis-store.d.ts

@@ -0,0 +1,31 @@
+import type { SessionData, SessionStore } from '../types/core';
+/**
+ * Minimal Redis client interface.
+ * Compatible with ioredis, node-redis, or any client implementing these methods.
+ */
+export interface RedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: any[]): Promise<any>;
+    del(key: string | string[]): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+}
+/**
+ * Redis-backed session store.
+ * Ideal for distributed/multi-server deployments.
+ * Requires a Redis client to be passed in.
+ */
+export declare class RedisSessionStore implements SessionStore<SessionData> {
+    private client;
+    private defaultTtl;
+    private prefix;
+    constructor(client: RedisClient, defaultTtl?: number, prefix?: string);
+    private key;
+    get(sid: string): Promise<SessionData | null>;
+    set(sid: string, session: SessionData, ttl?: number): Promise<void>;
+    destroy(sid: string): Promise<void>;
+    touch(sid: string, session: SessionData, ttl?: number): Promise<void>;
+    all(): Promise<Record<string, SessionData>>;
+    length(): Promise<number>;
+    clear(): Promise<void>;
+}

package/dist/streaming/index.d.ts

@@ -0,0 +1,3 @@
+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';