@stacksjs/bun-router 0.0.12 → 0.0.14

package/README.md

@@ -1,397 +1,720 @@
-# @bun-router
+<p align="center"><img src=".github/art/cover.jpg" alt="Social Card of this repo"></p>
 
-A Laravel-inspired router for Bun applications.
+[![npm version][npm-version-src]][npm-version-href]
+[![GitHub Actions][github-actions-src]][github-actions-href]
+[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
+<!-- [![npm downloads][npm-downloads-src]][npm-downloads-href] -->
+<!-- [![Codecov][codecov-src]][codecov-href] -->
+
+# bun-router
+
+A high-performance, feature-rich 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
+- Fast and efficient routing system
+- Support for all HTTP methods
+- Path parameters and parameter constraints
+- Middleware support with built-in middleware
+- Group routing, resource routing, and nested routes
+- Named routes and URL generation
+- Domain and subdomain routing
+- CSRF protection and session management
+- Type-safe API
+- Native Bun.serve() integration
+- WebSocket support
 
 ## Installation
 
 ```bash
-bun add @bun-router
+bun add bun-router
 ```
 
 ## Basic Usage
 
 ```typescript
-import { route } from '@bun-router'
+import { Router } from 'bun-router'
 
-// Basic route with inline handler
-route.get('/', () => new Response('Hello World!'))
+// Create a router
+const router = new Router()
 
-// Route with parameters
-route.get('/users/{id}', (req) => {
-  const { id } = req.params
-  return Response.json({ userId: id })
+// Define routes
+router.get('/', () => new Response('Hello, World!'))
+router.post('/users', async (req) => {
+  const data = await req.json()
+  return Response.json({ message: 'User created', data })
 })
 
-// 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({
+router.serve({
   port: 3000,
 })
 ```
 
-## Action Classes
+## Route Options
+
+```typescript
+// Route with path parameters
+router.get('/users/{id}', (req) => {
+  const { id } = req.params
+  return Response.json({ id })
+})
+
+// Named routes
+router.get('/users/{id}', getUserHandler, 'api', 'users.show')
 
-Action classes provide a clean way to organize your route handlers. Create a class that implements a `handle` method:
+// Generate URL for named route
+const url = router.route('users.show', { id: '123' })
+```
+
+## Middleware
 
 ```typescript
-// actions/subscribe_action.ts
-import type { EnhancedRequest } from '@bun-router'
+import { cors, jsonBody, Router } from 'bun-router'
+
+const router = new Router()
 
-export default class SubscribeAction {
-  async handle(request: EnhancedRequest): Promise<Response> {
-    const data = await request.json()
+// Use middleware globally
+router.use(jsonBody())
+router.use(cors())
 
-    // Handle subscription logic
+// Or apply to a group of routes
+router.group({
+  prefix: '/api',
+  middleware: [jsonBody(), cors()]
+}, () => {
+  router.get('/users', () => Response.json({ users: [] }))
+})
+```
+
+### Built-in Middleware
+
+- **Cors** - Handles Cross-Origin Resource Sharing
+- **JsonBody** - Parses JSON request bodies into `req.jsonBody`
+- **RequestId** - Adds unique IDs to requests with `X-Request-ID` header
+- **Session** - Provides session management with `req.session`
+- **Csrf** - Protects against cross-site request forgery
+- **Auth** - Basic authentication middleware
+
+### Creating Custom Middleware
+
+```typescript
+import { EnhancedRequest, MiddlewareHandler, NextFunction } from 'bun-router'
 
-    return Response.json({
-      success: true,
-      message: 'Subscribed successfully'
-    })
+class LoggerMiddleware {
+  async handle(req: EnhancedRequest, next: NextFunction): Promise<Response> {
+    console.log(`${req.method} ${req.url}`)
+    return next()
   }
 }
+
+// Use custom middleware
+router.use(new LoggerMiddleware())
 ```
 
-## Middleware
+## WebSocket Support
 
-Middleware allows you to run code before your route handlers. You can use middleware globally or for specific routes/groups.
+bun-router provides seamless integration with Bun's high-performance WebSocket capabilities:
 
-### Creating Middleware
+```typescript
+import type { ServerWebSocket } from 'bun'
+import { Router } from 'bun-router'
 
-Create a middleware class that implements the `handle` method:
+// Define data type for WebSocket clients
+interface ClientData {
+  userId: string
+  room: string
+}
 
-```typescript
-// middleware/auth.ts
-import type { EnhancedRequest, Middleware, NextFunction } from '@bun-router'
+// Create a router
+const router = new Router<ClientData>() // Type-safe WebSockets
 
-export default class AuthMiddleware implements Middleware {
-  async handle(req: EnhancedRequest, next: NextFunction): Promise<Response> {
-    const authHeader = req.headers.get('Authorization')
+// Add a regular HTTP route
+router.get('/', () => new Response('WebSocket Server'))
+
+// Configure WebSocket handling
+router.websocket({
+  // Handle new connections
+  open(ws) {
+    console.log('Client connected from:', ws.remoteAddress)
+
+    // Set client data (available in all handlers as ws.data)
+    ws.data = { userId: 'user_123', room: 'general' }
+
+    // Subscribe to topics for pub/sub messaging
+    ws.subscribe('general')
+    ws.send('Welcome to the server!')
+  },
 
-    if (!authHeader) {
-      return new Response('Unauthorized', { status: 401 })
+  // Handle incoming messages
+  message(ws, message) {
+    // Handle different message types (string, ArrayBuffer, Uint8Array)
+    const content = typeof message === 'string' ? message : 'Binary data received'
+    console.log(`Received from ${ws.data.userId}: ${content}`)
+
+    // Send response and check for backpressure
+    const sendResult = ws.send(`Echo: ${content}`)
+
+    if (sendResult === -1) {
+      console.log('Backpressure detected, message queued')
+    }
+    else if (sendResult === 0) {
+      console.log('Send failed, connection may be closed')
+    }
+    else {
+      console.log(`Sent ${sendResult} bytes`)
     }
 
-    // If auth passes, continue to next middleware or route handler
-    return next()
+    // Broadcast to all subscribers of a topic (except sender)
+    router.publish('general', `${ws.data.userId}: ${content}`)
+  },
+
+  // Handle disconnections
+  close(ws, code, reason) {
+    console.log(`Client ${ws.data.userId} disconnected: ${reason || 'No reason'} (${code})`)
+    ws.unsubscribe('general')
+  },
+
+  // Handle errors
+  error(ws, error) {
+    console.error(`Error for client ${ws.data.userId}:`, error)
+  },
+
+  // Handle backpressure relief
+  drain(ws) {
+    console.log(`Backpressure relieved for ${ws.data.userId}, socket ready for more data`)
+  },
+
+  // Advanced configuration options
+  maxPayloadLength: 16 _ 1024 _ 1024, // 16MB max message size (default)
+  idleTimeout: 120, // 2 minutes (default)
+  backpressureLimit: 1024 _ 1024, // 1MB (default)
+  closeOnBackpressureLimit: false, // Don't close on backpressure limit (default)
+
+  // Enable per-message compression
+  perMessageDeflate: {
+    compress: '16KB', // Use 16KB compression level
+    decompress: true
+  },
+
+  sendPings: true, // Send ping frames to keep connection alive (default)
+  publishToSelf: false // Don't send published messages to publisher (default)
+})
+
+// Start the server
+router.serve({ port: 3000 })
+```
+
+### WebSocket Utility Methods
+
+The router provides utility methods for working with WebSockets:
+
+```typescript
+// Publish a message to all subscribers of a topic
+// Returns: Number of bytes sent (or negative on error)
+const result = router.publish('room-123', JSON.stringify({
+  type: 'message',
+  text: 'Hello!'
+}), true) // Optional: enable compression
+
+// Get the number of subscribers for a topic
+const count = router.subscriberCount('room-123')
+
+// Upgrade an HTTP request to a WebSocket connection
+router.get('/custom-upgrade', (req) => {
+  const success = router.upgrade(req, {
+    // Optional custom headers for the 101 Switching Protocols response
+    headers: { 'X-Custom-Header': 'value' },
+
+    // Custom data to attach to the WebSocket
+    data: {
+      userId: '123',
+      authenticated: true,
+      permissions: ['read', 'write']
+    }
+  })
+
+  if (!success) {
+    return new Response('Failed to upgrade connection', { status: 400 })
   }
-}
+
+  // If upgrade is successful, this response is ignored
+  return new Response('Upgraded to WebSocket')
+})
+
+// Get client IP address
+router.get('/ip', (req) => {
+  const ip = router.requestIP(req)
+  return Response.json(ip)
+})
+
+// Set custom timeout for a request
+router.get('/long-operation', (req) => {
+  // Extend timeout to 5 minutes for this specific request
+  router.timeout(req, 300)
+
+  // Perform long operation...
+  return new Response('Operation completed')
+})
 ```
 
-### Using Middleware
+### WebSocket Patterns
 
-You can use middleware in several ways:
+Here are some common patterns for working with WebSockets:
 
-1. Global Middleware (applies to all routes):
+#### JSON Communication
 
 ```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()
+// Client-side
+const ws = new WebSocket('ws://localhost:3000/ws')
+ws.send(JSON.stringify({ type: 'login', userId: '123' }))
+
+// Server-side
+router.websocket({
+  message(ws, message) {
+    try {
+      const data = JSON.parse(message.toString())
+
+      switch (data.type) {
+        case 'login':
+          handleLogin(ws, data.userId)
+          break
+        case 'message':
+          handleMessage(ws, data)
+          break
+      }
+    }
+    catch (e) {
+      ws.send(JSON.stringify({ error: 'Invalid JSON' }))
+    }
+  }
 })
 ```
 
-2. Group Middleware (applies to all routes in a group):
+#### Room-Based Chat
 
 ```typescript
-route.group({
-  prefix: '/api',
-  middleware: ['Middleware/Auth']
-}, () => {
-  route.get('/users', 'Actions/User/IndexAction')
-  route.post('/users', 'Actions/User/StoreAction')
+router.websocket({
+  open(ws) {
+    ws.data = { userId: generateId(), room: 'lobby' }
+    ws.subscribe('lobby')
+    broadcastToRoom('lobby', `${ws.data.userId} joined the lobby`)
+  },
+
+  message(ws, message) {
+    const text = message.toString()
+
+    if (text.startsWith('/join ')) {
+      const newRoom = text.slice(6).trim()
+
+      // Leave current room
+      const oldRoom = ws.data.room
+      ws.unsubscribe(oldRoom)
+      broadcastToRoom(oldRoom, `${ws.data.userId} left the room`)
+
+      // Join new room
+      ws.data.room = newRoom
+      ws.subscribe(newRoom)
+      broadcastToRoom(newRoom, `${ws.data.userId} joined the room`)
+
+      ws.send(`You joined ${newRoom}`)
+    }
+    else {
+      // Regular message
+      broadcastToRoom(ws.data.room, `${ws.data.userId}: ${text}`)
+    }
+  }
 })
+
+function broadcastToRoom(room, message) {
+  router.publish(room, message)
+}
 ```
 
-3. Inline Middleware:
+#### Handling Backpressure
 
 ```typescript
-route.group({
-  middleware: [
-    async (req, next) => {
-      console.log('Processing request...')
-      const response = await next()
-      console.log('Request complete')
-      return response
+router.websocket({
+  message(ws, message) {
+    // Send a large response
+    const largeData = generateLargeResponse()
+    const result = ws.send(largeData)
+
+    if (result === -1) {
+      // Message was queued due to backpressure
+      console.log('Backpressure detected, will process more in drain event')
+
+      // Store state to resume in drain handler
+      ws.data.pendingOperations = [/_ ...operations to complete _/]
     }
-  ]
-}, () => {
-  route.get('/users', 'Actions/User/IndexAction')
+  },
+
+  drain(ws) {
+    // Socket is ready to receive more data
+    if (ws.data.pendingOperations?.length) {
+      const nextOp = ws.data.pendingOperations.shift()
+      processOperation(ws, nextOp)
+    }
+  }
 })
 ```
 
-## Route Groups
+## Bun-Native Features
 
-Group related routes with a common prefix and middleware:
+bun-router fully integrates with Bun's native `Bun.serve()` API, leveraging the latest Bun features for optimal performance.
+
+### Static Responses
+
+Define static routes without handler functions for optimal performance:
 
 ```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')
-  })
-})
+router.get('/health', () => new Response('OK'))
+router.get('/ready', () => new Response('Ready', {
+  headers: { 'X-Ready': '1' }
+}))
+
+// These are automatically optimized to Bun's static routes internally
 ```
 
-## Route Parameters
+### Method-Specific Handlers
 
-Access route parameters through the `params` object:
+The router automatically organizes multiple methods for the same path into Bun's method-specific handlers:
 
 ```typescript
-route.get('/users/{id}/posts/{postId}', (req) => {
-  const { id, postId } = req.params
-  return Response.json({ userId: id, postId })
-})
+router.get('/api/posts', getPosts)
+router.post('/api/posts', createPost)
+router.put('/api/posts/{id}', updatePost)
+router.delete('/api/posts/{id}', deletePost)
+
+// These will be organized into a more efficient format:
+// '/api/posts': {
+//   GET: getPosts,
+//   POST: createPost
+// },
+// '/api/posts/{id}': {
+//   PUT: updatePost,
+//   DELETE: deletePost
+// }
 ```
 
-## TypeScript Support
+### Hot Reloading
 
-The router is written in TypeScript and provides full type definitions:
+Update routes without restarting the server:
 
 ```typescript
-import type { ActionHandler, EnhancedRequest, Middleware, NextFunction } from '@bun-router'
+// Initial setup
+const router = new Router()
+router.get('/api/version', () => Response.json({ version: '1.0.0' }))
+const server = await router.serve({ port: 3000 })
+
+// Later, update routes without downtime
+router.get('/api/version', () => Response.json({ version: '2.0.0' }))
+await router.reload()
+```
 
-// Type-safe request handling
-const handler: ActionHandler = (req: EnhancedRequest) => {
-  const { id } = req.params
-  return Response.json({ id })
-}
+### Error Handling
 
-// Type-safe middleware
-const loggerMiddleware: Middleware = {
-  handle: async (req: EnhancedRequest, next: NextFunction) => {
-    console.log(`${req.method} ${req.url}`)
-    return next()
-  }
-}
+Add a global error handler for all routes:
+
+```typescript
+router.onError((error) => {
+  console.error(error)
+  return new Response(`Server Error: ${error.message}`, {
+    status: 500,
+    headers: { 'Content-Type': 'text/plain' }
+  })
+})
 
-route.use(loggerMiddleware.handle)
-route.get('/users/{id}', handler)
+// Define a route that might throw an error
+router.get('/api/risky', () => {
+  throw new Error('Something went wrong')
+})
+
+// Serve with the error handler
+router.serve({ port: 3000 })
 ```
 
-## Streaming Support
+### Type-Safe Route Parameters
 
-The router provides comprehensive streaming capabilities for modern web applications:
+TypeScript automatically infers parameter types from route paths:
 
-### File Streaming
+```typescript
+router.get('/orgs/{orgId}/repos/{repoId}', (req) => {
+  // TypeScript knows the shape of req.params
+  const { orgId, repoId } = req.params
+  return Response.json({ orgId, repoId })
+})
+```
+
+### Cookie Handling
 
-Stream files with automatic content-type detection:
+Built-in support for working with cookies:
 
 ```typescript
-// Basic file streaming
-route.get('/download/{filename}', (req) => {
-  const { filename } = req.params
-  return route.streamFile(`./uploads/${filename}`)
+router.get('/profile', (req) => {
+  // Read cookies
+  const userId = req.cookies.get('user_id')
+  const theme = req.cookies.get('theme') || 'light'
+
+  return Response.json({ userId, theme })
 })
 
-// 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)
+router.get('/login', (req) => {
+  // Set cookies
+  req.cookies.set('user_id', '12345', {
+    httpOnly: true,
+    secure: true,
+    maxAge: 60 _ 60 * 24 // 1 day
+  })
+
+  return new Response('Logged in')
+})
+
+router.get('/logout', (req) => {
+  // Delete cookies
+  req.cookies.delete('user_id')
+  return new Response('Logged out')
 })
 ```
 
-### Response Streaming
+### Authentication Helper
 
-Create streaming routes with clean, top-level API methods:
+Built-in methods for handling various authentication strategies:
 
 ```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))
+// Basic Authentication
+router.get('/api/protected', (req) => {
+  const auth = req.auth.basic()
+
+  if (!auth.isValid()) {
+    return auth.unauthorized('Protected area')
   }
+
+  const { username, password } = auth.credentials()
+  // Verify against your user database
+
+  return Response.json({ message: 'Authenticated' })
 })
 
-// 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))
-    }
+// Bearer Token Authentication
+router.get('/api/user-profile', (req) => {
+  const auth = req.auth.bearer()
+
+  if (!auth.isValid()) {
+    return auth.unauthorized('Invalid token')
   }
-  close()
+
+  const token = auth.token()
+  // Verify token validity
+
+  return Response.json({ message: 'Valid token' })
 })
 
-// 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
-```
+// JWT Authentication
+router.post('/api/login', async (req) => {
+  const { username, password } = await req.json()
+  // Verify credentials
 
-### Server-Sent Events (SSE)
+  const auth = req.auth.jwt()
+  const token = auth.sign({ userId: 123, role: 'admin' }, {
+    expiresIn: '1h',
+    secret: 'your-secret-key'
+  })
 
-Real-time data streaming to web clients:
+  return Response.json({ token })
+})
 
-```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))
+router.get('/api/dashboard', (req) => {
+  const auth = req.auth.jwt()
+
+  if (!auth.verify({ secret: 'your-secret-key' })) {
+    return auth.unauthorized('Invalid JWT')
   }
+
+  const payload = auth.payload()
+  return Response.json({ user: payload })
 })
 
-// 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
+// API Key Authentication
+router.get('/api/data', (req) => {
+  const auth = req.auth.apiKey('x-api-key')
+
+  if (!auth.isValid()) {
+    return auth.unauthorized('Invalid API key')
   }
-  
-  // Stream notifications...
+
+  const apiKey = auth.key()
+  // Verify API key against database and check scopes
+
+  return Response.json({ data: 'Secure data' })
 })
-```
 
-### JSON Streaming (NDJSON)
+// OAuth2 Authentication
+router.get('/auth/github', (req) => {
+  const auth = req.auth.oauth2({
+    provider: 'github',
+    clientId: 'your-client-id',
+    redirectUri: 'http://localhost:3000/auth/callback'
+  })
 
-Stream JSON objects line by line:
+  return auth.redirect()
+})
 
-```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 }
-  }
+router.get('/auth/callback', async (req) => {
+  const auth = req.auth.oauth2({
+    provider: 'github',
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    redirectUri: 'http://localhost:3000/auth/callback'
+  })
+
+  const { accessToken, profile } = await auth.handleCallback(req)
+  // Create or update user record
+
+  return Response.redirect('/dashboard')
 })
 
