@faapi/faapi 1.4.0 → 2.0.0

package/dist/testing.d.ts

@@ -0,0 +1,232 @@
+import { F as FaapiContext, a as FaapiMiddleware, I as InjectorMap, R as RouteManifest, W as WsRouteManifest, C as CorsOptions, H as HelmetOptions, L as LoggerOptions } from './routeTypes-FtbRkpVF.js';
+import { Server } from 'node:http';
+import { WebSocket } from 'ws';
+
+/**
+ * 测试专用：从选项对象创建 FaapiContext，免去手写 `new Request(url)` 的样板代码
+ *
+ * 与 createContext 的关系：createTestContext 内部构造 Request 后调 createContext，
+ * 语义完全一致，仅是测试场景的语法糖——不写无意义的 host、query 用对象形式、headers 直接传对象。
+ *
+ * 为什么不合并进 createContext：createContext 运行时也从真实 HTTP 请求构造 Request，
+ * 保持 `(request: Request)` 签名使运行时与测试同构；createTestContext 是纯测试便捷封装，
+ * 不引入运行时分支。
+ *
+ * body 不在此处理：createContext 本身不读 `request.body`，body 注入由 `invokeHandler`
+ * 的第 3 个参数负责。POST/PUT/PATCH 测试时 body 单独传给 invokeHandler，避免在两处传 body 产生混淆。
+ *
+ * @param options 请求选项（path 必填，其余可选）
+ * @returns FaapiContext
+ */
+declare function createTestContext(options: CreateTestContextOptions): FaapiContext;
+/**
+ * createTestContext 的选项
+ */
+interface CreateTestContextOptions {
+    /** 请求方法，默认 'GET' */
+    method?: string;
+    /** 请求路径，必填，如 '/api/user'（无需写 host） */
+    path: string;
+    /** 查询参数，对象形式，自动拼接到 URL（值会被 String() 转换；数组生成同名多值参数） */
+    query?: Record<string, string | number | boolean | Array<string | number | boolean>>;
+    /** 请求头 */
+    headers?: Record<string, string>;
+    /** 动态路由参数，默认 {} */
+    params?: Record<string, string>;
+    /** 业务配置（来自 faapi.config.ts），默认 {} */
+    config?: Record<string, unknown>;
+    /** 客户端 IP，默认 '' */
+    ip?: string;
+}
+
+/**
+ * 调用路由 handler 并将返回值转为 Response
+ *
+ * 流程（洋葱模型）：
+ * 1. 中间件按洋葱模型执行：mw1.before → mw2.before → ... → handler → ... → mw2.after → mw1.after
+ * 2. 中间件不调用 next() 即拦截请求（必须返回 Response）
+ * 3. 中间件可用 try/catch 捕获内层错误
+ * 4. 最内层执行注入器（按需）→ handler
+ *
+ * 注入器与中间件解耦：
+ * - 注入器按 handler 参数名匹配，只执行需要的
+ * - 注入器可读取中间件塞进 ctx 的值
+ */
+declare function invokeHandler(handler: (...args: unknown[]) => unknown, ctx: FaapiContext, body?: unknown, middlewares?: FaapiMiddleware[], injectors?: InjectorMap): Promise<Response>;
+
+/**
+ * createTestServer 入参
+ *
+ * 业务方一行代码启动带 schema 校验的 E2E 测试服务器。
+ * 详见 src/testServer.md。
+ */
+interface TestServerOptions {
+    /** 项目根目录（路由源码所在，必填） */
+    rootDir: string;
+    patterns?: string[];
+    /**
+     * schema 产物输出目录（绝对路径或相对 rootDir）。
+     * 不传时自动 mkdtemp 生成临时目录，close() 时清理。
+     * 传值时 close() 仍会清理该目录。
+     */
+    dist?: string;
+    /** CORS 中间件配置，默认 false（禁用，避免污染断言） */
+    cors?: CorsOptions | boolean;
+    /** 安全头配置，默认 false */
+    helmet?: HelmetOptions | boolean;
+    /** 请求日志配置，默认 false（避免污染测试输出） */
+    logger?: LoggerOptions | boolean;
+    /** 全局中间件（外层洋葱） */
+    middlewares?: FaapiMiddleware[];
+    /** 全局注入器 */
+    injectors?: InjectorMap;
+    /** 请求错误钩子（在错误响应生成后调用，用于副作用） */
+    onError?: (error: unknown, ctx: FaapiContext) => Promise<void> | void;
+    /** 业务配置（注入到 ctx.config） */
+    config?: Record<string, unknown>;
+    /** 请求体大小限制（字节），默认 10MB */
+    bodyLimit?: number;
+}
+/**
+ * createTestServer 返回值
+ *
+ * 业务方通过 baseUrl 发 fetch 请求，close() 一行完成 teardown。
+ */
+interface TestServer {
+    /** Node.js HTTP Server 实例（已 listen） */
+    server: Server;
+    /** 形如 http://localhost:<随机端口> */
+    baseUrl: string;
+    /** 排序后的路由清单 */
+    routes: RouteManifest;
+    /** WebSocket 路由清单 */
+    wsRoutes: WsRouteManifest;
+    /** schema 临时目录绝对路径（业务方调试时可查看生成的 zod.js） */
+    schemaDist: string;
+    /**
+     * 关闭 server + 清理 schema 目录 + 清空 schema 模块缓存
+     *
+     * 内部顺序：
+     * 1. server.closeAllConnections?.()（Node 18+，强制断开 WS / 长连接）
+     * 2. server.close()
+     * 3. fs.rm(schemaDist, { recursive, force })
+     * 4. invalidateSchemaCache()
+     *
+     * 幂等：重复调用不会重复清理。
+     */
+    close(): Promise<void>;
+}
+/**
+ * 一键启动带 schema 校验的 E2E 测试服务器
+ *
+ * 内部流程：
+ * 1. scanRoutes 扫描路由
+ * 2. sortRoutes 排序
+ * 3. mkdtemp 创建临时 schema 目录（或用传入的 dist）
+ * 4. generateSchemaFiles 生成 zod.js
+ * 5. createServer 创建 server（默认禁用 CORS/Helmet/Logger，避免污染断言）
+ * 6. server.listen(0) 随机端口
+ * 7. 返回 TestServer
+ *
+ * 详见 src/testServer.md。
+ *
+ * @param options rootDir 必填，其余可选
+ * @returns TestServer 实例
+ */
+declare function createTestServer(options: TestServerOptions): Promise<TestServer>;
+
+/**
+ * WebSocket 测试客户端
+ *
+ * 公开导出 connectWs + MessageQueue + waitForWsOpen，业务方测试 WS 路由时
+ * 免去手写"消息竞态防护 + 三事件监听 + 端口拼接"样板代码。
+ *
+ * 详见 src/wsTestClient.md。
+ */
+/**
+ * connectWs 入参
+ */
+interface WsTestClientOptions {
+    /** 等待 open 的超时（ms），默认 2000 */
+    timeout?: number;
+    /** 握手请求头（如 authorization） */
+    headers?: Record<string, string>;
+    /** WS 子协议 */
+    protocols?: string | string[];
+}
+/**
+ * connectWs 返回值
+ *
+ * 业务方通过 ws.send() 发消息，queue.next() 取消息，close() 关闭。
+ */
+interface WsTestClient {
+    /** ws 库原生实例，业务方可直接 ws.send() / ws.close() */
+    ws: WebSocket;
+    /** 已开始缓冲的消息队列，调 next(timeout?) 取下一条 */
+    queue: MessageQueue;
+    /**
+     * 关闭 ws 并等待 'close' 事件
+     *
+     * 内部：
+     * 1. 若 ws 仍 OPEN/CLOSING，调 ws.close()
+     * 2. 等待 'close' 事件（超时 1000ms 强制 resolve）
+     *
+     * 幂等：重复调用不抛错。
+     */
+    close(): Promise<void>;
+}
+/**
+ * 消息队列：避免 once('message') 与服务端 onOpen 推送的竞态
+ *
+ * 服务端在 handleUpgrade 回调里同步触发 onOpen 并 send('connected')，
+ * 客户端 'open' 事件触发后到注册 once('message') 之间存在窗口，
+ * 若 'connected' 在此窗口内到达，once 会错过。
+ *
+ * 队列在创建 ws 时立即监听 'message'，按 FIFO 顺序消费。
+ */
+declare class MessageQueue {
+    private queue;
+    private waiters;
+    private listener;
+    constructor(ws: WebSocket);
+    /**
+     * 取下一条消息
+     *
+     * 队列有则立即 resolve，无则注册 waiter 等待下一条 'message' 事件。
+     * 超时未到 → reject('WebSocket message timeout')，waiter 被清理。
+     *
+     * @param timeout 超时毫秒，默认 2000
+     */
+    next(timeout?: number): Promise<string>;
+}
+/**
+ * Promise 化等待 ws 'open' 事件
+ *
+ * 同时监听 'open' / 'error' / 'close' 三事件，任一触发都清理 timer，
+ * 避免 timer 泄漏。
+ *
+ * @param ws WebSocket 实例
+ * @param timeout 超时毫秒，默认 2000
+ * @returns 'open' → resolve；'error' → reject(err)；'close' → reject；超时 → reject
+ */
+declare function waitForWsOpen(ws: WebSocket, timeout?: number): Promise<void>;
+/**
+ * 一键连接 WS server
+ *
+ * 内部流程：
+ * 1. baseUrl 协议转换（http → ws，https → wss）
+ * 2. new WebSocket(url, protocols, { headers })
+ * 3. 立即创建 MessageQueue（开始缓冲消息，避免竞态）
+ * 4. waitForWsOpen 等待连接建立（三事件监听 + 超时清理）
+ * 5. 返回 WsTestClient
+ *
+ * 连接失败（中间件拦截 / 路径未匹配 / 超时）→ reject。
+ *
+ * @param baseUrl createTestServer().baseUrl（http://...）
+ * @param pathname WS 路径，如 '/api/chat'，可含 query
+ * @param options timeout / headers / protocols
+ * @returns WsTestClient 实例
+ */
+declare function connectWs(baseUrl: string, pathname: string, options?: WsTestClientOptions): Promise<WsTestClient>;
+
+export { type CreateTestContextOptions, FaapiContext, FaapiMiddleware, InjectorMap, MessageQueue, type TestServer, type TestServerOptions, type WsTestClient, type WsTestClientOptions, connectWs, createTestContext, createTestServer, invokeHandler, waitForWsOpen };