qhttpx 1.8.0

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/quantam-users.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const quantam_async_1 = require("quantam-async");
+const index_1 = require("../index");
+async function run() {
+    const app = new index_1.QHTTPX({
+        maxConcurrency: 512,
+        requestTimeoutMs: 10000,
+    });
+    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`;
+    const requestsPerUser = 10;
+    const userCount = 10000;
+    const maxConcurrentUsers = 1000;
+    const flow = (0, quantam_async_1.quantam)()
+        .name('user-flow')
+        .step(async (userId) => {
+        for (let i = 0; i < requestsPerUser; i += 1) {
+            const response = await fetch(url);
+            if (!response.ok) {
+                throw new Error(`user ${userId} request ${i} failed with status ${response.status}`);
+            }
+            await response.text();
+        }
+        return userId;
+    })
+        .retry(3, 50)
+        .timeout(30000);
+    const inputs = [];
+    for (let i = 0; i < userCount; i += 1) {
+        inputs.push(i);
+    }
+    const start = Date.now();
+    try {
+        await flow.runMany(inputs, {
+            concurrency: maxConcurrentUsers,
+        });
+    }
+    catch (err) {
+        console.error('Quantam runMany error', err);
+    }
+    const durationSec = (Date.now() - start) / 1000;
+    const totalRequests = userCount * requestsPerUser;
+    const rps = totalRequests / durationSec;
+    console.log(`Quantam bench: users=${userCount}, requestsPerUser=${requestsPerUser}, ` +
+        `totalRequests=${totalRequests}, duration=${durationSec.toFixed(2)}s, rps=${rps.toFixed(0)}, concurrency=${maxConcurrentUsers}`);
+    await app.close();
+    process.exit(0);
+}
+run().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/src/benchmarks/simple-json.js

@@ -0,0 +1,58 @@
+"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,
+            amount: 10000,
+            connections: 10000,
+            pipelining: 1,
+            duration: 10,
+        }, (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', (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`;
+    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;
+    // Summary line that shows up clearly in CI/dev logs
+    console.log(`QHTTPX 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);
+});

package/dist/src/benchmarks/ultra-mode.js

@@ -0,0 +1,122 @@
+"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 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 startQHTTPXBalanced() {
+    const payloadBuffer = Buffer.from(JSON.stringify({ message: 'hello from qhttpx' }));
+    const app = new index_1.QHTTPX({
+        maxConcurrency: 1024,
+        metricsEnabled: false,
+        performanceMode: 'balanced',
+        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 startQHTTPXUltra() {
+    const payloadBuffer = Buffer.from(JSON.stringify({ message: 'hello from qhttpx ultra' }));
+    const app = new index_1.QHTTPX({
+        maxConcurrency: 1024,
+        performanceMode: 'ultra',
+        jsonSerializer: () => payloadBuffer,
+    });
+    app.get('/json', (ctx) => {
+        ctx.json({ message: 'hello from qhttpx ultra' });
+    });
+    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 run() {
+    const results = [];
+    console.log('=== QHTTPX Balanced Mode ===');
+    const balanced = await startQHTTPXBalanced();
+    try {
+        const r = await runAutocannon('QHTTPX-Balanced', balanced.url);
+        results.push(r);
+    }
+    finally {
+        await balanced.app.close();
+    }
+    console.log('\n=== QHTTPX Ultra Mode ===');
+    const ultra = await startQHTTPXUltra();
+    try {
+        const r = await runAutocannon('QHTTPX-Ultra', ultra.url);
+        results.push(r);
+    }
+    finally {
+        await ultra.app.close();
+    }
+    console.log('\n=== Fastify Baseline ===');
+    const fast = await startFastify();
+    try {
+        const r = await runAutocannon('Fastify', fast.url);
+        results.push(r);
+    }
+    finally {
+        await fast.app.close();
+    }
+    console.log('\n=== Summary ===');
+    for (const r of results) {
+        console.log(`${r.name}: ${r.rps.toFixed(0)} req/sec, p99=${r.p99.toFixed(1)}ms, total=${r.total}`);
+    }
+    // Calculate improvement
+    const balanced_rps = results[0]?.rps || 0;
+    const ultra_rps = results[1]?.rps || 0;
+    const fastify_rps = results[2]?.rps || 0;
+    if (ultra_rps > 0 && balanced_rps > 0) {
+        const improvement = ((ultra_rps - balanced_rps) / balanced_rps * 100).toFixed(1);
+        console.log(`\nUltra vs Balanced improvement: ${improvement}%`);
+    }
+    if (ultra_rps > 0 && fastify_rps > 0) {
+        const ratio = (ultra_rps / fastify_rps).toFixed(2);
+        console.log(`Ultra vs Fastify ratio: ${ratio}x`);
+    }
+    process.exit(0);
+}
+run().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/src/cli/index.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const cluster_1 = __importDefault(require("cluster"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const args = process.argv.slice(2);
+const command = args[0];
+if (!command) {
+    printHelp();
+    process.exit(1);
+}
+const targetFile = args[1];
+if (command === 'start') {
+    if (!targetFile) {
+        console.error('Error: Please provide an entry file (e.g., qhttpx start dist/index.js)');
+        process.exit(1);
+    }
+    runStart(targetFile);
+}
+else if (command === 'dev') {
+    if (!targetFile) {
+        console.error('Error: Please provide an entry file (e.g., qhttpx dev src/index.ts)');
+        process.exit(1);
+    }
+    runDev(targetFile);
+}
+else if (command === 'new') {
+    if (!targetFile) {
+        console.error('Error: Please provide a project name (e.g., qhttpx new my-app)');
+        process.exit(1);
+    }
+    runNew(targetFile);
+}
+else {
+    console.error(`Unknown command: ${command}`);
+    printHelp();
+    process.exit(1);
+}
+function printHelp() {
+    console.log('Usage: qhttpx <command> [options]');
+    console.log('Commands:');
+    console.log('  start <file>   Run in production cluster mode (Node.js)');
+    console.log('  dev <file>     Run in development mode with hot reload (tsx)');
+    console.log('  new <name>     Create a new QHTTPX project');
+}
+function runStart(entry) {
+    const absoluteEntry = path_1.default.resolve(process.cwd(), entry);
+    if (cluster_1.default.isPrimary) {
+        const numCPUs = os_1.default.cpus().length;
+        console.log(`[QCLI] 🚀 Starting Cluster Mode`);
+        console.log(`[QCLI] 📂 Entry: ${absoluteEntry}`);
+        console.log(`[QCLI] 💻 Workers: ${numCPUs}`);
+        for (let i = 0; i < numCPUs; i++) {
+            cluster_1.default.fork();
+        }
+        cluster_1.default.on('exit', (worker) => {
+            console.log(`[QCLI] 💀 Worker ${worker.process.pid} died. Restarting...`);
+            cluster_1.default.fork();
+        });
+    }
+    else {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            require(absoluteEntry);
+        }
+        catch (err) {
+            console.error(`[QCLI] Failed to load entry file: ${absoluteEntry}`);
+            console.error(err);
+            process.exit(1);
+        }
+    }
+}
+function runDev(entry) {
+    const absoluteEntry = path_1.default.resolve(process.cwd(), entry);
+    console.log(`[QCLI] 🛠️  Starting Dev Mode`);
+    console.log(`[QCLI] 📂 Entry: ${absoluteEntry}`);
+    let child = null;
+    const startChild = () => {
+        // Use tsx for dev execution
+        child = (0, child_process_1.spawn)('npx', ['tsx', absoluteEntry], {
+            stdio: 'inherit',
+            shell: true,
+            cwd: process.cwd()
+        });
+        child.on('close', (code) => {
+            if (code !== 0 && code !== null) {
+                console.log(`[QCLI] App crashed (code ${code}). Waiting for changes...`);
+            }
+        });
+    };
+    const restartChild = () => {
+        if (child) {
+            console.log('[QCLI] 🔄 File changed. Restarting...');
+            // On Windows, killing a shell-spawned process is tricky.
+            // But 'child.kill()' usually works for the handle.
+            // For deeper tree killing, we might need a library, but let's try standard kill.
+            child.kill();
+            child = null;
+        }
+        startChild();
+    };
+    startChild();
+    // Watcher
+    let debounceTimer;
+    const watchDir = path_1.default.dirname(absoluteEntry); // Watch the directory of the entry file (usually src)
+    console.log(`[QCLI] 👀 Watching: ${watchDir}`);
+    // Recursive watch is platform dependent, but 'recursive: true' works on Windows/macOS
+    try {
+        fs_1.default.watch(watchDir, { recursive: true }, (eventType, filename) => {
+            if (!filename)
+                return;
+            // Ignore node_modules and .git
+            if (filename.includes('node_modules') || filename.includes('.git'))
+                return;
+            clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(() => {
+                restartChild();
+            }, 200); // 200ms debounce
+        });
+    }
+    catch {
+        console.warn('[QCLI] Recursive watch not supported or failed. Falling back to simple watch.');
+        // Fallback or just fail gracefully
+    }
+}
+function runNew(projectName) {
+    const projectDir = path_1.default.resolve(process.cwd(), projectName);
+    if (fs_1.default.existsSync(projectDir)) {
+        console.error(`Error: Directory ${projectName} already exists.`);
+        process.exit(1);
+    }
+    console.log(`[QCLI] ✨ Creating new QHTTPX project in ${projectName}...`);
+    fs_1.default.mkdirSync(projectDir);
+    fs_1.default.mkdirSync(path_1.default.join(projectDir, 'src'));
+    // package.json
+    const pkgJson = {
+        name: projectName,
+        version: '0.0.1',
+        scripts: {
+            dev: 'qhttpx dev src/index.ts',
+            start: 'qhttpx start dist/index.js',
+            build: 'tsc'
+        },
+        dependencies: {
+            'qhttpx': '^1.0.0'
+        },
+        devDependencies: {
+            'typescript': '^5.0.0',
+            '@types/node': '^20.0.0',
+            'tsx': '^4.0.0'
+        }
+    };
+    fs_1.default.writeFileSync(path_1.default.join(projectDir, 'package.json'), JSON.stringify(pkgJson, null, 2));
+    // tsconfig.json
+    const tsConfig = {
+        compilerOptions: {
+            target: 'ES2020',
+            module: 'commonjs',
+            rootDir: 'src',
+            outDir: 'dist',
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            forceConsistentCasingInFileNames: true
+        },
+        include: ['src']
+    };
+    fs_1.default.writeFileSync(path_1.default.join(projectDir, 'tsconfig.json'), JSON.stringify(tsConfig, null, 2));
+    // src/index.ts
+    const indexTs = `import { createHttpApp } from 'qhttpx';
+
+const app = createHttpApp();
+
+app.get('/', (ctx) => {
+  ctx.json({ message: 'Hello from QHTTPX!' });
+});
+
+app.listen(3000).then(({ port }) => {
+  console.log(\`Server running on port \${port}\`);
+});
+`;
+    fs_1.default.writeFileSync(path_1.default.join(projectDir, 'src', 'index.ts'), indexTs);
+    // .gitignore
+    const gitignore = `node_modules
+dist
+.env
+`;
+    fs_1.default.writeFileSync(path_1.default.join(projectDir, '.gitignore'), gitignore);
+    console.log(`[QCLI] ✅ Project created successfully!`);
+    console.log(`\nNext steps:`);
+    console.log(`  cd ${projectName}`);
+    console.log(`  npm install`);
+    console.log(`  npm run dev`);
+}

package/dist/src/client/index.js

@@ -0,0 +1,72 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-unsafe-function-type */
+// RPC Client for QHTTPX
+// Allows end-to-end type safety similar to Hono's 'hc' or Elysia's 'eden'
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hc = hc;
+// Proxy-based client generator
+function hc(baseUrl, options = {}) {
+    const handler = {
+        get(target, prop, receiver) {
+            if (typeof prop !== 'string')
+                return Reflect.get(target, prop, receiver);
+            // If it's a method call like .$get()
+            if (prop.startsWith('$')) {
+                const method = prop.slice(1).toUpperCase();
+                return async (args = {}) => {
+                    let url = baseUrl;
+                    const path = target.__path || '';
+                    // Replace params in path :id
+                    let finalPath = path;
+                    if (args.param) {
+                        Object.entries(args.param).forEach(([key, value]) => {
+                            finalPath = finalPath.replace(`:${key}`, String(value));
+                        });
+                    }
+                    url += finalPath;
+                    // Append query params
+                    if (args.query) {
+                        const searchParams = new URLSearchParams();
+                        Object.entries(args.query).forEach(([key, value]) => {
+                            searchParams.append(key, String(value));
+                        });
+                        url += `?${searchParams.toString()}`;
+                    }
+                    const fetchOptions = {
+                        ...options,
+                        method,
+                        headers: {
+                            ...options.headers,
+                            ...(args.header || {}),
+                            ...(args.json ? { 'Content-Type': 'application/json' } : {}),
+                        },
+                    };
+                    if (args.json) {
+                        fetchOptions.body = JSON.stringify(args.json);
+                    }
+                    else if (args.form) {
+                        // Handle FormData
+                        fetchOptions.body = args.form;
+                    }
+                    const res = await fetch(url, fetchOptions);
+                    // Return a wrapper that allows typed access
+                    return {
+                        ok: res.ok,
+                        status: res.status,
+                        statusText: res.statusText,
+                        headers: res.headers,
+                        json: () => res.json(),
+                        text: () => res.text(),
+                        blob: () => res.blob(),
+                    };
+                };
+            }
+            // It's a path segment
+            const newPath = (target.__path || '') + '/' + prop;
+            const proxy = new Proxy({ __path: newPath }, handler);
+            return proxy;
+        }
+    };
+    return new Proxy({ __path: '' }, handler);
+}