@coderbuzz/ken 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2783 @@
+/**
+ * Ken Framework - Context Types
+ * Shared type definitions for all Context implementations
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+/**
+ * Remote information including address and port.
+ */
+interface RemoteInfo {
+    address: string;
+    port: number;
+}
+type Validator = (val: any, ctx?: any) => any;
+/**
+ * Flatten intersection types into a single object type for better IDE display.
+ * Converts A & B & C into a single flat object with all properties.
+ */
+type Flatten<T> = T extends infer U ? {
+    [K in keyof U]: U[K];
+} : never;
+/**
+ * Type-level utilities to extract param names from route path patterns.
+ */
+type ExtractParams<Path extends string> = Path extends `${infer Segment}/${infer Rest}` ? ExtractParams<Segment> & ExtractParams<Rest> : Path extends `:${infer Param}?` ? {
+    [K in Param]?: string;
+} : Path extends `:${infer Param}` ? {
+    [K in Param]: string;
+} : Path extends `*` ? {
+    "*": string;
+} : {};
+type ParamsFromPath<Path extends string> = Flatten<ExtractParams<Path>>;
+/**
+ * Error handler function signature.
+ * Receives the thrown error and request context, returns a Response.
+ * Route-level onError takes priority over app-level.
+ */
+type ErrorHandler = (error: unknown, ctx: Context<any, any>) => Response | Promise<Response>;
+/**
+ * Route Schema definition for validation and type inference.
+ * Flat architecture for best DX.
+ */
+interface Schema {
+    onError?: ErrorHandler;
+    state?: StateMiddleware;
+    params?: Record<string, Validator>;
+    query?: Record<string, Validator>;
+    headers?: Record<string, Validator>;
+    cookies?: Record<string, Validator>;
+    json?: Validator;
+    text?: Validator;
+    form?: Record<string, Validator>;
+}
+/**
+ * Middleware handler function signature.
+ * Used for side-effect middleware (logger, CORS, etc.) that don't produce state values.
+ */
+type MiddlewareHandler = (ctx: Context<any, any>) => void | Response | Promise<void | Response>;
+/**
+ * State Middleware definition and type inference.
+ * Middleware functions that can return values (auth, user data) or void (guards, loggers).
+ */
+type StateMiddleware = {
+    [key: string]: (ctx: Context<any, any>) => any;
+};
+type ContainsUndefined<T> = [T] extends [Exclude<T, undefined>] ? false : true;
+type InferObject<T, Default> = T extends Record<string, Validator> ? Flatten<{
+    [K in keyof T as ContainsUndefined<ReturnType<T[K]>> extends true ? K : never]?: ReturnType<T[K]>;
+} & {
+    [K in keyof T as ContainsUndefined<ReturnType<T[K]>> extends true ? never : K]: ReturnType<T[K]>;
+}> : Default;
+type InferValidator<T, Default> = T extends Validator ? ReturnType<T> : Default;
+/**
+ * Context Interface - What route handlers see
+ * All runtime-specific Context classes must implement this
+ *
+ * @template S - Schema type for validation
+ * @template Path - Route path string for param extraction
+ * @template TState - Accumulated state from middleware
+ */
+interface Context<S extends Schema = {}, Path extends string = string, TState = {}> {
+    /**
+     * Request URL
+     */
+    readonly url: string;
+    /**
+     * HTTP method
+     */
+    readonly method: string;
+    /**
+     * Raw body stream (runtime-specific)
+     */
+    readonly body: any;
+    /**
+     * State from executed middleware. Only includes middleware with non-void returns.
+     */
+    state: Flatten<TState & (S extends {
+        state: infer M extends StateMiddleware;
+    } ? {
+        [K in keyof M as Awaited<ReturnType<M[K]>> extends void ? never : K]: Exclude<Awaited<ReturnType<M[K]>>, Response>;
+    } : {})>;
+    /**
+     * Remote information (IP address and port)
+     */
+    readonly remoteInfo: RemoteInfo;
+    /**
+     * Route parameters (lazily parsed and validated)
+     */
+    readonly params: InferObject<S['params'], ParamsFromPath<Path>>;
+    /**
+     * Query parameters (lazily parsed and validated)
+     */
+    readonly query: InferObject<S['query'], Record<string, string>>;
+    /**
+     * Headers (lazily parsed and validated)
+     */
+    readonly headers: InferObject<S['headers'], Record<string, string>>;
+    /**
+     * Cookies (lazily parsed and validated)
+     */
+    readonly cookies: InferObject<S['cookies'], Record<string, string>>;
+    /**
+     * JSON body (lazily parsed and validated)
+     */
+    readonly json: Promise<InferValidator<S['json'], any>>;
+    /**
+     * Text body (lazily parsed and validated)
+     */
+    readonly text: Promise<InferValidator<S['text'], string>>;
+    /**
+     * Form body (lazily parsed and validated)
+     */
+    readonly form: Promise<InferObject<S['form'], FormData>>;
+    /**
+     * Register callback to be called after handler finishes (success or failure).
+     * Useful for middleware that needs to perform cleanup or logging after response.
+     */
+    onFinish(callback: (resp?: Response) => void): void;
+    /**
+     * Set a cookie to be sent with the response.
+     * Cookies are collected and applied to the response via onFinish callback.
+     *
+     * @param name - Cookie name
+     * @param value - Cookie value
+     * @param options - Cookie options (path, domain, maxAge, expires, httpOnly, secure, sameSite)
+     */
+    setCookie(name: string, value: string, options?: {
+        path?: string;
+        domain?: string;
+        maxAge?: number;
+        expires?: Date;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: 'Strict' | 'Lax' | 'None';
+    }): void;
+    /**
+     * Internal: Execute all registered onFinish callbacks.
+     * Called by framework after handler completes.
+     */
+    _executeFinishCallbacks(resp?: Response): void;
+}
+
+/**
+ * Ken Framework - Core Router
+ * High-performance radix tree router with type-safe route matching
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Handler function type - receives Context and returns any value
+ * The return value is converted to Response by the runtime
+ */
+type Handler = (ctx: any) => any;
+/**
+ * Raw route registration entry
+ * Stored during registration phase, compiled by runtime
+ */
+interface RouteRegistration {
+    method: string;
+    path: string;
+    schema?: Schema;
+    handler?: Handler;
+    staticValue?: unknown;
+}
+/**
+ * Route info returned by getRoutes()
+ */
+interface RouteInfo {
+    method: string;
+    path: string;
+}
+/**
+ * Match result from router
+ */
+interface MatchResult {
+    handler: (...args: any[]) => any;
+    schema?: Schema;
+    params: Record<string, string>;
+    response?: Response;
+}
+/**
+ * Router - Core routing implementation
+ *
+ * Stores raw route registrations during registration phase.
+ * Runtimes compile routes with their native executors.
+ */
+declare class Router {
+    private staticRoutes;
+    private dynamicRoot;
+    routes: RouteRegistration[];
+    /**
+     * Register a compiled route (called by runtime during compilation)
+     */
+    registerCompiled(method: string, path: string, handler: (...args: any[]) => any, schema?: Schema, response?: Response): void;
+    private insertDynamic;
+    /**
+     * Create matcher function for route lookup
+     */
+    matcher(): (method: string, pathname: string) => MatchResult | undefined;
+    /**
+     * Dynamic-only matcher (skips static routes)
+     * Used when native routing handles static routes
+     */
+    dynamicOnlyMatcher(): (method: string, pathname: string) => MatchResult | undefined;
+    /**
+     * Get all registered routes as an array of { method, path } objects.
+     *
+     * @example
+     * ```ts
+     * const routes = app.getRoutes();
+     * // [{ method: 'GET', path: '/' }, { method: 'POST', path: '/users' }, ...]
+     * ```
+     */
+    getRoutes(): RouteInfo[];
+    /**
+     * Clear all compiled routes (for recompilation)
+     */
+    clear(): void;
+}
+
+/**
+ * Ken Framework - WebSocket Types
+ * Runtime-agnostic WebSocket abstractions
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+/**
+ * WebSocket message data type
+ */
+type WsMessageData = string | ArrayBuffer | Uint8Array;
+/**
+ * WebSocket ready states
+ */
+declare const WsReadyState: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+type WsReadyStateValue = (typeof WsReadyState)[keyof typeof WsReadyState];
+/**
+ * WebSocket peer - represents a single connected client.
+ *
+ * Provides send/close/subscribe/unsubscribe/publish methods.
+ * The `data` field carries user-defined per-connection state
+ * set via the `upgrade` handler.
+ *
+ * @template T - User-defined per-connection data type
+ */
+interface WsPeer<T = unknown> {
+    /** User-defined per-connection data (set in upgrade handler) */
+    readonly data: T;
+    /** Remote address of the connected client */
+    readonly remoteAddress: string;
+    /** Current ready state of the connection */
+    readonly readyState: WsReadyStateValue;
+    /**
+     * Send a message to this peer.
+     * @param data - Message to send (string, ArrayBuffer, or Uint8Array)
+     * @param compress - Whether to compress this message (default: false)
+     * @returns Number of bytes sent, or -1 if buffered/failed
+     */
+    send(data: WsMessageData, compress?: boolean): number;
+    /**
+     * Close the connection.
+     * @param code - Close status code (default: 1000)
+     * @param reason - Close reason string
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * Subscribe this peer to a topic for pub/sub messaging.
+     * @param topic - Topic name to subscribe to
+     */
+    subscribe(topic: string): void;
+    /**
+     * Unsubscribe this peer from a topic.
+     * @param topic - Topic name to unsubscribe from
+     */
+    unsubscribe(topic: string): void;
+    /**
+     * Publish a message to all subscribers of a topic (excluding this peer).
+     * @param topic - Topic to publish to
+     * @param data - Message data to publish
+     * @param compress - Whether to compress this message (default: false)
+     */
+    publish(topic: string, data: WsMessageData, compress?: boolean): void;
+    /**
+     * Check if this peer is subscribed to a topic.
+     * @param topic - Topic name to check
+     */
+    isSubscribed(topic: string): boolean;
+    /**
+     * Send a ping frame to this peer.
+     * @param data - Optional ping payload
+     */
+    ping(data?: WsMessageData): void;
+    /**
+     * Send a pong frame to this peer.
+     * @param data - Optional pong payload
+     */
+    pong(data?: WsMessageData): void;
+}
+/**
+ * WebSocket event handlers.
+ *
+ * @template T - User-defined per-connection data type
+ *
+ * @example
+ * ```ts
+ * app.ws<{ userId: string }>('/chat', {
+ *   upgrade(req) {
+ *     const token = req.headers.get('authorization');
+ *     return { userId: verifyToken(token) };
+ *   },
+ *   open(peer) {
+ *     peer.subscribe('chat');
+ *     peer.publish('chat', `${peer.data.userId} joined`);
+ *   },
+ *   message(peer, message) {
+ *     peer.publish('chat', `${peer.data.userId}: ${message}`);
+ *   },
+ *   close(peer, code, reason) {
+ *     peer.publish('chat', `${peer.data.userId} left`);
+ *   },
+ * });
+ * ```
+ */
+interface WsHandler<T = unknown> {
+    /**
+     * Called during HTTP→WebSocket upgrade.
+     * Return per-connection data, or a Response to reject the upgrade.
+     * If not provided, upgrades are accepted with `undefined` data.
+     */
+    upgrade?: (req: Request) => T | Response | Promise<T | Response>;
+    /**
+     * Called when a connection is established.
+     */
+    open?: (peer: WsPeer<T>) => void | Promise<void>;
+    /**
+     * Called when a message is received from the client.
+     */
+    message: (peer: WsPeer<T>, message: WsMessageData) => void | Promise<void>;
+    /**
+     * Called when the connection is closed.
+     */
+    close?: (peer: WsPeer<T>, code: number, reason: string) => void | Promise<void>;
+    /**
+     * Called when a ping frame is received.
+     */
+    ping?: (peer: WsPeer<T>, data: WsMessageData) => void;
+    /**
+     * Called when a pong frame is received.
+     */
+    pong?: (peer: WsPeer<T>, data: WsMessageData) => void;
+    /**
+     * Called when an error occurs on the connection.
+     */
+    error?: (peer: WsPeer<T>, error: Error) => void;
+}
+/**
+ * WebSocket configuration options.
+ */
+interface WsOptions {
+    /**
+     * Maximum message size in bytes.
+     * Messages exceeding this limit will close the connection.
+     * @default 16_777_216 (16 MB)
+     */
+    maxPayloadLength?: number;
+    /**
+     * Maximum number of bytes that can be buffered for sending.
+     * @default 16_777_216 (16 MB)
+     */
+    backpressureLimit?: number;
+    /**
+     * Interval in seconds between server-initiated ping frames.
+     * Set to 0 to disable automatic pings.
+     * @default 30
+     */
+    pingInterval?: number;
+    /**
+     * Timeout in seconds to wait for a pong response before closing.
+     * @default 10
+     */
+    pongTimeout?: number;
+    /**
+     * Whether to enable per-message compression.
+     * @default false
+     */
+    perMessageDeflate?: boolean;
+    /**
+     * Idle timeout in seconds. Connections idle for this long are closed.
+     * Set to 0 to disable.
+     * @default 120
+     */
+    idleTimeout?: number;
+}
+/**
+ * Internal WebSocket route registration
+ */
+interface WsRoute<T = unknown> {
+    path: string;
+    handler: WsHandler<T>;
+    options?: WsOptions;
+}
+
+/**
+ * Ken Framework - App
+ * Type-safe routing with schema validation and middleware support
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Infer state shape from middleware definitions.
+ * Excludes middleware with void return types.
+ */
+type InferState<T extends StateMiddleware> = Flatten<{
+    [K in keyof T as Awaited<ReturnType<T[K]>> extends void ? never : K]: Exclude<Awaited<ReturnType<T[K]>>, Response>;
+}>;
+/**
+ * Typed handler function
+ */
+type TypedHandler<S extends Schema = {}, P extends string = string, TState = {}> = (ctx: Context<S, P, TState>) => any;
+/**
+ * App - Type-safe router with schema validation
+ *
+ * Provides full type inference for:
+ * - Route parameters from path patterns
+ * - Query/headers/cookies/body from schema validators
+ * - State from middleware definitions
+ *
+ * @template TState - Accumulated middleware state type
+ */
+declare class App<TState extends StateMiddleware = {}> extends Router {
+    private middleware;
+    /** App-level error handler */
+    private _onError?;
+    /** Not-found handler for this app */
+    private _notFoundHandler?;
+    /** Accumulated not-found entries from child apps (via .use() and .define()) */
+    private _notFoundEntries;
+    /** WebSocket route registrations */
+    wsRoutes: WsRoute<any>[];
+    /**
+     * Set app-level error handler.
+     * Called when route handlers or middleware throw errors.
+     * Route-level onError (in schema) takes priority over app-level.
+     *
+     * @param handler - Error handler function
+     *
+     * @example
+     * ```ts
+     * app.onError((error, ctx) => {
+     *   console.error(ctx.method, ctx.url, error);
+     *   return Response.json(
+     *     { status: 500, message: error instanceof Error ? error.message : 'Internal Server Error' },
+     *     { status: 500 }
+     *   );
+     * });
+     * ```
+     */
+    onError(handler: ErrorHandler): void;
+    /**
+     * Set custom 404 Not Found handler.
+     * Called when no route matches the request.
+     * Supports nested configuration via .use() prefix scoping.
+     *
+     * @param handler - Handler function that receives Context
+     *
+     * @example
+     * ```ts
+     * // App-level
+     * app.notFound((ctx) => {
+     *   return Response.json({ error: 'Not Found', path: ctx.url }, { status: 404 });
+     * });
+     *
+     * // Sub-app with prefix scoping
+     * const api = new App();
+     * api.notFound((ctx) => Response.json({ error: 'API Not Found' }, { status: 404 }));
+     * app.use('/api', api);
+     *
+     * // Define scope with middleware state
+     * app.define({ auth: (ctx) => verifyAuth(ctx) }, (app) => {
+     *   app.notFound((ctx) => Response.json({ error: 'Protected', user: ctx.state.auth }, { status: 404 }));
+     * });
+     * ```
+     */
+    notFound(handler: TypedHandler<{}, string, TState>): void;
+    /**
+     * Apply middleware to routes matching pattern.
+     * Supports both side-effect middleware (function) and state-producing middleware (object).
+     *
+     * @param pattern - Route pattern (default "/*" for all routes)
+     * @param stateOrHandler - State middleware object or handler function
+     *
+     * @example
+     * ```ts
+     * // Side-effect middleware (no state, just side effects)
+     * app.apply('/*', (ctx) => { console.log(ctx.method, ctx.url); });
+     *
+     * // State-producing middleware (adds to ctx.state)
+     * app.apply('/*', { auth: (ctx) => verifyAuth(ctx) });
+     * ```
+     */
+    apply(pattern: string, handler: MiddlewareHandler): void;
+    apply(pattern: string, state: StateMiddleware): void;
+    /**
+     * Define middleware with lexical scoping and automatic type inference.
+     * Routes registered in the callback inherit middleware state types.
+     *
+     * @param state - State middleware object
+     * @param callback - Callback that receives scoped app with accumulated state types
+     */
+    define<S extends StateMiddleware>(state: S, callback: (app: App<Flatten<TState & InferState<S>>>) => void): void;
+    /**
+     * Match middleware patterns against route path.
+     */
+    matchMiddleware(path: string): StateMiddleware[];
+    /**
+     * Simple wildcard pattern matching.
+     */
+    private matchPattern;
+    /**
+     * Merge multiple middleware states with route schema.
+     */
+    mergeSchemas(middlewareStates: StateMiddleware[], routeSchema?: Schema): Schema | undefined;
+    /**
+     * Store raw route registration
+     */
+    private storeRoute;
+    /**
+     * Internal route registration logic
+     */
+    private register;
+    get<P extends string>(path: P, handler: TypedHandler<{}, P, TState>): void;
+    get<S extends Schema, P extends string>(path: P, schema: S, handler: TypedHandler<S, P, TState>): void;
+    get<P extends string, T = unknown>(path: P, staticValue: T): void;
+    get<S extends Schema, P extends string, T = unknown>(path: P, schema: S, staticValue: T): void;
+    post<P extends string>(path: P, handler: TypedHandler<{}, P, TState>): void;
+    post<S extends Schema, P extends string>(path: P, schema: S, handler: TypedHandler<S, P, TState>): void;
+    post<P extends string, T = unknown>(path: P, staticValue: T): void;
+    post<S extends Schema, P extends string, T = unknown>(path: P, schema: S, staticValue: T): void;
+    put<P extends string>(path: P, handler: TypedHandler<{}, P, TState>): void;
+    put<S extends Schema, P extends string>(path: P, schema: S, handler: TypedHandler<S, P, TState>): void;
+    put<P extends string, T = unknown>(path: P, staticValue: T): void;
+    put<S extends Schema, P extends string, T = unknown>(path: P, schema: S, staticValue: T): void;
+    patch<P extends string>(path: P, handler: TypedHandler<{}, P, TState>): void;
+    patch<S extends Schema, P extends string>(path: P, schema: S, handler: TypedHandler<S, P, TState>): void;
+    patch<P extends string, T = unknown>(path: P, staticValue: T): void;
+    patch<S extends Schema, P extends string, T = unknown>(path: P, schema: S, staticValue: T): void;
+    delete<P extends string>(path: P, handler: TypedHandler<{}, P, TState>): void;
+    delete<S extends Schema, P extends string>(path: P, schema: S, handler: TypedHandler<S, P, TState>): void;
+    delete<P extends string, T = unknown>(path: P, staticValue: T): void;
+    delete<S extends Schema, P extends string, T = unknown>(path: P, schema: S, staticValue: T): void;
+    head<P extends string>(path: P, handler: TypedHandler<{}, P, TState>): void;
+    head<S extends Schema, P extends string>(path: P, schema: S, handler: TypedHandler<S, P, TState>): void;
+    head<P extends string, T = unknown>(path: P, staticValue: T): void;
+    head<S extends Schema, P extends string, T = unknown>(path: P, schema: S, staticValue: T): void;
+    options<P extends string>(path: P, handler: TypedHandler<{}, P, TState>): void;
+    options<S extends Schema, P extends string>(path: P, schema: S, handler: TypedHandler<S, P, TState>): void;
+    options<P extends string, T = unknown>(path: P, staticValue: T): void;
+    options<S extends Schema, P extends string, T = unknown>(path: P, schema: S, staticValue: T): void;
+    /**
+     * Mount another App with optional prefix
+     */
+    use(app: App): void;
+    use(prefix: string, app: App): void;
+    /**
+     * Register a WebSocket handler at the given path.
+     *
+     * The generic type parameter `T` defines per-connection data,
+     * which is set in the `upgrade` handler and accessible via `peer.data`.
+     *
+     * @template T - Per-connection data type
+     * @param path - URL path to handle WebSocket upgrades
+     * @param handler - WebSocket event handlers
+     *
+     * @example
+     * ```ts
+     * // Simple echo server
+     * app.ws('/ws', {
+     *   message(peer, message) {
+     *     peer.send(message);
+     *   },
+     * });
+     *
+     * // Chat with authentication and pub/sub
+     * app.ws<{ userId: string }>('/chat', {
+     *   upgrade(req) {
+     *     const token = req.headers.get('authorization');
+     *     return { userId: verifyToken(token) };
+     *   },
+     *   open(peer) {
+     *     peer.subscribe('chat');
+     *     peer.publish('chat', `${peer.data.userId} joined`);
+     *   },
+     *   message(peer, message) {
+     *     peer.publish('chat', `${peer.data.userId}: ${message}`);
+     *   },
+     *   close(peer) {
+     *     peer.publish('chat', `${peer.data.userId} left`);
+     *   },
+     * });
+     *
+     * // With options
+     * app.ws('/live', {
+     *   message(peer, message) { peer.send(message); },
+     * }, {
+     *   pingInterval: 15,
+     *   maxPayloadLength: 1024 * 1024,
+     * });
+     * ```
+     */
+    ws<T = unknown>(path: string, handler: WsHandler<T>, options?: WsOptions): void;
+    /**
+     * Print all registered routes to the console with colored formatting.
+     *
+     * Each HTTP method is color-coded:
+     * - GET (green), POST (blue), PUT (yellow), PATCH (cyan)
+     * - DELETE (red), HEAD (magenta), OPTIONS (white)
+     *
+     * @example
+     * ```ts
+     * app.get('/', 'Hello!');
+     * app.post('/users', handler);
+     * app.get('/users/:id', handler);
+     * app.ws('/chat', wsHandler);
+     * app.printRoutes();
+     * // ┌──────────┬────────────────────┐
+     * // │  Method  │ Path               │
+     * // ├──────────┼────────────────────┤
+     * // │  GET     │ /                  │
+     * // │  POST    │ /users             │
+     * // │  GET     │ /users/:id         │
+     * // │  WS      │ /chat              │
+     * // └──────────┴────────────────────┘
+     * ```
+     */
+    printRoutes(): void;
+    /**
+     * Combine prefix with path
+     */
+    private combinePath;
+}
+
+/**
+ * Ken Framework - AppServer
+ * Combines App routing with automatic runtime detection and server lifecycle.
+ *
+ * Usage:
+ * ```ts
+ * import { AppServer } from 'ken';
+ * const app = new AppServer({ port: 3000 });
+ * app.get('/hello', 'Hello, World!');
+ * await app.run();
+ * ```
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * AppServer initialization options.
+ */
+interface AppServerInit {
+    port?: number;
+    hostname?: string;
+}
+/**
+ * AppServer - App with built-in server lifecycle.
+ *
+ * Extends App with `run()` and `stop()` methods.
+ * Automatically detects the current runtime (Bun, Deno, Node.js)
+ * and lazily loads only the needed adapter.
+ *
+ * @template TState - Accumulated middleware state type
+ */
+declare class AppServer<TState extends StateMiddleware = {}> extends App<TState> {
+    /** Configured hostname */
+    hostname: string;
+    /** Configured port */
+    port: number;
+    private _server;
+    constructor(init?: AppServerInit);
+    /**
+     * Start the server with automatic runtime detection.
+     * Returns the resolved hostname and port.
+     *
+     * @example
+     * ```ts
+     * const app = new AppServer({ port: 3000 });
+     * app.get('/', 'Hello!');
+     * const { hostname, port } = await app.run();
+     * console.log(`Listening on ${hostname}:${port}`);
+     * ```
+     */
+    run(): Promise<{
+        hostname: string;
+        port: number;
+    }>;
+    /**
+     * Stop the server gracefully.
+     */
+    stop(): Promise<void>;
+}
+
+/**
+ * Ken Framework - Runtime Compiler
+ * Generic executor factory for all runtimes
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Default error handler - returns standard JSON error response.
+ * Response errors are passed through directly.
+ *
+ * Error response format:
+ * ```json
+ * { "status": 500, "message": "Internal Server Error" }
+ * ```
+ */
+declare function defaultErrorHandler(err: unknown): Response;
+
+/**
+ * Ken Framework - Runtime Adapters
+ * Auto-detection with lazy loading for each runtime
+ *
+ * Detection order:
+ * 1. Deno → loads deno runtime
+ * 2. Bun → loads bun runtime
+ * 3. Node.js → checks UWS env / uWebSockets.js availability
+ *    - UWS=1|true → use uWebSockets.js (error if not installed)
+ *    - UWS=0|false → use node:http
+ *    - Not set → try uWebSockets.js, fallback to node:http
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/** True when running on Deno */
+declare const isDeno: boolean;
+/** True when running on Bun */
+declare const isBun: boolean;
+/** True when running on Node.js (excludes Bun which also exposes process) */
+declare const isNode: boolean;
+/**
+ * Server instance returned by all runtime adapters.
+ */
+interface Server {
+    /** Start listening. Returns the resolved hostname and port. */
+    run(): Promise<{
+        hostname: string;
+        port: number;
+    }>;
+    /** Gracefully stop the server. */
+    stop(): void | Promise<void>;
+}
+/**
+ * Options accepted by every server factory.
+ */
+interface ServerOptions {
+    port?: number;
+    hostname?: string;
+    router: Router;
+}
+
+/**
+ * Ken Framework - Pathname Utilities
+ * Fast pathname extraction from URLs
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+/**
+ * Fast pathname extraction from URL string
+ * Optimized for hot path - avoids URL object creation
+ */
+declare function getPathname(url: string): string;
+
+/**
+ * Ken Framework - Encryption Utilities
+ * High-performance AES-GCM encryption with key caching
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+/**
+ * Generate a random 256-bit secret key as a base64 string
+ */
+declare function generateSecretKey(): string;
+/**
+ * Encrypt a string using AES-GCM.
+ * Returns base64-encoded: IV (12 bytes) + ciphertext.
+ * Uses cached CryptoKeys and manual base64 for maximum throughput.
+ */
+declare function encryptString(value: string, password: string): Promise<string>;
+/**
+ * Decrypt a base64-encoded encrypted string using AES-GCM.
+ * Uses cached CryptoKeys, manual base64 decode, and subarray (zero-copy) for IV/ciphertext split.
+ */
+declare function decryptString(encrypted: string, password: string): Promise<string>;
+
+/**
+ * Ken Framework - Memoize Utility
+ * High-performance function memoization with configurable cache strategy
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+/**
+ * Options for configuring memoize behavior.
+ */
+interface MemoizeOptions<Args extends unknown[]> {
+    /**
+     * Maximum number of cached entries. When exceeded, the oldest entry is evicted (LRU via insertion order).
+     * @default 256
+     */
+    maxSize?: number;
+    /**
+     * Time-to-live in milliseconds. Entries older than this are considered stale.
+     * When set to 0 or omitted, entries never expire.
+     * @default 0
+     */
+    ttl?: number;
+    /**
+     * Custom key resolver. Receives the same arguments as the memoized function
+     * and must return a string or number to use as the cache key.
+     * Defaults to using the first argument directly (fast path for single-arg functions).
+     */
+    key?: (...args: Args) => string | number;
+}
+interface CacheEntry<T> {
+    value: T;
+    expiry: number;
+}
+/** Memoized function with exposed cache and clear method */
+type MemoizedSync<Args extends unknown[], R> = ((...args: Args) => R) & {
+    cache: Map<string | number, CacheEntry<R>>;
+    clear: () => void;
+};
+/** Memoized async function with exposed cache, inflight map, and clear method */
+type MemoizedAsync<Args extends unknown[], R> = ((...args: Args) => Promise<R>) & {
+    cache: Map<string | number, CacheEntry<R>>;
+    inflight: Map<string | number, Promise<R>>;
+    clear: () => void;
+};
+/**
+ * Create a memoized version of a function. Auto-detects async functions
+ * at creation time and selects the optimal strategy:
+ *
+ * - **Sync**: Map-based cache with LRU eviction and TTL expiry.
+ * - **Async**: Same cache plus in-flight deduplication — concurrent calls
+ *   for the same key share a single Promise (thundering herd protection).
+ *
+ * Detection uses `fn.constructor.name === 'AsyncFunction'` (compile-time branch,
+ * zero per-call overhead).
+ *
+ * @example
+ * ```ts
+ * // Sync — auto-detected
+ * const expensive = memoize((id: string) => computeResult(id));
+ * expensive('abc'); // computes
+ * expensive('abc'); // cached
+ *
+ * // Async — auto-detected, with TTL and max size
+ * const fetchUser = memoize(
+ *   async (id: string) => db.users.findById(id),
+ *   { ttl: 30_000, maxSize: 500 }
+ * );
+ *
+ * // Multi-arg with custom key
+ * const multi = memoize(
+ *   (a: number, b: number) => a + b,
+ *   { key: (a, b) => `${a}:${b}` }
+ * );
+ * ```
+ */
+declare function memoize<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>, options?: MemoizeOptions<Args>): MemoizedAsync<Args, R>;
+declare function memoize<Args extends unknown[], R>(fn: (...args: Args) => R, options?: MemoizeOptions<Args>): MemoizedSync<Args, R>;
+
+/**
+ * Ken Framework - Compression Utilities
+ * High-performance string compression for cookies and JSON storage.
+ *
+ * Uses Web Standard CompressionStream/DecompressionStream API
+ * for cross-runtime compatibility (Bun, Node.js, Deno, Cloudflare Workers).
+ * Output is base64url-encoded (no +, /, or = characters) — safe for
+ * cookies, URLs, and JSON values without escaping.
+ *
+ * Default format is `brotli` — best compression ratio for cookie/session
+ * storage where every byte counts.
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+/** Supported compression formats — extends the Web Standard with brotli (supported by Bun, Node.js, Deno). */
+type SupportedCompressionFormat = CompressionFormat | 'brotli';
+/**
+ * Options for {@link compressString}.
+ *
+ * The `level` range depends on the chosen `encoding`:
+ * - **`brotli`**: 0–11 (default: `11` — best compression, slowest)
+ * - **`deflate` / `gzip` / `deflate-raw`**: 0–9 (default: runtime default, typically `6`)
+ *
+ * Lower values = faster encoding + larger output.
+ * Higher values = slower encoding + smaller output.
+ */
+interface CompressOptions$1 {
+    /** Compression format. Default: `'brotli'`. */
+    encoding?: SupportedCompressionFormat;
+    /**
+     * Compression quality level.
+     * - brotli: 0–11 (default 11)
+     * - deflate / gzip / deflate-raw: 0–9 (default ~6)
+     */
+    level?: number;
+}
+/** Options for {@link decompressString}. */
+interface DecompressOptions {
+    /** Compression format used during compression. Default: `'brotli'`. */
+    encoding?: SupportedCompressionFormat;
+}
+/**
+ * Compress a string and return a base64url-encoded result.
+ * Output is safe for cookies, URLs, and JSON values (no +, /, or = characters).
+ *
+ * Uses `brotli` by default for best compression ratio — produces smaller
+ * output than `deflate` or `gzip`, ideal for cookie/session storage.
+ *
+ * @param input - The string to compress
+ * @param options - Compression options: `encoding` (default `'brotli'`) and optional `level`
+ * @returns Base64url-encoded compressed string
+ *
+ * @example
+ * ```ts
+ * // Best compression (default brotli)
+ * const compressed = await compressString('Hello, World!');
+ *
+ * // Faster, lighter brotli
+ * const fast = await compressString('Hello, World!', { level: 4 });
+ *
+ * // gzip with max compression
+ * const gz = await compressString('Hello, World!', { encoding: 'gzip', level: 9 });
+ * ```
+ */
+declare function compressString(input: string, options?: CompressOptions$1): Promise<string>;
+/**
+ * Decompress a base64url-encoded compressed string back to the original.
+ *
+ * @param compressed - Base64url-encoded compressed string from {@link compressString}
+ * @param options - Decompression options: `encoding` must match what was used to compress (default `'brotli'`)
+ * @returns The original decompressed string
+ *
+ * @example
+ * ```ts
+ * const original = await decompressString(compressed);
+ * // 'Hello, World!'
+ *
+ * const original = await decompressString(compressed, { encoding: 'gzip' });
+ * ```
+ */
+declare function decompressString(compressed: string, options?: DecompressOptions): Promise<string>;
+
+/**
+ * Ken Framework - File Utilities
+ * Cross-runtime file operations: serve, list, upload, save
+ *
+ * Optimized paths per runtime:
+ * - Bun: Uses Bun.file() for zero-copy sendfile responses
+ * - Node.js / Deno: Uses node:fs streams with backpressure-aware ReadableStream
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+/**
+ * Get MIME type from a file path or extension.
+ * Falls back to `application/octet-stream` for unknown types.
+ *
+ * @example
+ * ```ts
+ * getMimeType('photo.jpg')  // 'image/jpeg'
+ * getMimeType('.css')       // 'text/css; charset=utf-8'
+ * ```
+ */
+declare function getMimeType(filePath: string): string;
+/**
+ * Options for {@link sendFile}.
+ */
+interface SendFileOptions {
+    /** Override Content-Type (auto-detected from extension by default) */
+    contentType?: string;
+    /** Trigger browser download. `true` uses original filename, string sets a custom filename. */
+    download?: boolean | string;
+    /** Cache-Control header value (e.g., `'public, max-age=3600'`) */
+    cacheControl?: string;
+    /** Additional response headers */
+    headers?: Record<string, string>;
+    /** HTTP status code override for the full-file response (default: 200) */
+    status?: number;
+    /**
+     * Incoming request headers for conditional and range request support.
+     * Pass `ctx.headers` or the raw `Headers` object.
+     * Enables ETag / If-None-Match, Last-Modified / If-Modified-Since,
+     * and Range (206 Partial Content) handling.
+     */
+    reqHeaders?: Headers | Record<string, string>;
+}
+/**
+ * Options for {@link listDirectory}.
+ */
+interface ListDirectoryOptions {
+    /** Recurse into subdirectories (default: `false`) */
+    recursive?: boolean;
+    /** Maximum recursion depth when `recursive` is `true` (default: `10`) */
+    maxDepth?: number;
+    /** Include file stats — size & modifiedAt (default: `true`) */
+    stats?: boolean;
+    /** Filter entries. Return `true` to include, `false` to skip. */
+    filter?: (entry: FileEntry) => boolean;
+}
+/**
+ * A single file or directory entry returned by {@link listDirectory}.
+ */
+interface FileEntry {
+    /** Filename (including extension) */
+    name: string;
+    /** Relative path from the listed directory root */
+    path: string;
+    /** `true` if the entry is a directory */
+    isDirectory: boolean;
+    /** Size in bytes (`0` for directories, `0` if stats disabled) */
+    size: number;
+    /** Last modified timestamp (epoch 0 if stats disabled) */
+    modifiedAt: Date;
+}
+/**
+ * Options for {@link receiveFiles}.
+ */
+interface ReceiveFileOptions {
+    /** Maximum individual file size in bytes */
+    maxFileSize?: number;
+    /** Maximum number of files to accept */
+    maxFiles?: number;
+    /** Allowed MIME types (e.g., `['image/png', 'image/jpeg']`) */
+    allowedTypes?: string[];
+    /** Only extract files from these form field names */
+    fields?: string[];
+}
+/**
+ * A file extracted by {@link receiveFiles}.
+ */
+interface UploadedFile {
+    /** Form field name the file was submitted under */
+    fieldName: string;
+    /** Original filename from the client */
+    fileName: string;
+    /** MIME type */
+    type: string;
+    /** Size in bytes */
+    size: number;
+    /** Raw file contents */
+    data: ArrayBuffer;
+}
+/**
+ * Serve a file as an HTTP `Response` with correct headers.
+ *
+ * Features:
+ * - Auto-detected Content-Type from file extension
+ * - Range request support (206 Partial Content) for streaming / resumable downloads
+ * - Conditional requests (ETag, Last-Modified → 304 Not Modified)
+ * - Content-Disposition for triggering downloads
+ * - Uses `Bun.file()` on Bun for zero-copy `sendfile` performance
+ *
+ * Returns a **404** `Response` when the file does not exist (no throw).
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * app.get('/files/:name', (ctx) =>
+ *   sendFile(`./public/${ctx.params.name}`)
+ * );
+ *
+ * // With caching and range support
+ * app.get('/media/:file', (ctx) =>
+ *   sendFile(`./media/${ctx.params.file}`, {
+ *     reqHeaders: ctx.headers,
+ *     cacheControl: 'public, max-age=86400',
+ *   })
+ * );
+ *
+ * // Force download
+ * app.get('/download/:file', (ctx) =>
+ *   sendFile(`./files/${ctx.params.file}`, { download: true })
+ * );
+ * ```
+ */
+declare function sendFile(filePath: string, options?: SendFileOptions): Promise<Response>;
+/**
+ * List the contents of a directory with optional metadata.
+ *
+ * Stat calls within each directory level are parallelized via `Promise.all`
+ * for maximum throughput. Uses an iterative stack (no recursion overhead).
+ *
+ * @example
+ * ```ts
+ * // Flat listing
+ * app.get('/browse', async () => {
+ *   return listDirectory('./data');
+ * });
+ *
+ * // Recursive with filter
+ * app.get('/browse/images', async () => {
+ *   return listDirectory('./public', {
+ *     recursive: true,
+ *     filter: (e) => e.isDirectory || e.name.endsWith('.png'),
+ *   });
+ * });
+ * ```
+ */
+declare function listDirectory(dirPath: string, options?: ListDirectoryOptions): Promise<FileEntry[]>;
+/**
+ * Extract uploaded files from `FormData` with validation.
+ *
+ * @example
+ * ```ts
+ * app.post('/upload', async (ctx) => {
+ *   const files = await receiveFiles(await ctx.form, {
+ *     maxFileSize: 10 * 1024 * 1024, // 10 MB
+ *     maxFiles: 5,
+ *     allowedTypes: ['image/png', 'image/jpeg'],
+ *   });
+ *
+ *   for (const file of files) {
+ *     await saveFile(`./uploads/${file.fileName}`, file.data);
+ *   }
+ *   return { uploaded: files.length };
+ * });
+ * ```
+ */
+declare function receiveFiles(formData: FormData, options?: ReceiveFileOptions): Promise<UploadedFile[]>;
+/**
+ * Save data to a file. Auto-creates parent directories when needed.
+ * Works across Bun, Node.js, and Deno.
+ *
+ * @example
+ * ```ts
+ * await saveFile('./uploads/photo.jpg', file.data);
+ * await saveFile('./data/config.json', JSON.stringify(config));
+ * ```
+ */
+declare function saveFile(filePath: string, data: Blob | ArrayBuffer | Uint8Array | string): Promise<void>;
+
+/**
+ * Ken Framework - Basic Authentication Middleware
+ * Validates HTTP Basic Authentication credentials
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the Basic Auth middleware.
+ */
+interface BasicAuthOptions {
+    /** Expected username (required if verifyUser is not provided) */
+    username?: string;
+    /** Expected password (required if verifyUser is not provided) */
+    password?: string;
+    /** Realm for WWW-Authenticate header (default: "Secure Area") */
+    realm?: string;
+    /** Custom verification function. Return true to allow access. */
+    verifyUser?: (username: string, password: string, ctx: Context) => boolean | Promise<boolean>;
+}
+/**
+ * Basic Authentication middleware.
+ *
+ * Validates the `Authorization: Basic <base64>` header.
+ * Returns 401 Response if credentials are missing or invalid.
+ *
+ * @example
+ * ```ts
+ * // Static credentials
+ * app.get("/admin", {
+ *   state: { auth: basicAuth({ username: 'admin', password: 'secret' }) }
+ * }, (ctx) => Response.json({ user: ctx.state.auth.username }));
+ *
+ * // Custom verification
+ * app.get("/admin", {
+ *   state: { auth: basicAuth({ verifyUser: (u, p) => u === 'admin' && p === 'secret' }) }
+ * }, (ctx) => Response.json({ user: ctx.state.auth.username }));
+ * ```
+ */
+declare function basicAuth(options: BasicAuthOptions): ((ctx: Context) => Promise<{
+    username: string;
+} | Response>) | ((ctx: Context) => {
+    username: string;
+} | Response);
+
+/**
+ * Ken Framework - Bearer Authentication Middleware
+ * Validates Bearer token in the Authorization header
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the Bearer Auth middleware.
+ */
+interface BearerAuthOptions {
+    /** Expected token(s). Ignored if verifyToken is provided. */
+    token?: string | string[];
+    /** Custom token verification function. Return true to allow access. */
+    verifyToken?: (token: string, ctx: Context) => boolean | Promise<boolean>;
+    /** Realm for WWW-Authenticate header (default: "") */
+    realm?: string;
+    /** Prefix/scheme for the Authorization header (default: "Bearer") */
+    prefix?: string;
+    /** Header name to read token from (default: "authorization") */
+    headerName?: string;
+}
+/**
+ * Bearer Authentication middleware.
+ *
+ * Validates the `Authorization: Bearer <token>` header.
+ * Returns 401 Response if token is missing or invalid.
+ *
+ * @example
+ * ```ts
+ * app.get("/api/data", {
+ *   state: { auth: bearerAuth({ token: 'my-api-token' }) }
+ * }, (ctx) => Response.json({ token: ctx.state.auth.token }));
+ *
+ * // Multiple valid tokens
+ * app.get("/api/data", {
+ *   state: { auth: bearerAuth({ token: ['token-a', 'token-b'] }) }
+ * }, (ctx) => Response.json({ token: ctx.state.auth.token }));
+ *
+ * // Custom verification
+ * app.get("/api/data", {
+ *   state: { auth: bearerAuth({ verifyToken: async (t) => t === 'dynamic' }) }
+ * }, (ctx) => Response.json({ token: ctx.state.auth.token }));
+ * ```
+ */
+declare function bearerAuth(options: BearerAuthOptions): ((ctx: Context) => Promise<{
+    token: string;
+} | Response>) | ((ctx: Context) => {
+    token: string;
+} | Response);
+
+/**
+ * Ken Framework - Body Limit Middleware
+ * Rejects requests with bodies exceeding the configured size limit
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the Body Limit middleware.
+ */
+interface BodyLimitOptions {
+    /** Maximum body size in bytes */
+    maxSize: number;
+    /** Custom error handler. By default throws 413 Payload Too Large. */
+    onError?: (ctx: Context) => Response;
+}
+/**
+ * Body Limit middleware.
+ *
+ * Checks the `Content-Length` header and rejects requests exceeding the limit.
+ * Returns 413 Payload Too Large response if the body is too large.
+ *
+ * @example
+ * ```ts
+ * // Limit body to 1MB
+ * app.post("/upload", {
+ *   state: { limit: bodyLimit({ maxSize: 1024 * 1024 }) }
+ * }, async (ctx) => {
+ *   const body = await ctx.json;
+ *   return Response.json({ received: true });
+ * });
+ * ```
+ */
+declare function bodyLimit(options: BodyLimitOptions): (ctx: Context) => void | Response;
+
+/**
+ * Ken Framework - Cache Middleware
+ * Sets Cache-Control and related caching headers on responses
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the Cache middleware.
+ */
+interface CacheOptions {
+    /** Cache-Control max-age in seconds (default: 0) */
+    maxAge?: number;
+    /** Cache-Control s-maxage in seconds (for shared caches/CDNs) */
+    sMaxAge?: number;
+    /** Cache-Control stale-while-revalidate in seconds */
+    staleWhileRevalidate?: number;
+    /** Cache-Control stale-if-error in seconds */
+    staleIfError?: number;
+    /** Set `public` directive (default: false) */
+    public?: boolean;
+    /** Set `private` directive (default: false) */
+    private?: boolean;
+    /** Set `no-cache` directive (default: false) */
+    noCache?: boolean;
+    /** Set `no-store` directive (default: false) */
+    noStore?: boolean;
+    /** Set `must-revalidate` directive (default: false) */
+    mustRevalidate?: boolean;
+    /** Set `proxy-revalidate` directive (default: false) */
+    proxyRevalidate?: boolean;
+    /** Set `immutable` directive (default: false) */
+    immutable?: boolean;
+    /** Set `no-transform` directive (default: false) */
+    noTransform?: boolean;
+    /** Custom Vary header value */
+    vary?: string;
+}
+/**
+ * Cache middleware.
+ *
+ * Adds `Cache-Control` and optionally `Vary` headers to responses.
+ *
+ * @example
+ * ```ts
+ * // Cache for 1 hour
+ * app.get("/static", {
+ *   state: { caching: cache({ maxAge: 3600, public: true }) }
+ * }, () => new Response("static content"));
+ *
+ * // No caching
+ * app.get("/dynamic", {
+ *   state: { caching: cache({ noStore: true }) }
+ * }, () => Response.json({ time: Date.now() }));
+ * ```
+ */
+declare function cache(options?: CacheOptions): (ctx: Context) => void;
+
+/**
+ * Ken Framework - Compress Middleware
+ * Detects client-supported compression and provides encoding information
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Supported compression encodings.
+ */
+type CompressionEncoding = 'gzip' | 'deflate' | 'br';
+/**
+ * Options for the Compress middleware.
+ */
+interface CompressOptions {
+    /** Preferred encoding order (default: ['br', 'gzip', 'deflate']) */
+    preferred?: CompressionEncoding[];
+    /** Minimum body size in bytes to compress (default: 1024) */
+    threshold?: number;
+}
+/**
+ * Compress middleware.
+ *
+ * Parses the `Accept-Encoding` header and returns the best encoding
+ * in state. Adds `Vary: Accept-Encoding` to responses.
+ *
+ * Note: Ken delegates actual body compression to the runtime layer.
+ * Bun, Deno, and most reverse proxies handle compression natively.
+ * This middleware provides encoding preference in state and sets
+ * appropriate response headers.
+ *
+ * @example
+ * ```ts
+ * app.get("/data", {
+ *   state: { encoding: compress() }
+ * }, (ctx) => {
+ *   // ctx.state.encoding.encoding is 'gzip' | 'deflate' | 'br' | null
+ *   return Response.json({ data: largePayload });
+ * });
+ * ```
+ */
+declare function compress(options?: CompressOptions): (ctx: Context) => {
+    encoding: CompressionEncoding | null;
+};
+
+/**
+ * Ken Framework - CORS Middleware
+ * Cross-Origin Resource Sharing headers
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the CORS middleware.
+ */
+interface CorsOptions {
+    /**
+     * Allowed origin(s).
+     * - `'*'` allows all origins (default)
+     * - A string matches exactly
+     * - An array of strings matches any
+     * - A function receives the origin and returns the allowed origin
+     */
+    origin?: string | string[] | ((origin: string, ctx: Context) => string);
+    /** Allowed HTTP methods (default: ['GET','HEAD','PUT','POST','DELETE','PATCH']) */
+    allowMethods?: string[];
+    /** Allowed request headers */
+    allowHeaders?: string[];
+    /** Headers exposed to the client */
+    exposeHeaders?: string[];
+    /** Max age for preflight cache in seconds */
+    maxAge?: number;
+    /** Allow credentials (cookies, authorization headers) */
+    credentials?: boolean;
+}
+/**
+ * CORS middleware.
+ *
+ * Returns an App instance that automatically handles preflight OPTIONS requests
+ * and adds CORS headers to all responses for the specified path pattern.
+ *
+ * @example.
+ *
+ * @example
+ * ```ts
+ * // Use CORS for all routes - mount at root
+ * const corsApp = cors();
+ * corsApp.get("/api/data", () => Response.json({ data: 1 }));
+ * app.use(corsApp);
+ *
+ * // Use CORS for specific path prefix
+ * const apiCors = cors({ origin: 'https://example.com', credentials: true });
+ * apiCors.get("/data", () => Response.json({ data: 1 }));
+ * app.use('/api', apiCors);
+ * ```
+ */
+declare function cors(options?: CorsOptions): App;
+
+/**
+ * Ken Framework - CSRF Protection Middleware
+ * Cross-Site Request Forgery protection
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the CSRF middleware.
+ */
+interface CsrfOptions {
+    /**
+     * Allowed origin(s).
+     * - A string matches exactly
+     * - An array of strings matches any
+     * - A function receives the origin and returns true to allow
+     * - If not set, only same-origin requests are allowed
+     */
+    origin?: string | string[] | ((origin: string, ctx: Context) => boolean);
+}
+/**
+ * CSRF Protection middleware.
+ *
+ * Validates the `Origin` header on unsafe requests (POST, PUT, PATCH, DELETE)
+ * with form-compatible content types. Returns 403 if the origin is not allowed.
+ * Safe methods (GET, HEAD, OPTIONS) are always allowed.
+ *
+ * @example
+ * ```ts
+ * // Auto-detect same origin
+ * app.define({ protection: csrf() }, (app) => {
+ *   app.post("/submit", async (ctx) => {
+ *     const body = await ctx.json;
+ *     return Response.json({ success: true });
+ *   });
+ * });
+ *
+ * // Specific origin
+ * app.post("/submit", {
+ *   state: { protection: csrf({ origin: 'https://myapp.example.com' }) }
+ * }, async (ctx) => Response.json({ success: true }));
+ * ```
+ */
+declare function csrf(options?: CsrfOptions): (ctx: Context) => void | Response;
+
+/**
+ * Ken Framework - ETag Middleware
+ * Provides If-None-Match header value for conditional requests
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the ETag middleware.
+ */
+interface ETagOptions {
+    /** Use weak ETags (prefixed with W/) (default: false) */
+    weak?: boolean;
+}
+/**
+ * ETag middleware.
+ *
+ * Reads the `If-None-Match` request header and returns its value in state.
+ * The handler can compare this with its computed ETag to return 304.
+ *
+ * @example
+ * ```ts
+ * app.get("/data", {
+ *   state: { etagValue: etag() }
+ * }, (ctx) => {
+ *   const tag = '"data-v1"';
+ *   if (ctx.state.etagValue === tag) {
+ *     return new Response(null, { status: 304 });
+ *   }
+ *   return new Response("content", { headers: { 'ETag': tag } });
+ * });
+ * ```
+ */
+declare function etag(_options?: ETagOptions): (ctx: Context) => string | null;
+
+/**
+ * Ken Framework - IP Restriction Middleware
+ * Allow or deny requests based on client IP address
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the IP Restriction middleware.
+ */
+interface IpRestrictionOptions {
+    /** List of allowed IP addresses. If set, only these IPs are allowed. */
+    allowList?: string[];
+    /** List of denied IP addresses. Checked after allowList. */
+    denyList?: string[];
+    /** Custom error response factory */
+    onError?: (ctx: Context) => Response;
+}
+/**
+ * IP Restriction middleware.
+ *
+ * Restricts access based on client IP address using the remote info.
+ * Returns 403 if the IP is not in the allow list or is in the deny list.
+ *
+ * Remote IP detection checks proxy headers (CF-Connecting-IP, X-Real-IP,
+ * X-Forwarded-For, True-Client-IP) before falling back to runtime info.
+ *
+ * @example
+ * ```ts
+ * // Allow only specific IPs
+ * app.get("/admin", {
+ *   state: { ipCheck: ipRestriction({ allowList: ['127.0.0.1', '::1'] }) }
+ * }, () => Response.json({ admin: true }));
+ *
+ * // Deny specific IPs
+ * app.get("/public", {
+ *   state: { ipCheck: ipRestriction({ denyList: ['10.0.0.1'] }) }
+ * }, () => new Response("public content"));
+ * ```
+ */
+declare function ipRestriction(options: IpRestrictionOptions): (ctx: Context) => void | Response;
+
+/**
+ * Ken Framework - JWT Middleware
+ * JSON Web Token verification using Web Crypto API
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * JWT payload type
+ */
+interface JWTPayload {
+    /** Issuer */
+    iss?: string;
+    /** Subject */
+    sub?: string;
+    /** Audience */
+    aud?: string | string[];
+    /** Expiration time (seconds since epoch) */
+    exp?: number;
+    /** Not before (seconds since epoch) */
+    nbf?: number;
+    /** Issued at (seconds since epoch) */
+    iat?: number;
+    /** JWT ID */
+    jti?: string;
+    /** Custom claims */
+    [key: string]: unknown;
+}
+/**
+ * Supported HMAC algorithms
+ */
+type JWTAlgorithm = 'HS256' | 'HS384' | 'HS512';
+/**
+ * Options for the JWT middleware.
+ */
+interface JWTOptions {
+    /** HMAC secret key for signature verification */
+    secret: string;
+    /** Expected algorithm (default: 'HS256') */
+    algorithm?: JWTAlgorithm;
+    /** Expected issuer claim */
+    issuer?: string;
+    /** Expected audience claim */
+    audience?: string;
+    /** Header name (default: 'authorization') */
+    headerName?: string;
+    /** Token prefix (default: 'Bearer') */
+    prefix?: string;
+    /** Clock tolerance in seconds for exp/nbf checks (default: 0) */
+    clockTolerance?: number;
+}
+/**
+ * Verify a JWT token and return the payload.
+ *
+ * @param token - The JWT token string
+ * @param secret - The HMAC secret key
+ * @param options - Verification options
+ * @returns The decoded JWT payload
+ * @throws Error if the token is invalid
+ */
+declare function verifyJwt(token: string, secret: string, options?: {
+    algorithm?: JWTAlgorithm;
+    issuer?: string;
+    audience?: string;
+    clockTolerance?: number;
+}): Promise<JWTPayload>;
+/**
+ * Sign a JWT payload and return the token string.
+ *
+ * @param payload - The JWT payload
+ * @param secret - The HMAC secret key
+ * @param algorithm - The algorithm to use (default: 'HS256')
+ * @returns The signed JWT token string
+ */
+declare function signJwt(payload: JWTPayload, secret: string, algorithm?: JWTAlgorithm): Promise<string>;
+/**
+ * Decode a JWT token without verification (unsafe - for debugging only).
+ */
+declare function decodeJwt(token: string): {
+    header: any;
+    payload: JWTPayload;
+};
+/**
+ * JWT middleware.
+ *
+ * Verifies the JWT token from the Authorization header using HMAC.
+ * Returns 401 if the token is missing, invalid, or expired.
+ * Returns the decoded payload.
+ *
+ * @example
+ * ```ts
+ * app.get("/protected", {
+ *   state: { auth: jwt({ secret: 'my-secret-key' }) }
+ * }, (ctx) => Response.json({ user: ctx.state.auth.sub }));
+ * ```
+ */
+declare function jwt(options: JWTOptions): (ctx: Context) => Promise<JWTPayload | Response>;
+
+/**
+ * Ken Framework - JWK Middleware
+ * JSON Web Key Set (JWKS) based JWT verification
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * JWK key object
+ */
+interface JWK {
+    kty: string;
+    kid?: string;
+    use?: string;
+    alg?: string;
+    n?: string;
+    e?: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+    [key: string]: unknown;
+}
+/**
+ * JWKS response
+ */
+interface JWKS {
+    keys: JWK[];
+}
+/**
+ * Options for the JWK middleware.
+ */
+interface JWKOptions {
+    /** URL of the JWKS endpoint */
+    jwksUrl?: string;
+    /** Pre-loaded JWK keys (alternative to jwksUrl) */
+    keys?: JWK[];
+    /** Expected issuer claim */
+    issuer?: string;
+    /** Expected audience claim */
+    audience?: string;
+    /** Header name (default: 'authorization') */
+    headerName?: string;
+    /** Token prefix (default: 'Bearer') */
+    prefix?: string;
+    /** Clock tolerance in seconds for exp/nbf checks (default: 0) */
+    clockTolerance?: number;
+    /** Cache TTL for JWKS keys in milliseconds (default: 600000 = 10 min) */
+    cacheTtl?: number;
+}
+/**
+ * JWK middleware.
+ *
+ * Verifies JWT tokens using JSON Web Key Set (JWKS).
+ * Supports RSA (RS256/384/512) and ECDSA (ES256/384/512) algorithms.
+ * Keys are cached and refreshed automatically.
+ *
+ * @example
+ * ```ts
+ * // With JWKS URL (e.g., from Auth0, Firebase, etc.)
+ * app.get("/protected", {
+ *   state: { auth: jwk({ jwksUrl: 'https://auth.example.com/.well-known/jwks.json' }) }
+ * }, (ctx) => Response.json({ user: ctx.state.auth.sub }));
+ *
+ * // With pre-loaded keys
+ * app.get("/protected", {
+ *   state: { auth: jwk({ keys: [{ kty: 'RSA', n: '...', e: '...' }] }) }
+ * }, (ctx) => Response.json({ user: ctx.state.auth.sub }));
+ * ```
+ */
+declare function jwk(options: JWKOptions): (ctx: Context) => Promise<JWTPayload | Response>;
+
+/**
+ * Ken Framework - Logger Middleware
+ * Logs request/response information
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the Logger middleware.
+ */
+interface LoggerOptions {
+    /** Custom log function (default: console.log) */
+    logFn?: (message: string) => void;
+    /**
+     * Custom log format function.
+     * Receives request info and returns the log message.
+     */
+    format?: (info: {
+        method: string;
+        url: string;
+        status: number;
+        duration: number;
+    }) => string;
+}
+/**
+ * Logger middleware.
+ *
+ * Returns an App instance that logs all requests for all HTTP methods.
+ * Captures method, URL, status code, and response time.
+ *
+ * @example
+ * ```ts
+ * // Use logger for all routes (default console.log with colors)
+ * app.use(logger());
+ * app.get("/api/data", () => Response.json({ data: 1 }));
+ *
+ * // Use logger for specific path prefix
+ * app.use('/api', logger());
+ *
+ * // Custom log function
+ * const logs: string[] = [];
+ * app.use(logger({ logFn: (msg) => logs.push(msg) }));
+ * ```
+ */
+declare function logger(options?: LoggerOptions): App;
+
+/**
+ * Ken Framework - Request ID Middleware
+ * Generates a unique request identifier
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the Request ID middleware.
+ */
+interface RequestIdOptions {
+    /** Custom ID generator (default: crypto.randomUUID) */
+    generator?: () => string;
+    /** Header name to set on the response (default: 'X-Request-Id') */
+    headerName?: string;
+    /** Header name to read from the incoming request. If present, reuses the ID. */
+    requestHeaderName?: string;
+}
+/**
+ * Request ID middleware.
+ *
+ * Generates a unique ID for each request and returns it in state.
+ * Also adds the ID to the response via the specified header.
+ *
+ * @example
+ * ```ts
+ * app.get("/api/data", {
+ *   state: { reqId: requestId() }
+ * }, (ctx) => Response.json({ id: ctx.state.reqId }));
+ * ```
+ */
+declare function requestId(options?: RequestIdOptions): (ctx: Context) => string;
+
+/**
+ * Ken Framework - Secure Headers Middleware
+ * Adds security-related HTTP headers to responses
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the Secure Headers middleware.
+ * Set a header to `false` to disable it, or a string to override its value.
+ */
+interface SecureHeadersOptions {
+    /** Content-Security-Policy (default: not set) */
+    contentSecurityPolicy?: string | false;
+    /** Cross-Origin-Embedder-Policy (default: not set) */
+    crossOriginEmbedderPolicy?: string | false;
+    /** Cross-Origin-Opener-Policy (default: 'same-origin') */
+    crossOriginOpenerPolicy?: string | false;
+    /** Cross-Origin-Resource-Policy (default: 'same-origin') */
+    crossOriginResourcePolicy?: string | false;
+    /** Origin-Agent-Cluster (default: '?1') */
+    originAgentCluster?: string | false;
+    /** Referrer-Policy (default: 'no-referrer') */
+    referrerPolicy?: string | false;
+    /** Strict-Transport-Security (default: 'max-age=15552000; includeSubDomains') */
+    strictTransportSecurity?: string | false;
+    /** X-Content-Type-Options (default: 'nosniff') */
+    xContentTypeOptions?: string | false;
+    /** X-DNS-Prefetch-Control (default: 'off') */
+    xDnsPrefetchControl?: string | false;
+    /** X-Download-Options (default: 'noopen') */
+    xDownloadOptions?: string | false;
+    /** X-Frame-Options (default: 'SAMEORIGIN') */
+    xFrameOptions?: string | false;
+    /** X-Permitted-Cross-Domain-Policies (default: 'none') */
+    xPermittedCrossDomainPolicies?: string | false;
+    /** X-XSS-Protection (default: '0') */
+    xXssProtection?: string | false;
+    /** Remove X-Powered-By header (default: true) */
+    removePoweredBy?: boolean;
+}
+/**
+ * Secure Headers middleware.
+ *
+ * Adds security-related HTTP headers to responses. Uses sensible
+ * defaults inspired by Helmet. Individual headers can be overridden
+ * or disabled.
+ *
+ * @example
+ * ```ts
+ * // Use sensible defaults
+ * app.define({ sec: secureHeaders() }, (app) => {
+ *   app.get("/", () => new Response("secure"));
+ * });
+ *
+ * // Customize
+ * app.define({ sec: secureHeaders({
+ *   xFrameOptions: 'DENY',
+ *   contentSecurityPolicy: "default-src 'self'",
+ * }) }, (app) => {
+ *   app.get("/", () => new Response("secure"));
+ * });
+ * ```
+ */
+declare function secureHeaders(options?: SecureHeadersOptions): (ctx: Context) => void;
+
+/**
+ * Ken Framework - Session Middleware
+ * Flexible session management with customizable validation logic.
+ * Auto-detects sync vs async validation at initialization time.
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the Session middleware.
+ */
+interface SessionOptions<T = any> {
+    /** Name of the cookie to read session from */
+    cookieName: string;
+    /**
+     * Custom validation function.
+     * Receives the cookie value and context.
+     * Return session data on success, or throw/return a Response to deny access.
+     * Returning null/undefined also triggers the unauthorized handler.
+     */
+    validate: (cookieValue: string, ctx: Context) => T | Response | Promise<T | Response>;
+    /**
+     * Custom unauthorized response factory.
+     * Called when cookie is missing, validation returns null, or throws a non-Response error.
+     * Defaults to `new Response('Unauthorized', { status: 401 })`.
+     */
+    onUnauthorized?: (ctx: Context) => Response;
+}
+/**
+ * Session middleware with auto-detection of sync vs async validation.
+ *
+ * Reads a cookie, passes it to a user-supplied `validate` function,
+ * and either returns session data into `ctx.state` or short-circuits
+ * with a `Response`. The sync/async branch is resolved once at
+ * initialization time via `constructor.name` check — zero per-request overhead.
+ *
+ * @example
+ * ```ts
+ * // Sync — in-memory lookup
+ * const auth = session({
+ *   cookieName: '_sid',
+ *   validate: (sid) => {
+ *     const user = USERS.get(sid);
+ *     if (!user) throw new Response('Unauthorized', { status: 401 });
+ *     return user;
+ *   },
+ * });
+ *
+ * // Async — encrypted cookie + DB lookup
+ * const auth = session({
+ *   cookieName: '_ak',
+ *   validate: async (cookieValue, ctx) => {
+ *     const apiKey = await decryptString(cookieValue, secretKey);
+ *     if (!MEDIA_OWNERS[apiKey]?.active) {
+ *       throw new Response(null, {
+ *         status: 302,
+ *         headers: { 'Location': '/auth?redirect=' + ctx.url },
+ *       });
+ *     }
+ *     return apiKey;
+ *   },
+ * });
+ *
+ * app.get('/', { state: { session: auth } }, (ctx) => {
+ *   return Response.json({ key: ctx.state.session });
+ * });
+ * ```
+ */
+declare function session<T = any>(options: SessionOptions<T>): ((ctx: Context) => Promise<T | Response>) | ((ctx: Context) => T | Response);
+
+/**
+ * Ken Framework - Timeout Middleware
+ * Provides request timeout capabilities via AbortSignal
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the Timeout middleware.
+ */
+interface TimeoutOptions {
+    /** Timeout duration in milliseconds */
+    duration: number;
+    /** Custom timeout response (default: 408 Request Timeout) */
+    onTimeout?: (ctx: Context) => Response;
+}
+/**
+ * Timeout middleware.
+ *
+ * Creates an AbortController with a timeout. Returns the AbortSignal
+ * in state so the handler can check for timeout or pass it to fetch calls.
+ * The timer is automatically cleared when the response finishes.
+ *
+ * @example
+ * ```ts
+ * app.get("/slow-endpoint", {
+ *   state: { timeoutSig: timeout({ duration: 5000 }) }
+ * }, async (ctx) => {
+ *   // Pass signal to downstream fetch calls
+ *   const data = await fetch('https://api.example.com/data', {
+ *     signal: ctx.state.timeoutSig.signal,
+ *   });
+ *   return Response.json(await data.json());
+ * });
+ * ```
+ */
+declare function timeout(options: TimeoutOptions): (ctx: Context) => {
+    signal: AbortSignal;
+} | Response;
+
+/**
+ * Ken Framework - Timing Middleware
+ * Server-Timing header for performance monitoring
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Options for the Timing middleware.
+ */
+interface TimingOptions {
+    /** Metric name (default: 'total') */
+    name?: string;
+    /** Description for the Server-Timing entry */
+    description?: string;
+    /** Whether to include the timing header (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Timing middleware.
+ *
+ * Measures request processing time and adds a `Server-Timing` header
+ * to the response. Useful for performance monitoring.
+ *
+ * @example
+ * ```ts
+ * app.define({ perf: timing() }, (app) => {
+ *   app.get("/api/data", () => Response.json({ data: 1 }));
+ * });
+ * // Response header: Server-Timing: total;dur=2.5
+ *
+ * // Custom metric name
+ * app.get("/api/data", {
+ *   state: { perf: timing({ name: 'app', description: 'Application processing' }) }
+ * }, () => Response.json({ data: 1 }));
+ * // Response header: Server-Timing: app;desc="Application processing";dur=2.5
+ * ```
+ */
+declare function timing(options?: TimingOptions): (ctx: Context) => void;
+
+/**
+ * Ken Framework - WSClient Protocol Middleware
+ * Transparently handles the Ken Binary WebSocket Protocol (KBWP) for WSClient users.
+ *
+ * Includes:
+ *   - wsClientProtocol: registers a WebSocket route with full KBWP support
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Combined handler + options definition passed to {@link wsClientProtocol}.
+ *
+ * Merges all {@link WsHandler} callbacks and {@link WsOptions} fields into
+ * a single object so there is only one place to configure a WebSocket route.
+ *
+ * @template T - Per-connection data type
+ */
+interface WsDefinition<T = unknown> extends WsHandler<T> {
+    /** @see WsOptions.maxPayloadLength */
+    maxPayloadLength?: number;
+    /** @see WsOptions.backpressureLimit */
+    backpressureLimit?: number;
+    /** @see WsOptions.pingInterval */
+    pingInterval?: number;
+    /** @see WsOptions.pongTimeout */
+    pongTimeout?: number;
+    /** @see WsOptions.perMessageDeflate */
+    perMessageDeflate?: boolean;
+    /** @see WsOptions.idleTimeout */
+    idleTimeout?: number;
+    /**
+     * Authentication handler. When provided, all connections must authenticate
+     * via post-connect AUTH binary frame or URL query parameter (dev/staging).
+     *
+     * Called with the token string. Return user data (`T`) on success,
+     * or `null` to reject the connection.
+     *
+     * When not provided, auth is disabled — all connections pass through.
+     *
+     * @example
+     * ```ts
+     * wsClientProtocol<{ userId: string }>({
+     *   authenticate: async (token) => {
+     *     const user = await verifyJwt(token);
+     *     if (!user) return null;
+     *     return { userId: user.id };
+     *   },
+     *   message(peer, msg) {
+     *     // peer.data.userId is available here
+     *   },
+     * });
+     * ```
+     */
+    authenticate?: (token: string) => T | null | Promise<T | null>;
+    /**
+     * URL query parameter name for token-based auth (dev/staging support).
+     * When a connection URL contains this parameter, the token is validated
+     * during upgrade and the connection is pre-authenticated.
+     * Only used when `authenticate` is provided.
+     * @default 'token'
+     */
+    tokenParam?: string;
+}
+/**
+ * WebSocket middleware with full WSClient binary protocol (KBWP) support.
+ *
+ * Registers a WebSocket route at '/' and transparently handles the Ken
+ * Binary WebSocket Protocol — heartbeat (ping/pong), pub/sub, and
+ * request-response — so your `message` handler only receives domain messages.
+ *
+ * Returns an `App` instance so it composes naturally with `app.use()`.
+ * The path is supplied via the `app.use()` call, which prepends it to the
+ * WebSocket route.
+ *
+ * **Binary protocol messages intercepted (client → server):**
+ * - PING (0x01) → responds with PONG (0x02)
+ * - SUBSCRIBE (0x05) → calls `peer.subscribe(topic)`
+ * - UNSUBSCRIBE (0x06) → calls `peer.unsubscribe(topic)`
+ * - PUBLISH (0x07) → calls `peer.publish(topic, jsonEnvelope)`
+ *   so all topic subscribers receive a `{"type":"message",...}` envelope
+ *   that `WSClient` knows how to route.
+ * - REQUEST (0x03) → calls user `message` handler with decoded payload;
+ *   the first `peer.send()` is automatically wrapped in a RESPONSE (0x04)
+ *   frame echoing the correlation ID.
+ *
+ * **Non-binary messages** (plain strings) are forwarded directly to the
+ * user `message` handler without any protocol interception.
+ *
+ * All `WsOptions` fields can be co-located in the `config` object.
+ *
+ * @example
+ * ```ts
+ * // Mount at a path (no auth)
+ * app.use('/chat', wsClientProtocol({
+ *   pingInterval: 20,
+ *   idleTimeout: 60,
+ *   upgrade(req) {
+ *     const name = new URL(req.url).searchParams.get('name') ?? 'anon';
+ *     return { username: name };
+ *   },
+ *   open(peer) { peer.subscribe('chat'); },
+ *   message(peer, msg) { peer.send(`echo: ${msg}`); },
+ *   close(peer) { peer.unsubscribe('chat'); },
+ * }));
+ *
+ * // With post-connect binary auth (secure, invisible in logs)
+ * app.use('/ws', wsClientProtocol<{ userId: string }>({
+ *   authenticate: async (token) => {
+ *     const user = await verifyJwt(token);
+ *     return user ? { userId: user.id } : null;
+ *   },
+ *   // tokenParam: 'token', // also accepts ?token= in URL (for Insomnia/dev)
+ *   open(peer) { console.log('authed:', peer.data.userId); },
+ *   message(peer, msg) { peer.send(msg); },
+ * }));
+ * ```
+ *
+ * @template T - Per-connection data type
+ * @param config - Handler callbacks and optional WsOptions, co-located in one object
+ * @returns An `App` instance ready to be passed to `app.use()`
+ */
+declare function wsClientProtocol<T = unknown>(config: WsDefinition<T>): App;
+
+/**
+ * Ken Framework - Binary WebSocket Protocol Codec (KBWP)
+ *
+ * Compact binary framing for WebSocket messages optimized for bandwidth-
+ * constrained environments (4G, IoT, mobile). Eliminates JSON protocol
+ * overhead while preserving full pub/sub and request-response semantics.
+ *
+ * Frame layout (all multi-byte integers are big-endian):
+ *
+ *   ┌──────────┬──────────────────────────────────────────┐
+ *   │ Type (1B)│ Type-specific fields (variable)          │
+ *   └──────────┴──────────────────────────────────────────┘
+ *
+ * Message types:
+ *   0x01  PING         []                                   1 byte
+ *   0x02  PONG         []                                   1 byte
+ *   0x03  REQUEST      [corrId:u32] [payload…]              5+ bytes
+ *   0x04  RESPONSE     [corrId:u32] [payload…]              5+ bytes
+ *   0x05  SUBSCRIBE    [topicLen:u8] [topic…]               2+ bytes
+ *   0x06  UNSUBSCRIBE  [topicLen:u8] [topic…]               2+ bytes
+ *   0x07  PUBLISH      [topicLen:u8] [topic…] [payload…]    2+ bytes
+ *   0x08  MESSAGE      [topicLen:u8] [topic…] [payload…]    2+ bytes
+ *   0x09  AUTH         [payload…]                           1+ bytes
+ *   0x0A  AUTH_OK      [payload…]                           1+ bytes
+ *   0x0B  AUTH_FAIL    [payload…]                           1+ bytes
+ *
+ * Payload is the remaining bytes after fixed-length fields — no length
+ * prefix needed because WebSocket frames are already length-delimited.
+ *
+ * Bandwidth comparison vs JSON:
+ *   Ping:       1 byte vs 15 bytes ({"type":"ping"})           → 93% reduction
+ *   Subscribe:  ~6 bytes vs ~35 bytes                          → 83% reduction
+ *   Request:    5 + N vs 20 + N (JSON _kid overhead)           → significant
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+/** Binary protocol message type identifiers */
+declare const MsgType: {
+    readonly PING: 1;
+    readonly PONG: 2;
+    readonly REQUEST: 3;
+    readonly RESPONSE: 4;
+    readonly SUBSCRIBE: 5;
+    readonly UNSUBSCRIBE: 6;
+    readonly PUBLISH: 7;
+    readonly MESSAGE: 8;
+    readonly AUTH: 9;
+    readonly AUTH_OK: 10;
+    readonly AUTH_FAIL: 11;
+};
+type MsgTypeValue = (typeof MsgType)[keyof typeof MsgType];
+interface DecodedPing {
+    readonly type: typeof MsgType.PING;
+}
+interface DecodedPong {
+    readonly type: typeof MsgType.PONG;
+}
+interface DecodedRequest {
+    readonly type: typeof MsgType.REQUEST;
+    readonly corrId: number;
+    /** Raw JSON string payload (caller parses if needed) */
+    readonly payload: string;
+}
+interface DecodedResponse {
+    readonly type: typeof MsgType.RESPONSE;
+    readonly corrId: number;
+    /** Raw JSON string payload (caller parses if needed) */
+    readonly payload: string;
+}
+interface DecodedSubscribe {
+    readonly type: typeof MsgType.SUBSCRIBE;
+    readonly topic: string;
+}
+interface DecodedUnsubscribe {
+    readonly type: typeof MsgType.UNSUBSCRIBE;
+    readonly topic: string;
+}
+interface DecodedPublish {
+    readonly type: typeof MsgType.PUBLISH;
+    readonly topic: string;
+    /** Raw JSON string payload (caller parses if needed) */
+    readonly payload: string;
+}
+interface DecodedMessage {
+    readonly type: typeof MsgType.MESSAGE;
+    readonly topic: string;
+    /** Raw JSON string payload (caller parses if needed) */
+    readonly payload: string;
+}
+interface DecodedAuth {
+    readonly type: typeof MsgType.AUTH;
+    /** Auth token */
+    readonly payload: string;
+}
+interface DecodedAuthOk {
+    readonly type: typeof MsgType.AUTH_OK;
+    /** Optional data from server (may be empty) */
+    readonly payload: string;
+}
+interface DecodedAuthFail {
+    readonly type: typeof MsgType.AUTH_FAIL;
+    /** Reason string */
+    readonly payload: string;
+}
+type DecodedFrame = DecodedPing | DecodedPong | DecodedRequest | DecodedResponse | DecodedSubscribe | DecodedUnsubscribe | DecodedPublish | DecodedMessage | DecodedAuth | DecodedAuthOk | DecodedAuthFail;
+/** Returns the pre-allocated 1-byte PING frame. Do NOT mutate. */
+declare function encodePing(): Uint8Array;
+/** Returns the pre-allocated 1-byte PONG frame. Do NOT mutate. */
+declare function encodePong(): Uint8Array;
+/**
+ * Encode a REQUEST frame: [0x03][corrId:u32][payload UTF-8…]
+ *
+ * @param corrId  - Correlation ID (uint32, 0–4294967295)
+ * @param payload - JSON string payload
+ */
+declare function encodeRequest(corrId: number, payload: string): Uint8Array;
+/**
+ * Encode a RESPONSE frame: [0x04][corrId:u32][payload UTF-8…]
+ *
+ * @param corrId  - Correlation ID echoed from the REQUEST
+ * @param payload - Response data (string or binary)
+ */
+declare function encodeResponse(corrId: number, payload: string | Uint8Array): Uint8Array;
+/**
+ * Encode a SUBSCRIBE frame: [0x05][topicLen:u8][topic UTF-8…]
+ *
+ * @param topic - Topic name (max 255 UTF-8 bytes)
+ */
+declare function encodeSubscribe(topic: string): Uint8Array;
+/**
+ * Encode an UNSUBSCRIBE frame: [0x06][topicLen:u8][topic UTF-8…]
+ *
+ * @param topic - Topic name (max 255 UTF-8 bytes)
+ */
+declare function encodeUnsubscribe(topic: string): Uint8Array;
+/**
+ * Encode a PUBLISH frame: [0x07][topicLen:u8][topic UTF-8…][payload UTF-8…]
+ *
+ * @param topic   - Topic name (max 255 UTF-8 bytes)
+ * @param payload - JSON string payload
+ */
+declare function encodePublish(topic: string, payload: string): Uint8Array;
+/**
+ * Encode a MESSAGE frame: [0x08][topicLen:u8][topic UTF-8…][payload UTF-8…]
+ *
+ * @param topic   - Topic name (max 255 UTF-8 bytes)
+ * @param payload - JSON string payload
+ */
+declare function encodeMessage(topic: string, payload: string): Uint8Array;
+/**
+ * Decode a binary WebSocket frame into a typed message.
+ *
+ * @param data - Raw binary data (ArrayBuffer or Uint8Array)
+ * @returns Decoded frame, or `null` if the type byte is unrecognized or
+ *          the frame is too short for the declared type.
+ */
+declare function decode(data: ArrayBuffer | Uint8Array): DecodedFrame | null;
+/**
+ * Check if a binary buffer starts with a known Ken protocol type byte.
+ * Use this as a fast pre-check before calling `decode()`.
+ *
+ * @param data - Binary data (first byte is checked)
+ * @returns true if byte 0 is a recognized MsgType
+ */
+declare function isKenBinaryFrame(data: ArrayBuffer | Uint8Array): boolean;
+
+/**
+ * Ken Framework - WSClient
+ * High-performance, fault-tolerant WebSocket client with binary protocol.
+ * Zero-dependency. Works on Bun, Deno, and Node.js.
+ *
+ * Uses the Ken Binary WebSocket Protocol (KBWP) for minimal bandwidth
+ * overhead — optimized for 24/7 operation on bandwidth-constrained devices.
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/** Connection state enum — use numeric values for fast comparison */
+declare const WsClientState: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+    readonly RECONNECTING: 4;
+};
+type WsClientStateValue = (typeof WsClientState)[keyof typeof WsClientState];
+/**
+ * WSClient configuration options
+ */
+interface WsClientOptions {
+    /**
+     * Auth token. Sent as a binary AUTH frame (post-connect, secure)
+     * or as a `?token=` URL param depending on `authMode`.
+     */
+    token?: string;
+    /**
+     * How to send the auth token:
+     * - `'message'` — Post-connect binary AUTH frame (secure, invisible in logs). Default.
+     * - `'query'`   — URL query parameter (visible in logs, for dev tools like Insomnia).
+     *
+     * Only relevant when `token` is set. Ignored otherwise.
+     * @default 'message'
+     */
+    authMode?: 'message' | 'query';
+    /**
+     * Milliseconds to wait for AUTH_OK after sending AUTH frame.
+     * Only used when `authMode` is `'message'`.
+     * @default 10_000
+     */
+    authTimeout?: number;
+    /**
+     * Maximum number of reconnect attempts. Default: Infinity.
+     */
+    maxRetries?: number;
+    /**
+     * Multiplier applied to the backoff delay after each failed attempt.
+     * Default: 2
+     */
+    backoffFactor?: number;
+    /**
+     * Maximum backoff delay in ms. Default: 30_000
+     */
+    backoffMax?: number;
+    /**
+     * Base reconnect delay in ms. Default: 500
+     */
+    backoffBase?: number;
+    /**
+     * Milliseconds between application-level heartbeat pings.
+     * Set to 0 to disable. Default: 30_000
+     */
+    heartbeatInterval?: number;
+    /**
+     * Milliseconds before a `sendWait()` call times out. Default: 10_000
+     */
+    requestTimeout?: number;
+    /**
+     * Event hook — called for every incoming binary protocol frame.
+     * Receives the decoded frame object. Fires after internal routing
+     * (REQUEST/RESPONSE correlation, pub/sub dispatch) has been applied.
+     */
+    onFrame?: (frame: DecodedFrame) => void;
+    /**
+     * Event hook — called when the connection is established.
+     */
+    onConnect?: () => void;
+    /**
+     * Event hook — called when the connection is lost.
+     * Receives the WebSocket close code and reason.
+     */
+    onDisconnect?: (code: number, reason: string) => void;
+    /**
+     * Event hook — called before each reconnect attempt.
+     * Receives the attempt number (1-based) and the delay in ms.
+     */
+    onReconnectAttempt?: (attempt: number, delay: number) => void;
+    /**
+     * Event hook — called for every incoming message.
+     */
+    onData?: (data: string | ArrayBuffer) => void;
+}
+/**
+ * Ken WSClient — A fault-tolerant, high-performance WebSocket client
+ * with binary protocol transport.
+ *
+ * Features:
+ * - Ken Binary WebSocket Protocol (KBWP) — 80-93% bandwidth reduction
+ *   over JSON for protocol messages (ping/pong, subscribe, publish)
+ * - State machine (CONNECTING / OPEN / CLOSING / CLOSED / RECONNECTING)
+ * - Exponential backoff + jitter reconnection
+ * - 1-byte binary heartbeat (ping/pong)
+ * - Request-response via `sendWait()` with uint32 correlation IDs
+ *   (no field collision — corrId lives in binary header, not payload)
+ * - Pub/sub with binary framing (subscribe/unsubscribe/publish/message)
+ * - Full lifecycle hooks: onConnect, onDisconnect, onReconnectAttempt, onData
+ * - Zero memory leaks — all timers and listeners are strictly cleaned up
+ *
+ * @example
+ * ```ts
+ * const client = new WSClient('wss://api.example.com/ws', {
+ *   token: 'my-jwt',
+ *   onConnect: () => console.log('Connected'),
+ *   onDisconnect: (code) => console.log('Disconnected', code),
+ * });
+ *
+ * await client.connect();
+ *
+ * // Fire-and-forget (raw string — not wrapped in binary protocol)
+ * client.send('hello');
+ *
+ * // Request-response (binary REQUEST frame, no _kid collision)
+ * const result = await client.sendWait({ type: 'getData', id: 42 });
+ *
+ * // Pub/sub (binary SUBSCRIBE/PUBLISH frames)
+ * client.subscribe('events', (data) => console.log(data));
+ * client.publish('events', { action: 'click' });
+ *
+ * await client.close();
+ * ```
+ */
+declare class WSClient {
+    /** Current state of the connection */
+    state: WsClientStateValue;
+    private readonly _url;
+    private readonly _authTimeout;
+    private readonly _maxRetries;
+    private readonly _backoffFactor;
+    private readonly _backoffMax;
+    private readonly _backoffBase;
+    private readonly _heartbeatInterval;
+    private readonly _requestTimeout;
+    private readonly _onConnect;
+    private readonly _onDisconnect;
+    private readonly _onReconnectAttempt;
+    private readonly _onData;
+    private readonly _onFrame;
+    /** Active WebSocket instance */
+    private _ws;
+    /** Number of consecutive failed reconnect attempts */
+    private _retries;
+    /** Correlation registry: corrId (uint32) → PendingRequest */
+    private _pending;
+    /**
+     * Active pub/sub subscriptions: topic → callback.
+     * Persists across reconnects so topics are re-sent in _onOpen.
+     */
+    private _subscriptions;
+    /** Heartbeat timer handle */
+    private _heartbeatTimer;
+    /** Reconnect delay timer handle */
+    private _reconnectTimer;
+    /** Whether destroy() / close() was explicitly called */
+    private _destroyed;
+    /** Post-connect auth resolve/reject for the connect() promise */
+    private _authResolve;
+    private _authReject;
+    /** Auth timeout timer handle */
+    private _authTimer;
+    /** Whether auth is pending (post-connect, waiting for AUTH_OK/AUTH_FAIL) */
+    private _authPending;
+    /** Pre-encoded AUTH frame — zero per-reconnect allocation */
+    private readonly _authFrame;
+    /**
+     * Monotonically increasing uint32 counter for correlation IDs.
+     * Wraps at 0xFFFFFFFF to stay within 4-byte range.
+     */
+    private _idCounter;
+    private readonly _handleOpen;
+    private readonly _handleMessage;
+    private readonly _handleClose;
+    private readonly _handleError;
+    constructor(url: string, options?: WsClientOptions);
+    /**
+     * Connect to the WebSocket server.
+     * Returns a Promise that resolves when the connection is established.
+     * Safe to call multiple times — subsequent calls while already OPEN are no-ops.
+     */
+    connect(): Promise<void>;
+    /**
+     * Send a raw string or binary message. The connection must be OPEN.
+     * For fire-and-forget use cases.
+     *
+     * @returns true if sent, false if not connected.
+     */
+    send(data: string | ArrayBuffer | Uint8Array<ArrayBuffer>): boolean;
+    /**
+     * Send a JSON message and wait for a correlated response.
+     *
+     * Uses the binary REQUEST frame format: [0x03][corrId:u32][JSON payload].
+     * The correlation ID is carried in the binary header — NOT mixed into the
+     * user payload — eliminating the previous `_kid` field collision issue.
+     *
+     * The server must respond with a binary RESPONSE frame echoing the same
+     * corrId. When using `defineWsHandler`, this is handled automatically.
+     *
+     * @param data - Object to JSON-serialize and send.
+     * @param timeout - Override the default `requestTimeout` for this request.
+     * @returns Promise resolving with the parsed response payload.
+     * @throws If the connection is not open, the request times out, or the
+     *         connection closes before a response arrives.
+     */
+    sendWait<T = unknown>(data: Record<string, unknown>, timeout?: number): Promise<T>;
+    /**
+     * Subscribe to a server-side topic.
+     * Sends `{"type":"subscribe","topic":"..."}` to the server and registers a
+     * local callback invoked for each `{"type":"message","topic":"...","data":...}`
+     * frame received on that topic.
+     *
+     * Safe to call before `connect()` — the subscription is registered locally
+     * and sent once the connection opens (or re-opens after reconnect).
+     *
+     * Calling with the same topic replaces the existing callback.
+     *
+     * @param topic    - Topic name to subscribe to
+     * @param callback - Called with the `data` field from each topic message
+     */
+    subscribe(topic: string, callback: (data: unknown) => void): void;
+    /**
+     * Unsubscribe from a server-side topic.
+     * Sends `{"type":"unsubscribe","topic":"..."}` if currently connected.
+     * The local callback is removed regardless of connection state.
+     *
+     * @param topic - Topic name to unsubscribe from
+     */
+    unsubscribe(topic: string): void;
+    /**
+     * Publish a message to a server-side topic.
+     * Sends `{"type":"publish","topic":"...","data":...}` to the server.
+     * The server (when using `defineWsHandler`) re-broadcasts the message to all
+     * topic subscribers as `{"type":"message","topic":"...","data":...}`.
+     *
+     * @param topic - Topic to publish to
+     * @param data  - Payload (JSON-serializable)
+     * @returns true if sent, false if not connected
+     */
+    publish(topic: string, data: unknown): boolean;
+    /**
+     * Gracefully close the connection.
+     * Does NOT reconnect. Cleans up all resources.
+     */
+    close(code?: number, reason?: string): Promise<void>;
+    private _openConnection;
+    /** Open handler for auth mode — sends pre-encoded AUTH frame */
+    private _onOpenAuth;
+    /** Open handler for no-auth mode — proceeds directly to _finishOpen */
+    private _onOpenNoAuth;
+    /**
+     * Complete the open sequence: re-subscribe, start heartbeat, fire onConnect.
+     * Called directly from _onOpen (no auth) or from _onMessage after AUTH_OK.
+     */
+    private _finishOpen;
+    private _onMessage;
+    private _onClose;
+    private _onError;
+    private _scheduleReconnect;
+    /**
+     * Exponential backoff with full jitter to avoid thundering-herd reconnects.
+     * delay = random(0, min(backoffMax, backoffBase * backoffFactor^attempt))
+     */
+    private _computeBackoff;
+    private _clearReconnectTimer;
+    private _startHeartbeat;
+    private _stopHeartbeat;
+    private _detachHandlers;
+    /**
+     * Returns a monotonically increasing uint32 correlation ID.
+     * Wraps at 0xFFFFFFFF back to 1 (zero is reserved).
+     * No random component needed — IDs are scoped to a single connection
+     * and the uint32 space (4B values) far exceeds concurrent in-flight requests.
+     */
+    private _nextId;
+}
+
+/**
+ * Ken Framework - WebSocket Pub/Sub
+ *
+ * Two pub/sub abstractions:
+ *
+ * 1. PubSubHub — low-level exclude-sender pub/sub.
+ *    Used by Deno/Node peer adapters for WsPeer.subscribe / WsPeer.publish.
+ *    On Bun and uWS, native pub/sub is used directly by the peer adapters.
+ *
+ * 2. WsTopicHub — MQTT/Redis-style per-topic message routing.
+ *    Per-topic callbacks, include-all (broadcast) publish, dead peer detection.
+ *    Works uniformly across all runtimes.
+ *
+ * MIT License - Copyright (c) 2025 Indra Gunawan
+ */
+
+/**
+ * Per-topic message callback.
+ * Invoked when hub.dispatch(peer, message) is called for a subscribed peer.
+ *
+ * @template T - Per-connection data type
+ */
+type TopicCallback<T = unknown> = (peer: WsPeer<T>, message: WsMessageData) => void | Promise<void>;
+/**
+ * WsTopicHub — MQTT/Redis-style topic-based pub/sub for WebSocket servers.
+ *
+ * **Key differences from WsPeer.subscribe/publish:**
+ * - `hub.subscribe(peer, topic, callback)` registers a per-topic message handler
+ * - `hub.publish(topic, data)` broadcasts to ALL subscribers (including sender)
+ * - `hub.dispatch(peer, msg)` routes a message to the peer's topic callbacks
+ * - Dead peer detection via `markAlive()` + `startDeadPeerCheck()`
+ * - Works uniformly across Bun, Node, Deno, and uWS
+ *
+ * Uses native runtime pub/sub (Bun/uWS `peer.subscribe/publish`) for "exclude self"
+ * semantics when callers use `peer.publish()` directly. Hub publish() always uses
+ * an in-memory iterator for include-all broadcast.
+ *
+ * @template T - Per-connection data type
+ *
+ * @example
+ * ```ts
+ * const hub = new WsTopicHub<{ username: string }>();
+ *
+ * app.ws<{ username: string }>('/chat', {
+ *   upgrade(req) {
+ *     const name = new URL(req.url).searchParams.get('name') ?? 'anon';
+ *     return { username: name };
+ *   },
+ *   open(peer) {
+ *     hub.subscribe(peer, 'chat', (peer, msg) => {
+ *       hub.publish('chat', `${peer.data.username}: ${msg}`);
+ *     });
+ *   },
+ *   message(peer, msg) {
+ *     hub.dispatch(peer, msg);   // routes to topic callbacks
+ *   },
+ *   close(peer) {
+ *     hub.leave(peer);           // cleanup all subscriptions
+ *   },
+ *   pong(peer) {
+ *     hub.markAlive(peer);       // dead peer detection (Bun/Node/uWS)
+ *   },
+ * }, { pingInterval: 30 });
+ *
+ * // Server-initiated broadcast (from any route or CRON)
+ * hub.publish('chat', 'System: restarting in 60s');
+ *
+ * // Start automatic dead peer cleanup
+ * hub.startDeadPeerCheck(5_000, 120_000);
+ * ```
+ */
+declare class WsTopicHub<T = unknown> {
+    /** topic → Set<peer> — O(1) publish iteration */
+    private _topics;
+    /** peer → Map<topic, callback> — O(1) dispatch and cleanup */
+    private _peerTopics;
+    /** peer → last-pong timestamp (ms) — for dead peer detection */
+    private _lastPong;
+    private _deadPeerTimer;
+    /**
+     * Subscribe a peer to a topic with a per-message callback.
+     *
+     * The callback is invoked whenever `hub.dispatch(peer, msg)` is called while
+     * the peer is subscribed to this topic.
+     *
+     * A peer may be subscribed to multiple topics simultaneously, each with its
+     * own callback. Subsequent calls with the same topic replace the handler.
+     *
+     * @param peer    - The connected WebSocket peer
+     * @param topic   - Topic name (e.g. 'chat', 'notifications', 'room/42')
+     * @param handler - Called with (peer, message) on each dispatched message
+     */
+    subscribe(peer: WsPeer<T>, topic: string, handler: TopicCallback<T>): void;
+    /**
+     * Unsubscribe a peer from a specific topic.
+     * The peer remains subscribed to any other topics.
+     */
+    unsubscribe(peer: WsPeer<T>, topic: string): void;
+    /**
+     * Remove a peer from ALL topics and clean up liveness state.
+     * Call this from `WsHandler.close()` to prevent memory leaks.
+     */
+    leave(peer: WsPeer<T>): void;
+    /**
+     * Route an incoming message from a peer to all its registered topic handlers.
+     * Call this from `WsHandler.message()`.
+     *
+     * If the peer is subscribed to multiple topics, the message is dispatched
+     * to each topic's callback in insertion order.
+     */
+    dispatch(peer: WsPeer<T>, msg: WsMessageData): void;
+    /**
+     * Broadcast a message to ALL subscribers of a topic, including the sender.
+     *
+     * For "exclude self" semantics (the sender does not receive their own message),
+     * use `peer.publish(topic, data)` instead — which on Bun and uWS routes through
+     * the native C++ pub/sub engine.
+     */
+    publish(topic: string, data: WsMessageData, compress?: boolean): void;
+    /**
+     * Mark a peer as alive. Call from `WsHandler.pong()`.
+     *
+     * Works with native runtime protocol ping/pong (Bun, Node, uWS).
+     * On Deno, calling this has no effect as `handler.pong` is never triggered.
+     */
+    markAlive(peer: WsPeer<T>): void;
+    /**
+     * Returns true if the peer last responded within `timeoutMs` milliseconds.
+     */
+    isPeerAlive(peer: WsPeer<T>, timeoutMs: number): boolean;
+    /**
+     * Close and remove all peers that have not called `markAlive()` within `timeoutMs`.
+     * Recommended value: `(pingInterval + pongTimeout) * 1000`.
+     */
+    pruneDeadPeers(timeoutMs: number): void;
+    /**
+     * Start automatic dead peer detection at a fixed interval.
+     *
+     * @param checkIntervalMs - How often to scan for dead peers (ms)
+     * @param timeoutMs       - Peers unseen longer than this are closed and removed
+     *
+     * @example
+     * ```ts
+     * // Check every 5 seconds; close peers silent for 2 minutes
+     * hub.startDeadPeerCheck(5_000, 120_000);
+     *
+     * // Integrate with WsOptions:
+     * // { pingInterval: 30, pongTimeout: 10 }
+     * // → hub.startDeadPeerCheck(5_000, (30 + 10) * 1000);
+     * ```
+     */
+    startDeadPeerCheck(checkIntervalMs: number, timeoutMs: number): void;
+    /**
+     * Stop the automatic dead peer check started by `startDeadPeerCheck()`.
+     */
+    stopDeadPeerCheck(): void;
+    /** Number of peers currently subscribed to a topic. */
+    subscriberCount(topic: string): number;
+    /** Returns true if a peer is subscribed to the given topic. */
+    isSubscribed(peer: WsPeer<T>, topic: string): boolean;
+    /** Returns an array of all active topic names. */
+    topicNames(): string[];
+}
+
+export { App, AppServer, type AppServerInit, type BasicAuthOptions, type BearerAuthOptions, type BodyLimitOptions, type CacheOptions, type CompressOptions$1 as CompressOptions, type CompressionEncoding, type Context, type CorsOptions, type CsrfOptions, type DecodedFrame, type DecompressOptions, type ETagOptions, type ErrorHandler, type FileEntry, type Flatten, type InferObject, type InferState, type InferValidator, type IpRestrictionOptions, type JWK, type JWKOptions, type JWKS, type JWTAlgorithm, type JWTOptions, type JWTPayload, type ListDirectoryOptions, type LoggerOptions, type MemoizeOptions, type MiddlewareHandler, MsgType, type MsgTypeValue, type ParamsFromPath, type ReceiveFileOptions, type RemoteInfo, type RequestIdOptions, type RouteInfo, type Schema, type SecureHeadersOptions, type SendFileOptions, type Server, type ServerOptions, type SessionOptions, type StateMiddleware, type TimeoutOptions, type TimingOptions, type TopicCallback, type TypedHandler, type UploadedFile, type Validator, WSClient, type WsClientOptions, WsClientState, type WsClientStateValue, type WsDefinition, type WsHandler, type WsMessageData, type WsOptions, type WsPeer, WsReadyState, type WsReadyStateValue, WsTopicHub, basicAuth, bearerAuth, bodyLimit, cache, compress, compressString, cors, csrf, decode as decodeFrame, decodeJwt, decompressString, decryptString, defaultErrorHandler, encodeMessage, encodePing, encodePong, encodePublish, encodeRequest, encodeResponse, encodeSubscribe, encodeUnsubscribe, encryptString, etag, generateSecretKey, getMimeType, getPathname, ipRestriction, isBun, isDeno, isKenBinaryFrame, isNode, jwk, jwt, listDirectory, logger, memoize, receiveFiles, requestId, saveFile, secureHeaders, sendFile, session, signJwt, timeout, timing, verifyJwt, wsClientProtocol };