@stacksjs/bun-router 0.0.14 → 0.0.15

package/README.md

@@ -1,720 +1,397 @@
-<p align="center"><img src=".github/art/cover.jpg" alt="Social Card of this repo"></p>
+# @bun-router
 
-[![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.
+A Laravel-inspired router for Bun applications.
 
 ## Features
 
-- 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
+- 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
+bun add @bun-router
 ```
 
 ## Basic Usage
 
 ```typescript
-import { Router } from 'bun-router'
+import { route } from '@bun-router'
 
-// Create a router
-const router = new Router()
-
-// 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 })
-})
+// Basic route with inline handler
+route.get('/', () => new Response('Hello World!'))
 
-// Start the server
-router.serve({
-  port: 3000,
-})
-```
-
-## Route Options
-
-```typescript
-// Route with path parameters
-router.get('/users/{id}', (req) => {
+// Route with parameters
+route.get('/users/{id}', (req) => {
   const { id } = req.params
-  return Response.json({ id })
+  return Response.json({ userId: id })
 })
 
-// Named routes
-router.get('/users/{id}', getUserHandler, 'api', 'users.show')
-
-// Generate URL for named route
-const url = router.route('users.show', { id: '123' })
-```
-
-## Middleware
+// Route with action class
+route.post('/subscribe', 'Actions/SubscribeAction')
 
-```typescript
-import { cors, jsonBody, Router } from 'bun-router'
-
-const router = new Router()
+// Route grouping
+route.group({ prefix: '/api' }, () => {
+  route.get('/users', 'Actions/User/IndexAction')
+  route.post('/users', 'Actions/User/StoreAction')
+})
 
-// Use middleware globally
-router.use(jsonBody())
-router.use(cors())
+// Health check route
+route.health()
 
-// Or apply to a group of routes
-router.group({
-  prefix: '/api',
-  middleware: [jsonBody(), cors()]
-}, () => {
-  router.get('/users', () => Response.json({ users: [] }))
+// Start the server
+route.serve({
+  port: 3000,
 })
 ```
 
-### Built-in Middleware
+## Action Classes
 
-- **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
+Action classes provide a clean way to organize your route handlers. Create a class that implements a `handle` method:
 
 ```typescript
-import { EnhancedRequest, MiddlewareHandler, NextFunction } from 'bun-router'
-
-class LoggerMiddleware {
-  async handle(req: EnhancedRequest, next: NextFunction): Promise<Response> {
-    console.log(`${req.method} ${req.url}`)
-    return next()
-  }
-}
+// actions/subscribe_action.ts
+import type { EnhancedRequest } from '@bun-router'
 
-// Use custom middleware
-router.use(new LoggerMiddleware())
-```
-
-## WebSocket Support
+export default class SubscribeAction {
+  async handle(request: EnhancedRequest): Promise<Response> {
+    const data = await request.json()
 
-bun-router provides seamless integration with Bun's high-performance WebSocket capabilities:
+    // Handle subscription logic
 
-```typescript
-import type { ServerWebSocket } from 'bun'
-import { Router } from 'bun-router'
-
-// Define data type for WebSocket clients
-interface ClientData {
-  userId: string
-  room: string
+    return Response.json({
+      success: true,
+      message: 'Subscribed successfully'
+    })
+  }
 }
+```
 
-// Create a router
-const router = new Router<ClientData>() // Type-safe WebSockets
-
-// 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!')
-  },
-
-  // 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`)
-    }
-
-    // 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`)
-  },
+## Middleware
 
-  // 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)
+Middleware allows you to run code before your route handlers. You can use middleware globally or for specific routes/groups.
 
-  // Enable per-message compression
-  perMessageDeflate: {
-    compress: '16KB', // Use 16KB compression level
-    decompress: true
-  },
+### Creating Middleware
 
-  sendPings: true, // Send ping frames to keep connection alive (default)
-  publishToSelf: false // Don't send published messages to publisher (default)
-})
+Create a middleware class that implements the `handle` method:
 
-// Start the server
-router.serve({ port: 3000 })
-```
-
-### WebSocket Utility Methods
+```typescript
+// middleware/auth.ts
+import type { EnhancedRequest, Middleware, NextFunction } from '@bun-router'
 
