qhttpx 2.1.0 → 2.3.1

package/dist/index.d.ts

@@ -0,0 +1,433 @@
+interface RequestContext {
+    /** Unique Request ID (UUID v7) */
+    id: string;
+    method: string;
+    path: string;
+    status(code: number): this;
+    readonly statusCode: number;
+    send(data: any): void;
+    html(content: string): void;
+    req: {
+        json<T = any>(): T;
+        text(): string;
+        param(key: string): string;
+        query(key: string): string | undefined;
+        queries(key: string): string[] | undefined;
+        header(key: string): string | undefined;
+    };
+    query: Record<string, string | string[]>;
+    params: Record<string, string>;
+    json<T = any>(data?: any, status?: number): T | void;
+    text(): string;
+    /** High-performance parsed URL */
+    url: URL;
+    /** Read-only headers (zero-copy view) */
+    headers: ReadonlyMap<string, string>;
+    /** Environment variables (injected) */
+    env?: EnvContext;
+    /** Database Access Layer */
+    db?: DatabaseContext;
+    /** Performance metrics for this request */
+    perf?: RequestMetrics;
+    snapshot(): RequestSnapshot;
+}
+interface RequestSnapshot {
+    id: string;
+    method: string;
+    url: string;
+    path: string;
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    headers: Record<string, string>;
+    body: any;
+    env?: EnvContext;
+    perf?: RequestMetrics;
+}
+interface RequestMetrics {
+    startTime: number;
+    dbDuration: number;
+    parseDuration: number;
+    allocations: number;
+}
+interface EnvContext {
+    [key: string]: string | number | boolean;
+}
+interface DatabaseContext {
+    query(sql: string, ttl?: number): Promise<string>;
+    queryWithParams(sql: string, params: any[], ttl?: number): Promise<string>;
+    mongo(db: string, collection: string): {
+        find(query: any): Promise<any[]>;
+    };
+    [table: string]: any;
+}
+type NextFunction = () => Promise<void>;
+type Middleware = (ctx: RequestContext, next: NextFunction) => Promise<void | any>;
+interface UploadConfig {
+    dir: string;
+    handler?: Handler;
+}
+type RouteConfig = {
+    text?: string;
+    json?: any;
+    upload?: UploadConfig;
+};
+type Handler = ((ctx: RequestContext) => void | Promise<void> | Response | Promise<Response> | any | Promise<any>) | RouteConfig;
+interface RouteOptions {
+    rateLimit?: {
+        limit: number;
+        window: number;
+    };
+    cache?: {
+        ttl: number;
+    };
+    jwt?: boolean;
+    schema?: any;
+    querySchema?: any;
+    responseSchema?: any;
+    priority?: 'critical' | 'interactive' | 'background';
+    sloTarget?: number;
+}
+interface Route {
+    method: string;
+    path: string;
+    handler?: Handler;
+    middlewares: Middleware[];
+    options?: RouteOptions;
+    routeConfig?: RouteConfig;
+}
+interface RouteBuilder {
+    desc(description: string): this;
+    auth(strategy?: string): this;
+    jwt(): this;
+    cache(options: {
+        ttl: number;
+        key?: string;
+    }): this;
+    rateLimit(options: {
+        limit: number;
+        window: number;
+    }): this;
+    query(schemaBuilder: (q: QueryBuilder) => void): this;
+    schema(def: any): this;
+    responseSchema(def: any): this;
+    priority(level: 'critical' | 'interactive' | 'background'): this;
+    slo(targetMs: number): this;
+    respond(handler: Handler): void;
+}
+interface WebSocket {
+    send(message: string): void;
+    subscribe(room: string): void;
+    unsubscribe(room: string): void;
+    publish(room: string, message: string): void;
+}
+interface WsHandler {
+    open?: (ws: WebSocket) => void;
+    message?: (ws: WebSocket, message: string) => void;
+    close?: (ws: WebSocket) => void;
+}
+interface QueryBuilder {
+    string(name: string): QueryField;
+    int(name: string): QueryField;
+    bool(name: string): QueryField;
+}
+interface QueryField {
+    default(val: any): this;
+    optional(): this;
+    max(val: number): this;
+    min(val: number): this;
+}
+interface ListenOptions {
+    port: number;
+    tls?: {
+        cert: string;
+        key: string;
+    };
+    callback?: () => void;
+}
+interface FluentBuilder$1 {
+    validate(schema: Record<string, string>): this;
+    schema(def: any): this;
+    responseSchema(def: any): this;
+    query(schemaBuilder: (q: QueryBuilder) => void): this;
+    use(fn: (ctx: RequestContext, state: any) => Promise<any> | any): this;
+    transform(fn: (data: any) => Promise<any> | any): this;
+    hash(field?: string): this;
+    insert(table: string): this;
+    find(table: string, by: string): this;
+    ensure(condition: (state: any) => boolean, errorMsg?: string, status?: number): this;
+    verifyPassword(field?: string): this;
+    jwt(options?: {
+        secret?: string;
+        expiresIn?: string;
+    }): this;
+    respond(status?: number): void;
+    secure(): this;
+    autoFilter(table: string, allow: string[], options?: {
+        sort?: string[];
+        select?: string[];
+        defaultSort?: string;
+        defaultDirection?: 'ASC' | 'DESC';
+        maxLimit?: number;
+        pageParam?: string;
+        limitParam?: string;
+        sortParam?: string;
+        fieldsParam?: string;
+    }): this;
+    list(table: string, options?: {
+        where?: Record<string, string>;
+        limit?: number;
+    }): this;
+    update(table: string, options: {
+        where: Record<string, string>;
+        fields?: string[];
+    }): this;
+    delete(table: string, options: {
+        where: Record<string, string>;
+    }): this;
+}
+interface App$1 {
+    enableLogging(): void;
+    getMetrics(): string;
+    onError(handler: (err: unknown, ctx?: RequestContext) => void): this;
+    gracefulShutdown(signals?: string[]): this;
+    flow(method: string, path: string): FluentBuilder$1;
+    db: {
+        connectPostgres(url: string): Promise<void>;
+        connectSqlite(url: string): Promise<void>;
+        connectRedis(url: string): void;
+        connectMongo(url: string): Promise<void>;
+        query(sql: string, ttl?: number): Promise<string>;
+        redis: {
+            set(key: string, value: string, ttl?: number): Promise<void>;
+            get(key: string): Promise<string | null>;
+        };
+        mongo(db: string, collection: string): {
+            find(query: any): Promise<any[]>;
+        };
+    };
+    auth: {
+        setJwtSecret(secret: string): void;
+    };
+    get(path: string, config: RouteConfig): RouteBuilder;
+    get(path: string, handler: Handler): RouteBuilder;
+    get(path: string): RouteBuilder;
+    post(path: string, config: RouteConfig): RouteBuilder;
+    post(path: string, handler: Handler): RouteBuilder;
+    post(path: string): RouteBuilder;
+    put(path: string, config: RouteConfig): RouteBuilder;
+    put(path: string, handler: Handler): RouteBuilder;
+    put(path: string): RouteBuilder;
+    delete(path: string, config: RouteConfig): RouteBuilder;
+    delete(path: string, handler: Handler): RouteBuilder;
+    delete(path: string): RouteBuilder;
+    listen(port: number, callback?: () => void): void;
+    listen(options: ListenOptions): void;
+    stop(): void;
+    ws(path: string, handler: WsHandler): void;
+    static(prefix: string, root: string): this;
+    use(middleware: Middleware): this;
+    cors(config?: {
+        origin?: string;
+        methods?: string[];
+        headers?: string[];
+        credentials?: boolean;
+    }): this;
+}
+
+declare function loadEnv(filePath?: string): boolean;
+declare function env(key: string, defaultValue?: string): string;
+
+declare class TestClient {
+    private app;
+    port: number;
+    baseUrl: string;
+    private running;
+    constructor(app: App$1);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    get(path: string, headers?: Record<string, string>): Promise<Response>;
+    post(path: string, body: any, headers?: Record<string, string>): Promise<Response>;
+    put(path: string, body: any, headers?: Record<string, string>): Promise<Response>;
+    delete(path: string, headers?: Record<string, string>): Promise<Response>;
+}
+declare function createTestClient(app: App$1): TestClient;
+
+declare class FluentBuilder {
+    private app;
+    private method;
+    private path;
+    private steps;
+    private requestSchema?;
+    private responseSchemaDef?;
+    private queryBuilder?;
+    constructor(app: App$1, method: string, path: string);
+    desc(description: string): this;
+    auth(strategy?: string): this;
+    cache(options: {
+        ttl: number;
+        key?: string;
+    }): this;
+    rateLimit(options: {
+        limit: number;
+        window: number;
+    }): this;
+    status(statusCode: number): this;
+    priority(level: 'critical' | 'interactive' | 'background'): this;
+    slo(targetMs: number): this;
+    validate(schema: Record<string, string>): this;
+    schema(def: any): this;
+    responseSchema(def: any): this;
+    query(schemaBuilder: (q: any) => void): this;
+    queryState(fields?: string[]): this;
+    use(fn: (ctx: RequestContext, state: any) => Promise<any> | any): this;
+    sql(query: string, params?: any[] | ((state: any) => any[])): this;
+    transform(fn: (data: any) => Promise<any> | any): this;
+    hash(field?: string): this;
+    insert(table: string): this;
+    find(table: string, by: string): this;
+    ensure(condition: (state: any) => boolean, errorMsg?: string, status?: number): this;
+    verifyPassword(field?: string): this;
+    jwt(options?: {
+        secret?: string;
+        expiresIn?: string;
+    }): this;
+    respond(handlerOrStatus?: Handler | number): void;
+    private applyOptionsToRoute;
+    private useJwt;
+    secure(): this;
+    select(fields: string[]): this;
+    sort(field: string, direction?: 'ASC' | 'DESC'): this;
+    paginate(options: {
+        page: number;
+        limit: number;
+    }): this;
+    autoFilter(table: string, allow: string[], options?: {
+        sort?: string[];
+        select?: string[];
+        defaultSort?: string;
+        defaultDirection?: 'ASC' | 'DESC';
+        maxLimit?: number;
+        pageParam?: string;
+        limitParam?: string;
+        sortParam?: string;
+        fieldsParam?: string;
+    }): this;
+    list(table: string, options?: {
+        where?: Record<string, string>;
+        limit?: number;
+    }): this;
+    update(table: string, options: {
+        where: Record<string, string>;
+        fields?: string[];
+    }): this;
+    softDelete(table: string, options: {
+        where: Record<string, string>;
+    }): this;
+    delete(table: string, options: {
+        where: Record<string, string>;
+    }): this;
+}
+
+declare class Q {
+    static env: typeof env;
+    static loadEnv: typeof loadEnv;
+    static app(config?: any): App;
+    static schema(def: any): any;
+    static string(): SchemaBuilder;
+    static int(): SchemaBuilder;
+    static email(): SchemaBuilder;
+    static enum(...values: string[]): SchemaBuilder;
+}
+declare namespace Q {
+    type Context = RequestContext;
+    type Handler = Handler;
+}
+declare class SchemaBuilder {
+    private def;
+    constructor(type: string);
+    min(val: number): this;
+    max(val: number): this;
+    format(fmt: string): this;
+    enum(values: string[]): this;
+    toJSON(): any;
+}
+declare namespace App {
+    type Context = RequestContext;
+}
+declare class App implements App$1 {
+    private config?;
+    private engine;
+    private routes;
+    private handlers;
+    private handlerCounter;
+    private middlewares;
+    private staticRoutes;
+    private wsHandlers;
+    private activeSockets;
+    private corsConfig;
+    private loggingEnabled;
+    private errorHandler;
+    private errorHooksRegistered;
+    private shutdownHooksRegistered;
+    flow(method: string, path: string): FluentBuilder;
+    doc(path: string): this;
+    exportClient(outputPath: string): void;
+    private generateOpenApiSpec;
+    enableLogging(): void;
+    getMetrics(): string;
+    onError(handler: (err: unknown, ctx?: RequestContext) => void): this;
+    gracefulShutdown(signals?: string[]): this;
+    security(): this;
+    private pendingSecurity;
+    private registerErrorHooks;
+    private handleError;
+    db: {
+        connectPostgres(url: string): Promise<void>;
+        connectSqlite(url: string): Promise<void>;
+        connectRedis(url: string): void;
+        connectMongo(url: string): Promise<void>;
+        query(sql: string, ttl?: number): Promise<string>;
+        redis: {
+            set(key: string, value: string, ttl?: number): Promise<void>;
+            get(key: string): Promise<string | null>;
+        };
+        mongo(db: string, collection: string): {
+            find(query: any): Promise<any[]>;
+        };
+    };
+    auth: {
+        setJwtSecret(secret: string): void;
+    };
+    constructor(config?: any | undefined);
+    static(prefix: string, root: string): this;
+    use(fn: Middleware): this;
+    ws(path: string, handler: WsHandler): void;
+    cors(config?: {
+        origin?: string;
+        methods?: string[];
+        headers?: string[];
+        credentials?: boolean;
+    }): this;
+    get(path: string, config: RouteConfig): FluentBuilder;
+    get(path: string, handler: Handler): FluentBuilder;
+    get(path: string, options: RouteOptions, handler: Handler): FluentBuilder;
+    get(path: string): FluentBuilder;
+    post(path: string, config: RouteConfig): FluentBuilder;
+    post(path: string, handler: Handler): FluentBuilder;
+    post(path: string, options: RouteOptions, handler: Handler): FluentBuilder;
+    post(path: string): FluentBuilder;
+    put(path: string, config: RouteConfig): FluentBuilder;
+    put(path: string, handler: Handler): FluentBuilder;
+    put(path: string, options: RouteOptions, handler: Handler): FluentBuilder;
+    put(path: string): FluentBuilder;
+    delete(path: string, config: RouteConfig): FluentBuilder;
+    delete(path: string, handler: Handler): FluentBuilder;
+    delete(path: string, options: RouteOptions, handler: Handler): FluentBuilder;
+    delete(path: string): FluentBuilder;
+    private addRoute;
+    registerHandler(handler: Handler, serializer?: (doc: any) => string): number;
+    listen(portOrOptions: number | ListenOptions, cb?: () => void): void;
+    stop(): void;
+}
+
+export { App, type DatabaseContext, type EnvContext, FluentBuilder, type Handler, type ListenOptions, type Middleware, type NextFunction, Q, type QueryBuilder, type QueryField, type RequestContext, type RequestMetrics, type RequestSnapshot, type Route, type RouteBuilder, type RouteConfig, type RouteOptions, TestClient, type UploadConfig, type WebSocket, type WsHandler, createTestClient };