@faapi/faapi 0.0.0-canary.0

package/dist/index.d.ts

@@ -0,0 +1,786 @@
+import * as node_http from 'node:http';
+import ts from 'typescript';
+
+/**
+ * SSE（Server-Sent Events）支持
+ *
+ * 让 handler 能向客户端推送流式事件，用于 LLM token 流、进度通知等场景。
+ *
+ * 核心导出：
+ * - `encodeSseEvent(event)`：把 SSE 事件对象编码为符合 HTML5 SSE 规范的字符串
+ * - `createSseWriter()`：创建一个 SseWriter，封装 ReadableStream + Response，提供 send/close/sendError API
+ * - `SseWriter`：writer 类型，ctx.sse() 返回此类型
+ *
+ * 设计要点：
+ * - writer 内部用 ReadableStream + TextEncoder，send 时 enqueue，close 时 close controller
+ * - response 预设 text/event-stream、no-cache、keep-alive 头，状态码默认 200
+ * - close 后再 send 静默忽略，避免 handler 异步流程中误写已关闭的流
+ * - sendError 向流写入 event: error 后关闭，用于流式输出中报错的优雅终止
+ *
+ * 与 ctx 的集成：
+ * - ctx.sse() 调用 createSseWriter()，并把 response 缓存到 ctx 内部字段
+ * - invokeHandler 在 handler 返回后检查 ctx 是否持有 SSE response，有则优先使用
+ */
+/**
+ * SSE 事件字段
+ *
+ * 遵循 HTML5 SSE 规范：
+ * - `data`：消息数据，多行时每行加 `data: ` 前缀；对象自动 JSON.stringify
+ * - `event`：事件类型，客户端可用 addEventListener(event) 监听
+ * - `id`：事件 ID，客户端断线重连时通过 Last-Event-ID 头发送
+ * - `retry`：重连等待时间（毫秒）
+ * - `comment`：注释行（以 `:` 开头），用于 keep-alive 心跳，不传递给客户端消息
+ */
+interface SseEvent {
+    /** 消息数据。字符串原样输出；对象自动 JSON.stringify；多行时每行加 data: 前缀 */
+    data?: unknown;
+    /** 事件类型，客户端可用 addEventListener 监听 */
+    event?: string;
+    /** 事件 ID，客户端断线重连时通过 Last-Event-ID 头发送 */
+    id?: string | number;
+    /** 重连等待时间（毫秒） */
+    retry?: number;
+    /** 注释行（以 : 开头），用于 keep-alive 心跳 */
+    comment?: string;
+}
+/**
+ * SSE writer：封装流式推送 API
+ *
+ * 通过 `ctx.sse()` 创建，handler 调用 `send` 推送事件，`close` 关闭流。
+ * 框架在 handler 返回后，自动使用 writer.response 作为 HTTP 响应。
+ */
+interface SseWriter {
+    /** 推送一个 SSE 事件 */
+    send(event: SseEvent): void;
+    /** 推送一个 error 事件并关闭流（用于流式输出中报错的优雅终止） */
+    sendError(error: unknown): void;
+    /** 关闭流（多次调用安全） */
+    close(): void;
+    /** 流是否已关闭（handler 主动 close 或框架自动 close） */
+    readonly closed: boolean;
+    /** 客户端是否已断开（ReadableStream 被 cancel） */
+    readonly aborted: boolean;
+    /** 对应的 HTTP Response（由框架使用，用户一般不需要直接访问） */
+    readonly response: Response;
+}
+
+interface CookieOptions {
+    domain?: string;
+    path?: string;
+    maxAge?: number;
+    expires?: Date;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/**
+ * ctx.config 的类型：用户自定义业务配置
+ *
+ * 默认是 Record<string, unknown>（宽松）。用户可通过 `declare module '@faapi/faapi'` 增强：
+ *
+ * ```ts
+ * declare module '@faapi/faapi' {
+ *   interface FaapiContextConfig {
+ *     db: { host: string; port: number };
+ *   }
+ * }
+ * ```
+ *
+ * 增强后 `ctx.config.db.host` 即有类型提示。
+ */
+interface FaapiContextConfig extends Record<string, unknown> {
+}
+interface FaapiContext {
+    request: Request;
+    params: Record<string, string>;
+    query: URLSearchParams;
+    headers: Headers;
+    method: string;
+    path: string;
+    /** 解析后的所有 cookie 键值对 */
+    cookies: Record<string, string>;
+    /** 配置文件中的自定义业务配置（类型可通过 declare module '@faapi/faapi' 增强 FaapiContextConfig） */
+    config: FaapiContextConfig;
+    /**
+     * 设置响应状态码
+     */
+    setStatus(status: number): void;
+    /**
+     * 设置响应头
+     */
+    setHeader(key: string, value: string): void;
+    /**
+     * 返回 JSON 响应（handler 直接 return）
+     *
+     * ```ts
+     * return ctx.json({ error: 'Not found' }, 404);
+     * ```
+     */
+    json(data: unknown, status?: number): Response;
+    /**
+     * 返回 HTML 响应（handler 直接 return）
+     *
+     * ```ts
+     * return ctx.html('<h1>Hello</h1>');
+     * ```
+     */
+    html(html: string, status?: number): Response;
+    /**
+     * 返回重定向响应（handler 直接 return）
+     *
+     * ```ts
+     * return ctx.redirect('/login');
+     * ```
+     */
+    redirect(url: string, status?: number): Response;
+    /**
+     * 创建 SSE writer，用于流式推送事件（LLM token 流、进度通知等）
+     *
+     * handler 调用此方法后，通过返回的 writer 推送事件，框架自动把 writer.response
+     * 作为 HTTP 响应（Content-Type: text/event-stream）。与 ctx.json / ctx.html 互斥。
+     *
+     * ```ts
+     * export async function POST(ctx) {
+     *   const sse = ctx.sse();
+     *   for await (const chunk of stream) {
+     *     sse.send({ data: chunk.text });
+     *   }
+     *   sse.close();
+     * }
+     * ```
+     */
+    sse(): SseWriter;
+    /**
+     * 读取 cookie 值
+     */
+    getCookie(name: string): string | undefined;
+    /**
+     * 设置 cookie
+     */
+    setCookie(name: string, value: string, options?: CookieOptions): void;
+    /**
+     * 删除 cookie（设置过期）
+     */
+    deleteCookie(name: string): void;
+}
+
+/**
+ * faapi 中间件（洋葱模型）
+ *
+ * 单一 async 函数，通过 `await next()` 衔接前置/后置逻辑：
+ * - `await next()` 之前的代码：前置处理（鉴权、日志开始计时等）
+ * - `await next()` 之后的代码：后置处理（日志输出、响应修改等）
+ * - 不调用 `next()` 即拦截请求（如鉴权失败直接返回 Response）
+ * - `next()` 返回内层 Response，中间件可选择使用或替换
+ * - 返回 `Response`：作为响应返回（可用于拦截或错误处理）
+ * - 返回 `void`：使用 `await next()` 返回的内层响应
+ *
+ * 错误处理用 try/catch 包裹 `await next()`，而非独立的 error 钩子。
+ *
+ * 执行顺序（洋葱模型）：
+ * ```
+ * mw1.before → mw2.before → handler → mw2.after → mw1.after
+ * ```
+ *
+ * 示例 middlewares.ts：
+ * ```ts
+ * import type { FaapiMiddleware } from '@faapi/faapi';
+ *
+ * export default [
+ *   // 鉴权：不调 next() 即拦截
+ *   async (ctx, next) => {
+ *     const token = ctx.headers.get('authorization');
+ *     if (!token) return new Response('Unauthorized', { status: 401 });
+ *     ctx.user = await verifyToken(token);
+ *     await next();
+ *   },
+ *   // 日志：before/after 一体，闭包共享状态
+ *   async (ctx, next) => {
+ *     const start = Date.now();
+ *     await next();
+ *     console.log(`${ctx.method} ${ctx.path} ${Date.now() - start}ms`);
+ *   },
+ *   // 错误处理：try/catch 语义
+ *   async (ctx, next) => {
+ *     try {
+ *       await next();
+ *     } catch (err) {
+ *       return new Response(JSON.stringify({ error: String(err) }), { status: 500 });
+ *     }
+ *   },
+ * ] satisfies FaapiMiddleware[];
+ * ```
+ */
+type FaapiMiddleware = (ctx: FaapiContext, next: () => Promise<Response>) => Promise<void | Response>;
+
+/**
+ * 注入器：按参数名匹配，提供 handler 所需的依赖
+ *
+ * 注入器是 faapi 的依赖注入扩展点，与中间件解耦：
+ * - 中间件只管请求流程（鉴权、日志、错误处理）
+ * - 注入器只管提供依赖（数据库连接、用户对象等）
+ *
+ * 注入器可以读取中间件塞进 ctx 的值（如鉴权中间件塞的 ctx.user），
+ * 也可以独立提供依赖（如数据库连接池）。
+ *
+ * 注入器按需执行：只对 handler 声明的参数执行对应的注入器，避免无谓计算。
+ *
+ * 在 middlewares.ts 中通过命名导出 `injectors` 注册：
+ * ```ts
+ * import type { InjectorMap } from '@faapi/faapi';
+ *
+ * export const injectors: InjectorMap = {
+ *   db: () => getDbConnection(),
+ *   user: (ctx) => ctx.user,  // 取中间件塞的值
+ * };
+ * ```
+ */
+type Injector = (ctx: FaapiContext) => unknown | Promise<unknown>;
+/**
+ * 注入器映射表：参数名 → 注入器函数
+ *
+ * key 必须与 handler 参数名一致，运行时按参数名匹配执行。
+ */
+type InjectorMap = Record<string, Injector>;
+
+interface CorsOptions {
+    origin?: string | string[] | true;
+    methods?: string[];
+    allowedHeaders?: string[];
+    exposeHeaders?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+}
+/**
+ * 创建 CORS 中间件（洋葱模型）
+ *
+ * - origin=true: 允许所有来源（反射请求的 Origin）
+ * - origin=string: 允许指定来源
+ * - origin=string[]: 允许多个来源
+ *
+ * OPTIONS 预检请求直接返回 204，不调用 next()。
+ */
+declare function cors(options?: CorsOptions): FaapiMiddleware;
+
+interface LoggerOptions {
+    /** 自定义日志输出函数，默认 console.log */
+    log?: (message: string) => void;
+}
+/**
+ * 创建请求日志中间件（洋葱模型）
+ *
+ * 日志格式：GET /api/users 200 12ms
+ * 错误格式：POST /api/users 400 45ms - Error: ...
+ *
+ * before/after 一体，闭包变量共享开始时间，无需污染 ctx。
+ * 错误用 try/catch 捕获，记录后重新抛出（让上层处理）。
+ * 成功时从 next() 返回的 Response 读取状态码。
+ */
+declare function logger(options?: LoggerOptions): FaapiMiddleware;
+
+declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+type HttpMethod = (typeof HTTP_METHODS)[number];
+
+interface RouteRecord {
+    method: HttpMethod;
+    urlPath: string;
+    filePath: string;
+    paramNames: string[];
+    isDynamic: boolean;
+    /** 是否为 catch-all 路由（[...slug]） */
+    isCatchAll?: boolean;
+    /** 路由对应的中间件集合（从根到路由目录合并，构建时加载） */
+    middlewares?: FaapiMiddleware[];
+    /** 路由对应的注入器映射表（从根到路由目录合并，构建时加载） */
+    injectors?: InjectorMap;
+}
+type RouteManifest = RouteRecord[];
+/**
+ * 路由单个参数的 schema 描述
+ *
+ * 供 @faapi/schema 扩展包消费，通过 MCP 暴露给 LLM。
+ */
+interface RouteParamSchema {
+    name: string;
+    type: string;
+    required: boolean;
+}
+/**
+ * 路由单个输入源的 schema 描述
+ */
+interface RouteInputSchema {
+    source: 'query' | 'body' | 'params';
+    schemaName: string | null;
+    properties: RouteParamSchema[];
+}
+/**
+ * 路由的完整 schema 描述
+ *
+ * 由 @faapi/schema 扩展包的 buildRouteSchemas 生成。
+ * 主包只定义类型契约，逻辑实现在扩展包。
+ */
+interface RouteInfo {
+    method: string;
+    path: string;
+    filePath: string;
+    isDynamic: boolean;
+    inputs: RouteInputSchema[];
+}
+
+/**
+ * 插件上下文：插件 setup 函数接收的框架能力
+ *
+ * 插件通过 ctx 访问路由、服务器实例等，不需要直接依赖框架内部模块。
+ */
+interface PluginContext {
+    /** 项目根目录 */
+    rootDir: string;
+    /** 当前路由清单 */
+    routes: RouteManifest;
+    /** HTTP 服务器实例 */
+    server: node_http.Server;
+    /** 自定义业务配置（faapi.config.ts 中的自定义 key） */
+    config: Record<string, unknown>;
+    /** 插件选项（来自声明中的 options 字段或元组第二个元素） */
+    options?: unknown;
+}
+/**
+ * faapi 插件接口
+ *
+ * 插件是一个对象，包含 name 和 setup 函数。
+ * 框架在 server 启动后、onReady 之前按声明顺序加载插件，调用 setup(ctx)。
+ *
+ * ```ts
+ * import type { FaapiPlugin, PluginContext } from '@faapi/faapi';
+ *
+ * export default {
+ *   name: 'my-plugin',
+ *   setup(ctx: PluginContext) {
+ *     console.log(`Plugin loaded, ${ctx.routes.length} routes found`);
+ *   },
+ * } satisfies FaapiPlugin;
+ * ```
+ */
+interface FaapiPlugin {
+    /** 插件名称（用于去重和日志） */
+    name: string;
+    /** 插件初始化函数，在 server 启动后、onReady 之前调用 */
+    setup: (ctx: PluginContext) => Promise<void> | void;
+}
+/**
+ * 插件声明：用户在 faapi.config.ts 的 plugins 字段中使用
+ *
+ * 支持三种形式：
+ * - 包名字符串：`'@faapi/schema'`
+ * - 带选项的元组：`['@faapi/schema', { stdio: true }]`
+ * - 完整声明对象：`{ package: '@faapi/schema', enable: true }`
+ * - 本地路径：`{ path: './my-plugin' }`
+ */
+type PluginDeclaration = string | [string, unknown] | {
+    package: string;
+    enable?: boolean;
+    options?: unknown;
+} | {
+    path: string;
+    enable?: boolean;
+    options?: unknown;
+};
+
+/**
+ * 统一响应格式化函数
+ *
+ * 当配置了 responseFormat 时，handler 返回的非 Response 值会经过此函数包装
+ * 例如：{ code: 0, data, message: 'success' }
+ */
+type ResponseFormatFn = (data: unknown, ctx: FaapiContext) => unknown;
+/**
+ * 错误响应格式化函数
+ *
+ * 替代内置的 formatErrorResponse，允许自定义错误响应格式
+ */
+type ErrorFormatFn = (error: unknown, ctx?: FaapiContext) => Response;
+/**
+ * 生命周期钩子
+ */
+interface LifecycleHooks {
+    /** 路由加载完成、服务器启动前调用（适合初始化数据库连接等） */
+    onReady?: (ctx: LifecycleContext) => Promise<void> | void;
+    /** 服务器关闭时调用（适合清理资源、优雅关闭） */
+    onClose?: (ctx: LifecycleContext) => Promise<void> | void;
+    /**
+     * 请求错误已被 errorFormat 处理为响应后调用（参考 Fastify onError 语义）
+     *
+     * 时机：handler 抛错 → errorFormat 生成错误响应（失败则由框架内置 formatErrorResponse 兜底）
+     *      → 响应发出后 → onError 触发副作用
+     *
+     * 职责：日志上报、告警、链路追踪等副作用。**不修改、不替换已生成的响应**。
+     * 自身抛错会被捕获并忽略，不影响响应已发送的事实。
+     *
+     * 与 errorFormat 的区别：
+     * - errorFormat：把 error 翻译成 Response（主入口，决定响应内容）
+     * - onError：响应发出后的副作用（不能改响应）
+     */
+    onError?: (error: unknown, ctx: FaapiContext) => Promise<void> | void;
+}
+/**
+ * 生命周期上下文
+ */
+interface LifecycleContext {
+    /** 项目根目录 */
+    rootDir: string;
+    /** 当前路由清单 */
+    routes: RouteManifest;
+    /** 服务器实例 */
+    server: node_http.Server;
+}
+/**
+ * faapi 配置文件类型
+ *
+ * 在项目根目录创建 faapi.config.ts：
+ * ```ts
+ * import type { FaapiConfig } from '@faapi/faapi';
+ * export default {
+ *   port: 3000,
+ *   cors: { origin: '*' },
+ * } satisfies FaapiConfig;
+ * ```
+ *
+ * 多环境配置：
+ * ```ts
+ * import type { FaapiConfig } from '@faapi/faapi';
+ * export default {
+ *   port: 3000,
+ *   cors: { origin: '*' },
+ *   // 自定义业务配置（任意 key）
+ *   db: { host: 'localhost', port: 5432 },
+ * } satisfies FaapiConfig;
+ * ```
+ *
+ * 环境覆盖通过 faapi.config.{NODE_ENV}.ts 实现（如 faapi.config.production.ts）
+ */
+interface FaapiConfig {
+    /** 服务端口，默认 3000（可被 --port / PORT 环境变量覆盖） */
+    port?: number;
+    /** app 目录，默认 'app' */
+    appDir?: string;
+    /** 路由扫描 patterns，默认扫描 app/api 下所有 ts 文件 */
+    patterns?: string[];
+    /** 静态文件目录 */
+    staticDir?: string;
+    /** CORS 配置，false 禁用 */
+    cors?: CorsOptions | boolean;
+    /** 统一响应格式化函数 */
+    responseFormat?: ResponseFormatFn;
+    /** 错误响应格式化函数 */
+    errorFormat?: ErrorFormatFn;
+    /** 生命周期钩子 */
+    lifecycle?: LifecycleHooks;
+    /**
+     * 全局中间件：对所有路由（HTTP + WebSocket 握手）生效
+     *
+     * 执行顺序：全局中间件在最外层，目录中间件在内层，handler 最内层。
+     * 全局中间件拦截（返回 Response）则目录中间件和 handler 不执行。
+     * 全局中间件塞入 ctx 的值，目录中间件和 handler 可读取。
+     *
+     * 与 CORS 的关系：CORS 由 `cors` 字段配置，全局中间件在 CORS 之后执行。
+     *
+     * ```ts
+     * import type { FaapiConfig, FaapiMiddleware } from '@faapi/faapi';
+     *
+     * const requestId: FaapiMiddleware = async (ctx, next) => {
+     *   ctx.requestId = crypto.randomUUID();
+     *   await next();
+     * };
+     *
+     * export default {
+     *   middlewares: [requestId],
+     * } satisfies FaapiConfig;
+     * ```
+     *
+     * 详见 `src/middleware/README.md` 全局中间件章节。
+     */
+    middlewares?: FaapiMiddleware[];
+    /**
+     * 全局注入器：对所有路由的 handler 参数注入生效
+     *
+     * 合并规则：`{ ...全局注入器, ...目录注入器 }`，目录注入器覆盖全局同名。
+     * 全局注入器独立于中间件链，仅提供依赖（db、redis 等），不参与请求流程。
+     *
+     * ```ts
+     * import type { FaapiConfig, InjectorMap } from '@faapi/faapi';
+     *
+     * export default {
+     *   injectors: {
+     *     db: () => getDbConnection(),
+     *     redis: () => getRedis(),
+     *   },
+     * } satisfies FaapiConfig;
+     * ```
+     *
+     * 详见 `src/middleware/README.md` 全局注入器章节。
+     */
+    injectors?: InjectorMap;
+    /**
+     * 插件：应用级扩展，在 server 启动后、onReady 之前按声明顺序加载
+     *
+     * 与中间件的区别：中间件拦截每个请求，插件在启动时初始化（如启动后台服务、注册协议等）
+     *
+     * ```ts
+     * import type { FaapiConfig } from '@faapi/faapi';
+     * export default {
+     *   plugins: [
+     *     '@faapi/schema',                          // 包名
+     *     ['@faapi/schema', { stdio: true }],        // 带选项
+     *     { package: '@faapi/schema', enable: true }, // 完整声明
+     *     { path: './my-plugin' },                    // 本地路径
+     *   ],
+     * } satisfies FaapiConfig;
+     * ```
+     */
+    plugins?: PluginDeclaration[];
+    /**
+     * 扩展 ctx：在每次请求创建上下文后调用，可挂载自定义方法（如 ctx.xml、ctx.stream）
+     *
+     * 类型增强：用户通过 `declare module '@faapi/faapi'` 扩展 FaapiContext 接口获得类型提示
+     *
+     * ```ts
+     * // faapi.config.ts
+     * declare module '@faapi/faapi' {
+     *   interface FaapiContext {
+     *     xml(data: string): Response;
+     *   }
+     * }
+     * export default {
+     *   extendContext(ctx) {
+     *     ctx.xml = (data) => new Response(data, { headers: { 'Content-Type': 'application/xml' } });
+     *   },
+     * } satisfies FaapiConfig;
+     * ```
+     */
+    extendContext?: (ctx: FaapiContext) => void;
+    /**
+     * 自定义业务配置（任意 key）
+     *
+     * 用户可以在这里放数据库连接、Redis 配置等
+     * 通过 ctx.config 访问
+     *
+     * ```ts
+     * export default {
+     *   db: { host: 'localhost', port: 5432 },
+     *   redis: { host: '127.0.0.1', port: 6379 },
+     * } satisfies FaapiConfig;
+     * ```
+     */
+    [key: string]: unknown;
+}
+
+/**
+ * WebSocket Handler 类型定义与 socket 封装
+ *
+ * 用户在 handler.ts 中导出 WS 函数，返回事件回调对象。
+ * 框架在协议升级成功后调用对应回调，传递封装后的 WsSocket。
+ *
+ * @see wsHandler.md 功能说明
+ */
+/**
+ * faapi 封装的 WebSocket socket 抽象
+ *
+ * 不直接暴露 ws 库的原生 socket，提供更安全、易用的 API。
+ * send 对象时自动 JSON.stringify。
+ */
+interface WsSocket {
+    /** 发送数据（string/Buffer 直发，对象自动 JSON.stringify） */
+    send(data: string | Buffer | object): void;
+    /** 关闭连接 */
+    close(code?: number, reason?: string | Buffer): void;
+    /** 连接状态：0=connecting, 1=open, 2=closing, 3=closed */
+    readonly readyState: number;
+}
+/**
+ * WebSocket 事件回调集合
+ *
+ * 用户在 WS handler 中返回此对象，框架在对应事件触发时调用。
+ * 所有回调可选，未提供则忽略事件。
+ */
+interface WsEventHandlers {
+    /** 连接建立时触发 */
+    onOpen?: (ws: WsSocket) => void;
+    /** 收到客户端消息时触发 */
+    onMessage?: (ws: WsSocket, message: string | Buffer) => void;
+    /** 连接关闭时触发 */
+    onClose?: (ws: WsSocket, code: number, reason: string) => void;
+    /** 发生错误时触发 */
+    onError?: (ws: WsSocket, error: Error) => void;
+}
+/**
+ * WebSocket 上下文（握手阶段构造）
+ *
+ * 与 HTTP FaapiContext 类似但精简，提供路由参数、查询参数、请求头、配置。
+ * 可通过 declare module '@faapi/faapi' 增强自定义字段。
+ */
+interface WsContext {
+    /** 动态路由参数（如 [id] → params.id） */
+    params: Record<string, string>;
+    /** URL 查询参数 */
+    query: URLSearchParams;
+    /** 请求头 */
+    headers: Headers;
+    /** 业务配置（来自 faapi.config.ts） */
+    config: Record<string, unknown>;
+    /** 中间件塞入的用户信息（鉴权等） */
+    user?: unknown;
+    /** 允许通过 declare module 扩展 */
+    [key: string]: unknown;
+}
+/**
+ * WS handler 签名：接收 WsContext，返回事件回调对象（或无返回）
+ */
+type WsHandler = (ctx: WsContext) => WsEventHandlers | void;
+
+/**
+ * 为指定文件创建 TypeScript Program（带缓存）
+ *
+ * @param filePath 要分析的 .ts 文件绝对路径
+ */
+declare function createProgram(filePath: string): ts.Program;
+
+/**
+ * Schema 提取错误
+ *
+ * 遇到无法解析或不支持运行时校验的类型时抛出，
+ * 避免静默降级为 any 导致用户不知情。
+ */
+declare class SchemaExtractionError extends Error {
+    readonly typeText: string;
+    readonly reason: string;
+    constructor(typeText: string, reason: string, options?: ErrorOptions);
+}
+/**
+ * 运行时类型描述
+ *
+ * 用于校验器在运行时判断值的结构是否符合声明类型。
+ * 相比单纯的字符串，能描述数组元素类型、嵌套对象、联合类型等。
+ */
+type RuntimeType = {
+    kind: 'string';
+} | {
+    kind: 'number';
+} | {
+    kind: 'boolean';
+} | {
+    kind: 'bigint';
+} | {
+    kind: 'null';
+} | {
+    kind: 'undefined';
+} | {
+    kind: 'any';
+} | {
+    kind: 'unknown';
+} | {
+    kind: 'literal';
+    value: string | number | boolean;
+} | {
+    kind: 'array';
+    element: RuntimeType;
+} | {
+    kind: 'object';
+    properties: PropertyType[];
+} | {
+    kind: 'union';
+    members: RuntimeType[];
+} | {
+    kind: 'date';
+} | {
+    kind: 'record';
+    key: RuntimeType;
+    value: RuntimeType;
+} | {
+    kind: 'ref';
+    name: string;
+};
+interface PropertyType {
+    name: string;
+    type: RuntimeType;
+    optional: boolean;
+}
+
+interface HandlerTypeInfo {
+    name: string;
+    properties: PropertyType[];
+    /** 完整的运行时类型描述（用于嵌套校验） */
+    runtimeType: RuntimeType;
+}
+/**
+ * 从源文件中提取指定名称的类型信息
+ *
+ * 支持的类型声明：
+ * - interface 声明（含继承）
+ * - type 别名（type Query = { ... }）
+ *
+ * 遇到不支持的类型时抛 `SchemaExtractionError`，错误信息包含文件路径和类型名。
+ *
+ * @param program TypeScript Program
+ * @param filePath 源文件路径
+ * @param typeName 类型名，如 'GETQuery'
+ */
+declare function extractTypeInfo(program: ts.Program, filePath: string, typeName: string): HandlerTypeInfo | null;
+
+/**
+ * 根据 HTTP 方法判断主输入类型
+ *
+ * - GET / DELETE / HEAD：query（URL 查询参数）
+ * - POST / PUT / PATCH：body（请求体）
+ *
+ * 注意：所有方法都可能同时有 query 和 body，
+ * 这里返回的是"主输入"（用于校验和注入）。
+ * DELETE 请求也支持 body（见 resolveInput.ts）。
+ */
+declare function getInputTypeForMethod(method: string): 'query' | 'body';
+
+/**
+ * 单个参数的 schema 描述（简化版，供扩展包消费）
+ */
+interface SchemaPropertyDescriptor {
+    name: string;
+    type: string;
+    required: boolean;
+}
+/**
+ * 单个输入源的 schema 描述
+ */
+interface InputSchemaDescriptor {
+    /** 输入源类型名（如 'Query'、'CreateUserBody'），无类型声明时 null */
+    schemaName: string | null;
+    /** 参数列表 */
+    properties: SchemaPropertyDescriptor[];
+}
+/**
+ * 查询指定路由 handler 的输入参数 schema
+ *
+ * 复用 schemaRegistry 已有的类型提取结果，避免重复 AST 分析。
+ * 在 schema 尚未注册时返回 undefined。
+ *
+ * @param filePath handler 文件绝对路径
+ * @param method HTTP 方法（GET/POST 等）
+ * @param inputType 输入源类型（query/body/params）
+ */
+declare function getSchemaProperties(filePath: string, method: string, inputType: 'query' | 'body' | 'params'): InputSchemaDescriptor | undefined;
+
+/**
+ * 加载 faapi 配置文件
+ *
+ * 查找顺序：
+ * 1. 指定的 configPath
+ * 2. faapi.config.ts / faapi.config.js（基础配置）
+ * 3. faapi.config.{env}.ts / faapi.config.{env}.js（环境覆盖，深度合并）
+ *
+ * 环境由 NODE_ENV 或 FAAPI_ENV 决定，默认 'development'
+ *
+ * @param rootDir 项目根目录
+ * @param configPath 指定的配置文件路径（可选）
+ * @returns 合并后的配置，如果无配置文件则返回 null
+ */
+declare function loadConfig(rootDir: string, configPath?: string): Promise<Partial<FaapiConfig> | null>;
+
+export { type CorsOptions, type ErrorFormatFn, type FaapiConfig, type FaapiContext, type FaapiContextConfig, type FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, type Injector, type InjectorMap, type InputSchemaDescriptor, type LifecycleContext, type LifecycleHooks, type LoggerOptions, type PluginContext, type PluginDeclaration, type PropertyType, type ResponseFormatFn, type RouteInfo, type RouteInputSchema, type RouteManifest, type RouteParamSchema, type RuntimeType, SchemaExtractionError, type SchemaPropertyDescriptor, type SseEvent, type SseWriter, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, cors, createProgram, extractTypeInfo, getInputTypeForMethod, getSchemaProperties, loadConfig, logger };