-The router provides utility methods for working with WebSockets:
+export default class AuthMiddleware implements Middleware {
+  async handle(req: EnhancedRequest, next: NextFunction): Promise<Response> {
+    const authHeader = req.headers.get('Authorization')
 
-```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 (!authHeader) {
+      return new Response('Unauthorized', { status: 401 })
     }
-  })
 
-  if (!success) {
-    return new Response('Failed to upgrade connection', { status: 400 })
+    // If auth passes, continue to next middleware or route handler
+    return next()
   }
-
-  // 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')
-})
+}
 ```
 
-### WebSocket Patterns
+### Using Middleware
 
-Here are some common patterns for working with WebSockets:
+You can use middleware in several ways:
 
-#### JSON Communication
+1. Global Middleware (applies to all routes):
 
 ```typescript
-// 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' }))
-    }
-  }
+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()
 })
 ```
 
-#### Room-Based Chat
+2. Group Middleware (applies to all routes in a group):
 
 ```typescript
-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}`)
-    }
-  }
+route.group({
+  prefix: '/api',
+  middleware: ['Middleware/Auth']
+}, () => {
+  route.get('/users', 'Actions/User/IndexAction')
+  route.post('/users', 'Actions/User/StoreAction')
 })
-
-function broadcastToRoom(room, message) {
-  router.publish(room, message)
-}
 ```
 
-#### Handling Backpressure
+3. Inline Middleware:
 
 ```typescript
-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.group({
+  middleware: [
+    async (req, next) => {
+      console.log('Processing request...')
+      const response = await next()
+      console.log('Request complete')
+      return response
     }
-  },
-
-  drain(ws) {
-    // Socket is ready to receive more data
-    if (ws.data.pendingOperations?.length) {
-      const nextOp = ws.data.pendingOperations.shift()
-      processOperation(ws, nextOp)
-    }
-  }
+  ]
+}, () => {
+  route.get('/users', 'Actions/User/IndexAction')
 })
 ```
 
-## Bun-Native Features
-
-bun-router fully integrates with Bun's native `Bun.serve()` API, leveraging the latest Bun features for optimal performance.
-
-### Static Responses
+## Route Groups
 
-Define static routes without handler functions for optimal performance:
+Group related routes with a common prefix and middleware:
 
 ```typescript
-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.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')
+  })
+})
 ```
 
-### Method-Specific Handlers
+## Route Parameters
 
-The router automatically organizes multiple methods for the same path into Bun's method-specific handlers:
+Access route parameters through the `params` object:
 
 ```typescript
-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
-// }
+route.get('/users/{id}/posts/{postId}', (req) => {
+  const { id, postId } = req.params
+  return Response.json({ userId: id, postId })
+})
 ```
 
-### Hot Reloading
+## TypeScript Support
 
-Update routes without restarting the server:
+The router is written in TypeScript and provides full type definitions:
 
 ```typescript
-// 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()
-```
-
-### Error Handling
-
-Add a global error handler for all routes:
+import type { ActionHandler, EnhancedRequest, Middleware, NextFunction } from '@bun-router'
 
-```typescript
-router.onError((error) => {
-  console.error(error)
-  return new Response(`Server Error: ${error.message}`, {
-    status: 500,
-    headers: { 'Content-Type': 'text/plain' }
-  })
-})
+// Type-safe request handling
+const handler: ActionHandler = (req: EnhancedRequest) => {
+  const { id } = req.params
+  return Response.json({ id })
+}
 
-// Define a route that might throw an error
-router.get('/api/risky', () => {
-  throw new Error('Something went wrong')
-})
+// Type-safe middleware
+const loggerMiddleware: Middleware = {
+  handle: async (req: EnhancedRequest, next: NextFunction) => {
+    console.log(`${req.method} ${req.url}`)
+    return next()
+  }
+}
 
-// Serve with the error handler
-router.serve({ port: 3000 })
+route.use(loggerMiddleware.handle)
+route.get('/users/{id}', handler)
 ```
 
-### Type-Safe Route Parameters
+## Streaming Support
 
-TypeScript automatically infers parameter types from route paths:
+The router provides comprehensive streaming capabilities for modern web applications:
 
-```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
+### File Streaming
 
-Built-in support for working with cookies:
+Stream files with automatic content-type detection:
 
 ```typescript
-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 })
-})
-
-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')
+// Basic file streaming
+route.get('/download/{filename}', (req) => {
+  const { filename } = req.params
+  return route.streamFile(`./uploads/${filename}`)
 })
 
-router.get('/logout', (req) => {
-  // Delete cookies
-  req.cookies.delete('user_id')
-  return new Response('Logged out')
+// 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)
 })
 ```
 