-// 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
+### File Streaming
+
+Easily stream files with range support:
+
+```typescript
+router.get('/files/{filename}', async (req) => {
+  const filename = req.params.filename
+  const path = `./uploads/${filename}`
+
+  // Simple file streaming
+  return router.streamFile(path, {
+    headers: {
+      'Content-Type': 'application/octet-stream',
+      'Content-Disposition': `attachment; filename="${filename}"`
     }
-  }
+  })
+})
+
+// With range support for video/audio streaming
+router.get('/videos/{id}', async (req) => {
+  const videoPath = `./videos/${req.params.id}.mp4`
+  return router.streamFileWithRanges(videoPath, req)
 })
 ```
 
-### Transform Streams
+## Route Groups
+
+```typescript
+router.group({
+  prefix: '/api',
+  middleware: [jsonBody()]
+}, () => {
+  router.get('/users', getUsersHandler)
+  router.post('/users', createUserHandler)
+})
+```
 
-Process incoming request streams using Bun's TransformStream:
+## Parameter Constraints
 
 ```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' } }
-))
+router.get('/users/{id}', getUserHandler)
+  .whereNumber('id')
+
+router.get('/categories/{slug}', getCategoryHandler)
+  .whereAlpha('slug')
+
+// Available constraints
+router.whereNumber('id')
+router.whereAlpha('name')
+router.whereAlphaNumeric('username')
+router.whereUuid('id')
+router.whereIn('status', ['active', 'pending'])
 ```
 
