qhttpx 1.9.2 → 1.9.3

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.9.3] - 2026-01-20
+**"The Distribution Fix"**
+
+### Fixed
+- **Distribution**: Removed `dist` from `.gitignore` to allow committing build artifacts if needed, while maintaining strict `!dist` whitelist in `.npmignore` to guarantee inclusion in the published package.
+- **Documentation**: Added a "Side-by-Side" Code Comparison section to `README.md` comparing QHTTPX, Express, and Fastify to showcase Developer Experience (DX).
+- **Metrics**: Exposed Request Fusion metrics (Total Fused, Total Processed) via the `/__qhttpx/metrics` endpoint for better feature visibility.
+
 ## [1.9.2] - 2026-01-20
 **"The Dependency Polish Update"**
 

package/README.md

@@ -56,6 +56,52 @@ Most Node.js frameworks rely on the event loop blindly. QHTTPX introduces a **Co
 | **Static Assets** | **✅ Smart Streaming** | Standard | Standard | Standard |
 | **Type Safety** | **✅ First-class** | Good | Partial | First-class |
 
+### 🆚 Code Comparison
+
+See how QHTTPX simplifies common patterns compared to Express and Fastify.
+
+**The Task**: A simple API endpoint that reads a query parameter, sets a header, and returns JSON.
+
+#### Express
+```javascript
+const express = require('express');
+const app = express();
+
+app.get('/hello', (req, res) => {
+  const name = req.query.name || 'World';
+  res.setHeader('X-Powered-By', 'Express');
+  res.json({ message: `Hello ${name}` });
+});
+
+app.listen(3000);
+```
+
+#### Fastify
+```javascript
+const fastify = require('fastify')();
+
+fastify.get('/hello', async (request, reply) => {
+  const name = request.query.name || 'World';
+  reply.header('X-Powered-By', 'Fastify');
+  return { message: `Hello ${name}` };
+});
+
+fastify.listen({ port: 3000 });
+```
+
+#### QHTTPX
+```typescript
+import { app } from 'qhttpx';
+
+app.get('/hello', ({ query, setHeader, json }) => {
+  const name = query.name || 'World';
+  setHeader('X-Powered-By', 'QHTTPX');
+  json({ message: `Hello ${name}` });
+});
+
+app.listen(3000);
+```
+
 ---
 
 ## ✨ Key Features
@@ -92,34 +138,50 @@ npm install qhttpx
 
 ## ⚡ Quick Start
 
-### 1. Create a Project (Recommended)
-
-Scaffold a production-ready QHTTPX application instantly using our CLI tool:
+### 1. The Modern Way (TypeScript + tsx) - Recommended
+Best for development and production with modern tooling.
 
+**Option A: Scaffolding (Fastest)**
 ```bash
-npm create qhttpx@latest
+npm create qhttpx@latest my-app
+cd my-app
+npm install
+npm run dev
 ```
-This will set up a project with TypeScript, Request Fusion, and best practices pre-configured.
 
-### 2. The Rapid Way (Singleton)
-Get up and running instantly with the singleton instance and destructuring support.
+**Option B: Manual Setup**
+```bash
+npm install qhttpx tsx
+```
 
+*src/index.ts*
 ```typescript
-import { app } from "qhttpx";
+import { app } from 'qhttpx';
+
+app.get('/', ({ json }) => json({ msg: 'Works!' }));
+app.listen(3000, () => console.log('Server running on http://localhost:3000'));
+```
 
-// Concise, destructured handlers
-app.get("/", ({ json }) => json({ message: "Hello World" }));
+Run with: `npx tsx src/index.ts`
 
-// Unified error handling
-app.onError(({ error, json }) => {
-  json({ error: "Something went wrong", details: error }, 500);
-});
+### 2. The Classic Way (JavaScript + CommonJS)
+For legacy environments or simple scripts.
+
+```bash
+npm install qhttpx
+```
 
-// Start listening
-app.listen(3000, () => console.log("Server running on http://localhost:3000"));
+*index.js*
+```javascript
+const { app } = require('qhttpx');
+
+app.get('/', ({ json }) => json({ msg: 'Works!' }));
+app.listen(3000, () => console.log('Running on http://localhost:3000'));
 ```
 
