vector-framework 1.1.1 → 1.2.1

package/README.md

@@ -1,706 +1,177 @@
-# Vector Framework
+# vector
 
-**Blazing fast, secure, and developer-friendly API framework for Bun**
+<img width="1640" height="664" alt="vector-bw-banner" src="https://github.com/user-attachments/assets/afeb8c6e-0729-4fea-9054-7972f8af9365" />
 
-- **100,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
+Blazing fast, secure, and developer-friendly API framework for Bun.
 
-## Quick Start
+Vector is a Bun-first framework for building HTTP APIs with declarative route files, strong TypeScript inference, and zero runtime dependencies.
+
+- **Zero Dependencies**: No runtime routing dependency
+- **Bun Native**: TypeScript-first workflow with the Bun runtime
+- **Type Safe**: Typed request/auth/context with schema-driven validation
+- **Built In**: Middleware, auth hooks, caching, CORS, OpenAPI generation
 
-### Installation
+## Installation
 
 ```bash
 bun add vector-framework
 ```
 
-### 1. Configure Your App
+Requirements:
+
+- Bun `>= 1.0.0`
+
+## Quick Start
 
-Create `vector.config.ts` in your project root:
+### 1. Create `vector.config.ts`
 
-```typescript
-// vector.config.ts
+```ts
 import type { VectorConfigSchema } from "vector-framework";
 
 const config: VectorConfigSchema = {
-  // Server configuration
   port: 3000,
   hostname: "localhost",
   development: process.env.NODE_ENV !== "production",
-  routesDir: "./routes", // Auto-discovers routes here
-
-  // CORS configuration
-  cors: {
-    origin: "*",
-    credentials: true,
-    allowHeaders: ["Content-Type", "Authorization"],
-    allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
-  },
-
-  // 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;
+  routesDir: "./routes",
+  defaults: {
+    route: {
+      expose: true,
+      auth: false,
+    },
   },
-
-  // 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;
 ```
 
-### 2. Create Your First Route
+### 2. Create a route file
 
-```typescript
+```ts
 // routes/hello.ts
 import { route } from "vector-framework";
 
-// Simple public endpoint
 export const hello = route(
-  {
-    method: "GET",
-    path: "/hello/:name",
-    expose: true, // Public endpoint (default: true)
-  },
-  async (req) => {
-    return { message: `Hello ${req.params.name}!` };
-  }
-);
-
-// Protected endpoint - uses auth from config
-export const getProfile = route(
-  {
-    method: "GET",
-    path: "/profile",
-    auth: true, // Requires authentication
-    expose: true,
-  },
+  { method: "GET", path: "/hello/:name", expose: true },
   async (req) => {
-    return {
-      user: req.authUser, // Typed from your auth handler
-      timestamp: new Date(),
-    };
-  }
-);
-
-// Cached endpoint
-export const getUsers = route(
-  {
-    method: "GET",
-    path: "/users",
-    cache: 300, // Cache for 5 minutes
-    expose: true,
+    return { message: `Hello ${req.params.name}` };
   },
-  async () => {
-    // Expensive operation, will be cached
-    const users = await db.users.findMany();
-    return { users };
-  }
 );
 ```
 
-### 3. Start Your Server
+### 3. Run the server
 
 ```bash
-# Development mode with hot reload
 bun vector dev
-
-# Production mode
-bun vector start
-
-# With custom options
-bun vector dev --port 4000 --routes ./api
 ```
 
-That's it! Your API is running at `http://localhost:3000` 🎉
-
-## TypeScript Type Safety
-
-Vector provides full type safety with customizable types. Define your types in the config and use them in routes:
-
-```typescript
-// vector.config.ts
-import type { VectorConfigSchema, VectorTypes } from "vector-framework";
+Your API will be available at `http://localhost:3000`.
 
-// Define your custom user type
-interface MyUser {
-  id: string;
-  email: string;
-  role: "admin" | "user";
-  permissions: string[];
-}
-
-// Extend Vector types
-interface MyAppTypes extends VectorTypes {
-  auth: MyUser;
-}
-
-// Use in config with type parameter
-const config: VectorConfigSchema<MyAppTypes> = {
-  port: 3000,
+## Production Start
 
-  // 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"],
-    };
-  },
-};
-
-export default config;
-export type { MyAppTypes }; // Export for use in routes
-```
-
-```typescript
-// routes/admin.ts
-import { route, APIError } from "vector-framework";
-import type { MyAppTypes } from "../vector.config";
-
-// Use type parameter to get fully typed request
-export const adminOnly = route<MyAppTypes>(
-  {
-    method: "GET",
-    path: "/admin/data",
-    auth: true,
-    expose: true,
-  },
-  async (req) => {
-    // req.authUser is now typed as MyUser
-    if (req.authUser?.role !== "admin") {
-      throw APIError.forbidden("Admin access required");
-    }
-
-    // TypeScript knows these properties exist
-    return {
-      user: req.authUser.email,
-      permissions: req.authUser.permissions,
-    };
-  }
-);
-```
-
-## Core Features
-
-### Route Options
-
-```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
-}
+```bash
+bun vector start --config ./vector.config.ts --routes ./routes --port 8080 --host 0.0.0.0
 ```
 
