qhttpx 1.9.3 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.0.0] - 2026-01-21
+**"The Ultra-Simple API Update"**
+
+### Added
+- **Ultra-Simple API**: Introduced `import { app } from "qhttpx"` singleton pattern for zero-boilerplate setup.
+- **Fluent Configuration**: Chained methods `.database()`, `.security()`, `.log()`, `.validate()`, `.production()` for one-line feature enabling.
+- **Return-Based Responses**: Route handlers can now directly return objects (auto-serialized to JSON) or strings, replacing manual `ctx.json()` calls.
+- **Inline Validation**: Declarative schema validation directly in route definitions: `app.post("/", { body: Schema, handler: ... })`.
+- **Semantic Errors**: Added `api.httpError(404, "Message")` helper for consistent, throw-able error handling.
+- **Fluent Rate Limiting**: New `.rateLimit("strict")` presets and `.allow(N).per("interval")` builder for intuitive DDoS protection.
+- **Modular Plugins**: New `plugin(api => ...)` helper for creating reusable, encapsulated route modules.
+- **Production Defaults**: `.production()` method automatically enables Clustering, Compression, Caching, and Adaptive Scheduler.
+
+### Changed
+- **Architecture**: Complete shift to **Pure TypeScript** core. Removed Native C++ bindings to improve portability, reduce build complexity, and eliminate `node-gyp` dependencies while maintaining high performance.
+- **Routing**: `app.routes()` now accepts plugin modules for cleaner code organization.
+- **Status Codes**: POST requests returning data automatically default to `201 Created`.
+
+### Removed
+- **Native Mode**: Removed C++ addon (`node-addon-api`) and associated build steps. QHTTPX is now 100% JS/TS, running everywhere Node.js runs.
+
+## [1.9.4] - 2026-01-20
+**"The Silent Performance Update"**
+
+### Changed
+- **Performance**: Disabled logging by default in standard presets to reduce I/O overhead and improve throughput in production environments.
+
 ## [1.9.3] - 2026-01-20
 **"The Distribution Fix"**
 

package/README.md

