qhttpx 1.8.1 → 1.8.3

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,86 @@
+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;
+    post(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+    put(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
+    delete(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): 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, hostname?: string): 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;
+}

package/dist/src/core/server.js

@@ -111,6 +111,18 @@ class QHTTPX {
     set405Handler(handler) {
         this.setMethodNotAllowedHandler(handler);
     }
+    /**
+     * Alias for setErrorHandler
+     */
+    onError(handler) {
+        this.setErrorHandler(handler);
+    }
+    /**
+     * Alias for setNotFoundHandler
+     */
+    notFound(handler) {
+        this.setNotFoundHandler(handler);
+    }
     onStart(hook) {
         this.onStartHooks.push(hook);
     }
@@ -239,12 +251,16 @@ class QHTTPX {
             const middleware = middlewares[i];
             const next = pipeline;
             pipeline = (ctx) => {
-                return middleware(ctx, async () => {
+                const nextFn = async () => {
                     const result = next(ctx);
                     if (result && typeof result.then === 'function') {
                         await result;
                     }
-                });
+                };
+                // Attach next to ctx for destructuring support
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                ctx.next = nextFn;
+                return middleware(ctx, nextFn);
             };
         }
         if (stringifier) {
@@ -450,95 +466,98 @@ class QHTTPX {
             requestId: '',
             requestStart: 0,
             serializer: null,
-            json(payload, status = 200) {
-                const res = this.res;
-                if (!res.headersSent) {
-                    res.statusCode = status;
-                    res.setHeader('content-type', 'application/json; charset=utf-8');
-                }
-                let body;
-                if (this.serializer) {
-                    body = this.serializer(payload);
-                }
-                else if (useFastStringify) {
-                    body = (0, serializer_1.fastJsonStringify)(payload);
-                }
-                else if (jsonSerializer) {
-                    body = jsonSerializer(payload);
-                }
-                else {
-                    body = JSON.stringify(payload);
-                }
-                res.end(body);
-            },
-            send(payload, status = 200) {
-                const res = this.res;
-                if (!res.headersSent) {
-                    res.statusCode = status;
-                }
-                res.end(payload);
-            },
-            html(payload, status = 200) {
-                const res = this.res;
-                if (!res.headersSent) {
-                    res.statusCode = status;
-                    res.setHeader('content-type', 'text/html; charset=utf-8');
-                }
-                res.end(payload);
-            },
-            redirect(url, status = 302) {
-                const res = this.res;
-                if (!res.headersSent) {
-                    res.statusCode = status;
-                    res.setHeader('Location', url);
-                }
-                res.end();
-            },
-            setCookie(name, value, options) {
-                const res = this.res;
-                const serialized = (0, cookies_1.serializeCookie)(name, value, options);
-                let existing = res.getHeader('Set-Cookie');
-                if (Array.isArray(existing)) {
-                    existing.push(serialized);
-                    res.setHeader('Set-Cookie', existing);
-                }
-                else if (existing) {
-                    res.setHeader('Set-Cookie', [existing, serialized]);
-                }
-                else {
-                    res.setHeader('Set-Cookie', serialized);
-                }
-            },
+            path: '',
+            error: undefined,
             db: this.options.database,
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            render: async (view, locals) => {
-                const engine = this.options.viewEngine;
-                if (!engine) {
-                    throw new Error('No view engine registered');
-                }
-                const viewsPath = this.options.viewsPath || process.cwd();
-                const fullPath = path_1.default.resolve(viewsPath, view);
-                const html = await engine.render(fullPath, locals || {});
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                const res = ctx.res;
-                if (!res.headersSent) {
-                    res.statusCode = 200;
-                    res.setHeader('content-type', 'text/html; charset=utf-8');
-                }
-                res.end(html);
-            },
-            validate: async (schema, data) => {
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                const target = data ?? ctx.body;
-                const result = await this.validator.validate(schema, target);
-                if (result.success) {
-                    return result.data;
-                }
-                throw new types_1.HttpError(400, 'Validation Error', {
-                    code: 'VALIDATION_ERROR',
-                    details: result.error,
-                });
-            },
+        };
+        // Helper to get response object from closure-captured ctx
+        // We use arrow functions to ensure they don't depend on 'this' context at call site
+        // enabling destructuring like: ({ json }) => json(...)
+        ctx.json = (payload, status = 200) => {
+            const res = ctx.res;
+            if (!res.headersSent) {
+                res.statusCode = status;
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+            }
+            let body;
+            if (ctx.serializer) {
+                body = ctx.serializer(payload);
+            }
+            else if (useFastStringify) {
+                body = (0, serializer_1.fastJsonStringify)(payload);
+            }
+            else if (jsonSerializer) {
+                body = jsonSerializer(payload);
+            }
+            else {
+                body = JSON.stringify(payload);
+            }
+            res.end(body);
+        };
+        ctx.send = (payload, status = 200) => {
+            const res = ctx.res;
+            if (!res.headersSent) {
+                res.statusCode = status;
+            }
+            res.end(payload);
+        };
+        ctx.html = (payload, status = 200) => {
+            const res = ctx.res;
+            if (!res.headersSent) {
+                res.statusCode = status;
+                res.setHeader('content-type', 'text/html; charset=utf-8');
+            }
+            res.end(payload);
+        };
+        ctx.redirect = (url, status = 302) => {
+            const res = ctx.res;
+            if (!res.headersSent) {
+                res.statusCode = status;
+                res.setHeader('Location', url);
+            }
+            res.end();
+        };
+        ctx.setCookie = (name, value, options) => {
+            const res = ctx.res;
+            const serialized = (0, cookies_1.serializeCookie)(name, value, options);
+            let existing = res.getHeader('Set-Cookie');
+            if (Array.isArray(existing)) {
+                existing.push(serialized);
+                res.setHeader('Set-Cookie', existing);
+            }
+            else if (existing) {
+                res.setHeader('Set-Cookie', [existing, serialized]);
+            }
+            else {
+                res.setHeader('Set-Cookie', serialized);
+            }
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ctx.render = async (view, locals) => {
+            const engine = this.options.viewEngine;
+            if (!engine) {
+                throw new Error('No view engine registered');
+            }
+            const viewsPath = this.options.viewsPath || process.cwd();
+            const fullPath = path_1.default.resolve(viewsPath, view);
+            const html = await engine.render(fullPath, locals || {});
+            const res = ctx.res;
+            if (!res.headersSent) {
+                res.statusCode = 200;
+                res.setHeader('content-type', 'text/html; charset=utf-8');
+            }
+            res.end(html);
+        };
+        ctx.validate = async (schema, data) => {
+            const target = data ?? ctx.body;
+            const result = await this.validator.validate(schema, target);
+            if (result.success) {
+                return result.data;
+            }
+            throw new types_1.HttpError(400, 'Validation Error', {
+                code: 'VALIDATION_ERROR',
+                details: result.error,
+            });
         };
         return ctx;
     }
@@ -565,6 +584,7 @@ class QHTTPX {
         }
         mutableCtx.state = {};
         mutableCtx.disableAutoEnd = false;
+        mutableCtx.path = url.pathname;
         return ctx;
     }
     releaseContext(ctx) {
@@ -582,6 +602,8 @@ class QHTTPX {
         mutableCtx.serializer = null;
         mutableCtx.cookies = null;
         mutableCtx.state = null;
+        mutableCtx.path = '';
+        mutableCtx.error = undefined;
         // render method is static per context instance creation (closure over options), 
         // but good to keep it consistent.
         // Wait, 'render' is defined in 'createContext' and depends on 'this.options'.
@@ -851,23 +873,29 @@ class QHTTPX {
             }
         }
     }
-    async handleError(err, ctx) {
+    handleError(err, ctx) {
         const res = ctx.res;
         if (res.writableEnded) {
             return;
         }
         if (this.errorHandler) {
             try {
-                const result = this.errorHandler(err, ctx);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const errorContext = ctx;
+                errorContext.error = err;
+                const result = this.errorHandler(errorContext);
                 if (result && typeof result.then === 'function') {
-                    await result;
+                    return result.then(() => {
+                        // Ensure response is sent if handler didn't
+                    });
                 }
                 if (res.writableEnded) {
                     return;
                 }
             }
-            catch {
+            catch (handlerErr) {
                 // Fall through to default error handling below
+                console.error('Error in error handler:', handlerErr);
             }
         }
         if (res.writableEnded) {

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

@@ -0,0 +1,15 @@
+import { Readable } from 'stream';
+import { QHTTPXContext } from './types';
+export type SseOptions = {
+    retryMs?: number;
+};
+export type SseStream = {
+    send: (data: unknown, event?: string) => void;
+    close: () => void;
+};
+export declare function createSseStream(ctx: QHTTPXContext, options?: SseOptions): SseStream;
+export type StreamOptions = {
+    contentType?: string;
+    status?: number;
+};
+export declare function sendStream(ctx: QHTTPXContext, stream: Readable, options?: StreamOptions): Promise<void>;

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

@@ -0,0 +1,29 @@
+import { Scheduler } from './scheduler';
+export type QHTTPXTaskHandler = (payload: unknown) => void | Promise<void>;
+export type QHTTPXTaskOptions = {
+    maxRetries?: number;
+    backoffMs?: number;
+};
+export type TaskMetrics = {
+    registeredTasks: number;
+    totalEnqueued: number;
+    totalCompleted: number;
+    totalFailed: number;
+    totalOverloaded: number;
+    totalRetried: number;
+};
+export declare class TaskEngine {
+    private readonly scheduler;
+    private readonly tasks;
+    private registeredTasksCount;
+    private totalEnqueued;
+    private totalCompleted;
+    private totalFailed;
+    private totalOverloaded;
+    private totalRetried;
+    constructor(scheduler: Scheduler);
+    register(name: string, handler: QHTTPXTaskHandler, options?: QHTTPXTaskOptions): void;
+    enqueue(name: string, payload: unknown): Promise<void>;
+    getMetrics(): TaskMetrics;
+    private executeWithRetry;
+}