qhttpx 1.8.3 → 1.8.5

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.8.5] - 2026-01-20
+**"The Usability IV Update"**
+
+### Added
+- **Context Headers**: Added `ctx.headers` (alias for `req.headers`) for direct access to request headers.
+- **Environment**: Added `dotenv` and updated `@types/node` dependencies.
+
+## [1.8.4] - 2026-01-20
+**"The Usability III Update"**
+
+### Added
+- **Flexible Route Signatures**: Routes now support `(path, options, handler)` signature for cleaner validation configuration.
+- **Simplified Listen**: `app.listen(port, callback)` is now supported, matching standard patterns.
+- **Updated Examples**: `examples/api-server.ts` rewritten to demonstrate the "Rapid Way" (Fusion, Validation, WebSockets, Typed Files).
+
 ## [1.8.3] - 2026-01-20
 **"The Developer Experience II Update"**
 

package/README.md

@@ -77,30 +77,42 @@ npm install qhttpx
 
 ## ⚡ Quick Start
 
-### 1. The Standard Way
-Clean, explicit, and scalable from day one.
+### 1. The Rapid Way (Recommended)
+Get up and running instantly with the singleton instance and destructuring support.
 
 ```typescript
-// Import the framework (Default Export supported)
-import QHTTPX from "qhttpx";
+import { app } from "qhttpx";
 
-// Create app (Automatically includes: CORS, Security Headers, Logging, Body Parsing)
-const app = QHTTPX();
+// Concise, destructured handlers
+app.get("/", ({ json }) => json({ message: "Hello World" }));
 
-app.get("/", (ctx) => {
-  return ctx.json({ message: "Welcome to QHTTPX" });
+// Unified error handling
+app.onError(({ error, json }) => {
+  json({ error: "Something went wrong", details: error }, 500);
 });
 
-// Async validation with Zod support
-app.post("/users", async (ctx) => {
-  const body = await ctx.body();
-  return ctx.status(201).json({ created: true, body });
+// Start listening
+app.listen(3000, () => console.log("Server running on http://localhost:3000"));
+```
+
+### 2. The Custom Way
+When you need specific configuration options or multiple instances.
+
+```typescript
+import { createHttpApp } from "qhttpx";
+
+const app = createHttpApp({
+  enableRequestFusion: true, // Enable coalescing
+  maxBodySize: "1mb"
 });
 
-// Start the server
-app.listen(3000).then(({ port }) => {
-  console.log(`Server running on http://localhost:${port}`);
+app.get("/users", async ({ json, query }) => {
+  const { page } = query;
+  // ...
+  json({ page });
 });
+
+app.listen(3000);
 ```
 
 ### 2. The Scalable Way (Cluster Mode)
@@ -143,13 +155,12 @@ app.get('/events', (ctx) => {
 });
 
 // WebSockets with Rooms
-app.websocket('/chat', {
-  open(ws) {
-    ws.subscribe('general');
-  },
-  message(ws, msg) {
-    ws.publish('general', msg); // Broadcast to everyone in 'general'
-  }
+app.upgrade('/chat', (ws) => {
+  ws.join('general');
+  ws.on('message', (msg) => {
+    // Broadcast to 'general' room
+    app.websocket.to('general').emit(`Echo: ${msg}`);
+  });
 });
 ```
 