-### Request Object
-
-Every route handler receives a typed request object:
+Notes:
 
-```typescript
-export const example = route(
-  { method: "POST", path: "/example/:id" },
-  async (req) => {
-    // 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
-  }
-);
-```
+- `start` uses the same config and route options as `dev`.
+- `start` sets `NODE_ENV=production`.
+- File watching is only enabled for `dev`.
 
-### Error Handling
+## Programmatic Start
 
-Vector provides comprehensive error responses. Requests with a malformed URL are automatically rejected with a `400 Bad Request` before reaching your handler. Unhandled exceptions in handlers return a `500 Internal Server Error`.
+```ts
+import { startVector } from "vector-framework";
 
-```typescript
-import { APIError } from "vector-framework";
+const app = await startVector({
+  configPath: "./vector.config.ts",
+});
 
-export const example = route(
-  { method: "GET", path: "/data/:id" },
-  async (req) => {
-    // Client errors (4xx)
-    if (!req.params.id) {
-      throw APIError.badRequest("ID is required");
-    }
-
-    const data = await findData(req.params.id);
-    if (!data) {
-      throw APIError.notFound("Data not found");
-    }
-
-    if (!canAccess(req.authUser, data)) {
-      throw APIError.forbidden("Access denied");
-    }
-
-    // Rate limiting
-    if (await isRateLimited(req)) {
-      throw APIError.tooManyRequests("Please wait before trying again");
-    }
-
-    // Server errors (5xx)
-    try {
-      return await processData(data);
-    } catch (error) {
-      throw APIError.internalServerError("Processing failed");
-    }
-  }
-);
+console.log(`Listening on ${app.server.hostname}:${app.server.port}`);
 ```
 
-## Configuration Reference
+Notes:
 
-### VectorConfigSchema
+- `startVector()` does not enable file watching.
+- `app.stop()` stops immediately (used for dev reload flows).
+- `await app.shutdown()` performs graceful shutdown and runs config `shutdown` hook.
 
-```typescript
-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
+## Optional: Validation + OpenAPI
 
-  // CORS
-  cors?: CorsOptions | boolean;
-
-  // Handlers
-  auth?: ProtectedHandler;    // Authentication handler
-  cache?: CacheHandler;        // Cache handler
-
-  // Middleware
-  before?: BeforeMiddleware[]; // Pre-request middleware
-  after?: AfterMiddleware[];    // Post-response middleware
-}
+```bash
+bun add -d zod
 ```
 
-### Example: Full Configuration
+Vector is not tied to Zod. It supports any validation library that implements the
+`StandardSchemaV1` interface (`~standard` v1).
 
-```typescript
-// vector.config.ts
-import type { VectorConfigSchema } from "vector-framework";
-import { verifyJWT } from "./lib/auth";
-import { redis } from "./lib/redis";
+Common compatible choices include:
 
-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,
-
-  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,
-  },
+- Zod (v4+)
+- Valibot
+- ArkType
 
-  auth: async (request) => {
-    const token = request.headers.get("Authorization")?.replace("Bearer ", "");
-    if (!token) throw new Error("No token provided");
+For OpenAPI schema conversion, your library also needs `StandardJSONSchemaV1`
+(`~standard.jsonSchema.input/output`). If those converters are missing, runtime
+validation still works, but schema conversion is skipped.
 
-    const user = await verifyJWT(token);
-    if (!user) throw new Error("Invalid token");
+```ts
+import { route } from "vector-framework";
+import { z } from "zod";
 
