@stacksjs/bun-router 0.0.5 → 0.0.6

package/dist/auth.d.ts

@@ -0,0 +1,134 @@
+import type { EnhancedRequest, JwtPayload } from './types';
+export interface JwtVerifyOptions {
+    issuer?: string;
+    audience?: string;
+    subject?: string;
+    algorithms?: string[];
+    expiresIn?: string | number;
+    notBefore?: string | number;
+    ignoreExpiration?: boolean;
+    allowInvalidAsymmetricKeyTypes?: boolean;
+}
+export interface JwtSignOptions {
+    algorithm?: 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512' | 'ES256' | 'ES384' | 'ES512' | 'PS256' | 'PS384' | 'PS512' | 'none';
+    expiresIn?: string | number;
+    notBefore?: string | number;
+    audience?: string | string[];
+    issuer?: string;
+    subject?: string;
+    keyid?: string;
+    jwtid?: string;
+    noTimestamp?: boolean;
+    header?: Record<string, any>;
+    encoding?: string;
+}
+export interface ApiKeyOptions {
+    source?: 'header' | 'query' | 'cookie';
+    keyName?: string;
+    keyPrefix?: string;
+}
+export interface OAuth2Config {
+    clientId: string;
+    clientSecret: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    redirectUri: string;
+    scope?: string;
+    state?: string;
+}
+export type { JwtPayload };
+/**
+ * Simple JWT implementation for signing and verifying tokens
+ */
+export declare class JWT {
+    private secret;
+    constructor(secret: string);
+    /**
+     * Sign payload into a JWT token
+     */
+    sign(payload: Record<string, any>, options?: JwtSignOptions): string;
+    /**
+     * Verify a JWT token and return the decoded payload
+     */
+    verify(token: string, options?: JwtVerifyOptions): Record<string, any> | null;
+    /**
+     * Decode a JWT token without verifying the signature
+     */
+    decode(token: string): {
+        header: Record<string, any>;
+        payload: Record<string, any>;
+    } | null;
+    /**
+     * Simple signature creation - Note: This is NOT secure for production
+     * In a real app, use Bun's crypto functionality or a dedicated JWT library
+     */
+    private createSignature;
+    /**
+     * Parse timespan string to seconds
+     */
+    private parseTimespan;
+}
+/**
+ * API Key manager to generate, validate and handle API keys
+ */
+export declare class ApiKeyManager {
+    private keys;
+    private options;
+    constructor(options?: ApiKeyOptions);
+    /**
+     * Generate a new API key
+     */
+    generateKey(owner: string, scopes?: string[], expiresIn?: number): string;
+    /**
+     * Validate an API key
+     */
+    validateKey(key: string, requiredScopes?: string[]): boolean;
+    /**
+     * Get key information
+     */
+    getKeyInfo(key: string): {
+        owner: string;
+        scopes: string[];
+        expiresAt?: Date;
+    } | null;
+    /**
+     * Revoke an API key
+     */
+    revokeKey(key: string): boolean;
+    /**
+     * Extract API key from request based on configured source
+     */
+    extractFromRequest(req: EnhancedRequest): string | null;
+    /**
+     * Generate a random string for keys
+     */
+    private randomString;
+}
+/**
+ * OAuth2 helper for authorization code flow
+ */
+export declare class OAuth2Helper {
+    private config;
+    constructor(config: OAuth2Config);
+    /**
+     * Generate authorization URL for redirect
+     */
+    getAuthorizationUrl(additionalParams?: Record<string, string>): string;
+    /**
+     * Exchange authorization code for access token
+     */
+    exchangeCodeForToken(code: string): Promise<Record<string, any>>;
+    /**
+     * Refresh an access token using a refresh token
+     */
+    refreshToken(refreshToken: string): Promise<Record<string, any>>;
+}
+/**
+ * Authentication helpers namespace
+ */
+declare const Auth: {
+    JWT: typeof JWT;
+    ApiKeyManager: typeof ApiKeyManager;
+    OAuth2Helper: typeof OAuth2Helper;
+};
+export default Auth;

package/dist/cache/lru-cache.d.ts

