qhttpx 1.8.0

package/docs/DATABASE.md

@@ -0,0 +1,142 @@
+# Database Engine & Query Fusion
+
+QHTTPX includes a powerful, built-in database engine designed for high performance and flexibility. It features a multi-database adapter system, connection pooling, and a unique **Query Fusion** engine that automatically optimizes high-concurrency workloads.
+
+## Features
+
+- **Multi-Database Support**: Connect to PostgreSQL, MongoDB, SQLite, and more using a unified API.
+- **Dynamic Adapters**: Drivers (`pg`, `mongodb`) are optional. The framework only loads what you use.
+- **Query Fusion**: Automatically merges identical queries (e.g., `SELECT * FROM users WHERE id = ?`) into single batched queries (e.g., `WHERE id IN (...)`) to reduce network roundtrips.
+- **Batch Execution**: Send multiple operations in a single HTTP request.
+- **Context Integration**: Access database connections directly from your route handlers via `ctx.db`.
+
+## Installation
+
+The core framework is lightweight. Install the driver for the database you intend to use:
+
+```bash
+# For PostgreSQL
+npm install pg
+
+# For MongoDB
+npm install mongodb
+```
+
+## Basic Usage
+
+### 1. Configure the Server
+
+Initialize the `DatabaseManager` and pass it to your QHTTPX application.
+
+```typescript
+import { createHttpApp } from 'qhttpx';
+import { DatabaseManager } from 'qhttpx/database';
+
+const db = new DatabaseManager({
+  default: 'main',
+  connections: {
+    main: {
+      type: 'postgres',
+      host: 'localhost',
+      port: 5432,
+      username: 'user',
+      password: 'password',
+      database: 'mydb'
+    }
+  }
+});
+
+const app = createHttpApp({ db });
+
+// Connect during startup
+await app.listen(3000);
+```
+
+### 2. Accessing the Database in Routes
+
+Use `ctx.db.get()` to retrieve the active connection.
+
+```typescript
+app.get('/users/:id', async (ctx) => {
+  const db = ctx.db.get('main');
+  const userId = ctx.params.id;
+  
+  // Standard Query
+  const users = await db.query('SELECT * FROM users WHERE id = $1', [userId]);
+  
+  return ctx.json(users[0]);
+});
+```
+
+## Bring Your Own Connection
+
+If you have a pre-initialized database connection (e.g., from an external library or legacy code), you can register it manually without using the built-in configuration.
+
+```typescript
+import { Client } from 'pg';
+import { PostgresAdapter } from 'qhttpx/database';
+
+// 1. Initialize your connection externally
+const client = new Client({ connectionString: process.env.DATABASE_URL });
+await client.connect();
+
+// 2. Wrap it in an adapter
+const adapter = new PostgresAdapter({});
+// Note: You'll need to set the internal pool/client manually if bypassing connect()
+// Or simply let QHTTPX manage the connection for you.
+
+// 3. Register it
+db.registerConnection('legacy_db', adapter);
+```
+
+## Query Fusion & Batching
+
+The "Killer Feature" of QHTTPX is its ability to coalesce multiple individual requests into a single database query.
+
+### How it works
+
+1.  **Client** sends a batch of operations:
+    ```json
+    POST /batch
+    {
+      "ops": [
+        { "id": "req1", "type": "getUser", "args": [1] },
+        { "id": "req2", "type": "getUser", "args": [2] },
+        { "id": "req3", "type": "getUser", "args": [3] }
+      ]
+    }
+    ```
+
+2.  **Server** defines a coalescing resolver:
+    ```typescript
+    import { QueryCoalescer } from 'qhttpx/database';
+
+    const userCoalescer = new QueryCoalescer(async (ids) => {
+      // This runs ONCE for the entire batch
+      return await db.query('SELECT * FROM users WHERE id = ANY($1)', [ids]);
+    });
+
+    app.op('getUser', async (id) => {
+      return await userCoalescer.execute(id);
+    });
+    ```
+
+3.  **Result**: Instead of 3 separate DB queries, QHTTPX executes **1 query**. The results are automatically distributed back to the correct original requests.
+
+## Supported Databases
+
+| Database | Adapter Type | Driver Required |
+| :--- | :--- | :--- |
+| **PostgreSQL** | `postgres` | `npm install pg` |
+| **MongoDB** | `mongo` | `npm install mongodb` |
+| **Memory** | `memory` | *(Built-in)* |
+
+## API Reference
+
+### `DatabaseManager`
+
+-   `constructor(config: DatabaseEngineOptions)`
+-   `registerAdapter(type: string, adapter: AdapterConstructor)`: Register custom adapters.
+-   `registerConnection(name: string, adapter: DatabaseAdapter)`: Register initialized connections.
+-   `connect(name?: string)`: Connect to a specific or default DB.
+-   `get(name?: string)`: Get an active adapter instance.

