vector-framework 0.9.7 → 0.9.9

package/README.md

@@ -1,8 +1,11 @@
 # Vector Framework
 
-**The speed of Bun. The developer experience you love.**
+**Blazing fast, secure, and developer-friendly API framework for Bun**
 
-Vector brings the blazing performance of Bun to developers who appreciate the simplicity and elegance of frameworks like Encore. Build production-ready APIs with a familiar, declarative syntax while leveraging Bun's incredible speed.
+- **70,000+ requests/second** - Optimized for extreme performance
+- **Single dependency** - Only itty-router, minimizing security risks
+- **Zero build step** - Native TypeScript execution with Bun
+- **Encore-like DX** - Declarative, type-safe APIs you'll love
 
 ## Quick Start
 
@@ -12,9 +15,9 @@ Vector brings the blazing performance of Bun to developers who appreciate the si
 bun add vector-framework
 ```
 
-### Configuration
+### 1. Configure Your App
 
-Create a `vector.config.ts` file in your project root:
+Create `vector.config.ts` in your project root:
 
 ```typescript
 // vector.config.ts
@@ -22,507 +25,674 @@ import type { VectorConfigSchema } from "vector-framework";
 
 const config: VectorConfigSchema = {
   // Server configuration
-  port: 3000, // Server port (default: 3000)
-  hostname: "localhost", // Server hostname (default: localhost)
-  routesDir: "./routes", // Routes directory (default: ./routes)
-  development: process.env.NODE_ENV !== "production", // Development mode
-  reusePort: true, // Reuse port (default: true)
-  idleTimeout: 60, // Idle timeout in seconds (default: 60)
+  port: 3000,
+  hostname: "localhost",
+  development: process.env.NODE_ENV !== "production",
+  routesDir: "./routes", // Auto-discovers routes here
 
   // CORS configuration
   cors: {
-    origin: "*", // String, array, or function
-    credentials: true, // Allow credentials
+    origin: "*",
+    credentials: true,
     allowHeaders: ["Content-Type", "Authorization"],
     allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
-    exposeHeaders: ["X-Total-Count"],
-    maxAge: 86400, // Preflight cache duration in seconds
   },
+
+  // Authentication handler
+  auth: async (request) => {
+    const token = request.headers.get("Authorization")?.replace("Bearer ", "");
+    if (token === "valid-token") {
+      return { id: "user-123", email: "user@example.com" };
+    }
+    throw new Error("Invalid token");
+  },
+
+  // Optional: Cache handler (Redis example)
+  cache: async (key, factory, ttl) => {
+    // Your caching logic here
+    const cached = await redis.get(key);
+    if (cached) return JSON.parse(cached);
+
+    const value = await factory();
+    await redis.setex(key, ttl, JSON.stringify(value));
+    return value;
+  },
+
+  // Optional: Middleware
+  before: [
+    async (request) => {
+      console.log(`${request.method} ${request.url}`);
+      return request;
+    }
+  ],
+  after: [
+    async (response, request) => {
+      const duration = Date.now() - (request.startTime || Date.now());
+      response.headers.set("X-Response-Time", `${duration}ms`);
+      return response;
+    }
+  ],
 };
 
 export default config;
 ```
 
-### Your First API (Encore-style)
+### 2. Create Your First Route
 
 ```typescript
 // routes/hello.ts
 import { route } from "vector-framework";
 
-// Public endpoint - clean and declarative
+// Simple public endpoint
 export const hello = route(
   {
     method: "GET",
     path: "/hello/:name",
+    expose: true, // Public endpoint (default: true)
   },
   async (req) => {
-    const { name } = req.params!;
-    return { message: `Hello ${name}!` };
+    return { message: `Hello ${req.params.name}!` };
   }
 );
 
-// Protected endpoint - auth built-in
+// Protected endpoint - uses auth from config
 export const getProfile = route(
   {
     method: "GET",
     path: "/profile",
-    auth: true, // That's it! Auth handled.
+    auth: true, // Requires authentication
+    expose: true,
   },
   async (req) => {
     return {
-      user: req.authUser,
-      lastLogin: new Date(),
+      user: req.authUser, // Typed from your auth handler
+      timestamp: new Date(),
     };
   }
 );
