@kozojs/core 0.2.3 → 0.2.5

package/lib/index.d.ts

@@ -1,8 +1,12 @@
 import * as hono from 'hono';
-import { Hono, Context } from 'hono';
+import { Context } from 'hono';
+import { Hono } from 'hono/quick';
+import { IncomingMessage, ServerResponse, Server } from 'node:http';
 import { z } from 'zod';
 export { z } from 'zod';
 import { TSchema, Static } from '@sinclair/typebox';
+import { ValidateFunction } from 'ajv';
+export { CorsOptions, FileSystemRoutingOptions, HttpBadRequestError, HttpConflictError, HttpError, HttpForbiddenError, HttpInternalServerError, HttpNotFoundError, HttpUnauthorizedError, LoggerOptions, ManifestHttpMethod, ManifestRoute, RateLimitOptions, RoutesManifest, applyFileSystemRouting, clearRateLimitStore, cors, createFileSystemRouting, errorHandler, logger, rateLimit } from './middleware/index.js';
 
 type SchemaType = z.ZodType<any> | TSchema;
 type RouteSchema = {
@@ -12,8 +16,10 @@ type RouteSchema = {
     response?: SchemaType | Record<number, SchemaType>;
 };
 type InferSchema<T> = T extends z.ZodType<any> ? z.infer<T> : T extends TSchema ? Static<T> : unknown;
-type KozoContext<S extends RouteSchema = {}> = {
-    services: Services;
+/** Infer the response data type from a schema's response field */
+type InferResponse<T> = T extends SchemaType ? InferSchema<T> : T extends Record<number, SchemaType> ? InferSchema<T[200]> : unknown;
+type KozoContext<S extends RouteSchema = {}, TServices extends Services = Services> = {
+    services: TServices;
     body: InferSchema<S['body']>;
     query: InferSchema<S['query']>;
     params: InferSchema<S['params']>;
@@ -21,10 +27,89 @@ type KozoContext<S extends RouteSchema = {}> = {
     json: (data: any) => Response;
     text: (data: string, status?: number, headers?: any) => Response;
 };
-type KozoHandler<S extends RouteSchema = {}> = (ctx: KozoContext<S>) => any | Promise<any>;
+type KozoHandler<S extends RouteSchema = {}, TServices extends Services = Services> = (ctx: KozoContext<S, TServices>) => any | Promise<any>;
 interface Services {
     [key: string]: unknown;
 }
+interface KozoEnv {
+    Variables: {
+        services: Services;
+        user?: unknown;
+    };
+}
+/**
+ * Context object passed to native route handlers (used with `nativeListen`).
+ *
+ * Offers the same type inference as `KozoContext` but operates directly on
+ * Node.js primitives — no Hono adapter, no Web API Request/Response.
+ *
+ * @typeParam S       - Route schema (body, query, params, response)
+ * @typeParam TSvc    - Services type (injected at constructor)
+ */
+interface NativeKozoContext<S extends RouteSchema = {}, TSvc extends Services = Services> {
+    /** Raw Node.js incoming request */
+    readonly req: IncomingMessage;
+    /** Raw Node.js server response */
+    readonly res: ServerResponse;
+    /** Route parameters — typed from schema.params */
+    readonly params: InferSchema<S['params']>;
+    /** Parsed query string — typed from schema.query */
+    readonly query: InferSchema<S['query']>;
+    /** Parsed request body — typed from schema.body */
+    readonly body: InferSchema<S['body']>;
+    /** Injected services — typed from Kozo<TServices> */
+    readonly services: TSvc;
+    /** Send a JSON response (default status 200). Uses fast-json-stringify if schema.response is defined. */
+    json(data: InferResponse<S['response']>, status?: number): void;
+    /** Send a plain text response. */
+    text(data: string, status?: number): void;
+    /** Send an HTML response (SSR page rendering). */
+    html(data: string, status?: number): void;
+    /** Set a response header. Returns `this` for chaining. */
+    header(name: string, value: string): this;
+    /** Redirect to another URL (default 302). */
+    redirect(url: string, status?: number): void;
+}
+/**
+ * Handler function type for native routes (used with `nativeListen`).
+ *
+ * @typeParam S    - Route schema
+ * @typeParam TSvc - Services shape
+ */
+type NativeKozoHandler<S extends RouteSchema = {}, TSvc extends Services = Services> = (ctx: NativeKozoContext<S, TSvc>) => void | Promise<void>;
+interface HandlerContext<TBody = unknown, TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, string> = Record<string, string>> {
+    body: TBody;
+    params: TParams;
+    query: TQuery;
+    headers: Record<string, string>;
+    services: Services;
+    user?: unknown;
+    c: any;
+}
+type RouteHandler<TBody = unknown> = (ctx: HandlerContext<TBody>) => Promise<unknown> | unknown;
+interface RouteMeta {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    auth?: boolean;
+    rateLimit?: {
+        max: number;
+        window: number;
+    };
+}
+interface RouteModule {
+    default: RouteHandler;
+    schema?: RouteSchema;
+    meta?: RouteMeta;
+    middleware?: Array<(ctx: HandlerContext) => Promise<void> | void>;
+}
+type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+interface RouteDefinition {
+    path: string;
+    method: HttpMethod;
+    filePath: string;
+    module: RouteModule;
+}
 interface OpenAPIConfigRef {
     info: {
         title: string;
@@ -40,9 +125,9 @@ interface OpenAPIConfigRef {
         description?: string;
     }>;
 }
-interface KozoConfig {
+interface KozoConfig<TServices extends Services = Services> {
     routesDir?: string;
-    services?: Services;
+    services?: TServices;
     port?: number;
     mode?: 'safe' | 'turbo';
     runtime?: 'node' | 'bun';
@@ -91,6 +176,102 @@ interface RouteInfo {
  */
 declare function generateTypedClient(routes: RouteInfo[], options?: ClientGeneratorOptions): string;
 
+type DatabaseProvider = 'postgresql' | 'mysql' | 'sqlite';
+type DatabaseInstance = Record<string, unknown>;
+/**
+ * Shutdown configuration options
+ */
+interface ShutdownOptions {
+    /** Maximum time to wait for in-flight requests to complete (default: 30000ms) */
+    timeoutMs?: number;
+    /** Callback fired when shutdown starts */
+    onShutdownStart?: (inflightCount: number) => void;
+    /** Callback fired when all requests complete before timeout */
+    onShutdownComplete?: () => void;
+    /** Callback fired when shutdown times out */
+    onShutdownTimeout?: (remainingInflight: number) => void;
+    /** Database instance to close (optional) */
+    database?: DatabaseInstance;
+    /** Database provider type (required if database is provided) */
+    databaseProvider?: DatabaseProvider;
+}
+/**
+ * Internal state for tracking in-flight requests
+ */
+interface InflightTracker {
+    count: number;
+    requests: Set<Promise<unknown>>;
+}
+/**
+ * Create an in-flight request tracker
+ */
+declare function createInflightTracker(): InflightTracker;
+/**
+ * Track a request - call at the start of each request
+ */
+declare function trackRequest(tracker: InflightTracker): () => void;
+/**
+ * Shutdown state machine
+ */
+type ShutdownState = 'running' | 'shutting-down' | 'shutdown';
+/**
+ * Graceful shutdown manager
+ */
+declare class ShutdownManager {
+    private state;
+    private abortController;
+    private server;
+    private tracker;
+    private database;
+    private databaseProvider;
+    constructor();
+    /**
+     * Get current shutdown state
+     */
+    getState(): ShutdownState;
+    /**
+     * Check if server is shutting down
+     */
+    isShuttingDown(): boolean;
+    /**
+     * Get current in-flight request count
+     */
+    getInflightCount(): number;
+    /**
+     * Set the server instance for shutdown
+     */
+    setServer(server: Server): void;
+    /**
+     * Set database for cleanup
+     */
+    setDatabase(db: DatabaseInstance, provider: DatabaseProvider): void;
+    /**
+     * Get the AbortController signal for request cancellation
+     */
+    getAbortSignal(): AbortSignal | undefined;
+    /**
+     * Create a request tracker middleware
+     * Returns an untrack function to call when request completes
+     */
+    trackRequest(): () => void;
+    /**
+     * Initiate graceful shutdown
+     */
+    shutdown(options?: ShutdownOptions): Promise<void>;
+    /**
+     * Wait for all in-flight requests to complete
+     */
+    private drainRequests;
+    /**
+     * Close database connections based on provider
+     */
+    private closeDatabase;
+}
+/**
+ * Create a shutdown manager instance
+ */
+declare function createShutdownManager(): ShutdownManager;
+
 interface Plugin {
     name: string;
     version?: string;
@@ -98,38 +279,380 @@ interface Plugin {
 }
 /**
  * Kozo - High-performance TypeScript framework with Zod schemas
+ *
+ * @typeParam TServices - Shape of the services object injected into every handler.
+ *   Pass it once at construction: `createKozo<{ db: Database }>({ services: { db } })`
+ *   and all handler contexts will have `ctx.services.db` fully typed.
  */
-declare class Kozo {
+declare class Kozo<TServices extends Services = Services> {
     private app;
     private services;
     private routes;
-    constructor(config?: KozoConfig);
+    private nativeRoutes;
+    private shutdownManager;
+    private wasmRouter;
+    /** Maps each NativeRouteHandler to its zero-shim uWS counterpart */
+    private uwsHandlerMap;
+    private _routesDir?;
+    constructor(config?: KozoConfig<TServices>);
     use(plugin: Plugin): this;
+    /**
+     * Load routes from the file system using the configured routesDir.
+     * Each route file is dynamically imported, its schema compiled, and handler registered.
+     * This is a no-op if routesDir is not configured.
+     */
+    loadRoutes(routesDir?: string): Promise<this>;
     generateClient(baseUrl?: string): string;
     generateClient(options?: ClientGeneratorOptions): string;
-    get<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S>): void;
-    post<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S>): void;
-    put<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S>): void;
-    patch<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S>): void;
-    delete<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S>): void;
+    get<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S, TServices>): this;
+    post<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S, TServices>): this;
+    put<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S, TServices>): this;
+    patch<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S, TServices>): this;
+    delete<S extends RouteSchema>(path: string, schema: S, handler: KozoHandler<S, TServices>): this;
     private register;
+    /**
+     * Start a raw Node.js HTTP server (no @hono/node-server adapter).
+     * Writes directly to ServerResponse — eliminates Web API Request/Response
+     * allocation and adapter overhead for maximum throughput.
+     *
+     * When the Zig WASM radix trie is available (`src/wasm/radix.wasm`),
+     * ALL route matching (static + dynamic) runs through the zero-copy
+     * trie — one call into WASM per request.
+     *
+     * When the .wasm file is absent (Edge deploy, CI without Zig, etc.)
+     * routing falls back transparently to the JS Map + RegExp approach.
+     *
+     * Returns { port, server } so the caller can close the server when done.
+     */
+    nativeListen(port?: number): Promise<{
+        port: number;
+        server: Server;
+    }>;
     listen(port?: number): Promise<void>;
+    /**
+     * Graceful shutdown — drains in-flight requests before closing.
+     * Use getShutdownManager().setDatabase(db, provider) to register DB cleanup.
+     */
+    shutdown(options?: ShutdownOptions): Promise<void>;
+    getShutdownManager(): ShutdownManager;
     getApp(): Hono;
     get fetch(): (request: Request, Env?: unknown, executionCtx?: hono.ExecutionContext) => Response | Promise<Response>;
 }