package/docs/ECOSYSTEM.md

@@ -0,0 +1,146 @@
+# SaaS & Ecosystem Integration Guide
+
+QHTTPX is designed as a **Universal Runtime**. It provides a high-performance core but imposes **zero restrictions** on the libraries you choose to build your application.
+
+If you are building a SaaS (e.g., a Notion clone), you will likely need specialized tools for Authentication, Caching, and Database management. QHTTPX integrates seamlessly with the standard Node.js ecosystem.
+
+## 🔓 Authentication (JWT / OAuth)
+QHTTPX does not ship with a built-in auth strategy (like Passport) to keep the core lightweight. Instead, it exposes the `ctx` object, allowing you to use libraries like `jose`, `jsonwebtoken`, or `oslo` easily.
+
+### Example: JWT Auth with `jose`
+You can install `jose` (`npm install jose`) and write a simple middleware:
+
+```typescript
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { QHTTPXMiddleware } from 'qhttpx';
+
+const JWKS = createRemoteJWKSet(new URL('https://your-auth-provider/.well-known/jwks.json'));
+
+export const authMiddleware: QHTTPXMiddleware = async (ctx, next) => {
+  const authHeader = ctx.req.headers['authorization'];
+  
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    ctx.res.statusCode = 401;
+    ctx.res.end('Unauthorized');
+    return;
+  }
+
+  try {
+    const token = authHeader.split(' ')[1];
+    const { payload } = await jwtVerify(token, JWKS);
+    
+    // Attach user to context state
+    ctx.state.user = payload;
+    
+    await next();
+  } catch (err) {
+    ctx.res.statusCode = 403;
+    ctx.res.end('Forbidden');
+  }
+};
+
+// Usage
+app.use(authMiddleware);
+app.get('/dashboard', (ctx) => {
+  const userId = ctx.state.user.sub;
+  ctx.json({ message: `Hello ${userId}` });
+});
+```
+
+## ⚡ Caching (Redis / Memcached)
+For high-scale SaaS, you often need a shared cache layer. QHTTPX's middleware pipeline allows you to intercept requests and serve from cache before hitting your database.
+
+### Example: Redis Caching with `ioredis`
+Install `ioredis` (`npm install ioredis`):
+
+```typescript
+import Redis from 'ioredis';
+import { QHTTPXMiddleware } from 'qhttpx';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+export const redisCache: QHTTPXMiddleware = async (ctx, next) => {
+  if (ctx.req.method !== 'GET') return next();
+
+  const key = `cache:${ctx.url.pathname}`;
+  const cached = await redis.get(key);
+
+  if (cached) {
+    ctx.res.setHeader('X-Cache', 'HIT');
+    ctx.res.setHeader('Content-Type', 'application/json');
+    ctx.res.end(cached);
+    return;
+  }
+
+  // Hook into response to cache the result
+  const originalJson = ctx.json;
+  ctx.json = (body, status) => {
+    // Save to Redis (expire in 60s)
+    redis.setex(key, 60, JSON.stringify(body));
+    originalJson(body, status);
+  };
+
+  await next();
+};
+```
+
+## 🗄️ Database (Prisma / Drizzle / TypeORM)
+QHTTPX is database-agnostic. You can use any ORM or Query Builder.
+
+### Example: Using Prisma
+1. `npm install prisma @prisma/client`
+2. `npx prisma init`
+
+```typescript
+import { PrismaClient } from '@prisma/client';
+import { QHTTPX } from 'qhttpx';
+
+const prisma = new PrismaClient();
+const app = new QHTTPX();
+
+// Inject prisma into context (optional, or just import global)
+app.use(async (ctx, next) => {
+  ctx.state.db = prisma;
+  await next();
+});
+
+app.get('/users', async (ctx) => {
+  const users = await prisma.user.findMany();
+  ctx.json(users);
+});
+```
+
+## 📦 File Uploads to S3
+While QHTTPX supports `multipart/form-data` parsing locally via `ctx.files`, for a SaaS you typically stream directly to S3.
+
+You can use `@aws-sdk/client-s3` inside a handler:
+
+```typescript
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+
+const s3 = new S3Client({ region: 'us-east-1' });
+
+app.post('/upload', async (ctx) => {
+  // Use busboy stream from QHTTPX (advanced) or just buffer
+  const file = ctx.files?.['avatar'];
+  
+  await s3.send(new PutObjectCommand({
+    Bucket: 'my-saas-bucket',
+    Key: `avatars/${Date.now()}_${file.name}`,
+    Body: file.data
+  }));
+  
+  ctx.json({ success: true });
+});
+```
+
+## Summary
+| Requirement | Recommended Tool | QHTTPX Integration |
+| :--- | :--- | :--- |
+| **Auth** | `jose`, `jsonwebtoken`, `lucia` | Middleware + `ctx.state.user` |
+| **Database** | `prisma`, `drizzle-orm`, `mongoose` | Import globally or attach to `ctx` |
+| **Caching** | `ioredis`, `node-cache` | Middleware interceptor |
+| **Validation** | `zod`, `valibot` | Native `ctx.validate(schema)` support |
+| **Email** | `resend`, `nodemailer` | Call directly in handlers |
+
+**Verdict**: Yes, you have full freedom to install and use any NPM package. QHTTPX acts as the high-performance glue holding your stack together.