-```
 
-### Start Your Server
-
-```typescript
-// server.ts
-import vector from "vector-framework";
-
-// Set up auth (once, globally)
-vector.protected = async (request) => {
-  const token = request.headers.get("Authorization")?.replace("Bearer ", "");
-  // Your auth logic here
-  if (token === "valid-token") {
-    return { id: "user-123", email: "user@example.com" };
+// Cached endpoint
+export const getUsers = route(
+  {
+    method: "GET",
+    path: "/users",
+    cache: 300, // Cache for 5 minutes
+    expose: true,
+  },
+  async () => {
+    // Expensive operation, will be cached
+    const users = await db.users.findMany();
+    return { users };
   }
-  throw new Error("Invalid token");
-};
-
-// Start server - routes auto-discovered from ./routes
-vector.serve({ port: 3000 });
+);
 ```
 
-### CLI Commands
+### 3. Start Your Server
 
 ```bash
-# Run development server
+# Development mode with hot reload
 bun vector dev
 
-# Run production server
+# Production mode
 bun vector start
 
-# Build for production
-bun vector build
-
-# Run with custom options
-bun vector dev --port 3000 --routes ./api
+# With custom options
+bun vector dev --port 4000 --routes ./api
 ```
 
-## Why Vector?
-
-If you've been looking for Encore-like developer experience with Bun's performance, Vector is your answer. Define your routes declaratively, enjoy automatic type safety, and ship faster than ever.
+That's it! Your API is running at `http://localhost:3000` 🎉
 
-## Features
+## TypeScript Type Safety
 
-- **Fast & Lightweight** - Built on Bun and itty-router for maximum performance
-- **Type-Safe** - Full TypeScript support with excellent type inference
-- **Auto Route Discovery** - Automatically discovers and loads routes from your filesystem
-- **Middleware System** - Flexible pre/post request middleware pipeline
-- **Built-in Authentication** - Simple but powerful authentication system
-- **Response Caching** - Automatic response caching with configurable TTL
-- **CORS Support** - Configurable CORS with sensible defaults
-- **Developer Experience** - Auto route discovery and CLI tools
+Vector provides full type safety with customizable types. Define your types in the config and use them in routes:
 
-## Familiar Patterns, Modern Performance
+```typescript
+// vector.config.ts
+import type { VectorConfigSchema, VectorTypes } from "vector-framework";
 
-### Real-World Example: User Service
+// Define your custom user type
+interface MyUser {
+  id: string;
+  email: string;
+  role: "admin" | "user";
+  permissions: string[];
+}
 
-```typescript
-// routes/users.ts
-import { route } from "vector-framework";
-import { db } from "../db";
+// Extend Vector types
+interface MyAppTypes extends VectorTypes {
+  auth: MyUser;
+}
 
-// Public endpoint with caching
-export const listUsers = route(
-  {
-    method: "GET",
-    path: "/users",
-    cache: 300, // Cache for 5 minutes
-  },
-  async () => {
-    const users = await db.user.findMany();
-    return { users };
-  }
-);
+// Use in config with type parameter
+const config: VectorConfigSchema<MyAppTypes> = {
+  port: 3000,
 
-// Protected endpoint with automatic body parsing
-export const createUser = route(
-  {
-    method: "POST",
-    path: "/users",
-    auth: true, // Auth required
+  // Auth handler returns your custom type
+  auth: async (request): Promise<MyUser> => {
+    // Your auth logic
+    return {
+      id: "user-123",
+      email: "user@example.com",
+      role: "admin",
+      permissions: ["read", "write"],
+    };
   },
-  async (req) => {
-    const { name, email } = req.content; // Type-safe, auto-parsed
+};
 
-    const user = await db.user.create({
-      data: { name, email },
-    });
+export default config;
+export type { MyAppTypes }; // Export for use in routes
+```
 
-    return { user };
-  }
-);
+```typescript
+// routes/admin.ts
+import { route, APIError } from "vector-framework";
+import type { MyAppTypes } from "../vector.config";
 
-// Parameter extraction made simple
-export const getUser = route(
+// Use type parameter to get fully typed request
+export const adminOnly = route<MyAppTypes>(
   {
     method: "GET",
-    path: "/users/:id",
+    path: "/admin/data",
+    auth: true,
+    expose: true,
   },
   async (req) => {
-    const { id } = req.params!;
-    const user = await db.user.findUnique({ where: { id } });
-
-    if (!user) {
-      throw new APIError("User not found", 404);
+    // req.authUser is now typed as MyUser
+    if (req.authUser?.role !== "admin") {
+      throw APIError.forbidden("Admin access required");
     }
 
-    return { user };
+    // TypeScript knows these properties exist
+    return {
+      user: req.authUser.email,
+      permissions: req.authUser.permissions,
+    };
   }
 );
 ```
 
-## Why Choose Vector?
-
-### 🚀 Bun-Powered Performance
+## Core Features
 
-- **Native TypeScript** execution without transpilation overhead
-- **Significantly faster** startup times and request handling
-- **Minimal memory footprint** thanks to Bun's efficient runtime
+### Route Options
 
-### 💡 Developer Experience
-
-- **Encore-inspired API** - If you know Encore, you already know Vector
-- **Auto route discovery** - Just write your routes, we'll find them
-- **Type safety everywhere** - Full TypeScript support
-- **Built-in essentials** - Auth, caching, CORS, middleware - all included
+```typescript
+interface RouteOptions {
+  method: string;           // HTTP method (GET, POST, etc.)
+  path: string;            // Route path with params (/users/:id)
+  expose?: boolean;        // Make route accessible (default: true)
+  auth?: boolean;          // Require authentication
+  cache?: number | {       // Cache configuration
+    ttl: number;          // Time to live in seconds
+    key?: string;         // Custom cache key
+  };
+  rawRequest?: boolean;    // Skip body parsing
+  rawResponse?: boolean;   // Return raw response
+  responseContentType?: string; // Response content type
+}
+```
 
-### 🔄 Easy Migration
+### Request Object
 
-Moving from Express, Fastify, or Encore? Vector makes it simple:
+Every route handler receives a typed request object:
 
 ```typescript
-// Encore-style (what you know)
-export const get = api(
-  { expose: true, method: "GET", path: "/hello/:name" },
-  async ({ name }: { name: string }): Promise<Response> => {
-    const msg = `Hello ${name}!`;
-    return { message: msg };
-  }
-);
-
-// Vector-style (what you write)
-export const hello = route(
-  { expose: true, method: "GET", path: "/hello/:name" },
+export const example = route(
+  { method: "POST", path: "/example/:id" },
   async (req) => {
-    return { message: `Hello ${req.params.name}!` };
+    // All available request properties:
+    req.params.id;        // URL parameters
+    req.query.search;      // Query parameters
+    req.headers;           // Request headers
+    req.cookies;           // Parsed cookies
+    req.content;           // Parsed body (JSON/form data)
+    req.authUser;          // Authenticated user (when auth: true)
+    req.context;           // Request context
+    req.metadata;          // Route metadata
   }
 );
 ```
 
-## For Encore Users
+### Error Handling
 
-Switching from Encore? You'll feel right at home. Vector provides the same declarative, type-safe API design with the performance benefits of Bun:
-
-| Encore                 | Vector                           |
-| ---------------------- | -------------------------------- |
-| `api.requireAuth()`    | `{ auth: true }` in route config |
-| Auto-generated clients | Not yet available                |
-| Built-in tracing       | Middleware support               |
-| Cloud deployment       | Deploy anywhere Bun runs         |
-
-**The key difference:** Vector runs on Bun, giving you significantly better performance and lower resource usage while maintaining the developer experience you love.
-
-## Route Options
+Vector provides comprehensive error responses:
 
 ```typescript
-interface RouteOptions {
-  method: string; // HTTP method (GET, POST, etc.)
-  path: string; // Route path with params (/users/:id)
-  expose?: boolean; // Make route accessible (default: true)
-  auth?: boolean; // Require authentication (default: false)
-  cache?:
-    | number
-    | {
-        // Cache configuration
-        ttl: number; // Time to live in seconds
-        key?: string; // Custom cache key
-      };
-  rawRequest?: boolean; // Skip body parsing (default: false)
-  rawResponse?: boolean; // Return raw response (default: false)
-  responseContentType?: string; // Response content type
-}
-```
+import { APIError } from "vector-framework";
 
-## Middleware
+export const example = route(
+  { method: "GET", path: "/data/:id" },
+  async (req) => {
+    // Client errors (4xx)
+    if (!req.params.id) {
+      throw APIError.badRequest("ID is required");
+    }
 
-### Before Middleware (Pre-handlers)
+    const data = await findData(req.params.id);
+    if (!data) {
+      throw APIError.notFound("Data not found");
+    }
 
-```typescript
-const authMiddleware = async (request) => {
-  // Modify request or return Response to short-circuit
-  request.customData = "value";
-  return request;
-};
+    if (!canAccess(req.authUser, data)) {
+      throw APIError.forbidden("Access denied");
+    }
+
+    // Rate limiting
+    if (await isRateLimited(req)) {
+      throw APIError.tooManyRequests("Please wait before trying again");
+    }
 
-const rateLimitMiddleware = async (request) => {
-  // Return Response to stop processing
-  if (tooManyRequests) {
-    return new Response("Too Many Requests", { status: 429 });
+    // Server errors (5xx)
+    try {
+      return await processData(data);
+    } catch (error) {
+      throw APIError.internalServerError("Processing failed");
+    }
   }
-  return request;
-};
+);
 ```
 
-### Finally Middleware (Post-handlers)
+## Configuration Reference
+
+### VectorConfigSchema
 
 ```typescript
-const corsMiddleware = async (response, request) => {
-  // Modify response headers
-  response.headers.set("X-Custom-Header", "value");
-  return response;
-};
+interface VectorConfigSchema {
+  // Server
+  port?: number;              // Server port (default: 3000)
+  hostname?: string;          // Server hostname (default: localhost)
+  reusePort?: boolean;        // Reuse port (default: true)
+  development?: boolean;      // Development mode
+  routesDir?: string;         // Routes directory (default: ./routes)
+  routeExcludePatterns?: string[]; // Patterns to exclude from route scanning
+  idleTimeout?: number;       // Idle timeout in seconds
+
+  // CORS
+  cors?: CorsOptions | boolean;
+
+  // Handlers
+  auth?: ProtectedHandler;    // Authentication handler
+  cache?: CacheHandler;        // Cache handler
+
+  // Middleware
+  before?: BeforeMiddleware[]; // Pre-request middleware
+  after?: AfterMiddleware[];    // Post-response middleware
+}
 ```
 
-## Authentication
-
-Implement your authentication logic:
+### Example: Full Configuration
 
 ```typescript
-vector.protected = async (request) => {
-  const authHeader = request.headers.get("Authorization");
-
-  if (!authHeader?.startsWith("Bearer ")) {
-    throw new Error("Invalid authorization header");
-  }
+// vector.config.ts
+import type { VectorConfigSchema } from "vector-framework";
+import { verifyJWT } from "./lib/auth";
+import { redis } from "./lib/redis";
 
-  const token = authHeader.substring(7);
-  const user = await validateToken(token);
+const config: VectorConfigSchema = {
+  port: process.env.PORT || 3000,
+  hostname: "0.0.0.0",
+  development: process.env.NODE_ENV !== "production",
+  routesDir: "./api/routes",
+  routeExcludePatterns: ["*.test.ts", "*.spec.ts"], // Optional: custom exclusions
+  idleTimeout: 60,
 
-  if (!user) {
-    throw new Error("Invalid token");
-  }
+  cors: {
+    origin: ["https://example.com", "https://app.example.com"],
+    credentials: true,
+    allowHeaders: ["Content-Type", "Authorization", "X-Request-ID"],
+    allowMethods: ["GET", "POST", "PUT", "DELETE"],
+    maxAge: 86400,
+  },
 
-  return user; // This will be available as req.authUser
-};
-```
+  auth: async (request) => {
+    const token = request.headers.get("Authorization")?.replace("Bearer ", "");
+    if (!token) throw new Error("No token provided");
 
-## Caching
+    const user = await verifyJWT(token);
+    if (!user) throw new Error("Invalid token");
 
-Implement your caching strategy:
+    return user;
+  },
 
-```typescript
-vector.cache = async (key, factory, ttl) => {
-  // Example with Redis
-  const cached = await redis.get(key);
-  if (cached) return JSON.parse(cached);
+  cache: async (key, factory, ttl) => {
+    const cached = await redis.get(key);
+    if (cached) return JSON.parse(cached);
 
-  const value = await factory();
-  await redis.setex(key, ttl, JSON.stringify(value));
+    const value = await factory();
+    await redis.setex(key, ttl, JSON.stringify(value));
+    return value;
+  },
 
-  return value;
+  before: [
+    // Logging middleware
+    async (request) => {
+      request.startTime = Date.now();
+      console.log(`[${new Date().toISOString()}] ${request.method} ${request.url}`);
+      return request;
+    },
+
+    // Request ID middleware
+    async (request) => {
+      request.id = crypto.randomUUID();
+      return request;
+    },
+  ],
+
+  after: [
+    // Response time header
+    async (response, request) => {
+      const duration = Date.now() - (request.startTime || Date.now());
+      response.headers.set("X-Response-Time", `${duration}ms`);
+      return response;
+    },
+
+    // Security headers
+    async (response) => {
+      response.headers.set("X-Content-Type-Options", "nosniff");
+      response.headers.set("X-Frame-Options", "DENY");
+      return response;
+    },
+  ],
 };
+
+export default config;
 ```
 
-## Configuration
+## CLI Commands
 
-```typescript
-interface VectorConfig {
-  port?: number; // Server port (default: 3000)
-  hostname?: string; // Server hostname (default: localhost)
-  reusePort?: boolean; // Reuse port (default: true)
-  development?: boolean; // Development mode
-  routesDir?: string; // Routes directory (default: ./routes)
-  autoDiscover?: boolean; // Auto-discover routes (default: true)
-  idleTimeout?: number; // Idle timeout in seconds (default: 60)
-  cors?: CorsOptions; // CORS configuration
-  before?: BeforeMiddlewareHandler[]; // Pre-request middleware
-  finally?: AfterMiddlewareHandler[]; // Post-response middleware
-}
+```bash
+# Development server with hot reload
+bun vector dev
 
-interface CorsOptions {
-  origin?: string | string[] | ((origin: string) => boolean);
-  credentials?: boolean;
-  allowHeaders?: string | string[];
-  allowMethods?: string | string[];
-  exposeHeaders?: string | string[];
-  maxAge?: number;
-}
-```
+# Production server
+bun vector start
 
-### Middleware Configuration
+# Build for production
+bun vector build
 
-```typescript
-// Add before middleware (runs before routes)
-vector.before(async (request) => {
-  console.log(`${request.method} ${request.url}`);
-  return request;
-});
-
-// Add finally middleware (runs after routes)
-vector.finally(async (response, request) => {
-  response.headers.set("X-Response-Time", Date.now() - request.startTime);
-  return response;
-});
+# Command options
+bun vector dev --port 4000         # Custom port
+bun vector dev --host 0.0.0.0      # Custom host
+bun vector dev --routes ./api      # Custom routes directory
+bun vector dev --config ./custom.config.ts  # Custom config file
 ```
 
 ## Project Structure
 
 ```
 my-app/
-├── routes/               # Auto-discovered routes
-│   ├── users.ts
-│   ├── posts.ts
-│   └── health.ts
-├── middleware/           # Custom middleware
+├── vector.config.ts      # Framework configuration
+├── routes/              # Auto-discovered routes
+│   ├── users.ts        # /users endpoints
+│   ├── posts.ts        # /posts endpoints
+│   ├── users.test.ts   # Test file (automatically excluded)
+│   └── admin/          # Nested routes
+│       └── stats.ts    # /admin/stats endpoints
+├── lib/                # Your libraries
 │   ├── auth.ts
-│   └── logging.ts
-├── server.ts            # Main server file
+│   ├── db.ts
+│   └── redis.ts
 └── package.json
 ```
 
-## TypeScript Support
+## Route Discovery
 
-Vector is written in TypeScript and provides full type safety with customizable types:
+Vector automatically discovers and loads route files from your `routesDir` (default: `./routes`). By default, the following file patterns are excluded from route scanning:
+
+- `*.test.ts`, `*.test.js`, `*.test.tsx`, `*.test.jsx` - Test files
+- `*.spec.ts`, `*.spec.js`, `*.spec.tsx`, `*.spec.jsx` - Spec files
+- `*.tests.ts`, `*.tests.js` - Test suite files
+- `**/__tests__/**` - Test directories
+- `*.interface.ts`, `*.type.ts` - Type definition files
+- `*.d.ts` - TypeScript declaration files
+
+You can customize the exclusion patterns using the `routeExcludePatterns` configuration option:
 
 ```typescript
-import { createVector, route, APIError } from "vector-framework";
-import type { VectorRequest, VectorTypes } from "vector-framework";
+// vector.config.ts
+const config: VectorConfigSchema = {
+  routesDir: "./routes",
+  // Custom exclusion patterns (overrides defaults)
+  routeExcludePatterns: [
+    "*.test.ts",
+    "*.spec.ts",
+    "*.mock.ts",
+    "_*.ts", // Exclude files starting with underscore
+  ],
+};
+```
 
-// Define your custom user type
-interface MyUser {
-  id: string;
-  email: string;
-  role: "admin" | "user";
-  permissions: string[];
-}
+## Performance
 
-// Extend Vector types
-interface MyAppTypes extends VectorTypes {
-  auth: MyUser;
-}
+Vector achieves exceptional performance through:
 
-// Create typed Vector instance
-const vector = createVector<MyAppTypes>();
-
-// Configure authentication with your custom type
-vector.protected = async (request): Promise<MyUser> => {
-  // Your auth logic here
-  return {
-    id: "user-123",
-    email: "user@example.com",
-    role: "admin",
-    permissions: ["read", "write"],
-  };
-};
+- **Bun Runtime**: Native TypeScript execution without transpilation
+- **Minimal Dependencies**: Only itty-router (3KB) as dependency
+- **Optimized Routing**: Efficient regex-based route matching
+- **Smart Caching**: Built-in response caching with configurable TTL
 
-// Routes automatically have typed authUser
-vector.route(
-  { method: "GET", path: "/admin", expose: true, auth: true },
-  async (request) => {
-    // request.authUser is typed as MyUser
-    if (request.authUser?.role !== "admin") {
-      throw APIError.forbidden("Admin access required");
-    }
-    return { adminData: "..." };
-  }
-);
-```
+Benchmarks show Vector handling **70,000+ requests/second** on standard hardware.
+
+## Why Vector?
 
-## Error Handling
+### For Encore Users
+Love Encore's declarative API design but need more flexibility? Vector provides the same developer experience with the freedom to deploy anywhere Bun runs.
 
-Vector provides comprehensive built-in error responses for all HTTP status codes:
+### For Express/Fastify Users
+Tired of middleware chains and verbose configurations? Vector's declarative approach makes APIs cleaner and more maintainable.
 
-### Common Client Errors (4xx)
+### For New Projects
+Starting fresh? Vector gives you production-ready features from day one with minimal configuration.
+
+## Error Reference
+
+Vector provides comprehensive error responses for all HTTP status codes. All errors return a consistent format:
+
+```json
+{
+  "error": true,
+  "message": "Error message",
+  "statusCode": 400,
+  "timestamp": "2025-01-01T00:00:00.000Z"
+}
+```
+
+### Client Errors (4xx)
 
 ```typescript
 import { APIError } from "vector-framework";
 
-// Basic errors
-APIError.badRequest("Invalid input"); // 400
-APIError.unauthorized("Please login"); // 401
-APIError.forbidden("Access denied"); // 403
-APIError.notFound("Resource not found"); // 404
-APIError.conflict("Resource already exists"); // 409
-
-// Validation and input errors
-APIError.unprocessableEntity("Invalid data"); // 422
-APIError.invalidArgument("Field required"); // 422 (alias)
-APIError.payloadTooLarge("File too large"); // 413
-APIError.unsupportedMediaType("Invalid type"); // 415
-
-// Rate limiting and timeouts
-APIError.tooManyRequests("Rate limit exceeded"); // 429
-APIError.rateLimitExceeded("Try again later"); // 429 (alias)
-APIError.requestTimeout("Request took too long"); // 408
-
-// Method and protocol errors
-APIError.methodNotAllowed("POST not allowed"); // 405
-APIError.notAcceptable("Cannot produce response"); // 406
-APIError.preconditionFailed("ETag mismatch"); // 412
+// 400 Bad Request
+APIError.badRequest("Invalid input data");
+
+// 401 Unauthorized
+APIError.unauthorized("Authentication required");
+
+// 402 Payment Required
+APIError.paymentRequired("Subscription expired");
+
+// 403 Forbidden
+APIError.forbidden("Access denied");
+
+// 404 Not Found
+APIError.notFound("Resource not found");
+
+// 405 Method Not Allowed
+APIError.methodNotAllowed("POST not allowed on this endpoint");
+
+// 406 Not Acceptable
+APIError.notAcceptable("Cannot produce requested content type");
+
+// 408 Request Timeout
+APIError.requestTimeout("Request took too long");
+
+// 409 Conflict
+APIError.conflict("Resource already exists");
+
+// 410 Gone
+APIError.gone("Resource permanently deleted");
+
+// 411 Length Required
+APIError.lengthRequired("Content-Length header required");
+
+// 412 Precondition Failed
+APIError.preconditionFailed("ETag mismatch");
+
+// 413 Payload Too Large
+APIError.payloadTooLarge("Request body exceeds limit");
+
+// 414 URI Too Long
+APIError.uriTooLong("URL exceeds maximum length");
+
+// 415 Unsupported Media Type
+APIError.unsupportedMediaType("Content-Type not supported");
+
+// 416 Range Not Satisfiable
+APIError.rangeNotSatisfiable("Requested range cannot be satisfied");
+
+// 417 Expectation Failed
+APIError.expectationFailed("Expect header requirements not met");
+
+// 418 I'm a Teapot
+APIError.imATeapot("I refuse to brew coffee");
+
+// 421 Misdirected Request
+APIError.misdirectedRequest("Request sent to wrong server");
+
+// 422 Unprocessable Entity
+APIError.unprocessableEntity("Validation failed");
+
+// 423 Locked
+APIError.locked("Resource is locked");
+
+// 424 Failed Dependency
+APIError.failedDependency("Dependent request failed");
+
+// 425 Too Early
+APIError.tooEarly("Request is too early");
+
+// 426 Upgrade Required
+APIError.upgradeRequired("Protocol upgrade required");
+
+// 428 Precondition Required
+APIError.preconditionRequired("Precondition headers required");
+
+// 429 Too Many Requests
+APIError.tooManyRequests("Rate limit exceeded");
+
+// 431 Request Header Fields Too Large
+APIError.requestHeaderFieldsTooLarge("Headers too large");
+
+// 451 Unavailable For Legal Reasons
+APIError.unavailableForLegalReasons("Content blocked for legal reasons");
 ```
 
 ### Server Errors (5xx)
 
 ```typescript
-// Server errors
-APIError.internalServerError("Something went wrong"); // 500
-APIError.notImplemented("Feature coming soon"); // 501
-APIError.badGateway("Upstream server error"); // 502
-APIError.serviceUnavailable("Service down"); // 503
-APIError.maintenance("Under maintenance"); // 503 (alias)
-APIError.gatewayTimeout("Upstream timeout"); // 504
+// 500 Internal Server Error
+APIError.internalServerError("Something went wrong");
+
+// 501 Not Implemented
+APIError.notImplemented("Feature not yet available");
+
+// 502 Bad Gateway
+APIError.badGateway("Upstream server error");
+
+// 503 Service Unavailable
+APIError.serviceUnavailable("Service temporarily down");
+
+// 504 Gateway Timeout
+APIError.gatewayTimeout("Upstream server timeout");
+
+// 505 HTTP Version Not Supported
+APIError.httpVersionNotSupported("HTTP/3 not supported");
+
+// 506 Variant Also Negotiates
+APIError.variantAlsoNegotiates("Content negotiation error");
+
+// 507 Insufficient Storage
+APIError.insufficientStorage("Server storage full");
+
+// 508 Loop Detected
+APIError.loopDetected("Infinite loop detected");
+
+// 510 Not Extended
+APIError.notExtended("Extension required");
+
+// 511 Network Authentication Required
+APIError.networkAuthenticationRequired("Network login required");
+```
+
+### Convenience Aliases
+
+```typescript
+// Alias for 422 Unprocessable Entity
+APIError.invalidArgument("Field 'email' is required");
+
+// Alias for 429 Too Many Requests
+APIError.rateLimitExceeded("Try again in 60 seconds");
+
+// Alias for 503 Service Unavailable
+APIError.maintenance("Scheduled maintenance in progress");
 ```
 
 ### Custom Errors
 
 ```typescript
-// Create custom error with any status code
-APIError.custom(456, 'Custom error message');
+// Create error with any status code
+APIError.custom(456, "Custom error message");
 
-// All errors include additional metadata
-// Response format:
-{
-  "error": true,
-  "message": "Error message",
-  "statusCode": 400,
-  "timestamp": "2025-01-01T00:00:00.000Z"
-}
+// With custom content type
+APIError.custom(400, "Invalid XML", "application/xml");
 ```
 
 ### Usage in Routes
 
 ```typescript
-vector.route(
-  { method: "GET", path: "/api/data/:id", expose: true },
+export const example = route(
+  { method: "POST", path: "/api/users" },
   async (req) => {
-    // Validation
-    if (!req.params?.id) {
-      throw APIError.badRequest("ID is required");
+    // Validation errors
+    if (!req.content?.email) {
+      throw APIError.badRequest("Email is required");
     }
 
-    // Check rate limits
-    if (await isRateLimited(req)) {
-      throw APIError.tooManyRequests("Please wait before trying again");
+    if (!isValidEmail(req.content.email)) {
+      throw APIError.unprocessableEntity("Invalid email format");
     }
 
-    // Fetch data
-    const data = await fetchData(req.params.id);
-    if (!data) {
-      throw APIError.notFound("Data not found");
+    // Authentication errors
+    if (!req.authUser) {
+      throw APIError.unauthorized("Please login first");
     }
 
-    // Check permissions
-    if (!canAccess(req.authUser, data)) {
-      throw APIError.forbidden("You cannot access this resource");
+    if (req.authUser.role !== "admin") {
+      throw APIError.forbidden("Admin access required");
+    }
+
+    // Resource errors
+    const existingUser = await findUserByEmail(req.content.email);
+    if (existingUser) {
+      throw APIError.conflict("Email already registered");
     }
 
-    return data;
+    // Rate limiting
+    if (await checkRateLimit(req.authUser.id)) {
+      throw APIError.tooManyRequests("Maximum 5 users per hour");
+    }
+
+    try {
+      const user = await createUser(req.content);
+      return { user };
+    } catch (error) {
+      // Database errors
+      if (error.code === "STORAGE_FULL") {
+        throw APIError.insufficientStorage("Database full");
+      }
+
+      // Generic server error
+      throw APIError.internalServerError("Failed to create user");
+    }
   }
 );
 ```