-### Authentication Helper
+### Response Streaming
 
-Built-in methods for handling various authentication strategies:
+Create streaming routes with clean, top-level API methods:
 
 ```typescript
-// Basic Authentication
-router.get('/api/protected', (req) => {
-  const auth = req.auth.basic()
-
-  if (!auth.isValid()) {
-    return auth.unauthorized('Protected area')
+// 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))
   }
-
-  const { username, password } = auth.credentials()
-  // Verify against your user database
-
-  return Response.json({ message: 'Authenticated' })
 })
 
-// Bearer Token Authentication
-router.get('/api/user-profile', (req) => {
-  const auth = req.auth.bearer()
-
-  if (!auth.isValid()) {
-    return auth.unauthorized('Invalid token')
+// 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))
+    }
   }
-
-  const token = auth.token()
-  // Verify token validity
-
-  return Response.json({ message: 'Valid token' })
+  close()
 })
 
-// JWT Authentication
-router.post('/api/login', async (req) => {
-  const { username, password } = await req.json()
-  // Verify credentials
-
-  const auth = req.auth.jwt()
-  const token = auth.sign({ userId: 123, role: 'admin' }, {
-    expiresIn: '1h',
-    secret: 'your-secret-key'
-  })
-
-  return Response.json({ token })
-})
-
-router.get('/api/dashboard', (req) => {
-  const auth = req.auth.jwt()
-
-  if (!auth.verify({ secret: 'your-secret-key' })) {
-    return auth.unauthorized('Invalid JWT')
+// 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
+```
 
-  const payload = auth.payload()
-  return Response.json({ user: payload })
-})
+### Server-Sent Events (SSE)
 
-// API Key Authentication
-router.get('/api/data', (req) => {
-  const auth = req.auth.apiKey('x-api-key')
+Real-time data streaming to web clients:
 
-  if (!auth.isValid()) {
-    return auth.unauthorized('Invalid API key')
+```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))
   }
-
-  const apiKey = auth.key()
-  // Verify API key against database and check scopes
-
-  return Response.json({ data: 'Secure data' })
 })
 
-// OAuth2 Authentication
-router.get('/auth/github', (req) => {
-  const auth = req.auth.oauth2({
-    provider: 'github',
-    clientId: 'your-client-id',
-    redirectUri: 'http://localhost:3000/auth/callback'
-  })
-
-  return auth.redirect()
-})
-
-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')
+// 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...
 })
+```
 
-### File Streaming
+### JSON Streaming (NDJSON)
 
-Easily stream files with range support:
+Stream JSON objects line by line:
 
 ```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}"`
-    }
-  })
+// 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 }
+  }
 })
 
-// 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)
+// 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
+    }
+  }
 })
 ```
 
-## Route Groups
-
-```typescript
-router.group({
-  prefix: '/api',
-  middleware: [jsonBody()]
-}, () => {
-  router.get('/users', getUsersHandler)
-  router.post('/users', createUserHandler)
-})
-```
+### Transform Streams
 
-## Parameter Constraints
+Process incoming request streams using Bun's TransformStream:
 
 ```typescript
-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'])
+// 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' } }
+))
 ```
 
-## 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')
-```
+### Advanced Streaming Features
 
-## Redirects
+Leverage Bun's performance optimizations:
 
 ```typescript
-router.redirectRoute('/old-path', '/new-path')
-router.permanentRedirectRoute('/very-old-path', '/new-path')
-```
+// 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()
+})
 
-## Domain Routing
+// 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
+})
 
-```typescript
-router.domain('{account}.example.com', () => {
-  router.get('/', (req) => {
-    const account = req.params.account
-    return new Response(`Welcome to ${account}'s subdomain!`)
+// 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' }
+    }
   })
 })
 ```
 
-## Configuration
+## Server Configuration
+
+The `serve` method accepts all Bun server options:
 
 ```typescript
-const router = new Router({
-  verbose: true,
-  apiPrefix: '/api/v1',
-  defaultMiddleware: {
-    api: ['Middleware/Cors', 'Middleware/JsonBody'],
-    web: ['Middleware/Session', 'Middleware/Csrf']
-  }
+route.serve({
+  port: 3000,
+  hostname: 'localhost',
+  development: true,
 })
 ```
 
-## Changelog
-
-Please see our [releases](https://github.com/stackjs/bun-router/releases) page for more information on what has changed recently.
-
 ## Contributing
 
-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 -->
+Contributions are welcome! Please feel free to submit a Pull Request.