package/dist/examples/api-server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/api-server.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+// 1. Initialize App (Fusion + Aegis enabled)
+const app = (0, index_1.createHttpApp)({
+    enableRequestFusion: true, // ⚡ Auto-coalesce duplicate requests
+    metricsEnabled: true // 📊 Expose /__qhttpx/metrics
+});
+// 2. Global Middleware (Logging & Rate Limit)
+app.use(async ({ req, next }) => {
+    console.log(`[${req.method}] ${req.url}`);
+    if (next)
+        await next();
+});
+// 3. Validation Schema
+const UserSchema = {
+    body: {
+        type: 'object',
+        required: ['name', 'role'],
+        properties: { name: { type: 'string' }, role: { type: 'string' } }
+    }
+};
+// 4. Routes (Clean & Destructured)
+app.get('/', ({ json }) => json({ status: 'online', fusion: true }));
+// ⚡ Fused Endpoint: 1000 concurrent requests -> 1 DB execution
+app.get('/heavy', async ({ json }) => {
+    await new Promise(r => setTimeout(r, 100)); // Simulate DB
+    json({ data: 'Expensive Result', timestamp: Date.now() });
+});
+// 🛡️ Validated & Typed Route
+app.post('/users', { schema: UserSchema }, async ({ body, json }) => {
+    // Body is already validated and typed here
+    json({ created: true, user: body }, 201);
+});
+// 📂 File Uploads (Typed)
+app.post('/upload', ({ files, json }) => {
+    if (!files?.doc)
+        return json({ error: 'No file' }, 400);
+    const doc = Array.isArray(files.doc) ? files.doc[0] : files.doc;
+    json({ filename: doc.filename, size: doc.size });
+});
+// 📡 WebSockets (Pub/Sub)
+app.upgrade('/chat', (ws) => {
+    ws.join('general'); // Auto-join room
+    ws.on('message', (msg) => {
+        // Broadcast to room
+        app.websocket.to('general').emit(`Echo: ${msg}`);
+    });
+});
+// 5. Unified Error Handling
+app.onError(({ error, json }) => {
+    console.error(error); // Log internal error
+    json({ error: 'Internal Server Error', handled: true }, 500);
+});
+// 6. Start Server
+app.listen(3000, () => console.log('🚀 Server running on http://localhost:3000'));

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "qhttpx",
-    "version": "1.8.3",
+    "version": "1.8.5",
     "description": "The High-Performance Hybrid HTTP Runtime for Node.js. Built for extreme concurrency, request fusion, and zero-overhead scaling.",
     "main": "dist/src/index.js",
     "types": "dist/src/index.d.ts",
@@ -67,6 +67,7 @@
         "@typescript-eslint/eslint-plugin": "^8.53.0",
         "@typescript-eslint/parser": "^8.53.0",
         "autocannon": "^8.0.0",
+        "dotenv": "^17.2.3",
         "eslint": "^9.39.2",
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-prettier": "^5.5.5",

package/dist/src/core/server.d.ts