@@ -0,0 +1,139 @@
+/**
+ * High-performance LRU (Least Recently Used) cache implementation
+ * Optimized for Bun runtime with configurable size limits and TTL support
+ */
+export interface LRUCacheOptions {
+    maxSize: number;
+    ttl?: number;
+    onEvict?: (key: string, value: any) => void;
+    allowStale?: boolean;
+    updateAgeOnGet?: boolean;
+}
+export interface CacheEntry<T = any> {
+    value: T;
+    timestamp: number;
+    accessCount: number;
+    lastAccessed: number;
+    ttl?: number;
+}
+export interface CacheStats {
+    size: number;
+    maxSize: number;
+    hits: number;
+    misses: number;
+    evictions: number;
+    hitRate: number;
+    memoryUsage: number;
+}
+/**
+ * High-performance LRU cache with TTL support and detailed statistics
+ */
+export declare class LRUCache<T = any> {
+    private options;
+    private cache;
+    private head;
+    private tail;
+    private stats;
+    constructor(options: LRUCacheOptions);
+    /**
+     * Get value from cache
+     */
+    get(key: string): T | undefined;
+    /**
+     * Set value in cache
+     */
+    set(key: string, value: T, ttl?: number): void;
+    /**
+     * Delete key from cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Check if key exists in cache (without updating access time)
+     */
+    has(key: string): boolean;
+    /**
+     * Clear all entries from cache
+     */
+    clear(): void;
+    /**
+     * Get all keys in cache (ordered by recency)
+     */
+    keys(): string[];
+    /**
+     * Get all values in cache (ordered by recency)
+     */
+    values(): T[];
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * Prune expired entries
+     */
+    prune(): number;
+    /**
+     * Get entries sorted by access frequency
+     */
+    getFrequentlyUsed(limit?: number): Array<{
+        key: string;
+        value: T;
+        accessCount: number;
+    }>;
+    /**
+     * Resize cache (may trigger evictions)
+     */
+    resize(newMaxSize: number): void;
+    /**
+     * Check if entry is expired
+     */
+    private isExpired;
+    /**
+     * Move node to front of list (most recently used)
+     */
+    private moveToFront;
+    /**
+     * Add node to front of list
+     */
+    private addToFront;
+    /**
+     * Remove node from list
+     */
+    private removeNode;
+    /**
+     * Evict least recently used entry
+     */
+    private evictLRU;
+    /**
+     * Estimate memory usage in bytes
+     */
+    private estimateMemoryUsage;
+    /**
+     * Estimate size of a value in bytes
+     */
+    private estimateValueSize;
+}
+/**
+ * Factory function to create LRU cache with common configurations
+ */
+export declare const createLRUCache: {
+    /**
+     * Create a small cache for frequently accessed items
+     */
+    small: <T = any>(ttl?: number) => LRUCache<T>;
+    /**
+     * Create a medium cache for general purpose use
+     */
+    medium: <T = any>(ttl?: number) => LRUCache<T>;
+    /**
+     * Create a large cache for heavy caching scenarios
+     */
+    large: <T = any>(ttl?: number) => LRUCache<T>;
+    /**
+     * Create a custom configured cache
+     */
+    custom: <T = any>(options: LRUCacheOptions) => LRUCache<T>;
+};

package/dist/cache/middleware-memoization.d.ts

