qhttpx 1.8.2 → 1.8.4

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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"**
+
+### Added
+- **Unified Destructuring**: Added comprehensive support for destructuring `ctx` everywhere, including route handlers, error handlers, and middleware.
+- **Middleware DX**: Middleware can now access `next` via destructuring: `app.use(({ next }) => next())`.
+- **Type Safety**: `ctx.files` is now strongly typed as `QHTTPXFile | QHTTPXFile[]` (no more `any`).
+- **Unified Error Context**: `onError` now receives a `QHTTPXErrorContext` containing the `error` object (`({ error, json }) => ...`).
+- **Aliases**: Added `app.onError` and `app.notFound` aliases for cleaner code.
+
 ## [1.8.2] - 2026-01-20
 **"The Usability 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/assets/logo.svg

@@ -1,11 +1,25 @@
-<svg width="200" height="200" viewBox="0 0 200 200" fill="none" xmlns="http://www.w3.org/2000/svg">
-  <rect width="200" height="200" rx="40" fill="url(#paint0_linear)"/>
-  <path d="M100 40L151.962 70V130L100 160L48.0385 130V70L100 40Z" stroke="white" stroke-width="12" stroke-linejoin="round"/>
-  <text x="100" y="125" font-family="Arial, sans-serif" font-weight="900" font-size="80" fill="white" text-anchor="middle">Q</text>
-  <defs>
-    <linearGradient id="paint0_linear" x1="0" y1="0" x2="200" y2="200" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#2563EB"/>
-      <stop offset="1" stop-color="#7C3AED"/>
-    </linearGradient>
-  </defs>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Creator: CorelDRAW -->
+<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="28.726mm" height="11.2072mm" version="1.1" style="shape-rendering:geometricPrecision; text-rendering:geometricPrecision; image-rendering:optimizeQuality; fill-rule:evenodd; clip-rule:evenodd"
+viewBox="0 0 2872.6 1120.72"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xodm="http://www.corel.com/coreldraw/odm/2003">
+ <defs>
+  <style type="text/css">
+   <![CDATA[
+    .fil1 {fill:#2B2A29;fill-rule:nonzero}
+    .fil0 {fill:#00A0E3;fill-rule:nonzero}
+   ]]>
+  </style>
+ </defs>
+ <g id="Layer_x0020_1">
+  <metadata id="CorelCorpID_0Corel-Layer"/>
+  <path class="fil0" d="M414.71 674.26l197.01 0 87.46 110.27 107.44 123.19 171.39 213 -219.58 0 -120.61 -144.12 -68.18 -98.97 -154.93 -203.37zm74.29 379.69c-92.16,0 -175.15,-20.45 -248.97,-61.36 -73.59,-40.91 -132.13,-100.62 -175.15,-179.15 -43.26,-78.52 -64.89,-173.74 -64.89,-285.88 0,-112.85 21.63,-208.53 64.89,-287.06 43.02,-78.52 101.56,-138.23 175.15,-179.14 73.82,-40.91 156.81,-61.36 248.97,-61.36 91.93,0 174.68,20.45 248.27,61.36 73.82,40.91 132.12,100.62 175.15,179.14 42.79,78.53 64.41,174.21 64.41,287.06 0,112.61 -21.62,208.07 -64.41,286.59 -43.03,78.52 -101.33,138 -175.15,178.67 -73.59,40.68 -156.34,61.13 -248.27,61.13zm0 -213.7c49.61,0 92.4,-11.76 128.13,-35.74 35.97,-23.98 63.48,-59.01 82.76,-105.8 19.27,-46.54 28.91,-103.67 28.91,-171.15 0,-67.94 -9.64,-125.31 -28.91,-172.09 -19.28,-46.79 -46.79,-82.29 -82.76,-106.03 -35.73,-23.98 -78.52,-35.97 -128.13,-35.97 -50.07,0 -92.86,12.22 -128.83,36.2 -35.74,24.22 -63.24,59.48 -82.52,106.03 -19.28,46.79 -28.92,103.92 -28.92,171.86 0,67.48 9.64,124.61 28.92,170.92 19.28,46.31 46.78,81.58 82.52,105.79 35.97,23.98 78.76,35.98 128.83,35.98z"/>
+  <path class="fil1" d="M1106.72 521.64l0 310.02 -19.05 0 0 -615.95 19.05 0 0 253.01 -4.93 0c9.87,-35.28 29.49,-61.81 58.84,-79.45 29.35,-17.63 61.52,-26.38 96.52,-26.38 31.75,0 59.69,6.63 83.82,20.03 23.99,13.41 43.04,31.9 56.73,55.6 13.83,23.71 20.74,51.37 20.74,83.12l0 310.02 -19.05 0 0 -310.02c0,-41.91 -13.26,-75.64 -39.65,-101.32 -26.53,-25.68 -60.68,-38.38 -102.59,-38.52 -28.65,0.14 -54.33,6.06 -77.05,18.06 -22.72,11.99 -40.64,28.5 -53.76,49.67 -13.12,21.03 -19.62,45.01 -19.62,72.11z"/>
+  <path id="_1" class="fil1" d="M1687.12 369.52l0 18.91 -182.74 0 0 -18.91 182.74 0zm-114.86 -110.07l19.05 0 0 484.16c0,27.51 6.91,47.83 20.74,60.96 13.97,13.12 32.74,16.65 56.45,10.58 2.25,-0.56 4.65,-1.13 7.05,-1.83 2.54,-0.71 4.8,-1.42 7.06,-1.98l4.51 18.63c-2.4,0.56 -4.94,1.27 -7.62,1.83 -2.68,0.71 -5.22,1.41 -7.62,1.98 -30.9,7.33 -55.17,2.25 -72.95,-15.53 -17.78,-17.78 -26.67,-42.61 -26.67,-74.64l0 -484.16z"/>
+  <path id="_2" class="fil1" d="M1890.46 369.52l0 18.91 -182.74 0 0 -18.91 182.74 0zm-114.86 -110.07l19.05 0 0 484.16c0,27.51 6.91,47.83 20.74,60.96 13.97,13.12 32.74,16.65 56.45,10.58 2.25,-0.56 4.65,-1.13 7.05,-1.83 2.54,-0.71 4.8,-1.42 7.06,-1.98l4.51 18.63c-2.4,0.56 -4.94,1.27 -7.62,1.83 -2.68,0.71 -5.22,1.41 -7.62,1.98 -30.9,7.33 -55.17,2.25 -72.95,-15.53 -17.78,-17.78 -26.67,-42.61 -26.67,-74.64l0 -484.16z"/>
+  <path id="_3" class="fil1" d="M1988.81 1004.52l0 -635 19.05 0 0 118.11 2.4 0c8.05,-25.54 19.76,-47.7 35,-66.46 15.24,-18.77 33.3,-33.17 54.19,-43.18 20.74,-10.16 43.46,-15.1 68.01,-15.1 36.13,0 67.45,10.44 93.98,31.32 26.67,21.03 47.27,49.53 61.81,85.66 14.68,36.12 21.87,76.76 21.87,121.92 0,45.44 -7.19,86.36 -21.59,122.63 -14.53,36.26 -34.99,64.77 -61.66,85.79 -26.53,20.89 -58,31.33 -94.41,31.33 -24.83,0 -47.55,-5.08 -68.3,-15.24 -20.6,-10.16 -38.52,-24.7 -53.76,-43.61 -15.1,-18.9 -26.81,-41.2 -35.14,-66.74l-2.4 0 0 288.57 -19.05 0zm178.65 -181.89c32.46,0 60.54,-9.74 84.25,-29.21 23.7,-19.47 42.05,-45.86 55.03,-79.16 12.98,-33.31 19.47,-70.84 19.47,-112.47 0,-41.63 -6.49,-79.02 -19.47,-112.18 -12.98,-33.31 -31.33,-59.55 -55.03,-78.74 -23.71,-19.34 -51.79,-28.93 -84.25,-29.07 -32.59,0.14 -60.68,9.73 -84.52,29.07 -23.85,19.19 -42.34,45.43 -55.46,78.74 -13.12,33.16 -19.62,70.55 -19.62,112.18 0,41.63 6.5,79.16 19.48,112.47 12.84,33.3 31.33,59.69 55.17,79.16 23.85,19.47 52.07,29.21 84.95,29.21z"/>
+  <path id="_4" class="fil1" d="M2402.13 831.66l228.61 -319.62 0 13.27 -221.97 -309.6 23.14 0 138.15 192.61c8.18,11.29 16.37,22.58 24.41,33.73 7.9,11.15 15.95,22.44 23.99,33.87 7.9,11.43 15.8,23.28 23.56,35.28l-8.74 0c8.04,-12 15.94,-23.85 23.84,-35.28 7.76,-11.43 15.67,-22.72 23.71,-33.87 8.04,-11.15 15.95,-22.44 23.99,-33.73l138.01 -192.61 23.14 0 -221.97 310.44 0 -14.11 228.6 319.62 -23.14 0 -146.76 -205.04c-7.62,-11 -15.38,-22.01 -23.14,-32.87 -7.76,-10.87 -15.38,-21.88 -23.14,-33.02 -7.76,-11.29 -15.38,-22.58 -23.14,-34.15l8.32 0c-7.76,11.57 -15.38,22.86 -23,34.15 -7.62,11.14 -15.1,22.15 -22.72,33.02 -7.62,10.86 -15.38,21.87 -23.42,32.87l-147.18 205.04 -23.15 0z"/>
+ </g>
 </svg>

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.2",
+    "version": "1.8.4",
     "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",

package/dist/src/benchmarks/quantam-users.d.ts

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

package/dist/src/benchmarks/simple-json.d.ts

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

package/dist/src/benchmarks/ultra-mode.d.ts

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

package/dist/src/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/client/index.d.ts

@@ -0,0 +1,17 @@
+export type InferRequestType<T> = T extends {
+    request: infer R;
+} ? R : never;
+export type InferResponseType<T> = T extends {
+    response: infer R;
+} ? R : never;
+export declare function hc<T extends Record<string, any>>(baseUrl: string, options?: RequestInit): Client<T>;
+type Client<T> = {
+    [K in keyof T]: T[K] extends Function ? never : Client<T[K]>;
+} & {
+    $get: (args?: any) => Promise<any>;
+    $post: (args?: any) => Promise<any>;
+    $put: (args?: any) => Promise<any>;
+    $delete: (args?: any) => Promise<any>;
+    $patch: (args?: any) => Promise<any>;
+};
+export {};

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

@@ -0,0 +1,24 @@
+import { QHTTPXContext, QHTTPXOpHandler } from './types';
+import { DatabaseManager } from '../database/manager';
+export declare class BatchExecutor {
+    private ops;
+    private dbManager?;
+    private coalescers;
+    constructor(dbManager?: DatabaseManager);
+    register(name: string, handler: QHTTPXOpHandler): void;
+    handleBatch(ctx: QHTTPXContext, batch: Array<{
+        op: string;
+        params: unknown;
+        id?: unknown;
+    }>): Promise<{
+        results: ({
+            error: string;
+            id: unknown;
+            result?: undefined;
+        } | {
+            result: any;
+            id: unknown;
+            error?: undefined;
+        })[];
+    }>;
+}

package/dist/src/core/body-parser.d.ts

@@ -0,0 +1,15 @@
+import { IncomingMessage } from 'http';
+export type BodyParserOptions = {
+    maxBodyBytes?: number;
+};
+export type ParsedBody = {
+    body: unknown;
+    files?: Record<string, unknown>;
+};
+export interface IBodyParser {
+    parse(req: IncomingMessage, options?: BodyParserOptions): Promise<any>;
+}
+export declare class BodyParser {
+    static parse(req: IncomingMessage, options?: BodyParserOptions): Promise<any>;
+    private static parseMultipart;
+}

package/dist/src/core/buffer-pool.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Buffer pool for response bodies (small, medium, large).
+ * Reuses allocated buffers to reduce GC pressure.
+ */
+export type BufferPoolConfig = {
+    smallSize?: number;
+    mediumSize?: number;
+    largeSize?: number;
+    smallPoolSize?: number;
+    mediumPoolSize?: number;
+    largePoolSize?: number;
+};
+export declare class BufferPool {
+    private readonly smallSize;
+    private readonly mediumSize;
+    private readonly largeSize;
+    private readonly smallBuffers;
+    private readonly mediumBuffers;
+    private readonly largeBuffers;
+    private readonly smallPoolSize;
+    private readonly mediumPoolSize;
+    private readonly largePoolSize;
+    constructor(config?: BufferPoolConfig);
+    /**
+     * Acquire a buffer suitable for the given size.
+     * Returns a buffer from the appropriate pool.
+     */
+    acquire(size: number): Buffer;
+    /**
+     * Release a buffer back to the appropriate pool.
+     */
+    release(buffer: Buffer): void;
+    /**
+     * Get the number of available buffers in each pool.
+     */
+    getPoolStatus(): {
+        small: number;
+        medium: number;
+        large: number;
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { QHTTPXOptions } from './types';
+export type LoadConfigOptions = {
+    env?: NodeJS.ProcessEnv;
+    defaults?: QHTTPXOptions;
+    prefix?: string;
+};
+export declare function loadConfig(options?: LoadConfigOptions): QHTTPXOptions;

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

@@ -0,0 +1,14 @@
+import type { QHTTPXContext } from './types';
+export interface RequestFusionOptions {
+    windowMs?: number;
+    vary?: string[];
+}
+export declare class RequestFusion {
+    private inflight;
+    private cache;
+    private options;
+    constructor(options?: boolean | RequestFusionOptions);
+    coalesce(ctx: QHTTPXContext, next: (ctx: QHTTPXContext) => Promise<void> | void): Promise<void>;
+    private applyResult;
+    private getKey;
+}

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

@@ -0,0 +1,22 @@
+import pino from 'pino';
+export type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+export interface LoggerOptions {
+    level?: LogLevel;
+    pretty?: boolean;
+    name?: string;
+}
+export declare class Logger {
+    private pino;
+    constructor(options?: LoggerOptions);
+    info(msg: string, ...args: any[]): void;
+    info(obj: object, msg?: string, ...args: any[]): void;
+    error(msg: string, ...args: any[]): void;
+    error(obj: object, msg?: string, ...args: any[]): void;
+    warn(msg: string, ...args: any[]): void;
+    warn(obj: object, msg?: string, ...args: any[]): void;
+    debug(msg: string, ...args: any[]): void;
+    debug(obj: object, msg?: string, ...args: any[]): void;
+    fatal(msg: string, ...args: any[]): void;
+    fatal(obj: object, msg?: string, ...args: any[]): void;
+    child(bindings: pino.Bindings): Logger;
+}

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

@@ -0,0 +1,45 @@
+import type { TaskEngine, TaskMetrics } from './tasks';
+import { Scheduler } from './scheduler';
+export type LatencySnapshot = {
+    p50: number | null;
+    p95: number | null;
+    p99: number | null;
+};
+export type MetricsSnapshot = {
+    totalRequests: number;
+    inFlightRequests: number;
+    totalErrors: number;
+    totalTimeouts: number;
+    requestsPerSecond: number;
+    latency: LatencySnapshot;
+    scheduler: {
+        inFlight: number;
+    };
+    tasks?: TaskMetrics;
+    memory: {
+        rssBytes: number;
+        heapUsedBytes: number;
+    };
+};
+export declare class Metrics {
+    private readonly scheduler;
+    private readonly taskEngine?;
+    private readonly latencies;
+    private readonly maxLatencies;
+    private readonly enabled;
+    private totalRequests;
+    private inFlightRequests;
+    private totalErrors;
+    private totalTimeouts;
+    constructor(scheduler: Scheduler, options?: {
+        maxLatencies?: number;
+        enabled?: boolean;
+    }, taskEngine?: TaskEngine);
+    onRequestStart(): void;
+    onRequestEnd(durationMs: number, statusCode: number): void;
+    onTimeout(): void;
+    snapshot(): MetricsSnapshot;
+    private recordLatency;
+    private latencySnapshot;
+    private percentile;
+}

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

@@ -0,0 +1,9 @@
+export type WorkerSetting = 'auto' | number;
+export declare function calculateWorkerCount(setting: WorkerSetting): number;
+export type ResourceThresholds = {
+    maxRssBytes?: number;
+};
+export type ResourceSample = {
+    rssBytes: number;
+};
+export declare function isResourceOverloaded(sample: ResourceSample, thresholds: ResourceThresholds): boolean;

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

@@ -0,0 +1,34 @@
+import { RoutePriority } from './types';
+export type SchedulerOptions = {
+    maxConcurrency?: number;
+    workers?: number;
+};
+export type RunOptions = {
+    priority?: RoutePriority;
+    onOverloaded?: () => void;
+    timeoutMs?: number;
+    onTimeout?: () => void;
+};
+export type SchedulerStats = {
+    inFlight: number;
+    maxConcurrency: number;
+    workers: number;
+    perWorkerStats: {
+        workerId: number;
+        queued: number;
+    }[];
+};
+export declare class Scheduler {
+    private inFlight;
+    private readonly maxConcurrency;
+    private readonly workerCount;
+    private readonly perWorkerQueues;
+    private nextWorkerIndex;
+    constructor(options?: SchedulerOptions);
+    getCurrentInFlight(): number;
+    /**
+     * Get scheduler statistics (queued tasks per worker, etc.)
+     */
+    getStats(): SchedulerStats;
+    run(task: () => void | Promise<void>, options: RunOptions): Promise<void>;
+}

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

@@ -0,0 +1,26 @@
+import { QHTTPX } from './server';
+import { QHTTPXHandler, QHTTPXRouteOptions, QHTTPXMiddleware, QHTTPXPlugin, QHTTPXPluginOptions } from './types';
+/**
+ * A Scope represents a prefixed or isolated context for plugins.
+ * It proxies methods to the main QHTTPX instance but handles prefixing.
+ */
+export declare class QHTTPXScope {
+    private readonly app;
+    private readonly prefix;
+    constructor(app: QHTTPX, prefix?: string);
+    /**
+     * Registers a sub-plugin within this scope.
+     * Prefixes are concatenated (e.g. /v1 + /users = /v1/users).
+     */
+    register<Options extends QHTTPXPluginOptions>(plugin: QHTTPXPlugin<Options>, options?: Options): Promise<void>;
+    use(middleware: QHTTPXMiddleware): void;
+    get(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+    post(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+    put(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+    delete(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+    patch(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+    options(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+    head(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+    getApp(): QHTTPX;
+    private joinPaths;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Fast JSON serializer using fast-json-stringify
+ * For best performance, use schema-based stringifiers per route
+ */
+export declare function fastJsonStringify(value: unknown, schema?: unknown): string;
+/**
+ * Get a pre-compiled stringifier for a specific schema
+ * Use this in route handlers for maximum performance
+ */
+export declare function getStringifier(schema: unknown): (value: unknown) => string;

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

@@ -0,0 +1,90 @@
+import http from 'http';
+import { WebSocketManager } from './websocket';
+import { OpenAPIOptions } from '../openapi/generator';
+import { HTTPMethod, QHTTPXErrorHandler, QHTTPXHandler, QHTTPXMethodNotAllowedHandler, QHTTPXMiddleware, QHTTPXNotFoundHandler, QHTTPXOptions, QHTTPXRouteOptions, QHTTPXPlugin, QHTTPXPluginOptions } from './types';
+import { Logger } from './logger';
+export declare class QHTTPX {
+    private readonly options;
+    private readonly server;
+    readonly logger: Logger;
+    private readonly router;
+    private readonly scheduler;
+    private readonly middlewares;
+    private readonly workerCount;
+    private readonly tasks;
+    private readonly metrics;
+    private readonly contextPool;
+    private readonly bufferPool;
+    private pipelineRunner;
+    private errorHandler?;
+    private notFoundHandler?;
+    private methodNotAllowedHandler?;
+    private readonly tracer?;
+    private readonly onStartHooks;
+    private readonly onBeforeShutdownHooks;
+    private readonly onShutdownHooks;
+    private nextRequestId;
+    private readonly wsManager;
+    private readonly ultraMode;
+    private readonly batchExecutor?;
+    private readonly fusion?;
+    private readonly validator;
+    constructor(options?: QHTTPXOptions);
+    get serverInstance(): http.Server;
+    get websocket(): WebSocketManager;
+    setErrorHandler(handler: QHTTPXErrorHandler): void;
+    setNotFoundHandler(handler: QHTTPXNotFoundHandler): void;
+    setMethodNotAllowedHandler(handler: QHTTPXMethodNotAllowedHandler): void;
+    set404Handler(handler: QHTTPXNotFoundHandler): void;
+    set405Handler(handler: QHTTPXMethodNotAllowedHandler): void;
+    /**
+     * Alias for setErrorHandler
+     */
+    onError(handler: QHTTPXErrorHandler): void;
+    /**
+     * Alias for setNotFoundHandler
+     */
+    notFound(handler: QHTTPXNotFoundHandler): void;
+    onStart(hook: () => void | Promise<void>): void;
+    onBeforeShutdown(hook: () => void | Promise<void>): void;
+    onShutdown(hook: () => void | Promise<void>): void;
+    upgrade(path: string, handler: import('./websocket').WSHandler): void;
+    use(middleware: QHTTPXMiddleware): void;
+    private compileMiddlewarePipeline;
+    private compileRoutePipeline;
+    _registerRoute(method: HTTPMethod, path: string, handlerOrOptions: QHTTPXHandler | QHTTPXRouteOptions): void;
+    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;
+        put(handler: QHTTPXHandler | QHTTPXRouteOptions): /*elided*/ any;
+        delete(handler: QHTTPXHandler | QHTTPXRouteOptions): /*elided*/ any;
+    };
+    task(name: string, handler: import('./types').QHTTPXTaskHandler, options?: import('./types').QHTTPXTaskOptions): void;
+    enqueue(name: string, payload: unknown): Promise<void>;
+    op(name: string, handler: import('./types').QHTTPXOpHandler): void;
+    private registerInternalRoutes;
+    getOpenAPI(options: OpenAPIOptions): object;
+    listen(port: number, hostnameOrCallback?: string | (() => void), callback?: () => void): Promise<{
+        port: number;
+    }>;
+    close(): Promise<void>;
+    shutdown(): Promise<void>;
+    private createContext;
+    private acquireContext;
+    private releaseContext;
+    private handleRequest;
+    private handleUpgrade;
+    private runLifecycleHooks;
+    private handleError;
+    private generateRequestId;
+}