-### Advanced Streaming Features
+## RESTful Resources
+
+```typescript
+// Creates all RESTful routes for 'posts'
+router.resource('posts', 'PostsController')
+
+// Equivalent to:
+router.get('/posts', 'PostsController/index')
+router.get('/posts/{id}', 'PostsController/show')
+router.post('/posts', 'PostsController/store')
+router.put('/posts/{id}', 'PostsController/update')
+router.delete('/posts/{id}', 'PostsController/destroy')
+```
 
-Leverage Bun's performance optimizations:
+## Redirects
 
 ```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()
-})
+router.redirectRoute('/old-path', '/new-path')
+router.permanentRedirectRoute('/very-old-path', '/new-path')
+```
 
-// 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
-})
+## Domain Routing
 
-// 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' }
-    }
+```typescript
+router.domain('{account}.example.com', () => {
+  router.get('/', (req) => {
+    const account = req.params.account
+    return new Response(`Welcome to ${account}'s subdomain!`)
   })
 })
 ```
 
-## Server Configuration
-
-The `serve` method accepts all Bun server options:
+## Configuration
 
 ```typescript
-route.serve({
-  port: 3000,
-  hostname: 'localhost',
-  development: true,
+const router = new Router({
+  verbose: true,
+  apiPrefix: '/api/v1',
+  defaultMiddleware: {
+    api: ['Middleware/Cors', 'Middleware/JsonBody'],
+    web: ['Middleware/Session', 'Middleware/Csrf']
+  }
 })
 ```
 
+## Changelog
+
+Please see our [releases](https://github.com/stackjs/bun-router/releases) page for more information on what has changed recently.
+
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.
+
+## Community
+
+For help, discussion about best practices, or any other conversation that would benefit from being searchable:
+
+[Discussions on GitHub](https://github.com/stacksjs/bun-router/discussions)
+
+For casual chit-chat with others using this package:
+
+[Join the Stacks Discord Server](https://discord.gg/stacksjs)
+
+## Postcardware
+
+"Software that is free, but hopes for a postcard." We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.
+
+Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎
+
+## Sponsors
+
+We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
+
+- [JetBrains](https://www.jetbrains.com/)
+- [The Solana Foundation](https://solana.com/)
+
+## License
+
+The MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.
+
+Made with 💙
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/bun-router?style=flat-square
+[npm-version-href]: https://npmjs.com/package/bun-router
+[github-actions-src]: https://img.shields.io/github/actions/workflow/status/stacksjs/bun-router/ci.yml?style=flat-square&branch=main
+[github-actions-href]: https://github.com/stacksjs/bun-router/actions?query=workflow%3Aci
+
+<!-- [codecov-src]: https://img.shields.io/codecov/c/gh/stacksjs/bun-router/main?style=flat-square
+[codecov-href]: https://codecov.io/gh/stacksjs/bun-router -->