package/docs/NEXT_STEPS.md

@@ -0,0 +1,99 @@
+# The Path to "The Best Framework"
+
+To compete with frameworks like Fastify, Hono, and NestJS, QHTTPX needs to master **Type Safety**, **Performance (Serialization)**, and **Observability**.
+
+Here is the vision for the final version.
+
+## 1. Type-Safe Validation (Zod Integration)
+
+Currently, we use simple strings. The "Best" version integrates **Zod** for TypeScript inference.
+
+```typescript
+import { z } from 'zod';
+
+const UserSchema = z.object({
+  username: z.string().min(3),
+  email: z.string().email(),
+  age: z.number().optional()
+});
+
+app.post('/users', async (ctx) => {
+  // 1. Validates body against Zod schema
+  // 2. Throws 400 if invalid
+  // 3. 'body' is fully typed as { username: string, email: string, ... }
+  const body = await ctx.validate(UserSchema);
+  
+  // No need for "as string" casting
+  console.log(body.email); 
+});
+```
+
+## 2. JIT Response Serialization (Performance)
+
+`JSON.stringify` is slow. The "Best" frameworks compile schemas to code (JIT). This makes responses 2x-3x faster.
+
+```typescript
+const ResponseSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  // Exclude 'password' automatically
+});
+
+app.get('/users/:id', async (ctx) => {
+  const user = await db.getUser(ctx.params.id);
+  
+  // Uses a pre-compiled serializer function
+  // Faster than JSON.stringify and safer (strips sensitive fields)
+  ctx.schema(ResponseSchema).json(user);
+});
+```
+
+## 3. Automatic OpenAPI (Swagger) Generation
+
+Since we have schemas, we can generate documentation automatically.
+
+```typescript
+// Auto-generate OpenAPI v3 spec from routes and Zod schemas
+app.get('/openapi.json', (ctx) => {
+  ctx.json(app.getOpenAPISpec());
+});
+
+// Serve Swagger UI
+app.get('/docs', swaggerUI({ url: '/openapi.json' }));
+```
+
+## 4. End-to-End Type Safety (RPC Client)
+
+Share types between Backend and Frontend.
+
+```typescript
+// Shared Types (libs/types.ts)
+export type AppType = typeof app;
+
+// Frontend (client.ts)
+import { hc } from 'qhttpx/client';
+import type { AppType } from './server';
+
+const client = hc<AppType>('http://localhost:3000');
+
+// Fully typed! 
+// TypeScript knows that res.json() returns { id: number, name: string }
+const res = await client.users[':id'].$get({ 
+  param: { id: '123' } 
+});
+```
+
+## 5. Structured Logging (Observability)
+
+Replace `console.log` with a high-performance JSON logger (like Pino) for production observability.
+
+```typescript
+// Logs: {"level":"info","time":1630000000,"reqId":"req-1","msg":"Request completed","duration":12}
+app.log.info({ userId: 1 }, 'User logged in');
+```
+
+## Summary of Remaining Work
+
+1.  **Validator Upgrade**: Replace `SimpleValidator` with a `ZodValidator`.
+2.  **Serializer Compiler**: Implement `fast-json-stringify` logic.
+3.  **Type Extraction**: Build the `AppType` export logic.

