@kozojs/core 0.3.1 → 0.3.3

package/lib/index.d.ts

@@ -0,0 +1,657 @@
+import * as hono 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';
+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 = {
+    body?: SchemaType;
+    query?: SchemaType;
+    params?: SchemaType;
+    response?: SchemaType | Record<number, SchemaType>;
+};
+type InferSchema<T> = T extends z.ZodType<any> ? z.infer<T> : T extends TSchema ? Static<T> : unknown;
+/** 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']>;
+    req: any;
+    json: (data: any) => Response;
+    text: (data: string, status?: number, headers?: any) => Response;
+};
+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;
+        version: string;
+        description?: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
+}
+interface KozoConfig<TServices extends Services = Services> {
+    routesDir?: string;
+    services?: TServices;
+    port?: number;
+    mode?: 'safe' | 'turbo';
+    runtime?: 'node' | 'bun';
+    target?: 'node' | 'edge' | 'cloudflare' | 'vercel' | 'netlify';
+    monitoring?: {
+        enable: boolean;
+        metrics: ('req/sec' | 'latency' | 'errors')[];
+        port?: number;
+    };
+    basePath?: string;
+    openapi?: OpenAPIConfigRef;
+    onError?: (error: Error, ctx: any) => any;
+    onNotFound?: (ctx: any) => any;
+}
+
+/**
+ * Client Generator Options
+ */
+interface ClientGeneratorOptions {
+    /** Include Zod schemas for client-side validation (default: true) */
+    includeValidation?: boolean;
+    /** Base URL for the API (default: '') */
+    baseUrl?: string;
+    /** Enable runtime validation by default (default: false) */
+    validateByDefault?: boolean;
+    /** Custom headers to include in all requests */
+    defaultHeaders?: Record<string, string>;
+}
+/**
+ * Route information for client generation
+ */
+interface RouteInfo {
+    method: string;
+    path: string;
+    schema: RouteSchema;
+    /** Optional: store the Zod schema instance for type extraction */
+    zodSchemas?: {
+        body?: any;
+        query?: any;
+        params?: any;
+        response?: any;
+    };
+}
+/**
+ * Generate typed client code from routes
+ */
+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;
+    install: (app: Kozo) => void | Promise<void>;
+}
+/**
+ * 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<TServices extends Services = Services> {
+    private app;
+    private services;
+    private routes;
+    /** Routes registered directly with the uWS C++ radix router. */
+    private uwsRoutes;
+    private shutdownManager;
+    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, 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 uWebSockets.js HTTP server.
+     *
+     * All routes are registered directly with uWS's C++ radix trie router —
+     * zero JS routing overhead per request. The C++ HTTP parser (µHttpParser)
+     * eliminates all IncomingMessage/ServerResponse allocations.
+     *
+     * Throws if uWebSockets.js is not installed.
+     * Returns { port, server } so callers 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<TServices extends Services = Services>(config?: KozoConfig<TServices>): Kozo<TServices>;
+
+type ZValidatorErrors = {
+    instancePath: string;
+    message: string;
+}[];
+type ZValidator = ((data: unknown) => boolean) & {
+    errors: ZValidatorErrors | null;
+};
+type CompiledHandler = (c: Context) => Promise<Response> | Response;
+type UserHandler = (c: any) => any;
+type CompiledRoute = {
+    validateBody?: ZValidator;
+    validateQuery?: ZValidator;
+    validateParams?: ZValidator;
+    serialize?: (data: any) => string;
+};
+declare class SchemaCompiler {
+    static compile(schema: RouteSchema): CompiledRoute;
+}
+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, 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 };