QHttpX is a high-performance HTTP framework for Node.js. Minimal API. Maximum performance. Built-in features like Request Fusion, WebSockets, and rate limiting.

🚀 Why QHTTPX?

Most Node.js frameworks rely on the event loop blindly. QHTTPX introduces a Cooperative Scheduler and Request Fusion Engine to take control.

⚡ The "Quantum" Difference

| Feature | Traditional Frameworks | QHTTPX | |---------|------------------------|--------| | Architecture | Call Stack (Blocking risk) | Async Scheduler (Non-blocking) | | Simultaneous Requests | Handled individually (N executions) | Request Fusion (1 execution broadcast to N) | | Rate Limiting | Middleware (CPU heavy) | Aegis Engine (Zero-overhead Token Bucket) | | Routing | Regex / Linear Scan | Radix Tree (O(1) lookup) | | Streaming | Basic Pipe | Smart Streams (Backpressure-aware) |

🏆 Feature Comparison

| Feature | QHTTPX | Fastify | Express | Hono | | :--- | :---: | :---: | :---: | :---: | | Core Runtime | ⚡ Pure TypeScript | JS | JS | JS | | Request Fusion | ✅ Native | ❌ | ❌ | ❌ | | DDoS Protection | ✅ Built-in (Aegis) | ❌ | ❌ | ❌ | | JSON Serialization | ✅ Optimized Fast-Path | Schema-based | Slow | Slow | | Concurrency Model | ✅ Async Scheduler | Event Loop | Event Loop | Event Loop | | Rate Limiting | ✅ Zero-Overhead | Plugin | Middleware | Middleware | | Routing Algorithm | ✅ Optimized Radix | Radix Tree | Linear/Regex | RegExp/Trie | | WebSocket | ✅ Built-in Pub/Sub | Plugin | Plugin | Helper | | Multipart Uploads | ✅ Native | Plugin | Middleware | Plugin | | 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

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

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

import { app } from 'qhttpx';

app.get('/hello', ({ query, setHeader }) => {
  const name = query.name || 'World';
  setHeader('X-Powered-By', 'QHTTPX');
  return { message: `Hello ${name}` };
});

app.start(3000);

✨ Key Features

🛡️ Aegis Protection System

Built-in DDoS protection and Rate Limiting that runs before your business logic.

• Token Bucket Algorithm: Smooth traffic shaping.
• Dual-Layer Storage: Memory (L1) + Redis (L2) ready.
• Smart Headers: Automatic Retry-After and X-RateLimit-*.

⚛️ Request Fusion (Layer 2 Coalescing)

The only framework that automatically collapses simultaneous duplicate requests.

• Scenario: 1,000 users request /api/trending at the exact same millisecond.
• Result: QHTTPX executes the handler ONCE and broadcasts the result to all 1,000 users.
• Impact: Database load drops by 99.9%.

🔌 Full-Stack Ecosystem

Everything you need, built-in but modular.

• WebSockets: Real-time channels with "Rooms" support.
• SSE: Server-Sent Events helper createSSE().
• Views: Server-side rendering (EJS, Pug, etc.).
• Static Files: Range requests (Video streaming), ETag caching.
• Multipart: Native file upload handling.

📚 Documentation

New to QHttpX? Start here:

• API Reference - Complete API documentation with examples
• Security Guide - Production security best practices
• Production Deployment - Deploy to VPS, Docker, or Kubernetes
• Migration Guide - Migrate from v1.9.4 to v2.0+

📦 Installation

npm install qhttpx

⚡ Quick Start

1. The Modern Way (TypeScript + tsx) - Recommended

Best for development and production with modern tooling.

Option A: Scaffolding (Fastest)

npm create qhttpx@latest my-app
cd my-app
npm install
npm run dev

Option B: Manual Setup

npm install qhttpx tsx

src/index.ts

import { app } from 'qhttpx';

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

2. The Classic Way (JavaScript + CommonJS)

For legacy environments or simple scripts.

npm install qhttpx

index.js

const { app } = require('qhttpx');

app.get('/', () => ({ msg: 'Works!' }));
app.start(3000).then(() => console.log('Running on http://localhost:3000'));

Run with: node index.js

3. The Fluent Way (Advanced Configuration)

Use the chainable API to configure advanced features like Request Fusion, Metrics, and Body Limits.

import { app } from 'qhttpx';

app.fusion(true)          // Enable Request Coalescing
   .metrics(true)         // Enable Prometheus-style metrics
   .bodyLimit(1024 * 1024)// Set 1MB body limit
   .security({ cors: true });

app.get('/heavy-compute', async () => {
  // If 1000 users hit this at once, it executes ONLY ONCE
  return await db.query('SELECT * FROM heavy_table');
});

app.start(3000);

📚 Documentation

Detailed guides for every feature of QHTTPX:

• Routing: Radix tree, parameters, and groups.
• Middleware: Global and route-level hooks.
• Error Handling: Standard exceptions and global handlers.
• Aegis Rate Limiter: DDoS protection and traffic shaping.
• Request Fusion: "Thundering Herd" protection engine.
• WebSockets: Real-time Pub/Sub and Rooms.
• Static Files: Streaming, Range requests, and Caching.
• Ecosystem Integration: Auth, Database, and Validation patterns.

🤝 Ecosystem Compatibility

QHTTPX is an Open Runtime. It works seamlessly with standard tools:

• Databases: Prisma, Drizzle, TypeORM, Mongoose
• Auth: Jose (JWT), Passport (via adapter)
• Validation: Zod, Valibot
• Logging: Pino (Built-in)

👥 Team

QHTTPX is developed and maintained by Quantam Open Source.

Lead Developer

Byron Kennedy Pfukwa
Creator & Core Maintainer

Socials

Follow us for updates:

• QHTTPX (X): @qhttpx
• Open Quantam (X): @openquantam

📜 License

MIT © Quantam Open Source