@@ -0,0 +1,151 @@
+import type { EnhancedRequest, MiddlewareHandler } from '../types';
+import type { LRUCacheOptions } from './lru-cache';
+/**
+ * Middleware result memoization for expensive operations
+ * Caches middleware results based on request characteristics
+ */
+export interface MemoizationOptions extends Omit<LRUCacheOptions, 'maxSize'> {
+    maxSize: number;
+    keyGenerator?: (req: EnhancedRequest) => string;
+    shouldMemoize?: (req: EnhancedRequest, result: any) => boolean;
+    resultSerializer?: (result: any) => any;
+    resultDeserializer?: (serialized: any) => any;
+}
+export interface MemoizedResult<T = any> {
+    value: T;
+    timestamp: number;
+    requestFingerprint: string;
+    executionTime: number;
+    hitCount: number;
+}
+export interface MemoizationStats {
+    totalRequests: number;
+    cacheHits: number;
+    cacheMisses: number;
+    hitRate: number;
+    averageExecutionTime: number;
+    totalTimeSaved: number;
+    memoryUsage: number;
+}
+/**
+ * Middleware memoization system for caching expensive operations
+ */
+export declare class MiddlewareMemoizer {
+    private options;
+    private cache;
+    private stats;
+    constructor(options: MemoizationOptions);
+    /**
+     * Create a memoized version of a middleware function
+     */
+    memoize<_T = any>(middleware: MiddlewareHandler, options?: {
+        name?: string;
+        keyGenerator?: (req: EnhancedRequest) => string;
+        shouldMemoize?: (req: EnhancedRequest, result: any) => boolean;
+        ttl?: number;
+    }): MiddlewareHandler;
+    /**
+     * Create a memoized async function (not middleware)
+     */
+    memoizeFunction<TArgs extends any[], TResult>(fn: (...args: TArgs) => Promise<TResult>, options?: {
+        name?: string;
+        keyGenerator?: (...args: TArgs) => string;
+        shouldMemoize?: (result: TResult, ...args: TArgs) => boolean;
+        ttl?: number;
+    }): (...args: TArgs) => Promise<TResult>;
+    /**
+     * Invalidate cached results by pattern
+     */
+    invalidate(pattern: string | RegExp): number;
+    /**
+     * Invalidate cached results for specific user
+     */
+    invalidateForUser(userId: string): number;
+    /**
+     * Invalidate cached results by tag
+     */
+    invalidateByTag(tag: string): number;
+    /**
+     * Get most frequently used cached results
+     */
+    getPopularResults(limit?: number): Array<{
+        key: string;
+        hitCount: number;
+        executionTime: number;
+        timeSaved: number;
+    }>;
+    /**
+     * Get memoization statistics
+     */
+    getStats(): MemoizationStats;
+    /**
+     * Clear cache and reset statistics
+     */
+    clear(): void;
+    /**
+     * Prune expired entries
+     */
+    prune(): number;
+    /**
+     * Generate cache key for middleware
+     */
+    private generateCacheKey;
+    /**
+     * Generate request fingerprint for cache validation
+     */
+    private generateRequestFingerprint;
+    /**
+     * Update hit rate statistics
+     */
+    private updateHitRate;
+}
+/**
+ * Common memoization patterns and utilities
+ */
+export declare class MemoizationPatterns {
+    /**
+     * Memoize database queries
+     */
+    static createDatabaseMemoizer(options?: MemoizationOptions): MiddlewareMemoizer;
+    /**
+     * Memoize API calls
+     */
+    static createApiMemoizer(options?: MemoizationOptions): MiddlewareMemoizer;
+    /**
+     * Memoize authentication checks
+     */
+    static createAuthMemoizer(options?: MemoizationOptions): MiddlewareMemoizer;
+    /**
+     * Memoize rate limiting checks
+     */
+    static createRateLimitMemoizer(options?: MemoizationOptions): MiddlewareMemoizer;
+    /**
+     * Memoize expensive computations
+     */
+    static createComputationMemoizer(options?: MemoizationOptions): MiddlewareMemoizer;
+}
+/**
+ * Decorator for memoizing class methods
+ */
+export declare function Memoize(options?: {
+    memoizer: MiddlewareMemoizer;
+    keyGenerator?: (...args: any[]) => string;
+    ttl?: number;
+}): MethodDecorator;
+/**
+ * Factory functions for creating memoizers
+ */
+export declare const createMemoizer: {
+    /**
+     * Create memoizer for development
+     */
+    development: () => MiddlewareMemoizer;
+    /**
+     * Create memoizer for production
+     */
+    production: () => MiddlewareMemoizer;
+    /**
+     * Create custom memoizer
+     */
+    custom: (options: MemoizationOptions) => MiddlewareMemoizer;
+};

package/dist/cache/route-cache-warmer.d.ts