package/docs/OPENAPI.md

@@ -0,0 +1,99 @@
+# OpenAPI Generation
+
+QHTTPX can automatically generate an OpenAPI 3.0 specification from your route definitions and schemas. This allows you to easily create interactive documentation (Swagger UI) for your API.
+
+## Features
+
+- **Auto-Discovery**: Scans your router to find all registered endpoints.
+- **Schema Mapping**: Converts your `SimpleValidator` schemas into OpenAPI Schema Objects.
+- **Parameter Inference**: Automatically detects URL parameters (e.g., `/users/:id`) and query parameters.
+- **Zero Configuration**: Just call `app.getOpenAPI()`.
+
+## Usage
+
+### 1. Define Routes with Schemas
+
+To get the most out of OpenAPI, define schemas for your routes.
+
+```typescript
+app.post('/users/:id', {
+  schema: {
+    params: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' }
+      }
+    },
+    body: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', min: 3 },
+        email: { type: 'string', pattern: '^\\S+@\\S+\\.\\S+$' }
+      },
+      required: true
+    },
+    response: {
+      type: 'object',
+      properties: {
+        success: { type: 'boolean' },
+        id: { type: 'string' }
+      }
+    }
+  },
+  handler: (ctx) => { /* ... */ }
+});
+```
+
+### 2. Expose the Spec
+
+Create a route to serve the JSON specification.
+
+```typescript
+app.get('/swagger.json', (ctx) => {
+  const spec = app.getOpenAPI({
+    info: {
+      title: 'My Awesome API',
+      version: '1.0.0',
+      description: 'Powered by QHTTPX'
+    },
+    servers: [
+      { url: 'http://localhost:3000', description: 'Local Server' }
+    ]
+  });
+  
+  ctx.json(spec);
+});
+```
+
+### 3. (Optional) Serve Swagger UI
+
+You can easily serve a Swagger UI page that points to your spec.
+
+```typescript
+app.get('/docs', (ctx) => {
+  ctx.html(`
+    <!DOCTYPE html>
+    <html lang="en">
+    <head>
+      <meta charset="utf-8" />
+      <title>API Documentation</title>
+      <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui.css" />
+    </head>
+    <body>
+      <div id="swagger-ui"></div>
+      <script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-bundle.js"></script>
+      <script>
+        window.onload = () => {
+          window.ui = SwaggerUIBundle({
+            url: '/swagger.json',
+            dom_id: '#swagger-ui',
+          });
+        };
+      </script>
+    </body>
+    </html>
+  `);
+});
+```
+
+Now open `http://localhost:3000/docs` to see your interactive API documentation!

package/docs/PLUGINS.md