-    return user;
-  },
+const CreateUserInput = z.object({
+  body: z.object({
+    email: z.string().email(),
+    name: z.string().min(1),
+  }),
+});
 
-  cache: async (key, factory, ttl) => {
-    const cached = await redis.get(key);
-    if (cached) return JSON.parse(cached);
+const CreateUserSchema = { input: CreateUserInput };
 
-    const value = await factory();
-    await redis.setex(key, ttl, JSON.stringify(value));
-    return value;
+export const createUser = route(
+  { method: "POST", path: "/users", expose: true, schema: CreateUserSchema },
+  async (req) => {
+    return { created: true, email: req.content.email };
   },
-
-  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;
-```
-
-## CLI Commands
-
-```bash
-# Development server with hot reload
-bun vector dev
-
-# Production server
-bun vector start
-
-# Build for production
-bun vector build
-
-# 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/
-├── 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
-│   ├── db.ts
-│   └── redis.ts
-└── package.json
-```
-
-## Route Discovery
-
-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. Both single-segment (`*`) and multi-segment (`**`) glob patterns are supported:
-
-```typescript
-// vector.config.ts
-const config: VectorConfigSchema = {
-  routesDir: "./routes",
-  // Custom exclusion patterns (overrides defaults)
-  routeExcludePatterns: [
-    "*.test.ts",
-    "*.spec.ts",
-    "*.mock.ts",
-    "**/__tests__/**", // Exclude any nested __tests__ directory
-    "_*.ts",           // Exclude files starting with underscore
-  ],
-};
+);
 ```
 
-## Performance
-
-Vector achieves exceptional performance through:
-
-- **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
-
-Benchmarks show Vector handling **100,000+ requests/second** on standard hardware.
-
-## Why Vector?
-
-### 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.
+Enable OpenAPI in `vector.config.ts`:
 
-### For Express/Fastify Users
-Tired of middleware chains and verbose configurations? Vector's declarative approach makes APIs cleaner and more maintainable.
-
-### 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"
+```ts
+openapi: {
+  enabled: true,
+  path: '/openapi.json',
+  docs: false,
 }
 ```
 
-### Client Errors (4xx)
-
-```typescript
-import { APIError } from "vector-framework";
-
-// 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");
+## Documentation
 
-// 415 Unsupported Media Type
-APIError.unsupportedMediaType("Content-Type not supported");
+Start here for deeper guides:
 
-// 416 Range Not Satisfiable
-APIError.rangeNotSatisfiable("Requested range cannot be satisfied");
+- [Docs Index](docs/README.md)
+- [Configuration](docs/configuration.md)
+- [Routing and Request API](docs/routing.md)
+- [TypeScript Types](docs/typescript.md)
+- [Schema Validation](docs/schema-validation.md)
+- [OpenAPI and Docs UI](docs/openapi.md)
+- [CLI and Route Discovery](docs/cli-and-discovery.md)
+- [Error Reference](docs/errors.md)
+- [Migration Notes](docs/migration.md)
+- [Performance Notes](docs/performance.md)
 
-// 417 Expectation Failed
-APIError.expectationFailed("Expect header requirements not met");
+## Examples
 
-// 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
-// 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 error with any status code
-APIError.custom(456, "Custom error message");
-
-// With custom content type
-APIError.custom(400, "Invalid XML", "application/xml");
-```
-
-### Usage in Routes
-
-```typescript
-export const example = route(
-  { method: "POST", path: "/api/users" },
-  async (req) => {
-    // Validation errors
-    if (!req.content?.email) {
-      throw APIError.badRequest("Email is required");
-    }
-
-    if (!isValidEmail(req.content.email)) {
-      throw APIError.unprocessableEntity("Invalid email format");
-    }
-
-    // Authentication errors
-    if (!req.authUser) {
-      throw APIError.unauthorized("Please login first");
-    }
-
-    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");
-    }
-
-    // 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");
-    }
-  }
-);
-```
+- [examples/routes/health.ts](examples/routes/health.ts)
+- [examples/routes/events.ts](examples/routes/events.ts)
+- [examples/routes/commerce.ts](examples/routes/commerce.ts)
+- [tests/e2e/test-routes.ts](tests/e2e/test-routes.ts) (broader endpoint patterns)
+- [tests/e2e/test-zod-routes.ts](tests/e2e/test-zod-routes.ts) (Zod + I/O validation flows)
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome. Open an issue or pull request.
 
 ## License