@@ -0,0 +1,161 @@
+import type { LRUCache } from './lru-cache';
+import type { StreamingCache } from './streaming-cache';
+/**
+ * Route cache warming system for pre-populating caches with common routes
+ */
+export interface WarmupRoute {
+    path: string;
+    method: string;
+    priority: number;
+    frequency: number;
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    warmupData?: any;
+}
+export interface AnalyticsRoute {
+    path: string;
+    method: string;
+    frequency: number;
+}
+export interface RecentRoute {
+    path: string;
+    method: string;
+    timestamp: number;
+}
+export interface PrecomputeRoute {
+    path: string;
+    method: string;
+    computeFunction: () => Promise<any>;
+    cacheKey?: string;
+    ttl?: number;
+}
+export interface UserSegment {
+    segment: string;
+    commonRoutes: string[];
+    priority: number;
+}
+export interface TimeRange {
+    start: number;
+    end: number;
+}
+export interface TimeBasedPattern {
+    timeRange: TimeRange;
+    routes: string[];
+    priority: number;
+}
+export interface GeographicPattern {
+    region: string;
+    routes: string[];
+    priority: number;
+}
+export interface IntelligentWarmupPatterns {
+    userSegments?: UserSegment[];
+    timeBasedPatterns?: TimeBasedPattern[];
+    geographicPatterns?: GeographicPattern[];
+}
+export interface WarmupConfig {
+    enabled: boolean;
+    maxConcurrency: number;
+    warmupTimeout: number;
+    retryAttempts: number;
+    retryDelay: number;
+    scheduleInterval?: number;
+    priorityThreshold: number;
+}
+export interface WarmupStats {
+    totalRoutes: number;
+    successfulWarmups: number;
+    failedWarmups: number;
+    averageWarmupTime: number;
+    lastWarmupTime: number;
+    cacheHitRateImprovement: number;
+}
+/**
+ * Route cache warmer for pre-populating caches with frequently accessed routes
+ */
+export declare class RouteCacheWarmer {
+    private config;
+    private routes;
+    private routeCache;
+    private streamingCache?;
+    private stats;
+    private warmupTimer?;
+    constructor(config: WarmupConfig, routeCache: LRUCache<any>, streamingCache?: StreamingCache);
+    /**
+     * Register routes for cache warming
+     */
+    registerRoutes(routes: WarmupRoute[]): void;
+    /**
+     * Register a single route for cache warming
+     */
+    registerRoute(route: WarmupRoute): void;
+    /**
+     * Warm cache with registered routes
+     */
+    warmCache(options?: {
+        routes?: string[];
+        maxRoutes?: number;
+        skipLowPriority?: boolean;
+    }): Promise<WarmupStats>;
+    /**
+     * Warm specific route patterns based on analytics
+     */
+    warmFromAnalytics(analytics: {
+        topRoutes: AnalyticsRoute[];
+        recentRoutes: RecentRoute[];
+    }): Promise<void>;
+    /**
+     * Pre-compute and cache expensive route operations
+     */
+    precomputeRoutes(routes: PrecomputeRoute[]): Promise<number>;
+    /**
+     * Warm cache based on route patterns and user behavior
+     */
+    intelligentWarmup(patterns: IntelligentWarmupPatterns): Promise<void>;
+    /**
+     * Get cache warming statistics
+     */
+    getStats(): WarmupStats;
+    /**
+     * Clear warmup statistics
+     */
+    resetStats(): void;
+    /**
+     * Stop periodic warmup
+     */
+    stop(): void;
+    /**
+     * Warm routes with concurrency control
+     */
+    private warmRoutesWithConcurrency;
+    /**
+     * Warm a single route
+     */
+    private warmSingleRoute;
+    /**
+     * Build URL for route warming
+     */
+    private buildRouteUrl;
+    /**
+     * Schedule periodic cache warmup
+     */
+    private schedulePeriodicWarmup;
+}
+/**
+ * Factory functions for creating route cache warmers
+ */
+export declare const createRouteCacheWarmer: {
+    /**
+     * Create warmer for development environment
+     */
+    development: (routeCache: LRUCache<any>, streamingCache?: StreamingCache) => RouteCacheWarmer;
+    /**
+     * Create warmer for production environment
+     */
+    production: (routeCache: LRUCache<any>, streamingCache?: StreamingCache) => RouteCacheWarmer;
+    /**
+     * Create warmer with custom configuration
+     */
+    custom: (config: WarmupConfig, routeCache: LRUCache<any>, streamingCache?: StreamingCache) => RouteCacheWarmer;
+};