@@ -13,6 +13,7 @@
 
 [![npm version](https://img.shields.io/npm/v/qhttpx.svg?style=flat-square)](https://www.npmjs.com/package/qhttpx)
 [![Downloads](https://img.shields.io/npm/dm/qhttpx.svg?style=flat-square)](https://www.npmjs.com/package/qhttpx)
+[![Website](https://img.shields.io/badge/website-qhttpx.gridrr.com-blueviolet.svg?style=flat-square)](https://qhttpx.gridrr.com)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/Quantam-Open-Source/qhttpx/blob/main/LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
 [![TypeScript](https://img.shields.io/badge/Written%20in-TypeScript-blue?style=flat-square)](https://www.typescriptlang.org)
@@ -93,13 +94,13 @@ fastify.listen({ port: 3000 });
 ```typescript
 import { app } from 'qhttpx';
 
-app.get('/hello', ({ query, setHeader, json }) => {
+app.get('/hello', ({ query, setHeader }) => {
   const name = query.name || 'World';
   setHeader('X-Powered-By', 'QHTTPX');
-  json({ message: `Hello ${name}` });
+  return { message: `Hello ${name}` };
 });
 
-app.listen(3000);
+app.start(3000);
 ```
 
 ---
@@ -158,8 +159,14 @@ npm install qhttpx tsx
 ```typescript
 import { app } from 'qhttpx';
 
-app.get('/', ({ json }) => json({ msg: 'Works!' }));
-app.listen(3000, () => console.log('Server running on http://localhost:3000'));
+app.get('/', () => ({ msg: 'Works!' }));
+
+// Ultra-Simple One-Liners
+app.security()
+   .log()
+   .production();
+
+app.start(3000).then(({ port }) => console.log(`Server running on http://localhost:${port}`));
 ```
 
 Run with: `npx tsx src/index.ts`
@@ -175,13 +182,14 @@ npm install qhttpx
 ```javascript
 const { app } = require('qhttpx');
 
-app.get('/', ({ json }) => json({ msg: 'Works!' }));
-app.listen(3000, () => console.log('Running on http://localhost:3000'));
+app.get('/', () => ({ msg: 'Works!' }));
+app.start(3000).then(() => console.log('Running on http://localhost:3000'));
 ```
 
 Run with: `node index.js`
 
 ### 3. The Advanced Way (Custom Configuration)
+
 When you need specific configuration options or multiple instances.
 
 ```typescript
@@ -192,13 +200,10 @@ const app = createHttpApp({
   maxBodySize: "1mb"
 });
 
-app.get("/users", async ({ json, query }) => {
+app.get("/users", ({ json, query }) => {
   const { page } = query;
-  // ...
-  json({ page });
+  return { page };
 });
-
-app.listen(3000);
 ```
 
 ---

package/dist/examples/api-server.js

@@ -4,21 +4,26 @@ 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
+// Configure App via Fluent API
+index_1.app.fusion(true)
+    .metrics(true)
+    .production() // Enables Compression & Performance Mode
+    .security({
+    cors: true,
     rateLimit: {
         windowMs: 15 * 60 * 1000,
         max: 100,
         trustProxy: true
-    },
-    cors: true, // 🛡️ Built-in CORS
-    compression: true // 🗜️ Built-in Compression (Gzip/Brotli)
+    }
+});
+// Routes
+index_1.app.get('/', ({ json }) => json({ status: 'online', fusion: true }));
+// Fused Endpoint: 1000 concurrent requests -> 1 DB execution
+index_1.app.get('/heavy', async ({ json }) => {
+    await new Promise(r => setTimeout(r, 100)); // Simulate DB
+    json({ data: 'Expensive Result', timestamp: Date.now() });
 });
-// 2. Global Middleware (Logging is built-in by default)
-// No manual app.use(rateLimit(...)) needed!
-// 3. Validation Schema
+// Validation Schema
 const UserSchema = {
     body: {
         type: 'object',
@@ -26,52 +31,50 @@ const UserSchema = {
         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 }) => {
+// Validated & Typed Route
+index_1.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 }) => {
+// Header Auth Example
+index_1.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 }) => {
+// File Uploads
+index_1.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) => {
+// WebSockets
+index_1.app.upgrade('/chat', (ws) => {
     ws.join('general'); // Auto-join room
     ws.on('message', (msg) => {
         // Broadcast to room
-        app.websocket.to('general').emit(`Echo: ${msg}`);
+        index_1.app.websocket.to('general').emit(`Echo: ${msg}`);
     });
 });
-// 5. Unified Error Handling
-app.onError(({ error, json }) => {
-    if (error instanceof index_1.HttpError) {
+// Unified Error Handling
+index_1.app.onError(({ error, json }) => {
+    // Use duck typing or check prototype if HttpError is not imported
+    // But here we can use the error code or status property
+    // Or since we removed HttpError import, we can just check properties
+    if (error && typeof error === 'object' && 'status' in error && 'code' in error) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const err = error;
         return json({
-            error: error.message,
-            code: error.code,
-            details: error.details
-        }, error.status);
+            error: err.message,
+            code: err.code,
+            details: err.details
+        }, err.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'));
+// Start Server
+index_1.app.start(3000).then(() => console.log('🚀 Server running on http://localhost:3000'));

package/dist/examples/basic.js

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

package/dist/examples/compression.js

@@ -1,17 +1,15 @@
 "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 }) => {
+// Enable Production Mode
+// - Enables Compression (Gzip/Brotli)
+// - Sets Performance Mode
+index_1.app.production();
+index_1.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, () => {
+index_1.app.start(3000).then(() => {
     console.log('Compression-enabled server running on http://localhost:3000');
 });

package/dist/examples/cors.js

@@ -1,19 +1,18 @@
 "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
+// Enable CORS via Security Helper
+index_1.app.security({
     cors: {
         origin: ['http://localhost:5173', 'https://myapp.com'],
         methods: ['GET', 'POST'],
         credentials: true
     }
 });
-app.get('/api/data', ({ json }) => {
+// Or simple: app.security({ cors: true });
+index_1.app.get('/api/data', ({ json }) => {
     json({ data: 'This data is accessible via CORS' });
 });
-app.listen(3000, () => {
+index_1.app.start(3000).then(() => {
     console.log('CORS-enabled server running on http://localhost:3000');
 });

package/dist/examples/errors.js

@@ -1,25 +1,26 @@
 "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');
+index_1.app.get('/missing', () => {
+    throw index_1.app.error(404, 'Resource not found');
 });
-app.get('/private', () => {
-    throw new index_1.ForbiddenException('You do not have access');
+index_1.app.get('/private', () => {
+    throw index_1.app.error(403, 'You do not have access');
 });
 // Custom global error handler
-app.onError(({ error, json }) => {
-    if (error instanceof index_1.HttpError) {
+index_1.app.onError(({ error, json }) => {
+    if (error && typeof error === 'object' && 'status' in error) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const err = error;
         return json({
             status: 'error',
-            code: error.code,
-            message: error.message
-        }, error.status);
+            code: err.code,
+            message: err.message
+        }, err.status);
     }
     console.error('Unexpected error:', error);
     json({ status: 'error', message: 'Internal Server Error' }, 500);
 });
-app.listen(3000, () => {
+index_1.app.start(3000).then(() => {
     console.log('Error handling demo running on http://localhost:3000');
 });

package/dist/examples/file-upload.js

@@ -1,11 +1,9 @@
 "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 }) => {
+// Configure upload limits
+index_1.app.bodyLimit(10 * 1024 * 1024); // 10MB
+index_1.app.post('/upload', ({ files, json }) => {
     if (!files || !files.document) {
         return json({ error: 'No file uploaded' }, 400);
     }
@@ -18,7 +16,7 @@ app.post('/upload', ({ files, json }) => {
         size: doc.size
     });
 });
-app.listen(3000, () => {
+index_1.app.start(3000).then(() => {
     console.log('Upload server running on http://localhost:3000');
     console.log('Send POST to /upload with form-data field "document"');
 });

package/dist/examples/fusion.js

@@ -1,10 +1,10 @@
 "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
-});
+// Enable Request Fusion (Request Coalescing)
+index_1.app.fusion(true);
+// Enable Production Mode (Compression + Opts)
+index_1.app.production();
 // Simulate a slow database call
 const heavyTask = async () => {
     await new Promise(resolve => setTimeout(resolve, 500));
@@ -12,10 +12,10 @@ const heavyTask = async () => {
 };
 // If 1000 users hit this endpoint simultaneously, 
 // the handler runs ONLY ONCE, and the result is shared.
-app.get('/heavy', async ({ json }) => {
+index_1.app.get('/heavy', async ({ json }) => {
     const result = await heavyTask();
     json(result);
 });
-app.listen(3000, () => {
+index_1.app.start(3000).then(() => {
     console.log('Fusion-enabled server running on http://localhost:3000');
 });

package/dist/examples/rate-limiting.js

@@ -1,17 +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 }) => {
+// 1. Fluent Rate Limiting
+// Limit to 100 requests per 15 minutes
+index_1.app.rateLimit(100, '15m');
+// Alternative: Use presets
+// app.rateLimit('strict'); // 10 req / 15 min
+// app.rateLimit('relaxed'); // 1000 req / 1 hour
+// Alternative: Fluent Builder
+// app.allow(50).per('1m');
+index_1.app.get('/', ({ json }) => {
     json({ status: 'OK', message: 'Request accepted' });
 });
-app.listen(3000, () => {
+index_1.app.start(3000).then(() => {
     console.log('Rate-limited server running on http://localhost:3000');
 });

package/dist/examples/validation.js

@@ -1,8 +1,8 @@
 "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)
+// Initialize Validator
+index_1.app.validate();
 const UserSchema = {
     body: {
         type: 'object',
@@ -13,11 +13,10 @@ const UserSchema = {
         }
     }
 };
-// Apply schema to route
-app.post('/register', { schema: UserSchema }, ({ body, json }) => {
-    // 'body' is already validated and typed here (if using TS with inferred types)
+index_1.app.post('/register', { schema: UserSchema }, ({ body, json }) => {
+    // 'body' is already validated and typed here
     json({ success: true, user: body });
 });
-app.listen(3000, () => {
+index_1.app.start(3000).then(() => {
     console.log('Validation server running on http://localhost:3000');
 });

package/dist/examples/websockets.js

@@ -1,20 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const index_1 = require("../src/index");
-const app = (0, index_1.createHttpApp)();
-app.upgrade('/chat', (ws) => {
+index_1.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}`);
+        index_1.app.websocket.to('general').emit(`Echo: ${msg}`);
     });
     ws.on('close', () => {
         console.log('Client disconnected');
     });
 });
-app.listen(3000, () => {
+index_1.app.start(3000).then(() => {
     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

@@ -1,6 +1,6 @@
 {
     "name": "qhttpx",
-    "version": "1.9.3",
+    "version": "2.0.0",
     "gypfile": false,
     "description": "The Ultra-Fast HTTP Framework for Node.js",
     "main": "dist/src/index.js",
@@ -17,10 +17,7 @@
     },
     "files": [
         "dist",
-        "src/native",
-        "prebuilds",
         "scripts",
-        "binding.gyp",
         "README.md",
         "LICENSE",
         "CHANGELOG.md",
@@ -30,7 +27,6 @@
         "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",
@@ -72,6 +68,7 @@
         "type": "git",
         "url": "https://github.com/Quantam-Open-Source/qhttpx"
     },
+    "homepage": "https://qhttpx.gridrr.com",
     "type": "commonjs",
     "devDependencies": {
         "@types/autocannon": "^7.12.7",
@@ -91,7 +88,6 @@
         "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",
@@ -101,8 +97,7 @@
         "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",
+        "fastify": "^5.7.1",
         "pino": "^10.2.0",
         "pino-pretty": "^13.1.3",
         "quantam-async": "^0.1.1",

package/dist/src/benchmarks/quantam-users.js

@@ -7,8 +7,8 @@ async function run() {
         maxConcurrency: 512,
         requestTimeoutMs: 10000,
     });
-    app.get('/json', (ctx) => {
-        ctx.json({ message: 'hello from qhttpx' });
+    app.get('/json', ({ json }) => {
+        json({ message: 'hello from qhttpx' });
     });
     const { port } = await app.listen(0, '127.0.0.1');
     const url = `http://127.0.0.1:${port}/json`;

package/dist/src/benchmarks/quick-bench.js

@@ -0,0 +1,57 @@
+"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 index_1 = require("../index");
+function runAutocannon(url) {
+    return new Promise((resolve, reject) => {
+        const instance = (0, autocannon_1.default)({
+            url,
+            connections: 100,
+            pipelining: 10,
+            duration: 5, // Shorter duration for quick verification
+        }, (err, result) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            resolve(result);
+        });
+        instance.on('error', (err) => {
+            reject(err);
+        });
+    });
+}
+async function run() {
+    const payloadBuffer = Buffer.from(JSON.stringify({ message: 'hello from qhttpx' }));
+    const app = new index_1.QHTTPX({
+        maxConcurrency: 512,
+        metricsEnabled: false,
+        jsonSerializer: () => payloadBuffer,
+    });
+    app.get('/json', ({ json }) => {
+        json({ message: 'hello from qhttpx' });
+    });
+    const { port } = await app.listen(0, '127.0.0.1');
+    const url = `http://127.0.0.1:${port}/json`;
+    console.log('Running quick benchmark...');
+    const result = await runAutocannon(url);
+    autocannon_1.default.printResult(result);
+    const totalRequests = result.requests.total;
+    const sent = result.requests.sent;
+    const avgRps = result.requests.average.toFixed(0);
+    const p99 = result.latency.p99.toFixed(1);
+    const connections = result.connections;
+    const pipelining = result.pipelining;
+    console.log(`QHTTPX QUICK bench: total=${totalRequests} (sent=${sent}) req, ` +
+        `${avgRps} req/sec, p99=${p99}ms, connections=${connections}, ` +
+        `pipelining=${pipelining}`);
+    await app.close();
+    process.exit(0);
+}
+run().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});