@stacksjs/bun-router 0.0.2

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,397 @@
+# @bun-router
+
+A Laravel-inspired router for Bun applications.
+
+## Features
+
+- Laravel-style routing API
+- Support for route parameters
+- Route grouping
+- Action class support
+- Middleware support (global and route-specific)
+- Built on top of Bun's native HTTP server
+
+## Installation
+
+```bash
+bun add @bun-router
+```
+
+## Basic Usage
+
+```typescript
+import { route } from '@bun-router'
+
+// Basic route with inline handler
+route.get('/', () => new Response('Hello World!'))
+
+// Route with parameters
+route.get('/users/{id}', (req) => {
+  const { id } = req.params
+  return Response.json({ userId: id })
+})
+
+// Route with action class
+route.post('/subscribe', 'Actions/SubscribeAction')
+
+// Route grouping
+route.group({ prefix: '/api' }, () => {
+  route.get('/users', 'Actions/User/IndexAction')
+  route.post('/users', 'Actions/User/StoreAction')
+})
+
+// Health check route
+route.health()
+
+// Start the server
+route.serve({
+  port: 3000,
+})
+```
+
+## Action Classes
+
+Action classes provide a clean way to organize your route handlers. Create a class that implements a `handle` method:
+
+```typescript
+// actions/subscribe_action.ts
+import type { EnhancedRequest } from '@bun-router'
+
+export default class SubscribeAction {
+  async handle(request: EnhancedRequest): Promise<Response> {
+    const data = await request.json()
+
+    // Handle subscription logic
+
+    return Response.json({
+      success: true,
+      message: 'Subscribed successfully'
+    })
+  }
+}
+```
+
+## Middleware
+
+Middleware allows you to run code before your route handlers. You can use middleware globally or for specific routes/groups.
+
+### Creating Middleware
+
+Create a middleware class that implements the `handle` method:
+
+```typescript
+// middleware/auth.ts
+import type { EnhancedRequest, Middleware, NextFunction } from '@bun-router'
+
+export default class AuthMiddleware implements Middleware {
+  async handle(req: EnhancedRequest, next: NextFunction): Promise<Response> {
+    const authHeader = req.headers.get('Authorization')
+
+    if (!authHeader) {
+      return new Response('Unauthorized', { status: 401 })
+    }
+
+    // If auth passes, continue to next middleware or route handler
+    return next()
+  }
+}
+```
+
+### Using Middleware
+
+You can use middleware in several ways:
+
+1. Global Middleware (applies to all routes):
+
+```typescript
+route.use('Middleware/Auth')
+route.use('Middleware/Logger')
+
+// Or with inline middleware
+route.use(async (req, next) => {
+  console.log(`${req.method} ${req.url}`)
+  return next()
+})
+```
+
+2. Group Middleware (applies to all routes in a group):
+
+```typescript
+route.group({
+  prefix: '/api',
+  middleware: ['Middleware/Auth']
+}, () => {
+  route.get('/users', 'Actions/User/IndexAction')
+  route.post('/users', 'Actions/User/StoreAction')
+})
+```
+
+3. Inline Middleware:
+
+```typescript
+route.group({
+  middleware: [
+    async (req, next) => {
+      console.log('Processing request...')
+      const response = await next()
+      console.log('Request complete')
+      return response
+    }
+  ]
+}, () => {
+  route.get('/users', 'Actions/User/IndexAction')
+})
+```
+
+## Route Groups
+
+Group related routes with a common prefix and middleware:
+
+```typescript
+route.group({
+  prefix: '/api/v1',
+  middleware: ['Middleware/Auth', 'Middleware/RateLimit']
+}, () => {
+  // All routes here will be prefixed with /api/v1
+  route.get('/users', 'Actions/User/IndexAction')
+  route.post('/users', 'Actions/User/StoreAction')
+
+  // Nested groups
+  route.group({
+    prefix: '/admin',
+    middleware: ['Middleware/AdminAuth']
+  }, () => {
+    route.get('/stats', 'Actions/Admin/StatsAction')
+  })
+})
+```
+
+## Route Parameters
+
+Access route parameters through the `params` object:
+
+```typescript
+route.get('/users/{id}/posts/{postId}', (req) => {
+  const { id, postId } = req.params
+  return Response.json({ userId: id, postId })
+})
+```
+
+## TypeScript Support
+
+The router is written in TypeScript and provides full type definitions:
+
+```typescript
+import type { ActionHandler, EnhancedRequest, Middleware, NextFunction } from '@bun-router'
+
+// Type-safe request handling
+const handler: ActionHandler = (req: EnhancedRequest) => {
+  const { id } = req.params
+  return Response.json({ id })
+}
+
+// Type-safe middleware
+const loggerMiddleware: Middleware = {
+  handle: async (req: EnhancedRequest, next: NextFunction) => {
+    console.log(`${req.method} ${req.url}`)
+    return next()
+  }
+}
+
+route.use(loggerMiddleware.handle)
+route.get('/users/{id}', handler)
+```
+
+## Streaming Support
+
+The router provides comprehensive streaming capabilities for modern web applications:
+
+### File Streaming
+
+Stream files with automatic content-type detection:
+
+```typescript
+// Basic file streaming
+route.get('/download/{filename}', (req) => {
+  const { filename } = req.params
+  return route.streamFile(`./uploads/${filename}`)
+})
+
+// File streaming with range support (for video/audio)
+route.get('/video/{id}', async (req) => {
+  const { id } = req.params
+  const videoPath = `./videos/${id}.mp4`
+  return await route.streamFileWithRanges(videoPath, req)
+})
+```
+
+### Response Streaming
+
+Create streaming routes with clean, top-level API methods:
+
+```typescript
+// Default streaming (uses Bun's async generator optimization)
+route.stream('/stream-data', async function* () {
+  for (let i = 0; i < 100; i++) {
+    yield `Chunk ${i}\n`
+    await new Promise(resolve => setTimeout(resolve, 100))
+  }
+})
+
+// Direct streaming for high-performance scenarios
+route.streamDirect('/stream-direct', async ({ write, close }) => {
+  for (let i = 0; i < 1000; i++) {
+    write(`Data chunk ${i}\n`)
+    if (i % 100 === 0) {
+      await new Promise(resolve => setTimeout(resolve, 10))
+    }
+  }
+  close()
+})
+
+// Buffered streaming using Bun.ArrayBufferSink
+route.streamBuffered('/stream-buffered', async ({ write, flush, end }) => {
+  for (let i = 0; i < 1000; i++) {
+    write(`Item ${i}\n`)
+    if (i % 50 === 0) {
+      flush() // Flush buffer every 50 items
+    }
+  }
+  end()
+}, { highWaterMark: 1024 * 1024 }) // 1MB buffer
+```
+
+### Server-Sent Events (SSE)
+
+Real-time data streaming to web clients:
+
+```typescript
+// Basic SSE endpoint
+route.streamSSE('/events', async function* () {
+  let counter = 0
+  while (true) {
+    yield {
+      data: { timestamp: Date.now(), counter: counter++ },
+      event: 'update',
+      id: `msg-${counter}`
+    }
+    await new Promise(resolve => setTimeout(resolve, 1000))
+  }
+})
+
+// SSE with custom retry interval
+route.streamSSE('/notifications', async function* () {
+  yield {
+    data: 'Connection established',
+    event: 'connected',
+    retry: 5000 // Retry after 5 seconds if connection drops
+  }
+  
+  // Stream notifications...
+})
+```
+
+### JSON Streaming (NDJSON)
+
+Stream JSON objects line by line:
+
+```typescript
+// Stream database results
+route.streamJSON('/users/stream', async function* () {
+  const users = await getUsersFromDatabase()
+  for (const user of users) {
+    yield { id: user.id, name: user.name, email: user.email }
+  }
+})
+
+// Stream large datasets efficiently
+route.streamJSON('/analytics/data', async function* () {
+  for (let page = 1; page <= 100; page++) {
+    const data = await fetchAnalyticsPage(page)
+    for (const record of data) {
+      yield record
+    }
+  }
+})
+```
+
+### Transform Streams
+
+Process incoming request streams using Bun's TransformStream:
+
+```typescript
+// Transform uploaded data
+route.post('/process-upload', route.transformStream(
+  (chunk) => {
+    // Process each chunk (e.g., uppercase text)
+    const text = new TextDecoder().decode(chunk)
+    return text.toUpperCase()
+  },
+  { headers: { 'Content-Type': 'text/plain' } }
+))
+```
+
+### Advanced Streaming Features
+
+Leverage Bun's performance optimizations:
+
+```typescript
+// Use direct ReadableStream for maximum performance
+route.streamDirect('/high-performance-stream', async ({ write, close }) => {
+  // No queueing - data is written directly to the stream
+  for (let i = 0; i < 10000; i++) {
+    write(new Uint8Array([65 + (i % 26)])) // A-Z pattern
+  }
+  close()
+})
+
+// Buffered streaming with Bun.ArrayBufferSink
+route.streamBuffered('/buffered-data', async ({ write, flush, end }) => {
+  // Efficient incremental buffer building
+  for (let batch = 0; batch < 10; batch++) {
+    for (let i = 0; i < 100; i++) {
+      write(`Batch ${batch}, Item ${i}\n`)
+    }
+    flush() // Periodically flush the buffer
+    await new Promise(resolve => setTimeout(resolve, 100))
+  }
+  end()
+}, { 
+  highWaterMark: 512 * 1024, // 512KB buffer
+  asUint8Array: true 
+})
+
+// Mix streaming with middleware and route groups
+route.group({ prefix: '/api/v1', middleware: ['Auth'] }, () => {
+  route.streamJSON('/live-metrics', async function* () {
+    while (true) {
+      yield await getSystemMetrics()
+      await new Promise(resolve => setTimeout(resolve, 1000))
+    }
+  })
+  
+  route.streamSSE('/notifications', async function* () {
+    // Stream user-specific notifications
+    const userId = getCurrentUserId()
+    for await (const notification of watchNotifications(userId)) {
+      yield { data: notification, event: 'notification' }
+    }
+  })
+})
+```
+
+## Server Configuration
+
+The `serve` method accepts all Bun server options:
+
+```typescript
+route.serve({
+  port: 3000,
+  hostname: 'localhost',
+  development: true,
+})
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/bin/cli.ts

@@ -0,0 +1,9 @@
+/**
+ * This file is a simple entry point to the CLI implementation.
+ * The actual CLI code is now modularized in src/cli/ directory.
+ */
+import { createCLI } from '../src/cli/index'
+
+// Create and run the CLI
+const cli = createCLI()
+cli.parse()

package/dist/auth.d.ts

@@ -0,0 +1,77 @@
+import type { EnhancedRequest, JwtPayload } from './types';
+export type { JwtPayload };
+// Types
+export declare interface JwtVerifyOptions {
+  issuer?: string
+  audience?: string
+  subject?: string
+  algorithms?: string[]
+  expiresIn?: string | number
+  notBefore?: string | number
+  ignoreExpiration?: boolean
+  allowInvalidAsymmetricKeyTypes?: boolean
+}
+export declare 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 declare interface ApiKeyOptions {
+  source?: 'header' | 'query' | 'cookie'
+  keyName?: string
+  keyPrefix?: string
+}
+export declare interface OAuth2Config {
+  clientId: string
+  clientSecret: string
+  authorizeUrl: string
+  tokenUrl: string
+  redirectUri: string
+  scope?: string
+  state?: string
+}
+/**
+ * Simple JWT implementation for signing and verifying tokens
+ */
+export declare class JWT {
+  private secret: string;
+  constructor(secret: string);
+  sign(payload: Record<string, any>, options?: JwtSignOptions): string;
+  verify(token: string, options?: JwtVerifyOptions): Record<string, any> | null;
+  decode(token: string): { header: Record<string, any>, payload: Record<string, any> } | null;
+  private createSignature(data: string, secret: string, algorithm: string): string;
+  private parseTimespan(timespan: string): number;
+}
+/**
+ * API Key manager to generate, validate and handle API keys
+ */
+export declare class ApiKeyManager {
+  private keys: Map<string, { owner: string, scopes: string[], expiresAt?: Date }>;
+  private options: ApiKeyOptions;
+  constructor(options?: ApiKeyOptions);
+  generateKey(owner: string, scopes?: string[], expiresIn?: number): string;
+  validateKey(key: string, requiredScopes?: string[]): boolean;
+  getKeyInfo(key: string): { owner: string, scopes: string[], expiresAt?: Date } | null;
+  revokeKey(key: string): boolean;
+  extractFromRequest(req: EnhancedRequest): string | null;
+  private randomString(length: number): string;
+}
+/**
+ * OAuth2 helper for authorization code flow
+ */
+export declare class OAuth2Helper {
+  private config: OAuth2Config;
+  constructor(config: OAuth2Config);
+  getAuthorizationUrl(additionalParams?: Record<string, string>): string;
+  exchangeCodeForToken(code: string): Promise<Record<string, any>>;
+  refreshToken(refreshToken: string): Promise<Record<string, any>>;
+}
+export default Auth;

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

@@ -0,0 +1,88 @@
+/**
+ * Factory function to create LRU cache with common configurations
+ */
+export declare const createLRUCache: {
+  /**
+   * Create a small cache for frequently accessed items
+   */
+  small: () => unknown;
+  /**
+   * Create a medium cache for general purpose use
+   */
+  medium: () => unknown;
+  /**
+   * Create a large cache for heavy caching scenarios
+   */
+  large: () => unknown;
+  /**
+   * Create a custom configured cache
+   */
+  custom: () => unknown
+};
+/**
+ * High-performance LRU (Least Recently Used) cache implementation
+ * Optimized for Bun runtime with configurable size limits and TTL support
+ */
+export declare interface LRUCacheOptions {
+  maxSize: number
+  ttl?: number
+  onEvict?: (key: string, value: any) => void
+  allowStale?: boolean
+  updateAgeOnGet?: boolean
+}
+export declare interface CacheEntry<T = any> {
+  value: T
+  timestamp: number
+  accessCount: number
+  lastAccessed: number
+  ttl?: number
+}
+export declare interface CacheStats {
+  size: number
+  maxSize: number
+  hits: number
+  misses: number
+  evictions: number
+  hitRate: number
+  memoryUsage: number
+}
+/**
+ * Node in the doubly linked list for LRU tracking
+ */
+declare class LRUNode<T = any> {
+  public key: string;
+  public entry: CacheEntry<T>;
+  public prev?: LRUNode<T> | null;
+  public next?: LRUNode<T> | null;
+  constructor(key: string, entry: CacheEntry<T>, prev?: LRUNode<T> | null, next?: LRUNode<T> | null);
+}
+/**
+ * High-performance LRU cache with TTL support and detailed statistics
+ */
+export declare class LRUCache<T = any> {
+  private cache: any;
+  private head: LRUNode<T> | null;
+  private tail: LRUNode<T> | null;
+  private stats: any;
+  private options: LRUCacheOptions;
+  constructor(options: LRUCacheOptions);
+  get(key: string): T | undefined;
+  set(key: string, value: T, ttl?: number): void;
+  delete(key: string): boolean;
+  has(key: string): boolean;
+  clear(): void;
+  keys(): string[];
+  values(): T[];
+  getStats(): CacheStats;
+  resetStats(): void;
+  prune(): number;
+  getFrequentlyUsed(limit?: number): Array<{ key: string, value: T, accessCount: number }>;
+  resize(newMaxSize: number): void;
+  private isExpired(entry: CacheEntry<T>, now: number): boolean;
+  private moveToFront(node: LRUNode<T>): void;
+  private addToFront(node: LRUNode<T>): void;
+  private removeNode(node: LRUNode<T>): void;
+  private evictLRU(): void;
+  private estimateMemoryUsage(): number;
+  private estimateValueSize(value: any): number;
+}

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

@@ -0,0 +1,101 @@
+import { LRUCache } from './lru-cache';
+import type { EnhancedRequest, MiddlewareHandler } from '../types';
+import type { LRUCacheOptions } from './lru-cache';
+/**
+ * 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: () => any;
+  /**
+   * Create memoizer for production
+   */
+  production: () => any;
+  /**
+   * Create custom memoizer
+   */
+  custom: (options: MemoizationOptions) => any
+};
+/**
+ * Middleware result memoization for expensive operations
+ * Caches middleware results based on request characteristics
+ */
+export declare 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 declare interface MemoizedResult<T = any> {
+  value: T
+  timestamp: number
+  requestFingerprint: string
+  executionTime: number
+  hitCount: number
+}
+export declare 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 cache: LRUCache<MemoizedResult>;
+  private stats: MemoizationStats;
+  private options: MemoizationOptions;
+  constructor(options: MemoizationOptions);
+  memoize<_T = any>(middleware: MiddlewareHandler, options?: {
+      name?: string
+      keyGenerator?: (req: EnhancedRequest) => string
+      shouldMemoize?: (req: EnhancedRequest, result: any) => boolean
+      ttl?: number
+    }): MiddlewareHandler;
+  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(pattern: string | RegExp): number;
+  invalidateForUser(userId: string): number;
+  invalidateByTag(tag: string): number;
+  getPopularResults(limit?: number): Array<{
+    key: string
+    hitCount: number
+    executionTime: number
+    timeSaved: number
+  }>;
+  getStats(): MemoizationStats;
+  clear(): void;
+  prune(): number;
+  private generateCacheKey(req: EnhancedRequest, middlewareName: string, customKeyGenerator?: (req: EnhancedRequest) => string): string;
+  private generateRequestFingerprint(req: EnhancedRequest): string;
+  private updateHitRate(): void;
+}
+/**
+ * Common memoization patterns and utilities
+ */
+export declare class MemoizationPatterns {
+  static createDatabaseMemoizer(options?: MemoizationOptions): MiddlewareMemoizer;
+  static createApiMemoizer(options?: MemoizationOptions): MiddlewareMemoizer;
+  static createAuthMemoizer(options?: MemoizationOptions): MiddlewareMemoizer;
+  static createRateLimitMemoizer(options?: MemoizationOptions): MiddlewareMemoizer;
+  static createComputationMemoizer(options?: MemoizationOptions): MiddlewareMemoizer;
+}