@@ -0,0 +1,59 @@
+# QHTTPX Plugin System
+
+The QHTTPX Plugin System allows you to encapsulate and share functionality, routes, and middleware. Plugins are fully typed and support scoped routing.
+
+## Creating a Plugin
+
+A plugin is simply a function that accepts a `QHTTPXScope` and an options object.
+
+```typescript
+import { QHTTPXPlugin, QHTTPXScope } from 'qhttpx';
+
+type MyPluginOptions = {
+  secret: string;
+};
+
+const myPlugin: QHTTPXPlugin<MyPluginOptions> = async (scope, options) => {
+  // Register routes within this scope
+  scope.get('/info', (ctx) => {
+    ctx.json({ secret: options.secret });
+  });
+
+  // Register sub-plugins
+  // await scope.register(otherPlugin);
+};
+```
+
+## Registering a Plugin
+
+Use `app.register()` to load a plugin. You can optionally provide a `prefix` to namespace all routes within the plugin.
+
+```typescript
+import { createHttpApp } from 'qhttpx';
+import { myPlugin } from './my-plugin';
+
+const app = createHttpApp();
+
+// Routes will be available at /api/v1/info
+await app.register(myPlugin, { 
+  prefix: '/api/v1',
+  secret: 'super-secret'
+});
+```
+
+## Scope API
+
+The `scope` object passed to the plugin exposes standard routing methods:
+
+- `scope.get(path, handler)`
+- `scope.post(path, handler)`
+- `scope.put(path, handler)`
+- `scope.delete(path, handler)`
+- `scope.use(middleware)` (Currently global, scoped middleware coming soon)
+- `scope.register(plugin, options)`
+
+## Best Practices
+
+1. **Encapsulation**: Keep plugins self-contained. Avoid relying on global state.
+2. **Options**: Use the `options` object to pass configuration (database connections, secrets, etc.).
+3. **Async**: Plugins can be async. QHTTPX will await them during registration.

package/docs/REAL_WORLD_EXAMPLES.md

@@ -0,0 +1,109 @@
+# Real World Usage Examples
+
+Here is how QHTTPX looks in a production application.
+
+## 1. The Entry Point (`src/index.ts`)
+
+Clean setup with built-in clustering and rate limiting.
+
+```typescript
+import { createHttpApp } from 'qhttpx';
+import { rateLimit } from 'qhttpx/middleware';
+
+const app = createHttpApp({
+  // Enable built-in request coalescing for high traffic
+  enableRequestFusion: true,
+  // Auto-scale to CPU cores
+  workers: 'auto' 
+});
+
+// Global Rate Limiter (Aegis)
+app.use(rateLimit({
+  windowMs: 60 * 1000,
+  max: 1000,
+  keyGenerator: (req) => req.headers['x-api-key'] || req.ip
+}));
+
+// Start server
+app.listen(3000).then(({ port }) => {
+  console.log(`🚀 Server running on port ${port}`);
+});
+```
+
+## 2. Modular Features (`src/modules/users.ts`)
+
+Using the Plugin System to organize code.
+
+```typescript
+import { QHTTPXPlugin, QHTTPXScope } from 'qhttpx';
+
+export const userModule: QHTTPXPlugin = async (scope: QHTTPXScope) => {
+  
+  // GET /api/v1/users/:id
+  scope.get('/:id', async (ctx) => {
+    const userId = ctx.params.id;
+    // Auto-fused database query
+    const user = await ctx.db.query('SELECT * FROM users WHERE id = ?', [userId]);
+    
+    if (!user) return ctx.notFound();
+    ctx.json(user);
+  });
+
+  // POST /api/v1/users
+  scope.post('/', async (ctx) => {
+    // Built-in validation
+    const body = await ctx.validate({
+      email: 'string|required',
+      age: 'number|min:18'
+    });
+
+    // ... save user logic
+    ctx.json({ success: true });
+  });
+};
+```
+
+## 3. Registering Modules (`src/app.ts`)
+
+Bringing it all together with prefixes.
+
+```typescript
+import { userModule } from './modules/users';
+import { authModule } from './modules/auth';
+
+// Register plugins with prefixes
+await app.register(userModule, { prefix: '/api/v1/users' });
+await app.register(authModule, { prefix: '/api/v1/auth' });
+```
+
+## 4. High-Performance Query Fusion
+
+How the fusion engine simplifies code while boosting performance.
+
+```typescript
+// In your controller/handler:
+// You write simple queries:
+const user = await db.query('SELECT * FROM users WHERE id = ?', [1]);
+
+// QHTTPX automatically batches them into:
+// SELECT * FROM users WHERE id IN (1, 2, 3, ...)
+// And distributes the results back to each request.
+```
+
+## 5. Middleware & Guards
+
+Protecting routes is simple.
+
+```typescript
+const adminGuard = (ctx, next) => {
+  if (ctx.req.headers['x-role'] !== 'admin') {
+    return ctx.status(403).json({ error: 'Forbidden' });
+  }
+  return next();
+};
+
+// Apply to specific route
+app.delete('/db/drop', adminGuard, (ctx) => {
+  // ...
+});
+```