-declare function createKozo(config?: KozoConfig): Kozo;
+declare function createKozo<TServices extends Services = Services>(config?: KozoConfig<TServices>): Kozo<TServices>;
 
+type CompiledHandler = (c: Context) => Promise<Response> | Response;
 type UserHandler = (c: any) => any;
 type CompiledRoute = {
-    validateBody?: (data: any) => boolean;
-    validateQuery?: (data: any) => boolean;
-    validateParams?: (data: any) => boolean;
+    validateBody?: ValidateFunction;
+    validateQuery?: ValidateFunction;
+    validateParams?: ValidateFunction;
     serialize?: (data: any) => string;
     errors?: any;
 };
 declare class SchemaCompiler {
     static compile(schema: RouteSchema): CompiledRoute;
 }
-declare function compileRouteHandler(userHandler: UserHandler, schema: RouteSchema, services: any, compiled: CompiledRoute): (c: Context) => any;
+declare function compileRouteHandler(handler: UserHandler, schema: RouteSchema, services: Services, compiled: CompiledRoute): CompiledHandler;
+
+/**
+ * Build a NativeKozoContext for a native route handler.
+ *
+ * Called by the native handler compiler (`compiler.ts`) when the route
+ * is registered via `nativeRoute()`.  Not intended for direct use.
+ *
+ * @internal
+ */
+declare function buildNativeContext<S extends RouteSchema, TSvc extends Services>(req: IncomingMessage, res: ServerResponse, params: Record<string, string>, body: any, services: TSvc, serialize?: (data: any) => string): NativeKozoContext<S, TSvc>;
+
+/** Fast number → string for Content-Length. Cached for values < 10 000. */
+declare function fastCL(n: number): string;
+/**
+ * Write a 200 JSON response.
+ *
+ * IMPORTANT: `body` MUST be ASCII-safe (i.e. produced by JSON.stringify
+ * or fast-json-stringify).  We use `body.length` instead of
+ * `Buffer.byteLength(body)` — valid because JSON serializers escape
+ * non-ASCII to `\uXXXX`, keeping the output 7-bit clean.
+ */
+declare function fastWriteJson(res: ServerResponse, body: string): void;
+/**
+ * Write a plain text response.
+ */
+declare function fastWriteText(res: ServerResponse, body: string, status?: number): void;
+/**
+ * Write an HTML response (SSR page rendering).
+ */
+declare function fastWriteHtml(res: ServerResponse, body: string, status?: number): void;
+/**
+ * Write a JSON response with a custom status code.
+ */
+declare function fastWriteJsonStatus(res: ServerResponse, body: string, status: number): void;
+/**
+ * Write a pre-built 404 Not Found response (zero allocation).
+ */
+declare function fastWrite404(res: ServerResponse): void;
+/**
+ * Write a pre-built 500 Internal Server Error response (zero allocation).
+ */
+declare function fastWrite500(res: ServerResponse): void;
+/**
+ * Write a 400 validation error response.
+ * Allocates only the error body string.
+ */
+declare function fastWrite400(field: string, errors: any, res: ServerResponse): void;
+/**
+ * Write a KozoError as an RFC 7807 problem+json response.
+ * Falls back to 500 for unknown errors.
+ */
+declare function fastWriteError(err: unknown, res: ServerResponse): void;
+
+/**
+ * Kozo Error System - RFC 7807 Problem Details
+ *
+ * Standardized error format for all validation and runtime errors.
+ * Pre-serialized templates + frozen ResponseInit objects eliminate
+ * per-request allocations on the hot path.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7807
+ */
+interface ValidationError {
+    field: string;
+    message: string;
+    code: string;
+    value?: unknown;
+}
+interface ProblemDetails {
+    type: string;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    errors?: ValidationError[];
+}
+declare const ERROR_RESPONSES: {
+    readonly VALIDATION_FAILED: {
+        readonly type: "https://kozo.dev/errors/validation-failed";
+        readonly title: "Validation Failed";
+        readonly status: 400;
+    };
+    readonly INVALID_BODY: {
+        readonly type: "https://kozo.dev/errors/invalid-body";
+        readonly title: "Invalid Request Body";
+        readonly status: 400;
+    };
+    readonly INVALID_QUERY: {
+        readonly type: "https://kozo.dev/errors/invalid-query";
+        readonly title: "Invalid Query Parameters";
+        readonly status: 400;
+    };
+    readonly INVALID_PARAMS: {
+        readonly type: "https://kozo.dev/errors/invalid-params";
+        readonly title: "Invalid Path Parameters";
+        readonly status: 400;
+    };
+    readonly INTERNAL_ERROR: {
+        readonly type: "https://kozo.dev/errors/internal-error";
+        readonly title: "Internal Server Error";
+        readonly status: 500;
+    };
+    readonly NOT_FOUND: {
+        readonly type: "https://kozo.dev/errors/not-found";
+        readonly title: "Resource Not Found";
+        readonly status: 404;
+    };
+    readonly UNAUTHORIZED: {
+        readonly type: "https://kozo.dev/errors/unauthorized";
+        readonly title: "Unauthorized";
+        readonly status: 401;
+    };
+    readonly FORBIDDEN: {
+        readonly type: "https://kozo.dev/errors/forbidden";
+        readonly title: "Forbidden";
+        readonly status: 403;
+    };
+};
+/**
+ * Convert Ajv validation errors to standardized format
+ */
+declare function formatAjvErrors(errors: any[] | null | undefined): ValidationError[];
+/**
+ * Convert Zod validation errors to standardized format
+ */
+declare function formatZodErrors(errors: any): ValidationError[];
+/**
+ * Build a 400 Validation Failed response.
+ * Called on every invalid request — kept as lean as possible.
+ */
+declare function validationErrorResponse(field: string, ajvErrors: any[] | null | undefined, instance?: string): Response;
+/**
+ * Build a 500 Internal Server Error response.
+ */
+declare function internalErrorResponse(err: Error, instance?: string): Response;
+declare function notFoundResponse(instance?: string): Response;
+declare function unauthorizedResponse(instance?: string): Response;
+declare function forbiddenResponse(instance?: string): Response;
+declare class KozoError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    constructor(message: string, statusCode: number, code: string);
+    toResponse(instance?: string): Response;
+}
+declare class ValidationFailedError extends KozoError {
+    readonly errors: ValidationError[];
+    constructor(message: string, errors?: ValidationError[]);
+    toResponse(instance?: string): Response;
+}
+declare class NotFoundError extends KozoError {
+    constructor(message?: string);
+}
+declare class UnauthorizedError extends KozoError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends KozoError {
+    constructor(message?: string);
+}
+
+interface OpenAPIInfo {
+    title: string;
+    version: string;
+    description?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    license?: {
+        name: string;
+        url?: string;
+    };
+}
+interface OpenAPIConfig {
+    info: OpenAPIInfo;
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    security?: Array<Record<string, string[]>>;
+}
+interface OpenAPISpec {
+    openapi: '3.1.0';
+    info: OpenAPIInfo;
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    paths: Record<string, PathItem>;
+    components: {
+        schemas: Record<string, SchemaObject>;
+        securitySchemes?: Record<string, SecurityScheme>;
+    };
+    security?: Array<Record<string, string[]>>;
+}
+interface PathItem {
+    [method: string]: OperationObject;
+}
+interface OperationObject {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    parameters?: ParameterObject[];
+    requestBody?: RequestBodyObject;
+    responses: Record<string, ResponseObject>;
+    security?: Array<Record<string, string[]>>;
+}
+interface ParameterObject {
+    name: string;
+    in: 'query' | 'path' | 'header' | 'cookie';
+    required?: boolean;
+    schema: SchemaObject;
+    description?: string;
+}
+interface RequestBodyObject {
+    required?: boolean;
+    content: {
+        'application/json': {
+            schema: SchemaObject;
+        };
+    };
+}
+interface ResponseObject {
+    description: string;
+    content?: {
+        'application/json': {
+            schema: SchemaObject;
+        };
+    };
+}
+interface SchemaObject {
+    type?: string;
+    format?: string;
+    properties?: Record<string, SchemaObject>;
+    items?: SchemaObject;
+    required?: string[];
+    enum?: unknown[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    description?: string;
+    default?: unknown;
+    nullable?: boolean;
+    oneOf?: SchemaObject[];
+    anyOf?: SchemaObject[];
+    allOf?: SchemaObject[];
+    additionalProperties?: SchemaObject | boolean;
+    $ref?: string;
+}
+interface SecurityScheme {
+    type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+    scheme?: string;
+    bearerFormat?: string;
+    name?: string;
+    in?: 'query' | 'header' | 'cookie';
+}
+declare class OpenAPIGenerator {
+    private config;
+    private schemas;
+    private schemaCounter;
+    constructor(config: OpenAPIConfig);
+    /**
+     * Generate OpenAPI spec from routes
+     */
+    generate(routes: RouteDefinition[]): OpenAPISpec;
+    /**
+     * Convert Hono path params to OpenAPI format
+     * :id -> {id}
+     */
+    private honoPathToOpenApi;
+    /**
+     * Convert route to OpenAPI operation
+     */
+    private routeToOperation;
+    /**
+     * Generate operation ID from path and method
+     */
+    private generateOperationId;
+    /**
+     * Extract tag from path (first segment)
+     */
+    private extractTag;
+    /**
+     * Get HTTP status description
+     */
+    private getStatusDescription;
+    private capitalize;
+}
+declare function generateSwaggerHtml(specUrl: string, title?: string): string;
+declare function createOpenAPIGenerator(config: OpenAPIConfig): OpenAPIGenerator;
 
-export { type ClientGeneratorOptions, type CompiledRoute, Kozo, type KozoConfig, type KozoContext, type KozoHandler, type RouteInfo, type RouteSchema, SchemaCompiler, type Services, compileRouteHandler, createKozo, generateTypedClient };
+export { type ClientGeneratorOptions, type CompiledRoute, ERROR_RESPONSES, ForbiddenError, type InferResponse, type InferSchema, type InflightTracker, Kozo, type KozoConfig, type KozoContext, type KozoEnv, KozoError, type KozoHandler, type NativeKozoContext, type NativeKozoHandler, NotFoundError, type OpenAPIConfig, OpenAPIGenerator, type OpenAPIInfo, type OpenAPISpec, type ProblemDetails, type RouteInfo, type RouteSchema, SchemaCompiler, type Services, ShutdownManager, type ShutdownOptions, type ShutdownState, UnauthorizedError, type ValidationError, ValidationFailedError, buildNativeContext, compileRouteHandler, createInflightTracker, createKozo, createOpenAPIGenerator, createShutdownManager, fastCL, fastWrite400, fastWrite404, fastWrite500, fastWriteError, fastWriteHtml, fastWriteJson, fastWriteJsonStatus, fastWriteText, forbiddenResponse, formatAjvErrors, formatZodErrors, generateSwaggerHtml, generateTypedClient, internalErrorResponse, notFoundResponse, trackRequest, unauthorizedResponse, validationErrorResponse };