@nextrush/types 3.0.0

package/dist/index.d.ts

@@ -0,0 +1,915 @@
+/**
+ * @nextrush/types - HTTP Type Definitions
+ *
+ * Core HTTP types used across the NextRush framework.
+ * These types provide a clean abstraction over HTTP primitives,
+ * designed to work across multiple runtimes (Node.js, Bun, Deno, Edge).
+ *
+ * @packageDocumentation
+ */
+/**
+ * Standard HTTP methods supported by NextRush
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'TRACE' | 'CONNECT';
+/**
+ * Common HTTP methods for convenience
+ */
+type CommonHttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+/**
+ * HTTP methods as readonly tuple for iteration.
+ *
+ * Note: TRACE and CONNECT are intentionally excluded from this constant.
+ * - TRACE enables Cross-Site Tracing (XST) attacks and is disabled by most servers.
+ * - CONNECT is used for HTTP tunneling (proxies) and is not relevant to application routing.
+ * Both remain in the `HttpMethod` type for completeness (e.g., custom proxy adapters).
+ */
+declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];
+/**
+ * Incoming request headers (read-only)
+ */
+type IncomingHeaders = Readonly<Record<string, string | string[] | undefined>>;
+/**
+ * Outgoing response headers (writable)
+ */
+type OutgoingHeaders = Record<string, string | number | string[]>;
+/**
+ * HTTP status codes
+ */
+declare const HttpStatus: {
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly ACCEPTED: 202;
+    readonly NO_CONTENT: 204;
+    readonly MOVED_PERMANENTLY: 301;
+    readonly FOUND: 302;
+    readonly SEE_OTHER: 303;
+    readonly NOT_MODIFIED: 304;
+    readonly TEMPORARY_REDIRECT: 307;
+    readonly PERMANENT_REDIRECT: 308;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly PAYMENT_REQUIRED: 402;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly METHOD_NOT_ALLOWED: 405;
+    readonly NOT_ACCEPTABLE: 406;
+    readonly PROXY_AUTH_REQUIRED: 407;
+    readonly REQUEST_TIMEOUT: 408;
+    readonly CONFLICT: 409;
+    readonly GONE: 410;
+    readonly LENGTH_REQUIRED: 411;
+    readonly PRECONDITION_FAILED: 412;
+    readonly PAYLOAD_TOO_LARGE: 413;
+    readonly URI_TOO_LONG: 414;
+    readonly UNSUPPORTED_MEDIA_TYPE: 415;
+    readonly RANGE_NOT_SATISFIABLE: 416;
+    readonly EXPECTATION_FAILED: 417;
+    readonly IM_A_TEAPOT: 418;
+    readonly UNPROCESSABLE_ENTITY: 422;
+    readonly LOCKED: 423;
+    readonly FAILED_DEPENDENCY: 424;
+    readonly TOO_EARLY: 425;
+    readonly UPGRADE_REQUIRED: 426;
+    readonly PRECONDITION_REQUIRED: 428;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly REQUEST_HEADER_FIELDS_TOO_LARGE: 431;
+    readonly UNAVAILABLE_FOR_LEGAL_REASONS: 451;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly NOT_IMPLEMENTED: 501;
+    readonly BAD_GATEWAY: 502;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly GATEWAY_TIMEOUT: 504;
+    readonly HTTP_VERSION_NOT_SUPPORTED: 505;
+    readonly VARIANT_ALSO_NEGOTIATES: 506;
+    readonly INSUFFICIENT_STORAGE: 507;
+    readonly LOOP_DETECTED: 508;
+    readonly NOT_EXTENDED: 510;
+    readonly NETWORK_AUTH_REQUIRED: 511;
+};
+type HttpStatusCode = (typeof HttpStatus)[keyof typeof HttpStatus];
+/**
+ * Supported request body types after parsing
+ */
+type ParsedBody = string | Uint8Array | Record<string, unknown> | unknown[] | null | undefined;
+/**
+ * Supported response body types
+ *
+ * @remarks
+ * Uses structural stream interfaces to avoid coupling to any
+ * specific runtime (Node.js, Bun, Deno, Edge).
+ * Uint8Array and ArrayBuffer provide Web API compatibility.
+ */
+type ResponseBody = string | Uint8Array | ArrayBuffer | NodeStreamLike | WebStreamLike | Record<string, unknown> | unknown[] | null | undefined;
+/**
+ * Structural interface for Node.js-compatible readable streams.
+ * Matches Node.js `Readable` and `IncomingMessage` without importing `@types/node`.
+ */
+interface NodeStreamLike {
+    pipe(destination: unknown): unknown;
+}
+/**
+ * Structural interface for Web API ReadableStreams.
+ * Matches the global `ReadableStream<Uint8Array>` without requiring DOM lib types.
+ */
+interface WebStreamLike {
+    getReader(): unknown;
+    readonly locked: boolean;
+}
+/**
+ * Raw HTTP objects - generic to support multiple runtimes
+ *
+ * For Node.js: RawHttp<IncomingMessage, ServerResponse>
+ * For Bun: RawHttp<Request, Response>
+ * For Edge: RawHttp<Request, ResponseInit>
+ *
+ * @typeParam TReq - Raw request type for the runtime
+ * @typeParam TRes - Raw response type for the runtime
+ */
+interface RawHttp<TReq = unknown, TRes = unknown> {
+    readonly req: TReq;
+    readonly res: TRes;
+}
+/**
+ * Common content types
+ */
+declare const ContentType: {
+    readonly JSON: "application/json";
+    readonly HTML: "text/html";
+    readonly TEXT: "text/plain";
+    readonly XML: "application/xml";
+    readonly FORM: "application/x-www-form-urlencoded";
+    readonly MULTIPART: "multipart/form-data";
+    readonly OCTET_STREAM: "application/octet-stream";
+};
+type ContentTypeValue = (typeof ContentType)[keyof typeof ContentType];
+
+/**
+ * @nextrush/types - Runtime Type Definitions
+ *
+ * Types for cross-runtime support in NextRush.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Supported JavaScript runtimes
+ *
+ * @remarks
+ * NextRush detects the runtime environment and exposes it via `ctx.runtime`.
+ * This enables runtime-specific optimizations while maintaining a unified API.
+ */
+type Runtime = 'node' | 'bun' | 'deno' | 'deno-deploy' | 'cloudflare-workers' | 'vercel-edge' | 'edge' | 'unknown';
+/**
+ * Runtime feature capabilities
+ *
+ * @remarks
+ * Different runtimes have different feature sets. Use this to check
+ * what's available before using runtime-specific features.
+ */
+interface RuntimeCapabilities {
+    /** Supports Node.js streams (Readable, Writable) */
+    nodeStreams: boolean;
+    /** Supports Web Streams API (ReadableStream, WritableStream) */
+    webStreams: boolean;
+    /** Supports file system operations */
+    fileSystem: boolean;
+    /** Supports WebSocket */
+    webSocket: boolean;
+    /** Supports native fetch API */
+    fetch: boolean;
+    /** Supports crypto.subtle API */
+    cryptoSubtle: boolean;
+    /** Supports Web Workers / Worker Threads */
+    workers: boolean;
+}
+/**
+ * Runtime information object
+ */
+interface RuntimeInfo {
+    /** Runtime identifier */
+    runtime: Runtime;
+    /** Runtime version (if available) */
+    version: string | undefined;
+    /** Runtime capabilities */
+    capabilities: RuntimeCapabilities;
+}
+/**
+ * Body source interface for cross-runtime body reading
+ *
+ * @remarks
+ * Different runtimes have different APIs for reading request bodies:
+ * - Node.js: `IncomingMessage` stream with `on('data')` events
+ * - Bun/Deno/Edge: Web `Request` with `text()`, `arrayBuffer()` methods
+ *
+ * `BodySource` provides a unified interface for body parsers to work
+ * across all runtimes without runtime-specific code.
+ *
+ * @example
+ * ```typescript
+ * // Works on any runtime
+ * async function parseJson(bodySource: BodySource): Promise<unknown> {
+ *   const text = await bodySource.text();
+ *   return JSON.parse(text);
+ * }
+ * ```
+ */
+interface BodySource {
+    /**
+     * Read the body as a UTF-8 string
+     *
+     * @returns Promise resolving to the body as string
+     * @throws Error if body has already been consumed
+     */
+    text(): Promise<string>;
+    /**
+     * Read the body as a Uint8Array buffer
+     *
+     * @returns Promise resolving to the body as Uint8Array
+     * @throws Error if body has already been consumed
+     */
+    buffer(): Promise<Uint8Array>;
+    /**
+     * Read the body as JSON
+     *
+     * @returns Promise resolving to parsed JSON
+     * @throws BadRequestError if body is not valid JSON
+     * @throws Error if body has already been consumed
+     */
+    json<T = unknown>(): Promise<T>;
+    /**
+     * Get the body as a stream
+     *
+     * @remarks
+     * Returns the native stream type for the runtime:
+     * - Node.js: `Readable`
+     * - Web API: `ReadableStream<Uint8Array>`
+     *
+     * @returns The underlying stream
+     */
+    stream(): NodeStreamLike | WebStreamLike;
+    /**
+     * Whether the body has been consumed
+     *
+     * @remarks
+     * Most runtimes only allow the body to be read once. After calling
+     * `text()`, `buffer()`, `json()`, or `stream()`, subsequent calls
+     * may throw an error.
+     */
+    readonly consumed: boolean;
+    /**
+     * Content length from headers (if available)
+     *
+     * @remarks
+     * This is the value from the Content-Length header, which may not
+     * match the actual body size for chunked transfers.
+     */
+    readonly contentLength: number | undefined;
+    /**
+     * Content type from headers (if available)
+     */
+    readonly contentType: string | undefined;
+}
+/**
+ * Options for creating a BodySource
+ */
+interface BodySourceOptions {
+    /** Maximum body size in bytes (default: 1MB) */
+    limit?: number;
+    /** Encoding for text() method (default: 'utf-8') */
+    encoding?: 'utf-8' | 'utf8' | 'ascii' | 'latin1' | 'iso-8859-1' | 'utf-16le' | 'utf-16be';
+}
+
+/**
+ * @nextrush/types - Context Type Definitions
+ *
+ * The Context object is the heart of NextRush's request/response handling.
+ * It provides a unified interface for accessing request data and sending responses.
+ *
+ * Design Philosophy:
+ * - ctx.body = request body (INPUT)
+ * - ctx.json() = send JSON response (OUTPUT)
+ * - ctx.next() = call next middleware
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Route parameters extracted from URL path
+ * Example: /users/:id -> { id: '123' }
+ */
+type RouteParams = Record<string, string>;
+/**
+ * Query string parameters
+ * Example: ?page=1&limit=10 -> { page: '1', limit: '10' }
+ */
+type QueryParams = Record<string, string | string[] | undefined>;
+/**
+ * Request-scoped state object
+ * Use this to pass data between middleware
+ */
+type ContextState = Record<string | symbol, unknown>;
+/**
+ * The Context interface - core of NextRush request handling
+ *
+ * @example
+ * ```typescript
+ * app.get('/users/:id', async (ctx) => {
+ *   // Request data (input)
+ *   const { id } = ctx.params;
+ *   const { name } = ctx.body;
+ *
+ *   // Response (output)
+ *   ctx.status = 200;
+ *   ctx.json({ id, name });
+ * });
+ * ```
+ */
+interface Context {
+    /**
+     * HTTP method (GET, POST, PUT, DELETE, etc.)
+     * @readonly
+     */
+    readonly method: HttpMethod;
+    /**
+     * Full request URL including query string
+     * @example '/users/123?include=posts'
+     * @readonly
+     */
+    readonly url: string;
+    /**
+     * Request path without query string
+     * @example '/users/123'
+     * @readonly
+     */
+    readonly path: string;
+    /**
+     * Parsed query string parameters
+     * @example { include: 'posts', limit: '10' }
+     * @readonly
+     */
+    readonly query: QueryParams;
+    /**
+     * Request headers (read-only)
+     * Use ctx.get() for case-insensitive access
+     * @readonly
+     */
+    readonly headers: IncomingHeaders;
+    /**
+     * Client IP address
+     * @readonly
+     */
+    readonly ip: string;
+    /**
+     * Parsed request body (input).
+     *
+     * Populated by body-parser middleware (json, urlencoded, multipart).
+     * This is the **request body**, not the response body.
+     * Use `ctx.json()`, `ctx.send()`, or `ctx.html()` to set response output.
+     *
+     * @example
+     * ```typescript
+     * app.post('/users', async (ctx) => {
+     *   const { name, email } = ctx.body as CreateUserDto;
+     * });
+     * ```
+     */
+    body: unknown;
+    /**
+     * Route parameters from URL path
+     *
+     * @example
+     * ```typescript
+     * // Route: /users/:id/posts/:postId
+     * // URL: /users/123/posts/456
+     * ctx.params // { id: '123', postId: '456' }
+     * ```
+     */
+    params: RouteParams;
+    /**
+     * HTTP response status code
+     * @default 200
+     *
+     * @example
+     * ```typescript
+     * ctx.status = 201; // Created
+     * ctx.status = 404; // Not Found
+     * ```
+     */
+    status: number;
+    /**
+     * Send JSON response
+     * Automatically sets Content-Type: application/json
+     *
+     * @param data - Data to serialize as JSON
+     *
+     * @example
+     * ```typescript
+     * ctx.json({ users: [] });
+     * ctx.json({ error: 'Not found' });
+     * ```
+     */
+    json(data: unknown): void;
+    /**
+     * Send response (text, buffer, or stream)
+     * Automatically detects content type
+     *
+     * @param data - Response data
+     *
+     * @example
+     * ```typescript
+     * ctx.send('Hello World');
+     * ctx.send(Buffer.from('binary data'));
+     * ctx.send(fileStream);
+     * ```
+     */
+    send(data: ResponseBody): void;
+    /**
+     * Send HTML response
+     * Automatically sets Content-Type: text/html
+     *
+     * @param content - HTML string
+     *
+     * @example
+     * ```typescript
+     * ctx.html('<h1>Hello World</h1>');
+     * ```
+     */
+    html(content: string): void;
+    /**
+     * Redirect to another URL
+     *
+     * @param url - Target URL
+     * @param status - HTTP status code (default: 302)
+     *
+     * @example
+     * ```typescript
+     * ctx.redirect('/login');
+     * ctx.redirect('/new-page', 301); // Permanent redirect
+     * ```
+     */
+    redirect(url: string, status?: number): void;
+    /**
+     * Throw an HTTP error - stops execution and triggers error handler
+     *
+     * @param status - HTTP status code
+     * @param message - Error message (optional)
+     * @throws HttpError
+     *
+     * @example
+     * ```typescript
+     * ctx.throw(404, 'User not found');
+     * ctx.throw(401); // Uses default message "Unauthorized"
+     * ```
+     */
+    throw(status: number, message?: string): never;
+    /**
+     * Assert a condition, throw if falsy
+     *
+     * @param condition - Condition to check
+     * @param status - HTTP status code if assertion fails
+     * @param message - Error message (optional)
+     * @throws HttpError if condition is falsy
+     *
+     * @example
+     * ```typescript
+     * ctx.assert(user, 404, 'User not found');
+     * ctx.assert(user.isAdmin, 403, 'Admin access required');
+     * ctx.assert(ctx.body, 400); // Uses default "Bad Request"
+     * ```
+     */
+    assert(condition: unknown, status: number, message?: string): asserts condition;
+    /**
+     * Set response header
+     *
+     * @param field - Header name
+     * @param value - Header value (string, number, or array for multi-value headers like Set-Cookie)
+     *
+     * @example
+     * ```typescript
+     * ctx.set('X-Request-Id', '123');
+     * ctx.set('Cache-Control', 'no-cache');
+     * ctx.set('Set-Cookie', ['a=1; Path=/', 'b=2; Path=/']);
+     * ```
+     */
+    set(field: string, value: string | number | string[]): void;
+    /**
+     * Get request header (case-insensitive)
+     *
+     * @param field - Header name
+     * @returns Header value or undefined
+     *
+     * @example
+     * ```typescript
+     * const auth = ctx.get('Authorization');
+     * const contentType = ctx.get('content-type');
+     * ```
+     */
+    get(field: string): string | undefined;
+    /**
+     * Call the next middleware in the chain
+     * Modern syntax: ctx.next() instead of next()
+     *
+     * @example
+     * ```typescript
+     * app.use(async (ctx) => {
+     *   console.log('Before');
+     *   await ctx.next();
+     *   console.log('After');
+     * });
+     * ```
+     */
+    next(): Promise<void>;
+    /**
+     * Set the next middleware function
+     * @internal Used by middleware compose to wire up ctx.next()
+     */
+    setNext?(fn: Next): void;
+    /**
+     * Whether a response has already been sent
+     *
+     * @remarks
+     * Useful for middleware that needs to check if downstream
+     * middleware has already sent a response.
+     */
+    readonly responded: boolean;
+    /**
+     * Request-scoped state object
+     * Use to pass data between middleware
+     *
+     * @example
+     * ```typescript
+     * // Auth middleware
+     * app.use(async (ctx) => {
+     *   ctx.state.user = await validateToken(ctx.get('Authorization'));
+     *   await ctx.next();
+     * });
+     *
+     * // Route handler
+     * app.get('/profile', (ctx) => {
+     *   const user = ctx.state.user;
+     * });
+     * ```
+     */
+    state: ContextState;
+    /**
+     * Raw HTTP objects (platform-specific)
+     * Escape hatch for advanced use cases
+     *
+     * @remarks
+     * The type of `raw` depends on the adapter:
+     * - Node.js: `{ req: IncomingMessage, res: ServerResponse }`
+     * - Bun/Deno/Edge: `{ req: Request, res: Response | undefined }`
+     *
+     * @example
+     * ```typescript
+     * // Node.js adapter
+     * ctx.raw.req.socket.remoteAddress;
+     *
+     * // Web API adapter (Bun/Deno/Edge)
+     * ctx.raw.req.headers.get('authorization');
+     * ```
+     */
+    readonly raw: RawHttp;
+    /**
+     * Current JavaScript runtime
+     *
+     * @remarks
+     * Useful for runtime-specific optimizations or conditional logic.
+     *
+     * @example
+     * ```typescript
+     * if (ctx.runtime === 'bun') {
+     *   // Bun-specific optimization
+     * }
+     * ```
+     */
+    readonly runtime: Runtime;
+    /**
+     * Body source for cross-runtime body reading
+     *
+     * @remarks
+     * Used by body parsers to read request bodies in a runtime-agnostic way.
+     * Most applications should use `ctx.body` (set by body-parser middleware)
+     * instead of accessing `bodySource` directly.
+     *
+     * @example
+     * ```typescript
+     * // In a custom body parser
+     * const text = await ctx.bodySource.text();
+     * const json = JSON.parse(text);
+     * ```
+     */
+    readonly bodySource: BodySource;
+}
+/**
+ * Next function type (traditional Koa-style)
+ */
+type Next = () => Promise<void>;
+/**
+ * Middleware function type
+ * Supports both modern and traditional syntax
+ *
+ * Modern syntax (ctx.next()):
+ * ```typescript
+ * app.use(async (ctx) => {
+ *   await ctx.next();
+ * });
+ * ```
+ *
+ * Traditional syntax (next parameter):
+ * ```typescript
+ * app.use(async (ctx, next) => {
+ *   await next();
+ * });
+ * ```
+ */
+type Middleware = (ctx: Context, next: Next) => void | Promise<void>;
+/**
+ * Route handler type (alias for middleware)
+ */
+type RouteHandler = Middleware;
+/**
+ * Options for creating a new context
+ */
+interface ContextOptions {
+    /** HTTP method */
+    method: HttpMethod;
+    /** Request URL */
+    url: string;
+    /** Request headers */
+    headers?: IncomingHeaders;
+    /** Client IP */
+    ip?: string;
+    /** Raw HTTP objects */
+    raw: RawHttp;
+}
+
+/**
+ * @nextrush/types - Plugin Type Definitions
+ *
+ * Plugins are the extension mechanism for NextRush.
+ * They allow adding functionality without bloating the core.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Minimal Application interface for plugin registration
+ * The full Application class is in @nextrush/core
+ */
+interface ApplicationLike {
+    /**
+     * Register middleware
+     */
+    use(middleware: Middleware): this;
+    /**
+     * Get installed plugin by name
+     */
+    getPlugin<T extends Plugin>(name: string): T | undefined;
+}
+/**
+ * Plugin interface for extending NextRush
+ *
+ * Plugins are installed via app.plugin() and can:
+ * - Add middleware
+ * - Extend context
+ * - Add lifecycle hooks
+ *
+ * @example
+ * ```typescript
+ * class LoggerPlugin implements Plugin {
+ *   readonly name = 'logger';
+ *   readonly version = '1.0.0';
+ *
+ *   install(app: ApplicationLike) {
+ *     app.use(async (ctx, next) => {
+ *       const start = Date.now();
+ *       await next();
+ *       console.log(`${ctx.method} ${ctx.path} - ${Date.now() - start}ms`);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+interface Plugin {
+    /**
+     * Unique plugin name
+     * Used for identification and getPlugin() lookup
+     */
+    readonly name: string;
+    /**
+     * Plugin version (optional)
+     * Follows semver format
+     */
+    readonly version?: string;
+    /**
+     * Install plugin into application
+     * Called when app.plugin() is invoked
+     *
+     * @param app - Application instance
+     */
+    install(app: ApplicationLike): void | Promise<void>;
+    /**
+     * Cleanup when application shuts down (optional)
+     * Called during graceful shutdown
+     */
+    destroy?(): void | Promise<void>;
+}
+/**
+ * Extended plugin interface with lifecycle hooks
+ * For advanced plugins that need deeper integration
+ */
+interface PluginWithHooks extends Plugin {
+    /**
+     * Called before each request
+     */
+    onRequest?(ctx: Context): void | Promise<void>;
+    /**
+     * Called after each response
+     */
+    onResponse?(ctx: Context): void | Promise<void>;
+    /**
+     * Called when an error occurs
+     */
+    onError?(error: Error, ctx: Context): void | Promise<void>;
+    /**
+     * Extend the context object
+     * Add custom properties or methods
+     */
+    extendContext?(ctx: Context): void;
+}
+/**
+ * Plugin factory function type
+ * Allows creating plugins with options
+ *
+ * @example
+ * ```typescript
+ * const logger = createLoggerPlugin({ level: 'info' });
+ * app.plugin(logger);
+ * ```
+ */
+type PluginFactory<TOptions = unknown> = (options?: TOptions) => Plugin;
+/**
+ * Plugin metadata for registration and discovery
+ */
+interface PluginMeta {
+    /** Plugin name */
+    name: string;
+    /** Plugin version */
+    version: string;
+    /** Plugin description */
+    description?: string;
+    /** Plugin author */
+    author?: string;
+    /** Plugin repository URL */
+    repository?: string;
+    /** Plugin dependencies (other plugin names) */
+    dependencies?: string[];
+}
+
+/**
+ * @nextrush/types - Router Type Definitions
+ *
+ * Types for the NextRush router system.
+ * The router uses a radix tree for efficient route matching.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Route definition
+ */
+interface Route {
+    /** HTTP method */
+    method: HttpMethod;
+    /** Route path pattern */
+    path: string;
+    /** Route handler */
+    handler: RouteHandler;
+    /** Optional route-level middleware */
+    middleware?: Middleware[];
+}
+/**
+ * Matched route result
+ */
+interface RouteMatch {
+    /** Matched handler */
+    handler: RouteHandler;
+    /** Extracted route parameters */
+    params: Record<string, string>;
+    /** Router-level middleware stack (route-specific middleware is in the executor) */
+    middleware: Middleware[];
+    /** Pre-compiled executor for fast dispatch (internal) */
+    executor?: (ctx: Context) => Promise<void>;
+}
+/**
+ * Router interface for route registration
+ *
+ * @example
+ * ```typescript
+ * const router = createRouter();
+ *
+ * router.get('/users', listUsers);
+ * router.get('/users/:id', getUser);
+ * router.post('/users', createUser);
+ *
+ * app.use(router.routes());
+ * ```
+ */
+interface Router {
+    /**
+     * Register a GET route
+     */
+    get(path: string, ...handlers: RouteHandler[]): this;
+    /**
+     * Register a POST route
+     */
+    post(path: string, ...handlers: RouteHandler[]): this;
+    /**
+     * Register a PUT route
+     */
+    put(path: string, ...handlers: RouteHandler[]): this;
+    /**
+     * Register a DELETE route
+     */
+    delete(path: string, ...handlers: RouteHandler[]): this;
+    /**
+     * Register a PATCH route
+     */
+    patch(path: string, ...handlers: RouteHandler[]): this;
+    /**
+     * Register a HEAD route
+     */
+    head(path: string, ...handlers: RouteHandler[]): this;
+    /**
+     * Register an OPTIONS route
+     */
+    options(path: string, ...handlers: RouteHandler[]): this;
+    /**
+     * Register a route for any HTTP method
+     */
+    all(path: string, ...handlers: RouteHandler[]): this;
+    /**
+     * Register a route for specific method
+     */
+    route(method: HttpMethod, path: string, ...handlers: RouteHandler[]): this;
+    /**
+     * Mount router middleware
+     */
+    use(path: string, router: Router): this;
+    use(middleware: Middleware): this;
+    /**
+     * Register a redirect from one path to another
+     *
+     * @param from - Source path to redirect from
+     * @param to - Target path or URL to redirect to
+     * @param status - HTTP status code (default: 301)
+     */
+    redirect(from: string, to: string, status?: 301 | 302 | 303 | 307 | 308): this;
+    /**
+     * Get routes middleware function
+     * Mount this on the application
+     */
+    routes(): Middleware;
+    /**
+     * Match a route
+     */
+    match(method: HttpMethod, path: string): RouteMatch | null;
+}
+/**
+ * Router configuration options
+ */
+interface RouterOptions {
+    /**
+     * Prefix for all routes
+     * @example '/api/v1'
+     */
+    prefix?: string;
+    /**
+     * Whether to enable case-sensitive routing
+     * @default false
+     */
+    caseSensitive?: boolean;
+    /**
+     * Whether to enable strict routing (trailing slashes matter)
+     * @default false
+     */
+    strict?: boolean;
+}
+/**
+ * Supported route pattern types
+ */
+type RoutePattern = `/${string}` | `${string}/:${string}` | `${string}/*` | `${string}/:${string}/*`;
+/**
+ * Route parameter definition
+ */
+interface RouteParam {
+    /** Parameter name (without colon) */
+    name: string;
+    /** Whether the parameter is optional */
+    optional?: boolean;
+    /** Regex pattern for validation */
+    pattern?: RegExp;
+}
+
+export { type ApplicationLike, type BodySource, type BodySourceOptions, type CommonHttpMethod, ContentType, type ContentTypeValue, type Context, type ContextOptions, type ContextState, HTTP_METHODS, type HttpMethod, HttpStatus, type HttpStatusCode, type IncomingHeaders, type Middleware, type Next, type NodeStreamLike, type OutgoingHeaders, type ParsedBody, type Plugin, type PluginFactory, type PluginMeta, type PluginWithHooks, type QueryParams, type RawHttp, type ResponseBody, type Route, type RouteHandler, type RouteMatch, type RouteParam, type RouteParams, type RoutePattern, type Router, type RouterOptions, type Runtime, type RuntimeCapabilities, type RuntimeInfo, type WebStreamLike };