@@ -56,9 +56,13 @@ export declare class QHTTPX {
     register<Options extends QHTTPXPluginOptions>(plugin: QHTTPXPlugin<Options>, options?: Options): Promise<void>;
     private registerRoute;
     get(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+    get(path: string, config: import('./types').QHTTPXRouteConfig, handler: QHTTPXHandler): void;
     post(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+    post(path: string, config: import('./types').QHTTPXRouteConfig, handler: QHTTPXHandler): void;
     put(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+    put(path: string, config: import('./types').QHTTPXRouteConfig, handler: QHTTPXHandler): void;
     delete(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+    delete(path: string, config: import('./types').QHTTPXRouteConfig, handler: QHTTPXHandler): void;
     route(path: string): {
         get(handler: QHTTPXHandler | QHTTPXRouteOptions): /*elided*/ any;
         post(handler: QHTTPXHandler | QHTTPXRouteOptions): /*elided*/ any;
@@ -70,7 +74,7 @@ export declare class QHTTPX {
     op(name: string, handler: import('./types').QHTTPXOpHandler): void;
     private registerInternalRoutes;
     getOpenAPI(options: OpenAPIOptions): object;
-    listen(port: number, hostname?: string): Promise<{
+    listen(port: number, hostnameOrCallback?: string | (() => void), callback?: () => void): Promise<{
         port: number;
     }>;
     close(): Promise<void>;

package/dist/src/core/server.js

@@ -280,32 +280,38 @@ class QHTTPX {
         const scope = new scope_1.QHTTPXScope(this, options?.prefix);
         await plugin(scope, options);
     }
-    registerRoute(method, path, handlerOrOptions) {
+    registerRoute(method, path, handlerOrOptions, handlerIfOptions) {
         let handler;
         let schema;
         const options = {};
         if (typeof handlerOrOptions === 'function') {
             handler = handlerOrOptions;
         }
-        else {
-            handler = handlerOrOptions.handler;
+        else if (handlerIfOptions) {
+            handler = handlerIfOptions;
             schema = handlerOrOptions.schema;
             options.priority = handlerOrOptions.priority;
         }
+        else {
+            const opts = handlerOrOptions;
+            handler = opts.handler;
+            schema = opts.schema;
+            options.priority = opts.priority;
+        }
         const compiled = this.compileRoutePipeline(handler, schema);
         this.router.register(method, path, compiled, { ...options, schema });
     }
-    get(path, handler) {
-        this.registerRoute('GET', path, handler);
+    get(path, handlerOrOptions, handler) {
+        this.registerRoute('GET', path, handlerOrOptions, handler);
     }
-    post(path, handler) {
-        this.registerRoute('POST', path, handler);
+    post(path, handlerOrOptions, handler) {
+        this.registerRoute('POST', path, handlerOrOptions, handler);
     }
-    put(path, handler) {
-        this.registerRoute('PUT', path, handler);
+    put(path, handlerOrOptions, handler) {
+        this.registerRoute('PUT', path, handlerOrOptions, handler);
     }
-    delete(path, handler) {
-        this.registerRoute('DELETE', path, handler);
+    delete(path, handlerOrOptions, handler) {
+        this.registerRoute('DELETE', path, handlerOrOptions, handler);
     }
     route(path) {
         const register = (method, handler) => {
@@ -402,7 +408,17 @@ class QHTTPX {
         const generator = new generator_1.OpenAPIGenerator(this.router, options);
         return generator.generate();
     }
-    async listen(port, hostname) {
+    async listen(port, hostnameOrCallback, callback) {
+        let hostname;
+        let cb;
+        if (typeof hostnameOrCallback === 'function') {
+            cb = hostnameOrCallback;
+            hostname = undefined;
+        }
+        else {
+            hostname = hostnameOrCallback;
+            cb = callback;
+        }
         if (this.options.database) {
             await this.options.database.connect();
         }
@@ -424,6 +440,8 @@ class QHTTPX {
                 this.router.freeze();
                 void this.runLifecycleHooks(this.onStartHooks);
                 const address = this.server.address();
+                if (cb)
+                    cb();
                 if (address && typeof address === 'object') {
                     resolve({ port: address.port });
                 }
@@ -456,6 +474,7 @@ class QHTTPX {
         const ctx = {
             req: null,
             res: null,
+            headers: null,
             url: null,
             params: null,
             query: null,
@@ -571,6 +590,7 @@ class QHTTPX {
         const mutableCtx = ctx;
         mutableCtx.req = req;
         mutableCtx.res = res;
+        mutableCtx.headers = req.headers;
         mutableCtx.url = url;
         mutableCtx.params = params;
         mutableCtx.query = query;
@@ -592,6 +612,7 @@ class QHTTPX {
         const mutableCtx = ctx;
         mutableCtx.req = null;
         mutableCtx.res = null;
+        mutableCtx.headers = null;
         mutableCtx.url = null;
         mutableCtx.params = null;
         mutableCtx.query = null;

package/dist/src/core/types.d.ts

@@ -1,4 +1,4 @@
-import { IncomingMessage, ServerResponse } from 'http';
+import { IncomingMessage, ServerResponse, IncomingHttpHeaders } from 'http';
 import { URL } from 'url';
 import type { BufferPool, BufferPoolConfig } from './buffer-pool';
 import type { DatabaseManager } from '../database/manager';
@@ -42,6 +42,7 @@ export type QHTTPXFile = {
 export type QHTTPXContext = {
     readonly req: IncomingMessage;
     readonly res: ServerResponse;
+    readonly headers: IncomingHttpHeaders;
     readonly url: URL;
     readonly params: Record<string, string>;
     readonly query: Record<string, string | string[]>;
@@ -73,6 +74,7 @@ export type QHTTPXRouteOptions = {
     handler: QHTTPXHandler;
     priority?: RoutePriority;
 };
+export type QHTTPXRouteConfig = Omit<QHTTPXRouteOptions, 'handler'>;
 export type QHTTPXMiddleware = (ctx: QHTTPXContext, next: () => Promise<void>) => void | Promise<void>;
 export type QHTTPXErrorContext = QHTTPXContext & {
     error: unknown;

package/examples/api-server.ts

@@ -1,254 +1,62 @@
-import { createHash } from 'crypto';
-import { IncomingMessage } from 'http';
-import { Duplex } from 'stream';
-import { createHttpApp, HttpError } from '../src/index';
+import { createHttpApp } from '../src/index';
 
-// 1. Initialize the application (includes CORS, Security Headers, Logging)
-const app = createHttpApp({
-  metricsEnabled: true,
-  workers: 1,
+// 1. Initialize App (Fusion + Aegis enabled)
+const app = createHttpApp({ 
+  enableRequestFusion: true, // ⚡ Auto-coalesce duplicate requests
+  metricsEnabled: true       // 📊 Expose /__qhttpx/metrics
 });
 
-// 2. Mock Database
-const users = new Map<string, { id: string; name: string; role: string }>();
-
-// Seed some data
-users.set('1', { id: '1', name: 'Alice', role: 'admin' });
-users.set('2', { id: '2', name: 'Bob', role: 'user' });
-
-// 3. Register Background Tasks
-app.task('send-email', async (payload: any) => {
-  // Simulate heavy work
-  await new Promise((resolve) => setTimeout(resolve, 500));
-  console.log(`[Background Job] Sending email to ${payload.email}: "${payload.subject}"`);
-});
-
-// 4. Define Routes
-
-// Root
-app.get('/', (ctx) => {
-  ctx.json({
-    message: 'Welcome to QHTTPX Example API',
-    endpoints: [
-      'GET /api/users',
-      'POST /api/users',
-      'GET /api/users/:id',
-      'POST /api/jobs/email',
-      'WS /ws',
-      'GET /api/cookies',
-      'GET /api/redirect'
-    ],
-    documentation: 'https://github.com/your-repo/qhttpx'
-  });
-});
-
-app.get('/api/cookies', (ctx) => {
-  // Read cookies
-  const visited = parseInt(ctx.cookies['visited'] || '0');
-  
-  // Set cookie
-  ctx.setCookie('visited', (visited + 1).toString(), {
-    path: '/',
-    maxAge: 3600, // 1 hour
-    httpOnly: true,
-  });
-
-  ctx.json({
-    message: 'Cookie demo',
-    visited: visited + 1,
-    allCookies: ctx.cookies
-  });
+// 2. Global Middleware (Logging & Rate Limit)
+app.use(async ({ req, next }) => {
+  console.log(`[${req.method}] ${req.url}`);
+  if (next) await next();
 });
 
-app.get('/api/redirect', (ctx) => {
-  ctx.redirect('/api/users');
-});
-
-// User Routes using the Chainable Builder
-app.route('/api/users')
-  .get((ctx) => {
-    const userList = Array.from(users.values());
-    ctx.json({ data: userList, count: userList.length });
-  })
-  .post(async (ctx) => {
-    if (!ctx.body || typeof ctx.body !== 'object') {
-       ctx.json({ error: 'Invalid body' }, 400);
-       return;
-    }
-    
-    const body = ctx.body as any;
-    if (!body.name || !body.role) {
-      ctx.json({ error: 'Missing name or role' }, 400);
-      return;
-    }
-
-    const id = (users.size + 1).toString();
-    const newUser = { id, name: body.name, role: body.role };
-    users.set(id, newUser);
-
-    ctx.json({ message: 'User created', user: newUser }, 201);
-  });
-
-app.route('/api/users/:id')
-  .get((ctx) => {
-    const { id } = ctx.params;
-    const user = users.get(id);
-    
-    if (!user) {
-      ctx.json({ error: 'User not found' }, 404);
-      return;
-    }
-
-    ctx.json({ data: user });
-  })
-  .delete((ctx) => {
-    const { id } = ctx.params;
-    if (users.delete(id)) {
-      ctx.json({ message: 'User deleted' });
-    } else {
-      ctx.json({ error: 'User not found' }, 404);
-    }
-  });
-
-// Job Route
-app.post('/api/jobs/email', async (ctx) => {
-  const body = ctx.body as any;
-  if (!body.email) {
-    ctx.json({ error: 'Email required' }, 400);
-    return;
+// 3. Validation Schema
+const UserSchema = {
+  body: {
+    type: 'object',
+    required: ['name', 'role'],
+    properties: { name: { type: 'string' }, role: { type: 'string' } }
   }
+};
 
-  await app.enqueue('send-email', { 
-    email: body.email, 
-    subject: 'Welcome to QHTTPX!' 
-  });
+// 4. Routes (Clean & Destructured)
+app.get('/', ({ json }) => json({ status: 'online', fusion: true }));
 
-  ctx.json({ message: 'Email job queued', status: 'pending' }, 202);
+// ⚡ Fused Endpoint: 1000 concurrent requests -> 1 DB execution
+app.get('/heavy', async ({ json }) => {
+  await new Promise(r => setTimeout(r, 100)); // Simulate DB
+  json({ data: 'Expensive Result', timestamp: Date.now() });
 });
 
-// WebSocket Route
-app.upgrade('/ws', handleWebSocketEcho);
-
-// Error handling demo
-app.get('/error', () => {
-  throw new Error('Something went wrong!');
+// 🛡️ Validated & Typed Route
+app.post('/users', { schema: UserSchema }, async ({ body, json }) => {
+  // Body is already validated and typed here
+  json({ created: true, user: body }, 201);
 });
 
-// Custom Error Handlers (optional, defaults are good)
-app.setNotFoundHandler((ctx) => {
-  ctx.json({ error: 'Not Found', path: ctx.url.pathname }, 404);
+// 📂 File Uploads (Typed)
+app.post('/upload', ({ files, json }) => {
+  if (!files?.doc) return json({ error: 'No file' }, 400);
+  const doc = Array.isArray(files.doc) ? files.doc[0] : files.doc;
+  json({ filename: doc.filename, size: doc.size });
 });
 
-app.setErrorHandler((err, ctx) => {
-  if (err instanceof HttpError) {
-    ctx.json({ error: err.message, code: err.code, details: err.details }, err.status);
-    return;
-  }
-  ctx.json({ error: 'Internal Server Error' }, 500);
+// 📡 WebSockets (Pub/Sub)
+app.upgrade('/chat', (ws) => {
+  ws.join('general'); // Auto-join room
+  ws.on('message', (msg) => {
+    // Broadcast to room
+    app.websocket.to('general').emit(`Echo: ${msg}`);
+  });
 });
 
-// 5. Start Server
-const PORT = process.env.PORT ? parseInt(process.env.PORT) : 3000;
-app.listen(PORT, '0.0.0.0').then(({ port }) => {
-  console.log(`\n🚀 Server running at http://localhost:${port}`);
-  console.log(`   Try: curl http://localhost:${port}/api/users`);
+// 5. Unified Error Handling
+app.onError(({ error, json }) => {
+  console.error(error); // Log internal error
+  json({ error: 'Internal Server Error', handled: true }, 500);
 });
 
-// --- Helpers ---
-
-function createWebSocketAccept(key: string): string {
-  return createHash('sha1')
-    .update(key + '258EAFA5-E914-47DA-95CA-C5AB0DC85B11')
-    .digest('base64');
-}
-
-function handleWebSocketEcho(req: IncomingMessage, socket: Duplex, head: Buffer) {
-  void head;
-
-  const rawKeyHeader = req.headers['sec-websocket-key'];
-  let keyHeader: string | undefined;
-  if (typeof rawKeyHeader === 'string') {
-    keyHeader = rawKeyHeader;
-  } else if (Array.isArray(rawKeyHeader)) {
-    const values = rawKeyHeader as string[];
-    if (values.length > 0) {
-      keyHeader = values[0];
-    }
-  }
-
-  const key = keyHeader ?? '';
-  const accept = createWebSocketAccept(key);
-  const responseLines = [
-    'HTTP/1.1 101 Switching Protocols',
-    'Upgrade: websocket',
-    'Connection: Upgrade',
-    `Sec-WebSocket-Accept: ${accept}`,
-    '',
-    '',
-  ];
-  socket.write(responseLines.join('\r\n'));
-
-  socket.on('data', (buffer) => {
-    if (buffer.length < 2) return;
-
-    const opcode = buffer[0] & 0x0f;
-    const masked = (buffer[1] & 0x80) !== 0;
-    let payloadLength = buffer[1] & 0x7f;
-    let offset = 2;
-
-    if (payloadLength === 126) {
-      if (buffer.length < offset + 2) return;
-      payloadLength = buffer.readUInt16BE(offset);
-      offset += 2;
-    } else if (payloadLength === 127) {
-      return; // Too large for this demo
-    }
-
-    if (buffer.length < offset + payloadLength) return;
-
-    let maskingKey: Buffer | undefined;
-    if (masked) {
-      maskingKey = buffer.subarray(offset, offset + 4);
-      offset += 4;
-    }
-
-    const payload = buffer.subarray(offset, offset + payloadLength);
-
-    if (masked && maskingKey) {
-      for (let i = 0; i < payload.length; i += 1) {
-        payload[i] ^= maskingKey[i % 4];
-      }
-    }
-
-    if (opcode === 0x8) { // Close
-      socket.end();
-      return;
-    }
-
-    if (opcode === 0x1) { // Text
-      const message = payload.toString('utf8');
-      const textBytes = Buffer.from(message, 'utf8');
-      const length = textBytes.length;
-
-      let header: Buffer;
-      if (length < 126) {
-        header = Buffer.alloc(2);
-        header[0] = 0x81;
-        header[1] = length;
-      } else if (length < 65536) {
-        header = Buffer.alloc(4);
-        header[0] = 0x81;
-        header[1] = 126;
-        header.writeUInt16BE(length, 2);
-      } else {
-        return; // Too large
-      }
-
-      const frame = Buffer.concat([header, textBytes]);
-      socket.write(frame);
-    }
-  });
-
-  socket.on('end', () => socket.end());
-  socket.on('error', () => socket.destroy());
-}
+// 6. Start Server
+app.listen(3000, () => console.log('🚀 Server running on http://localhost:3000'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qhttpx",
-  "version": "1.8.3",
+  "version": "1.8.5",
   "description": "The High-Performance Hybrid HTTP Runtime for Node.js. Built for extreme concurrency, request fusion, and zero-overhead scaling.",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -67,6 +67,7 @@
     "@typescript-eslint/eslint-plugin": "^8.53.0",
     "@typescript-eslint/parser": "^8.53.0",
     "autocannon": "^8.0.0",
+    "dotenv": "^17.2.3",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",

package/src/core/server.ts

@@ -395,7 +395,11 @@ export class QHTTPX {
   private registerRoute(
     method: HTTPMethod,
     path: string,
-    handlerOrOptions: QHTTPXHandler | QHTTPXRouteOptions,
+    handlerOrOptions:
+      | QHTTPXHandler
+      | QHTTPXRouteOptions
+      | import('./types').QHTTPXRouteConfig,
+    handlerIfOptions?: QHTTPXHandler,
   ): void {
     let handler: QHTTPXHandler;
     let schema: RouteSchema | Record<string, unknown> | undefined;
@@ -403,30 +407,87 @@ export class QHTTPX {
 
     if (typeof handlerOrOptions === 'function') {
       handler = handlerOrOptions;
-    } else {
-      handler = handlerOrOptions.handler;
+    } else if (handlerIfOptions) {
+      handler = handlerIfOptions;
       schema = handlerOrOptions.schema;
       options.priority = handlerOrOptions.priority;
+    } else {
+      const opts = handlerOrOptions as QHTTPXRouteOptions;
+      handler = opts.handler;
+      schema = opts.schema;
+      options.priority = opts.priority;
     }
 
     const compiled = this.compileRoutePipeline(handler, schema);
     this.router.register(method, path, compiled, { ...options, schema });
   }
 
-  get(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
-    this.registerRoute('GET', path, handler);
+  get(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+  get(
+    path: string,
+    config: import('./types').QHTTPXRouteConfig,
+    handler: QHTTPXHandler,
+  ): void;
+  get(
+    path: string,
+    handlerOrOptions:
+      | QHTTPXHandler
+      | QHTTPXRouteOptions
+      | import('./types').QHTTPXRouteConfig,
+    handler?: QHTTPXHandler,
+  ): void {
+    this.registerRoute('GET', path, handlerOrOptions, handler);
   }
 
-  post(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
-    this.registerRoute('POST', path, handler);
+  post(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+  post(
+    path: string,
+    config: import('./types').QHTTPXRouteConfig,
+    handler: QHTTPXHandler,
+  ): void;
+  post(
+    path: string,
+    handlerOrOptions:
+      | QHTTPXHandler
+      | QHTTPXRouteOptions
+      | import('./types').QHTTPXRouteConfig,
+    handler?: QHTTPXHandler,
+  ): void {
+    this.registerRoute('POST', path, handlerOrOptions, handler);
   }
 
-  put(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
-    this.registerRoute('PUT', path, handler);
+  put(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+  put(
+    path: string,
+    config: import('./types').QHTTPXRouteConfig,
+    handler: QHTTPXHandler,
+  ): void;
+  put(
+    path: string,
+    handlerOrOptions:
+      | QHTTPXHandler
+      | QHTTPXRouteOptions
+      | import('./types').QHTTPXRouteConfig,
+    handler?: QHTTPXHandler,
+  ): void {
+    this.registerRoute('PUT', path, handlerOrOptions, handler);
   }
 
-  delete(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
-    this.registerRoute('DELETE', path, handler);
+  delete(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+  delete(
+    path: string,
+    config: import('./types').QHTTPXRouteConfig,
+    handler: QHTTPXHandler,
+  ): void;
+  delete(
+    path: string,
+    handlerOrOptions:
+      | QHTTPXHandler
+      | QHTTPXRouteOptions
+      | import('./types').QHTTPXRouteConfig,
+    handler?: QHTTPXHandler,
+  ): void {
+    this.registerRoute('DELETE', path, handlerOrOptions, handler);
   }
 
   route(path: string) {
@@ -541,7 +602,22 @@ export class QHTTPX {
     return generator.generate();
   }
 
-  public async listen(port: number, hostname?: string): Promise<{ port: number }> {
+  public async listen(
+    port: number,
+    hostnameOrCallback?: string | (() => void),
+    callback?: () => void,
+  ): Promise<{ port: number }> {
+    let hostname: string | undefined;
+    let cb: (() => void) | undefined;
+
+    if (typeof hostnameOrCallback === 'function') {
+      cb = hostnameOrCallback;
+      hostname = undefined;
+    } else {
+      hostname = hostnameOrCallback;
+      cb = callback;
+    }
+
     if (this.options.database) {
       await this.options.database.connect();
     }
@@ -567,6 +643,9 @@ export class QHTTPX {
         this.router.freeze();
         void this.runLifecycleHooks(this.onStartHooks);
         const address = this.server.address();
+        
+        if (cb) cb();
+
         if (address && typeof address === 'object') {
           resolve({ port: address.port });
         } else {
@@ -601,6 +680,7 @@ export class QHTTPX {
     const ctx: any = {
       req: null,
       res: null,
+      headers: null,
       url: null,
       params: null,
       query: null,
@@ -731,6 +811,7 @@ export class QHTTPX {
     const mutableCtx = ctx as any;
     mutableCtx.req = req;
     mutableCtx.res = res;
+    mutableCtx.headers = req.headers;
     mutableCtx.url = url;
     mutableCtx.params = params;
     mutableCtx.query = query;
@@ -754,6 +835,7 @@ export class QHTTPX {
     const mutableCtx = ctx as any;
     mutableCtx.req = null;
     mutableCtx.res = null;
+    mutableCtx.headers = null;
     mutableCtx.url = null;
     mutableCtx.params = null;
     mutableCtx.query = null;

package/src/core/types.ts

@@ -1,4 +1,4 @@
-import { IncomingMessage, ServerResponse } from 'http';
+import { IncomingMessage, ServerResponse, IncomingHttpHeaders } from 'http';
 import { URL } from 'url';
 import type { BufferPool, BufferPoolConfig } from './buffer-pool';
 import type { DatabaseManager } from '../database/manager';
@@ -59,6 +59,7 @@ export type QHTTPXFile = {
 export type QHTTPXContext = {
   readonly req: IncomingMessage;
   readonly res: ServerResponse;
+  readonly headers: IncomingHttpHeaders;
   readonly url: URL;
   readonly params: Record<string, string>;
   readonly query: Record<string, string | string[]>;
@@ -100,6 +101,9 @@ export type QHTTPXRouteOptions = {
   priority?: RoutePriority;
 };
 
+export type QHTTPXRouteConfig = Omit<QHTTPXRouteOptions, 'handler'>;
+
+
 export type QHTTPXMiddleware = (
   ctx: QHTTPXContext,
   next: () => Promise<void>,

package/tsconfig.json

@@ -13,5 +13,5 @@
     "declaration": true,
     "types": ["node", "vitest"]
   },
-  "include": ["src", "tests", "vitest.config.*"]
+  "include": ["src", "tests", "examples", "vitest.config.*"]
 }