qhttpx 1.8.2 → 1.8.4

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) {
@@ -264,32 +280,38 @@ class QHTTPX {
         const scope = new scope_1.QHTTPXScope(this, options?.prefix);
         await plugin(scope, options);
     }
-    registerRoute(method, path, handlerOrOptions) {
+    registerRoute(method, path, handlerOrOptions, handlerIfOptions) {
         let handler;
         let schema;
         const options = {};
         if (typeof handlerOrOptions === 'function') {
             handler = handlerOrOptions;
         }
-        else {
-            handler = handlerOrOptions.handler;
+        else if (handlerIfOptions) {
+            handler = handlerIfOptions;
             schema = handlerOrOptions.schema;
             options.priority = handlerOrOptions.priority;
         }
+        else {
+            const opts = handlerOrOptions;
+            handler = opts.handler;
+            schema = opts.schema;
+            options.priority = opts.priority;
+        }
         const compiled = this.compileRoutePipeline(handler, schema);
         this.router.register(method, path, compiled, { ...options, schema });
     }
-    get(path, handler) {
-        this.registerRoute('GET', path, handler);
+    get(path, handlerOrOptions, handler) {
+        this.registerRoute('GET', path, handlerOrOptions, handler);
     }
-    post(path, handler) {
-        this.registerRoute('POST', path, handler);
+    post(path, handlerOrOptions, handler) {
+        this.registerRoute('POST', path, handlerOrOptions, handler);
     }
-    put(path, handler) {
-        this.registerRoute('PUT', path, handler);
+    put(path, handlerOrOptions, handler) {
+        this.registerRoute('PUT', path, handlerOrOptions, handler);
     }
-    delete(path, handler) {
-        this.registerRoute('DELETE', path, handler);
+    delete(path, handlerOrOptions, handler) {
+        this.registerRoute('DELETE', path, handlerOrOptions, handler);
     }
     route(path) {
         const register = (method, handler) => {
@@ -386,7 +408,17 @@ class QHTTPX {
         const generator = new generator_1.OpenAPIGenerator(this.router, options);
         return generator.generate();
     }
-    async listen(port, hostname) {
+    async listen(port, hostnameOrCallback, callback) {
+        let hostname;
+        let cb;
+        if (typeof hostnameOrCallback === 'function') {
+            cb = hostnameOrCallback;
+            hostname = undefined;
+        }
+        else {
+            hostname = hostnameOrCallback;
+            cb = callback;
+        }
         if (this.options.database) {
             await this.options.database.connect();
         }
@@ -408,6 +440,8 @@ class QHTTPX {
                 this.router.freeze();
                 void this.runLifecycleHooks(this.onStartHooks);
                 const address = this.server.address();
+                if (cb)
+                    cb();
                 if (address && typeof address === 'object') {
                     resolve({ port: address.port });
                 }
@@ -450,95 +484,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 +602,7 @@ class QHTTPX {
         }
         mutableCtx.state = {};
         mutableCtx.disableAutoEnd = false;
+        mutableCtx.path = url.pathname;
         return ctx;
     }
     releaseContext(ctx) {
@@ -582,6 +620,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 +891,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;
+}

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

@@ -0,0 +1,135 @@
+import { IncomingMessage, ServerResponse } from 'http';
+import { URL } from 'url';
+import type { BufferPool, BufferPoolConfig } from './buffer-pool';
+import type { DatabaseManager } from '../database/manager';
+import type { RouteSchema, Validator } from '../validation/types';
+import type { ViewEngine } from '../views/types';
+import type { RequestFusionOptions } from './fusion';
+export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+export declare enum RoutePriority {
+    CRITICAL = "critical",
+    STANDARD = "standard",
+    BEST_EFFORT = "best-effort"
+}
+export type RouteOptions = {
+    priority?: RoutePriority;
+};
+export declare class HttpError extends Error {
+    status: number;
+    code?: string;
+    details?: unknown;
+    constructor(status: number, message?: string, options?: {
+        code?: string;
+        details?: unknown;
+    });
+}
+export type CookieOptions = {
+    domain?: string;
+    path?: string;
+    expires?: Date;
+    maxAge?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'lax' | 'strict' | 'none';
+};
+export type QHTTPXFile = {
+    filename: string;
+    encoding: string;
+    mimeType: string;
+    data: Buffer;
+    size: number;
+};
+export type QHTTPXContext = {
+    readonly req: IncomingMessage;
+    readonly res: ServerResponse;
+    readonly url: URL;
+    readonly params: Record<string, string>;
+    readonly query: Record<string, string | string[]>;
+    body: unknown;
+    files?: Record<string, QHTTPXFile | QHTTPXFile[]>;
+    readonly cookies: Record<string, string>;
+    state: Record<string, any>;
+    readonly bufferPool: BufferPool;
+    requestId: string | undefined;
+    requestStart: number | undefined;
+    serializer?: (value: unknown) => string;
+    readonly json: (body: unknown, status?: number) => void;
+    readonly send: (body: string | Buffer, status?: number) => void;
+    readonly html: (html: string, status?: number) => void;
+    readonly redirect: (url: string, status?: number) => void;
+    readonly setCookie: (name: string, value: string, options?: CookieOptions) => void;
+    readonly db?: DatabaseManager;
+    readonly call?: (op: string, params: any) => Promise<any>;
+    readonly render: (view: string, locals?: Record<string, any>) => Promise<void>;
+    readonly validate: <T = unknown>(schema: unknown, data?: unknown) => Promise<T>;
+    disableAutoEnd?: boolean;
+    readonly path: string;
+    readonly next?: () => Promise<void>;
+};
+export type QHTTPXOpHandler = (params: any, ctx: QHTTPXContext) => any | Promise<any>;
+export type QHTTPXHandler = (ctx: QHTTPXContext) => void | Promise<void>;
+export type QHTTPXRouteOptions = {
+    schema?: RouteSchema | Record<string, any>;
+    handler: QHTTPXHandler;
+    priority?: RoutePriority;
+};
+export type QHTTPXRouteConfig = Omit<QHTTPXRouteOptions, 'handler'>;
+export type QHTTPXMiddleware = (ctx: QHTTPXContext, next: () => Promise<void>) => void | Promise<void>;
+export type QHTTPXErrorContext = QHTTPXContext & {
+    error: unknown;
+};
+export type QHTTPXErrorHandler = (ctx: QHTTPXErrorContext) => void | Promise<void>;
+export type QHTTPXNotFoundHandler = (ctx: QHTTPXContext) => void | Promise<void>;
+export type QHTTPXMethodNotAllowedHandler = (ctx: QHTTPXContext, allowedMethods: HTTPMethod[]) => void | Promise<void>;
+export type QHTTPXTraceEvent = {
+    type: 'request_start';
+    method: string;
+    path: string;
+    requestId?: string;
+} | {
+    type: 'request_end';
+    method: string;
+    path: string;
+    statusCode: number;
+    durationMs: number;
+    requestId?: string;
+};
+export type QHTTPXTracer = (event: QHTTPXTraceEvent) => void | Promise<void>;
+export type QHTTPXTaskHandler = (payload: unknown) => void | Promise<void>;
+export type QHTTPXTaskOptions = {
+    maxRetries?: number;
+    backoffMs?: number;
+};
+export type PerformanceMode = 'balanced' | 'ultra';
+export type QHTTPXOptions = {
+    name?: string;
+    workers?: 'auto' | number;
+    maxConcurrency?: number;
+    requestTimeoutMs?: number;
+    maxMemoryBytes?: number;
+    maxBodyBytes?: number;
+    keepAliveTimeoutMs?: number;
+    headersTimeoutMs?: number;
+    metricsEnabled?: boolean;
+    jsonSerializer?: (value: unknown) => string | Buffer;
+    bufferPoolConfig?: BufferPoolConfig;
+    errorHandler?: QHTTPXErrorHandler;
+    notFoundHandler?: QHTTPXNotFoundHandler;
+    methodNotAllowedHandler?: QHTTPXMethodNotAllowedHandler;
+    tracer?: QHTTPXTracer;
+    performanceMode?: PerformanceMode;
+    database?: DatabaseManager;
+    enableBatching?: boolean | {
+        endpoint: string;
+    };
+    validator?: Validator;
+    enableRequestFusion?: boolean | RequestFusionOptions;
+    viewEngine?: ViewEngine;
+    viewsPath?: string;
+};
+export type QHTTPXPlugin<Options = any> = (app: any, // We use 'any' here to avoid circular dependency with QHTTPX class, or we could use an interface
+options: Options) => void | Promise<void>;
+export type QHTTPXPluginOptions = {
+    prefix?: string;
+    [key: string]: any;
+};

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

@@ -0,0 +1,25 @@
+import { IncomingMessage } from 'http';
+import { Duplex } from 'stream';
+import { WebSocket } from 'ws';
+export interface QHTTPXWebSocket extends WebSocket {
+    join(room: string): void;
+    leave(room: string): void;
+    id: string;
+}
+export type WSHandler = (ws: QHTTPXWebSocket, req: IncomingMessage) => void;
+export declare class WebSocketManager {
+    private readonly requestIdGenerator;
+    private readonly wss;
+    private readonly handlers;
+    private readonly rooms;
+    constructor(requestIdGenerator: () => string);
+    register(path: string, handler: WSHandler): void;
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): Promise<void>;
+    private join;
+    private leave;
+    private leaveAll;
+    to(room: string): {
+        emit: (data: unknown) => void;
+    };
+    broadcast(data: unknown): void;
+}

package/dist/src/core/worker-queue.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Lock-free (or lock-minimal) work queue for per-worker task distribution.
+ * Uses a simple ring buffer for high throughput.
+ */
+export type WorkItem<T> = {
+    id: number;
+    task: T;
+    priority: number;
+};
+export declare class WorkerQueue<T> {
+    private readonly capacity;
+    private readonly buffer;
+    private writeIndex;
+    private readIndex;
+    private size;
+    constructor(capacity?: number);
+    /**
+     * Enqueue a work item. Returns true if successful, false if queue is full.
+     */
+    enqueue(item: WorkItem<T>): boolean;
+    /**
+     * Dequeue a work item. Returns undefined if queue is empty.
+     */
+    dequeue(): WorkItem<T> | undefined;
+    /**
+     * Peek at the next item without removing it.
+     */
+    peek(): WorkItem<T> | undefined;
+    /**
+     * Check if the queue is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Get the current size of the queue.
+     */
+    getSize(): number;
+    /**
+     * Get the capacity of the queue.
+     */
+    getCapacity(): number;
+}

package/dist/src/database/adapters/memory.d.ts

@@ -0,0 +1,21 @@
+import { DatabaseAdapter, DatabaseConfig } from '../types';
+export declare class MemoryAdapter implements DatabaseAdapter {
+    private config;
+    private connected;
+    private collections;
+    constructor(config: DatabaseConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /**
+      * Execute a query against the in-memory database
+      * @param query Object specifying collection, action, and parameters
+      * @example
+      * // Find
+      * query({ collection: 'users', action: 'find', filter: { id: 1 } })
+      * // Insert
+      * query({ collection: 'users', action: 'insert', data: { name: 'Alice' } })
+      */
+    query<T = any>(query: any): Promise<T>;
+    private matches;
+}

package/dist/src/database/adapters/mongo.d.ts

@@ -0,0 +1,11 @@
+import { DatabaseAdapter, DatabaseConfig } from '../types';
+export declare class MongoAdapter implements DatabaseAdapter {
+    private client;
+    private db;
+    private config;
+    constructor(config: DatabaseConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    query<T = any>(query: string | object, params?: any[]): Promise<T>;
+    isConnected(): boolean;
+}

package/dist/src/database/adapters/postgres.d.ts

@@ -0,0 +1,10 @@
+import { DatabaseAdapter, DatabaseConfig } from '../types';
+export declare class PostgresAdapter implements DatabaseAdapter {
+    private pool;
+    private config;
+    constructor(config: DatabaseConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    query<T = any>(sql: string, params?: any[]): Promise<T>;
+    isConnected(): boolean;
+}

package/dist/src/database/adapters/sqlite.d.ts

@@ -0,0 +1,10 @@
+import { DatabaseAdapter, DatabaseConfig } from '../types';
+export declare class SQLiteAdapter implements DatabaseAdapter {
+    private db;
+    private config;
+    constructor(config: DatabaseConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    query<T = any>(sql: string, params?: any[]): Promise<T>;
+    isConnected(): boolean;
+}

package/dist/src/database/coalescer.d.ts

@@ -0,0 +1,14 @@
+import { DatabaseAdapter } from './types';
+export declare class QueryCoalescer<T = unknown> {
+    private pending;
+    private timeout;
+    private readonly adapter;
+    constructor(adapter: DatabaseAdapter);
+    /**
+      * Intercepts a query and attempts to coalesce it with others.
+      * Only supports simple queries of the form "SELECT ... WHERE col = ?" for now.
+      */
+    query(query: string, params?: unknown[]): Promise<T>;
+    private scheduleFlush;
+    private flush;
+}