@flight-framework/http 0.0.2 → 0.0.4

package/README.md

@@ -1,6 +1,40 @@
 # @flight-framework/http
 
-Ultra-fast HTTP server for Flight Framework, built on Web Standards.
+HTTP server for Flight Framework. Built on Web Standard APIs with radix-tree routing for maximum performance. Runs on Node.js, Bun, and Deno.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Routing](#routing)
+- [Route Parameters](#route-parameters)
+- [Middleware](#middleware)
+- [Context API](#context-api)
+- [Request Handling](#request-handling)
+- [Response Helpers](#response-helpers)
+- [Error Handling](#error-handling)
+- [Sub-Routers](#sub-routers)
+- [Runtime Adapters](#runtime-adapters)
+- [Static Files](#static-files)
+- [CORS](#cors)
+- [API Reference](#api-reference)
+- [License](#license)
+
+---
+
+## Features
+
+- Radix-tree routing for fast path matching
+- Native Request/Response APIs (Web Standard)
+- Multi-runtime support: Node.js, Bun, Deno
+- Middleware with async/await
+- Type-safe route parameters
+- Built-in helpers for JSON, HTML, redirects
+- Zero external runtime dependencies
+- Full TypeScript support
+
+---
 
 ## Installation
 
@@ -8,6 +42,8 @@ Ultra-fast HTTP server for Flight Framework, built on Web Standards.
 npm install @flight-framework/http
 ```
 
+---
+
 ## Quick Start
 
 ```typescript
@@ -16,140 +52,528 @@ import { serve } from '@flight-framework/http/node';
 
 const app = createServer();
 
-// Simple JSON response
 app.get('/', (c) => c.json({ message: 'Hello Flight!' }));
 
-// Route params
 app.get('/users/:id', (c) => {
     return c.json({ userId: c.params.id });
 });
 
-// POST with body
 app.post('/users', async (c) => {
     const body = await c.req.json();
-    return c.json({ created: true, data: body }, 201);
+    return c.json({ created: true, user: body }, 201);
 });
 
-// Start server
 serve(app, { port: 3000 });
+console.log('Server running at http://localhost:3000');
 ```
 
-## Features
+---
 
-- **Ultra-fast** - Radix-tree based routing for maximum performance
-- **Web Standards** - Uses native Request/Response APIs
-- **Multi-runtime** - Works with Node.js, Bun, and Deno
-- **Lightweight** - Minimal dependencies (~3kb core)
-- **TypeScript** - Full type safety out of the box
+## Routing
 
-## Runtime Adapters
+Register routes using HTTP method helpers:
 
-### Node.js
+```typescript
+app.get('/path', handler);      // GET
+app.post('/path', handler);     // POST
+app.put('/path', handler);      // PUT
+app.patch('/path', handler);    // PATCH
+app.delete('/path', handler);   // DELETE
+app.options('/path', handler);  // OPTIONS
+app.head('/path', handler);     // HEAD
+
+// All methods
+app.all('/path', handler);
+
+// Multiple methods
+app.on(['GET', 'POST'], '/path', handler);
+```
+
+### Route Patterns
 
 ```typescript
-import { createServer } from '@flight-framework/http';
-import { serve } from '@flight-framework/http/node';
+// Static path
+app.get('/about', handler);
 
-serve(app, { port: 3000 });
+// Single parameter
+app.get('/users/:id', handler);
+
+// Multiple parameters
+app.get('/posts/:year/:month/:slug', handler);
+
+// Optional parameter
+app.get('/files/:path?', handler);
+
+// Wildcard (catch-all)
+app.get('/assets/*', handler);
+
+// Named wildcard
+app.get('/docs/:path*', handler);
 ```
 
-### Bun
+---
+
+## Route Parameters
+
+Access route parameters from the context:
 
 ```typescript
-import { createServer } from '@flight-framework/http';
-import { serve } from '@flight-framework/http/bun';
+// Route: /users/:id/posts/:postId
+app.get('/users/:id/posts/:postId', (c) => {
+    const { id, postId } = c.params;
+    return c.json({ userId: id, postId });
+});
 
-serve(app, { port: 3000 });
+// Wildcard parameters
+// Route: /files/*
+// Request: /files/images/photo.jpg
+app.get('/files/*', (c) => {
+    const path = c.params['*'];  // "images/photo.jpg"
+    return c.text(`File: ${path}`);
+});
 ```
 
-### Deno
+### Type-Safe Parameters
 
 ```typescript
-import { createServer } from '@flight-framework/http';
-import { serve } from '@flight-framework/http/deno';
+import type { Context } from '@flight-framework/http';
 
-serve(app, { port: 3000 });
+interface UserParams {
+    id: string;
+    postId: string;
+}
+
+app.get('/users/:id/posts/:postId', (c: Context<UserParams>) => {
+    c.params.id;      // string (typed)
+    c.params.postId;  // string (typed)
+});
 ```
 
+---
+
 ## Middleware
 
+Middleware functions run before route handlers:
+
 ```typescript
-// Logging middleware
+// Global middleware (runs on all routes)
 app.use(async (c, next) => {
     const start = performance.now();
     const response = await next();
     const duration = performance.now() - start;
-    console.log(`${c.req.method} ${c.req.url} - ${duration}ms`);
+    console.log(`${c.req.method} ${c.req.url} - ${duration.toFixed(2)}ms`);
     return response;
 });
 
-// Auth middleware
-app.use(async (c, next) => {
-    const token = c.header('Authorization');
+// Path-specific middleware
+app.use('/api/*', async (c, next) => {
+    // Only runs on /api/* routes
+    return next();
+});
+```
+
+### Authentication Middleware
+
+```typescript
+const authMiddleware = async (c, next) => {
+    const token = c.header('Authorization')?.replace('Bearer ', '');
+    
     if (!token) {
         return c.json({ error: 'Unauthorized' }, 401);
     }
-    c.set('user', { id: '123' });
+    
+    const user = await verifyToken(token);
+    if (!user) {
+        return c.json({ error: 'Invalid token' }, 401);
+    }
+    
+    // Store user in context for later use
+    c.set('user', user);
     return next();
+};
+
+// Apply to specific routes
+app.use('/api/*', authMiddleware);
+
+// Access in route handler
+app.get('/api/profile', (c) => {
+    const user = c.get('user');
+    return c.json(user);
 });
 ```
 
-## Context Helpers
+### Middleware Chain
+
+Multiple middleware functions run in order:
+
+```typescript
+app.get('/protected', 
+    authMiddleware,
+    rateLimitMiddleware,
+    validationMiddleware,
+    (c) => {
+        return c.json({ data: 'secret' });
+    }
+);
+```
+
+---
+
+## Context API
+
+The context object provides access to request data and response helpers:
 
 ```typescript
 app.get('/demo', (c) => {
-    // JSON response
-    return c.json({ data: 'value' });
+    // Request object (Web Standard)
+    c.req;                    // Request
+    c.req.method;             // "GET"
+    c.req.url;                // Full URL
     
-    // Text response
-    return c.text('Hello');
+    // Route parameters
+    c.params;                 // { id: "123" }
+    c.params.id;              // "123"
     
-    // HTML response
-    return c.html('<h1>Hello</h1>');
+    // Query parameters
+    c.query('page');          // "1" or undefined
+    c.query('page', '1');     // "1" (with default)
+    c.queries('tags');        // ["a", "b"] (array)
     
-    // Redirect
-    return c.redirect('/other');
+    // Headers
+    c.header('Content-Type'); // "application/json"
+    c.header('X-Custom');     // Custom header value
     
-    // Access headers
-    const auth = c.header('Authorization');
+    // Cookies
+    c.cookie('session');      // Cookie value
     
-    // Access cookies
-    const session = c.cookie('session');
+    // Context storage
+    c.set('key', 'value');    // Store value
+    c.get('key');             // Retrieve value
     
-    // Access params
-    const id = c.params.id;
+    return c.json({ ok: true });
 });
 ```
 
-## API Reference
+---
 
-### `createServer(options?)`
+## Request Handling
 
-Create a new Flight HTTP server.
+### JSON Body
 
-### `app.get/post/put/delete/patch(path, ...handlers)`
+```typescript
+app.post('/api/users', async (c) => {
+    const body = await c.req.json();
+    // body is parsed JSON
+    return c.json({ received: body });
+});
+```
 
-Register a route handler.
+### Form Data
 
-### `app.use(...middleware)`
+```typescript
+app.post('/upload', async (c) => {
+    const form = await c.req.formData();
+    const name = form.get('name');
+    const file = form.get('file');  // File object
+    
+    return c.json({ name, fileName: file?.name });
+});
+```
 
-Add global middleware.
+### Raw Text
 
-### `app.route(path, subRouter)`
+```typescript
+app.post('/webhook', async (c) => {
+    const text = await c.req.text();
+    return c.text(`Received: ${text}`);
+});
+```
 
-Mount a sub-router.
+### Raw Binary
 
-### `app.notFound(handler)`
+```typescript
+app.post('/binary', async (c) => {
+    const buffer = await c.req.arrayBuffer();
+    return c.json({ bytes: buffer.byteLength });
+});
+```
+
+---
+
+## Response Helpers
+
+```typescript
+// JSON response
+c.json({ data: 'value' });
+c.json({ created: true }, 201);
+c.json({ error: 'Not found' }, 404);
+
+// Text response
+c.text('Hello, World!');
+c.text('Created', 201);
+
+// HTML response
+c.html('<h1>Hello</h1>');
+c.html('<!DOCTYPE html>...', 200);
+
+// Redirect
+c.redirect('/new-location');
+c.redirect('/login', 302);      // Temporary (default)
+c.redirect('/moved', 301);      // Permanent
+
+// No Content
+c.body(null, 204);
+
+// Custom response
+return new Response(body, {
+    status: 200,
+    headers: { 'X-Custom': 'value' },
+});
+
+// Set response headers
+c.header('X-Request-Id', requestId);
+c.header('Cache-Control', 'max-age=3600');
+
+// Set cookies
+c.cookie('session', token, {
+    httpOnly: true,
+    secure: true,
+    sameSite: 'Strict',
+    maxAge: 60 * 60 * 24,  // 1 day
+});
+```
 
-Set custom 404 handler.
+---
 
-### `app.onError(handler)`
+## Error Handling
 
-Set custom error handler.
+### Global Error Handler
 
-### `app.fetch(request)`
+```typescript
+app.onError((error, c) => {
+    console.error('Error:', error);
+    
+    if (error instanceof ValidationError) {
+        return c.json({ error: error.message }, 400);
+    }
+    
+    return c.json({ error: 'Internal Server Error' }, 500);
+});
+```
+
+### 404 Not Found
+
+```typescript
+app.notFound((c) => {
+    return c.json({ 
+        error: 'Not Found',
+        path: new URL(c.req.url).pathname,
+    }, 404);
+});
+```
+
+### Throwing Errors
+
+```typescript
+import { HTTPException } from '@flight-framework/http';
+
+app.get('/protected', (c) => {
+    if (!c.get('user')) {
+        throw new HTTPException(401, 'Unauthorized');
+    }
+    return c.json({ secret: 'data' });
+});
+```
+
+---
+
+## Sub-Routers
+
+Organize routes into modules:
+
+```typescript
+// routes/users.ts
+import { createServer } from '@flight-framework/http';
+
+export const users = createServer();
+
+users.get('/', (c) => c.json({ users: [] }));
+users.get('/:id', (c) => c.json({ id: c.params.id }));
+users.post('/', (c) => c.json({ created: true }));
+
+// main.ts
+import { createServer } from '@flight-framework/http';
+import { users } from './routes/users';
+
+const app = createServer();
+
+// Mount sub-router
+app.route('/api/users', users);
+
+// Routes:
+// GET  /api/users
+// GET  /api/users/:id
+// POST /api/users
+```
+
+---
+
+## Runtime Adapters
+
+### Node.js
+
+```typescript
+import { createServer } from '@flight-framework/http';
+import { serve } from '@flight-framework/http/node';
+
+const app = createServer();
+
+serve(app, { 
+    port: 3000,
+    hostname: '0.0.0.0',
+});
+```
+
+### Bun
+
+```typescript
+import { createServer } from '@flight-framework/http';
+import { serve } from '@flight-framework/http/bun';
+
+const app = createServer();
+
+serve(app, { port: 3000 });
+
+// Or use Bun's native API
+Bun.serve({
+    port: 3000,
+    fetch: app.fetch,
+});
+```
+
+### Deno
+
+```typescript
+import { createServer } from '@flight-framework/http';
+import { serve } from '@flight-framework/http/deno';
+
+const app = createServer();
+
+serve(app, { port: 3000 });
+
+// Or use Deno's native API
+Deno.serve({ port: 3000 }, app.fetch);
+```
+
+### Cloudflare Workers
+
+```typescript
+import { createServer } from '@flight-framework/http';
+
+const app = createServer();
+
+// ... define routes
+
+export default {
+    fetch: app.fetch,
+};
+```
+
+---
+
+## Static Files
+
+Serve static files from a directory:
+
+```typescript
+import { serveStatic } from '@flight-framework/http/static';
+
+// Serve from 'public' directory
+app.use('/static/*', serveStatic({ root: './public' }));
+
+// With options
+app.use('/assets/*', serveStatic({
+    root: './assets',
+    maxAge: 60 * 60 * 24,  // 1 day cache
+    index: 'index.html',
+}));
+```
+
+---
+
+## CORS
+
+Enable Cross-Origin Resource Sharing:
+
+```typescript
+import { cors } from '@flight-framework/http/cors';
+
+// Allow all origins
+app.use(cors());
+
+// Specific origins
+app.use(cors({
+    origin: 'https://example.com',
+    methods: ['GET', 'POST', 'PUT', 'DELETE'],
+    headers: ['Content-Type', 'Authorization'],
+    credentials: true,
+    maxAge: 86400,
+}));
+
+// Dynamic origin
+app.use(cors({
+    origin: (origin) => {
+        return origin.endsWith('.example.com');
+    },
+}));
+```
+
+---
+
+## API Reference
+
+### createServer(options?)
+
+Create a new Flight HTTP server.
 
-Handle a Request and return a Response (Web Standard).
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `strict` | `boolean` | `true` | Strict routing (trailing slash matters) |
+| `getPath` | `function` | - | Custom path extraction |
+
+### Context Methods
+
+| Method | Description |
+|--------|-------------|
+| `c.req` | Web Standard Request object |
+| `c.params` | Route parameters |
+| `c.query(name, default?)` | Get query parameter |
+| `c.queries(name)` | Get all values for query param |
+| `c.header(name)` | Get request header |
+| `c.cookie(name)` | Get cookie value |
+| `c.set(key, value)` | Store value in context |
+| `c.get(key)` | Retrieve value from context |
+| `c.json(data, status?)` | JSON response |
+| `c.text(text, status?)` | Text response |
+| `c.html(html, status?)` | HTML response |
+| `c.redirect(url, status?)` | Redirect response |
+| `c.body(body, status?)` | Raw body response |
+
+### App Methods
+
+| Method | Description |
+|--------|-------------|
+| `app.get/post/put/delete/patch(path, ...handlers)` | Register route |
+| `app.all(path, ...handlers)` | All HTTP methods |
+| `app.on(methods[], path, ...handlers)` | Specific methods |
+| `app.use(...middleware)` | Add middleware |
+| `app.use(path, ...middleware)` | Path-specific middleware |
+| `app.route(path, subRouter)` | Mount sub-router |
+| `app.notFound(handler)` | Custom 404 handler |
+| `app.onError(handler)` | Custom error handler |
+| `app.fetch(request)` | Handle request (Web Standard) |
+
+---
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flight-framework/http",
-    "version": "0.0.2",
+    "version": "0.0.4",
     "description": "Ultra-fast HTTP server for Flight Framework - Built on Web Standards",
     "keywords": [
         "flight",
@@ -54,4 +54,4 @@
         "typescript": "^5.7.0",
         "vitest": "^2.0.0"
     }
-}
+}