-### 3. The Custom Way (Advanced)
+Run with: `node index.js`
+
+### 3. The Advanced Way (Custom Configuration)
 When you need specific configuration options or multiple instances.
 
 ```typescript

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

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

package/dist/examples/api-server.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const dotenv_1 = require("dotenv");
+// Load .env
+(0, dotenv_1.config)();
+// 1. Initialize App (Fusion + Aegis enabled)
+const app = (0, index_1.createHttpApp)({
+    enableRequestFusion: true, // ⚡ Auto-coalesce duplicate requests
+    metricsEnabled: true, // 📊 Expose /__qhttpx/metrics
+    rateLimit: {
+        windowMs: 15 * 60 * 1000,
+        max: 100,
+        trustProxy: true
+    },
+    cors: true, // 🛡️ Built-in CORS
+    compression: true // 🗜️ Built-in Compression (Gzip/Brotli)
+});
+// 2. Global Middleware (Logging is built-in by default)
+// No manual app.use(rateLimit(...)) needed!
+// 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);
+});
+// � Header Auth Example
+app.post('/auth/verify', async ({ headers, json }) => {
+    const token = headers.authorization?.replace('Bearer ', '');
+    if (!token)
+        return json({ error: 'No token provided' }, 401);
+    // Verify token...
+    json({ valid: true, token });
+});
+// �📂 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 }) => {
+    if (error instanceof index_1.HttpError) {
+        return json({
+            error: error.message,
+            code: error.code,
+            details: error.details
+        }, error.status);
+    }
+    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/examples/basic.d.ts

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

package/dist/examples/basic.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)();
+app.get('/', ({ json }) => {
+    json({ message: 'Hello from QHTTPX!' });
+});
+app.listen(3000, () => {
+    console.log('Server running on http://localhost:3000');
+});

package/dist/examples/compression.d.ts

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

package/dist/examples/compression.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)({
+    // Enable Gzip/Brotli compression
+    compression: true
+    // Or with options:
+    // compression: { threshold: 2048 } // Only compress responses > 2KB
+});
+app.get('/large', ({ json }) => {
+    // Generate a large response to trigger compression
+    const data = Array(1000).fill('some repeated data to compress');
+    json({ data });
+});
+app.listen(3000, () => {
+    console.log('Compression-enabled server running on http://localhost:3000');
+});

package/dist/examples/cors.d.ts

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

package/dist/examples/cors.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)({
+    // Simple: Enable CORS for all origins
+    // cors: true 
+    // Advanced: Configure specific origins
+    cors: {
+        origin: ['http://localhost:5173', 'https://myapp.com'],
+        methods: ['GET', 'POST'],
+        credentials: true
+    }
+});
+app.get('/api/data', ({ json }) => {
+    json({ data: 'This data is accessible via CORS' });
+});
+app.listen(3000, () => {
+    console.log('CORS-enabled server running on http://localhost:3000');
+});

package/dist/examples/errors.d.ts

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

package/dist/examples/errors.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)();
+app.get('/missing', () => {
+    throw new index_1.NotFoundException('Resource not found');
+});
+app.get('/private', () => {
+    throw new index_1.ForbiddenException('You do not have access');
+});
+// Custom global error handler
+app.onError(({ error, json }) => {
+    if (error instanceof index_1.HttpError) {
+        return json({
+            status: 'error',
+            code: error.code,
+            message: error.message
+        }, error.status);
+    }
+    console.error('Unexpected error:', error);
+    json({ status: 'error', message: 'Internal Server Error' }, 500);
+});
+app.listen(3000, () => {
+    console.log('Error handling demo running on http://localhost:3000');
+});

package/dist/examples/file-upload.d.ts

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

package/dist/examples/file-upload.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)({
+    // Limits for uploads
+    maxBodyBytes: 10 * 1024 * 1024 // 10MB
+});
+app.post('/upload', ({ files, json }) => {
+    if (!files || !files.document) {
+        return json({ error: 'No file uploaded' }, 400);
+    }
+    const doc = Array.isArray(files.document) ? files.document[0] : files.document;
+    console.log(`Received file: ${doc.filename} (${doc.size} bytes)`);
+    json({
+        uploaded: true,
+        filename: doc.filename,
+        mimetype: doc.mimeType,
+        size: doc.size
+    });
+});
+app.listen(3000, () => {
+    console.log('Upload server running on http://localhost:3000');
+    console.log('Send POST to /upload with form-data field "document"');
+});

package/dist/examples/fusion.d.ts

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

package/dist/examples/fusion.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)({
+    // Enable Request Fusion (Request Coalescing)
+    enableRequestFusion: true
+});
+// Simulate a slow database call
+const heavyTask = async () => {
+    await new Promise(resolve => setTimeout(resolve, 500));
+    return { data: 'Expensive Result', timestamp: Date.now() };
+};
+// If 1000 users hit this endpoint simultaneously, 
+// the handler runs ONLY ONCE, and the result is shared.
+app.get('/heavy', async ({ json }) => {
+    const result = await heavyTask();
+    json(result);
+});
+app.listen(3000, () => {
+    console.log('Fusion-enabled server running on http://localhost:3000');
+});

package/dist/examples/rate-limiting.d.ts

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

package/dist/examples/rate-limiting.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)({
+    rateLimit: {
+        windowMs: 15 * 60 * 1000, // 15 minutes
+        max: 100, // Limit each IP to 100 requests per window
+        message: 'Too many requests, please try again later.',
+        trustProxy: true // Trust X-Forwarded-For header (useful behind proxies like Nginx)
+    }
+});
+app.get('/', ({ json }) => {
+    json({ status: 'OK', message: 'Request accepted' });
+});
+app.listen(3000, () => {
+    console.log('Rate-limited server running on http://localhost:3000');
+});

package/dist/examples/validation.d.ts

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

package/dist/examples/validation.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)();
+// Define a simple schema (or use Zod if configured)
+const UserSchema = {
+    body: {
+        type: 'object',
+        required: ['username', 'email'],
+        properties: {
+            username: { type: 'string' },
+            email: { type: 'string' }
+        }
+    }
+};
+// Apply schema to route
+app.post('/register', { schema: UserSchema }, ({ body, json }) => {
+    // 'body' is already validated and typed here (if using TS with inferred types)
+    json({ success: true, user: body });
+});
+app.listen(3000, () => {
+    console.log('Validation server running on http://localhost:3000');
+});

package/dist/examples/websockets.d.ts

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

package/dist/examples/websockets.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)();
+app.upgrade('/chat', (ws) => {
+    console.log('Client connected');
+    ws.join('general');
+    ws.on('message', (msg) => {
+        console.log(`Received: ${msg}`);
+        // Broadcast to everyone in 'general' room
+        app.websocket.to('general').emit(`Echo: ${msg}`);
+    });
+    ws.on('close', () => {
+        console.log('Client disconnected');
+    });
+});
+app.listen(3000, () => {
+    console.log('WebSocket Server running on http://localhost:3000');
+    console.log('Test with a WebSocket client at ws://localhost:3000/chat');
+});

package/dist/package.json

@@ -0,0 +1,112 @@
+{
+    "name": "qhttpx",
+    "version": "1.9.3",
+    "gypfile": false,
+    "description": "The Ultra-Fast HTTP Framework for Node.js",
+    "main": "dist/src/index.js",
+    "types": "dist/src/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/src/index.d.ts",
+            "require": "./dist/src/index.js",
+            "default": "./dist/src/index.js"
+        }
+    },
+    "bin": {
+        "qhttpx": "./dist/src/cli/index.js"
+    },
+    "files": [
+        "dist",
+        "src/native",
+        "prebuilds",
+        "scripts",
+        "binding.gyp",
+        "README.md",
+        "LICENSE",
+        "CHANGELOG.md",
+        "docs"
+    ],
+    "directories": {
+        "doc": "docs"
+    },
+    "scripts": {
+        "prebuild": "node -e \"try{require('child_process').execSync('prebuildify --napi --strip', {stdio: 'ignore'})}catch(e){}\"",
+        "prepublishOnly": "npm run build",
+        "build": "tsc -p tsconfig.json",
+        "lint": "eslint src tests --ext .ts",
+        "test": "vitest run",
+        "example": "npx tsx examples/api-server.ts",
+        "bench": "npm run build && node dist/src/benchmarks/simple-json.js",
+        "bench:quantam": "npm run build && node dist/src/benchmarks/quantam-users.js",
+        "bench:ultra": "npm run build && node dist/src/benchmarks/ultra-mode.js"
+    },
+    "keywords": [
+        "http",
+        "server",
+        "web",
+        "framework",
+        "typescript",
+        "fast",
+        "performance",
+        "high-performance",
+        "async",
+        "concurrency",
+        "request-fusion",
+        "coalescing",
+        "middleware",
+        "websocket",
+        "sse",
+        "rate-limit",
+        "rest",
+        "api",
+        "json",
+        "router",
+        "radix-tree",
+        "scheduler",
+        "ultra-fast",
+        "nodejs"
+    ],
+    "author": "Quantam Open Source",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Quantam-Open-Source/qhttpx"
+    },
+    "type": "commonjs",
+    "devDependencies": {
+        "@types/autocannon": "^7.12.7",
+        "@types/better-sqlite3": "^7.6.13",
+        "@types/busboy": "^1.5.4",
+        "@types/ioredis": "^4.28.10",
+        "@types/mongodb": "^4.0.6",
+        "@types/node": "^25.0.9",
+        "@types/pg": "^8.16.0",
+        "@types/ws": "^8.18.1",
+        "@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",
+        "mongodb": "^7.0.0",
+        "pg": "^8.17.1",
+        "prebuildify": "^6.0.1",
+        "prettier": "^3.8.0",
+        "tsx": "^4.21.0",
+        "typescript": "^5.9.3",
+        "vitest": "^4.0.17"
+    },
+    "dependencies": {
+        "better-sqlite3": "^12.6.2",
+        "busboy": "^1.6.0",
+        "fast-json-stringify": "^5.15.1",
+        "node-addon-api": "^8.5.0",
+        "node-gyp-build": "^4.8.4",
+        "pino": "^10.2.0",
+        "pino-pretty": "^13.1.3",
+        "quantam-async": "^0.1.1",
+        "ws": "^8.19.0",
+        "zod": "^4.3.5"
+    }
+}

package/dist/src/benchmarks/compare-frameworks.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const autocannon_1 = __importDefault(require("autocannon"));
+const fastify_1 = __importDefault(require("fastify"));
+const express_1 = __importDefault(require("express"));
+const index_1 = require("../index");
+async function runAutocannon(name, url) {
+    const result = await (0, autocannon_1.default)({
+        url,
+        connections: 200,
+        pipelining: 10,
+        duration: 10,
+    });
+    const total = result.requests.total;
+    const sent = result.requests.sent;
+    const rps = result.requests.average;
+    const p99 = result.latency.p99;
+    console.log(`${name} bench: total=${total} (sent=${sent}) req, ` +
+        `${rps.toFixed(0)} req/sec, p99=${p99.toFixed(1)}ms, connections=${result.connections}, pipelining=${result.pipelining}`);
+    return {
+        name,
+        total,
+        sent,
+        rps,
+        p99,
+    };
+}
+async function startQHTTPX() {
+    const payloadBuffer = Buffer.from(JSON.stringify({ message: 'hello from qhttpx' }));
+    const app = new index_1.QHTTPX({
+        maxConcurrency: 1024,
+        metricsEnabled: false,
+        jsonSerializer: () => payloadBuffer,
+    });
+    app.get('/json', (ctx) => {
+        ctx.json({ message: 'hello from qhttpx' });
+    });
+    const { port } = await app.listen(0, '127.0.0.1');
+    const url = `http://127.0.0.1:${port}/json`;
+    return { app, url };
+}
+async function startFastify() {
+    const app = (0, fastify_1.default)();
+    app.get('/json', async () => {
+        return { message: 'hello from fastify' };
+    });
+    await app.listen({ port: 0, host: '127.0.0.1' });
+    const address = app.server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Fastify address not available');
+    }
+    const url = `http://127.0.0.1:${address.port}/json`;
+    return { app, url };
+}
+async function startExpress() {
+    const app = (0, express_1.default)();
+    app.get('/json', (_req, res) => {
+        res.json({ message: 'hello from express' });
+    });
+    const server = await new Promise((resolve) => {
+        const s = app.listen(0, '127.0.0.1', () => {
+            resolve(s);
+        });
+    });
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Express address not available');
+    }
+    const url = `http://127.0.0.1:${address.port}/json`;
+    return { app, url, server };
+}
+async function run() {
+    const results = [];
+    const qhttpx = await startQHTTPX();
+    try {
+        const r = await runAutocannon('QHTTPX', qhttpx.url);
+        results.push(r);
+    }
+    finally {
+        await qhttpx.app.close();
+    }
+    const fast = await startFastify();
+    try {
+        const r = await runAutocannon('Fastify', fast.url);
+        results.push(r);
+    }
+    finally {
+        await fast.app.close();
+    }
+    const exp = await startExpress();
+    try {
+        const r = await runAutocannon('Express', exp.url);
+        results.push(r);
+    }
+    finally {
+        await new Promise((resolve, reject) => {
+            exp.server.close((err) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+    console.log('\nSummary:');
+    for (const r of results) {
+        console.log(`${r.name}: ${r.rps.toFixed(0)} req/sec, p99=${r.p99.toFixed(1)}ms, total=${r.total}`);
+    }
+    process.exit(0);
+}
+run().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/src/benchmarks/compare.d.ts

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