@faapi/faapi 1.4.0 → 2.0.0

package/dist/index.d.ts

@@ -1,498 +1,9 @@
+import { R as RouteManifest, C as CorsOptions, F as FaapiContext, H as HelmetOptions, L as LoggerOptions, a as FaapiMiddleware, I as InjectorMap, W as WsRouteManifest } from './routeTypes-FtbRkpVF.js';
+export { b as FaapiContextConfig, c as FailOptions, d as Injector, e as RouteInfo, f as RouteInputSchema, g as RouteOutputSchema, h as RouteParamSchema, S as SseEvent, i as SseWriter, j as cors, k as helmet, l as logger } from './routeTypes-FtbRkpVF.js';
 import * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
 import ts from 'typescript';
-import { WebSocket } from 'ws';
-
-/**
- * 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;
-    /**
-     * 直接写入原始字节/字符串,不做任何 SSE 序列化
-     *
-     * 用于透传上游已有的 SSE 原文(如 LLM 中转平台逐 chunk 转发 OpenAI 响应)。
-     * 调用方负责保证内容符合 HTML5 SSE 规范;`send` 会再次加 `data: ` 前缀,
-     * 不适用于原文透传场景。
-     *
-     * 接受 string 或 Uint8Array(Buffer 是 Uint8Array 子类,自然兼容)。
-     * 与 `send` 一致:close/aborted 后静默忽略,不抛错。
-     */
-    sendRaw(chunk: string | Uint8Array): 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.fail() 的参数类型(对象形式,status 和 code 均可省略)
- *
- * - status: HTTP 状态码(可选,省略时默认 500)
- * - code: 业务错误码(可选,省略时响应 body 里不含 code 字段)
- * - message: 人类可读错误描述(必填)
- *
- * status 和 code 是两个独立维度,无关联:
- * - status 控制 HTTP 状态码
- * - code 是 body 里的业务错误码字段
- *
- * ```ts
- * ctx.fail({ message: '出错' })                                  // HTTP 500, { error: { message: '出错' } }
- * ctx.fail({ status: 404, message: '用户不存在' })                // HTTP 404, { error: { message: '用户不存在' } }
- * ctx.fail({ status: 404, code: 'USER_NOT_FOUND', message: '用户不存在' }) // HTTP 404, { error: { code: 'USER_NOT_FOUND', message: '用户不存在' } }
- * ```
- */
-interface FailOptions {
-    /** HTTP 状态码(可选,省略时默认 500) */
-    status?: number;
-    /** 业务错误码(可选,省略时响应 body 里不含 code 字段) */
-    code?: string;
-    /** 人类可读错误描述 */
-    message: string;
-}
-/**
- * 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;
-    /**
-     * 客户端 IP
-     *
-     * 优先 `x-forwarded-for` 第一个 IP（反向代理场景），回退到 socket.remoteAddress。
-     * IPv6 形式 `::ffff:1.2.3.4` 会被规整为 IPv4 形式 `1.2.3.4`。
-     * 无法获取时为空字符串。
-     */
-    ip: string;
-    /**
-     * 客户端 User-Agent（请求头 `user-agent` 原值）
-     *
-     * 在 createContext 内部从 request.headers 读取（与 ip 不同，无需调用方传入）。
-     * 不做解析/规整，仅原样透传；无该请求头时为空字符串。
-     */
-    ua: string;
-    /** 解析后的所有 cookie 键值对 */
-    cookies: Record<string, string>;
-    /** 配置文件中的自定义业务配置（类型可通过 declare module '@faapi/faapi' 增强 FaapiContextConfig） */
-    config: FaapiContextConfig;
-    /**
-     * 设置响应状态码
-     */
-    setStatus(status: number): void;
-    /**
-     * 设置响应头
-     */
-    setHeader(key: string, value: string): void;
-    /**
-     * 设置 ETag 响应头
-     *
-     * handler 中基于业务数据（如 updatedAt / version / contentHash）设置 ETag：
-     * ```ts
-     * export function GET(ctx) {
-     *   const data = await fetchData();
-     *   ctx.setETag(`"${data.version}-${data.updatedAt}"`);
-     *   return data;
-     * }
-     * ```
-     */
-    setETag(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;
-    /**
-     * 显式包装成功响应(返回 Response 对象)
-     *
-     * 用 config.response.ok 包裹 data 并返回 Response。
-     * 等价于 handler 直接 `return data`(框架自动包裹),但显式调用语义更清晰。
-     *
-     * 返回 Response 对象,不会被框架自动包裹再次包装(避免双重包裹)。
-     *
-     * ```ts
-     * // 以下两种写法等价(假设配置了 response.ok = (data) => ({ data })):
-     * export function GET() {
-     *   return { id: 1 };              // 自动包裹 → { data: { id: 1 } }
-     * }
-     * export function GET2(ctx) {
-     *   return ctx.ok({ id: 1 });      // 显式包裹 → { data: { id: 1 } }
-     * }
-     * ```
-     */
-    ok(data: unknown): Response;
-    /**
-     * 返回错误响应(对象形式参数,status 和 code 均可省略)
-     *
-     * @param options.status  HTTP 状态码(可选,省略时默认 500)
-     * @param options.code    业务错误码(可选,省略时响应 body 里不含 code 字段)
-     * @param options.message 人类可读错误描述(必填)
-     *
-     * status 和 code 独立无关联:status 控制 HTTP 状态码,code 是 body 里的业务错误码字段。
-     *
-     * ```ts
-     * return ctx.fail({ message: '出错' });                                   // HTTP 500, { error: { message: '出错' } }
-     * return ctx.fail({ status: 404, message: '用户不存在' });                 // HTTP 404, { error: { message: '用户不存在' } }
-     * return ctx.fail({ status: 404, code: 'USER_NOT_FOUND', message: '用户不存在' }); // HTTP 404, { error: { code: 'USER_NOT_FOUND', message: '用户不存在' } }
-     * ```
-     */
-    fail(options: FailOptions): Response;
-    /**
-     * 读取 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;
-
-type LoggerFn = (messageOrObj: string | Record<string, unknown>, message?: string) => void;
-interface LoggerOptions {
-    /**
-     * 自定义日志函数
-     *
-     * - 传入 `console.log`（默认）：纯文本格式 `GET /api/users 200 12ms`
-     * - 传入 pino logger：结构化日志 `logger.info({ method, path, status, durationMs }, 'request completed')`
-     * - 传入 winston logger：`logger.info('GET /api/users 200 12ms', { method, path })`
-     */
-    log?: LoggerFn;
-}
-/**
- * 创建请求日志中间件（洋葱模型）
- *
- * 日志格式（文本模式）：GET /api/users 200 12ms
- * 错误格式（文本模式）：POST /api/users 400 45ms - Error: ...
- *
- * 结构化模式：传入 pino/winston 等 logger 实例时，会自动传递结构化字段。
- *
- * before/after 一体，闭包变量共享开始时间，无需污染 ctx。
- * 错误用 try/catch 捕获，记录后重新抛出（让上层处理）。
- * 成功时从 next() 返回的 Response 读取状态码。
- *
- * log 函数每次请求时读取（options.log ?? console.log），运行时替换 console.log 会生效。
- */
-declare function logger(options?: LoggerOptions): FaapiMiddleware;
-
-interface HelmetOptions {
-    contentSecurityPolicy?: string | false;
-    xFrameOptions?: 'DENY' | 'SAMEORIGIN' | false;
-    xContentTypeOptions?: boolean;
-    referrerPolicy?: string | false;
-    strictTransportSecurity?: string | false;
-    xDnsPrefetchControl?: boolean;
-    xDownloadOptions?: boolean;
-    xPermittedCrossDomainPolicies?: string | false;
-    crossOriginOpenerPolicy?: string | false;
-    crossOriginResourcePolicy?: string | false;
-    crossOriginEmbedderPolicy?: string | false;
-    originAgentCluster?: boolean;
-    xPoweredBy?: boolean;
-}
-declare function helmet(options?: HelmetOptions): 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;
-    /** 中间件文件绝对路径列表（根在前，路由目录在后；按需加载用） */
-    middlewarePaths?: string[];
-    /** 路由对应的中间件集合（从根到路由目录合并，按需加载后缓存） */
-    middlewares?: FaapiMiddleware[];
-    /** 路由对应的注入器映射表（从根到路由目录合并，按需加载后缓存） */
-    injectors?: InjectorMap;
-}
-/**
- * WebSocket 路由记录
- *
- * 与 HTTP RouteRecord 类似，但不绑定 HTTP 方法（WS 是协议升级，不区分 GET/POST）。
- * 一个 handler.ts 中导出 WS 即生成一条 WS 路由记录。
- */
-interface WsRouteRecord {
-    urlPath: string;
-    filePath: string;
-    paramNames: string[];
-    isDynamic: boolean;
-    /** 是否为 catch-all 路由（[...slug]） */
-    isCatchAll?: boolean;
-    /** 中间件文件绝对路径列表（根在前，路由目录在后；按需加载用） */
-    middlewarePaths?: string[];
-    /** 路由对应的中间件集合（握手阶段执行，复用鉴权/CORS/日志；按需加载后缓存） */
-    middlewares?: FaapiMiddleware[];
-    /** 路由对应的注入器映射表 */
-    injectors?: InjectorMap;
-}
-type RouteManifest = RouteRecord[];
-type WsRouteManifest = WsRouteRecord[];
-/**
- * 路由单个参数的 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 生成。
- * output 为 null 表示无显式返回类型注解、void/Promise<void>、或解析失败降级。
- */
-interface RouteOutputSchema {
-    /** 命名类型名(如 'UserResponse'),内联类型为 null */
-    schemaName: string | null;
-    /** 顶层属性列表 */
-    properties: RouteParamSchema[];
-}
-/**
- * 路由的完整 schema 描述
- *
- * 由 @faapi/schema 扩展包的 buildRouteSchemas 生成。
- * 主包只定义类型契约，逻辑实现在扩展包。
- */
-interface RouteInfo {
-    method: string;
-    path: string;
-    filePath: string;
-    isDynamic: boolean;
-    inputs: RouteInputSchema[];
-    /** 响应类型描述(null 表示无返回类型注解/void/解析失败) */
-    output: RouteOutputSchema | null;
-}
 
 /** HTTP 请求 handler 类型 */
 type RequestHandler = (req: IncomingMessage, res: ServerResponse) => void;
@@ -1237,208 +748,6 @@ interface ValidationIssue {
 }
 type ValidationErrorCode = 'TYPE_MISMATCH' | 'MISSING_FIELD' | 'INVALID_FORMAT' | 'INVALID_VALUE' | 'COERCE_FAILED';
 
-/**
- * 从 Request 对象创建 FaapiContext
- * @param request Web Request 对象
- * @param params 动态路由参数
- * @param config 自定义业务配置（来自 faapi.config.ts）
- * @param ip 客户端 IP（由调用方从 IncomingMessage 提取，HTTP/WS 握手均通过 utils/getClientIp）
- *
- * ua 不作为参数传入：User-Agent 是标准 HTTP 请求头，createContext 内部直接从
- * request.headers 读取（与 ip 不同，ip 需要从 IncomingMessage 提取故由调用方传入）。
- */
-declare function createContext(request: Request, params: Record<string, string>, config?: Record<string, unknown>, ip?: string): FaapiContext;
-
-/**
- * 调用路由 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>;
-
 interface InjectOptions {
     method?: string;
     path?: string;
@@ -1451,6 +760,31 @@ interface InjectResponse {
     headers: Headers;
     body: unknown;
 }
+/**
+ * 获取当前 faapi app 单例
+ *
+ * 用于在无法直接拿到 app 引用的场景（如 Next.js Server Component）中访问 app。
+ *
+ * @returns 当前 app 实例
+ * @throws 未初始化时抛错（需先调 `createProdApp()` / `createDevApp()`，或 `faapi dev` / `node dist/main` 启动）
+ *
+ * @example
+ * ```ts
+ * // Next.js RSC 中调用 faapi API（同进程，跳过 HTTP loopback）
+ * import { getApp } from '@faapi/faapi';
+ * import { headers } from 'next/headers';
+ *
+ * const app = getApp();
+ * const h = await headers();
+ * const res = await app.inject({
+ *   method: 'GET',
+ *   path: '/api/user',
+ *   headers: { cookie: h.get('cookie') ?? '', authorization: h.get('authorization') ?? '' },
+ * });
+ * const data = res.body;  // 已解析
+ * ```
+ */
+declare function getApp(): AppBase;
 interface CreateAppOptions {
     /** 项目根目录，默认 process.cwd() */
     rootDir?: string;
@@ -1476,8 +810,11 @@ interface AppBase {
     /**
      * 无服务器测试注入
      *
-     * 构建一个模拟请求直接走完整请求链路，不绑定端口。
-     * 需要在 listen() 之前调用（server 未启动时）。
+     * 构建一个模拟请求直接走完整请求链路（CORS / helmet / logger / 全局中间件 / 路由匹配 /
+     * schema 校验 / 目录中间件 / handler），不绑定端口，返回已解析的 `{ status, headers, body }`。
+     *
+     * `listen()` 前后均可调用——`listen()` 后调用常用于 Next.js Server Component 等同进程场景
+     * （配合 `getApp()` 拿到 app 实例）。
      */
     inject(options?: InjectOptions): Promise<InjectResponse>;
 }
@@ -1532,4 +869,4 @@ type ProdApp = AppBase;
  */
 declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-export { type ProdApp as App, type CorsOptions, type CreateAppOptions, type DevApp, type FaapiConfig, type FaapiContext, type FaapiContextConfig, FaapiError, type FaapiMiddleware, type FaapiPlugin, type FailOptions, type HandlerTypeInfo, type HelmetOptions, type InjectOptions, type InjectResponse, type Injector, type InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LoggerOptions, MessageQueue, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, type RouteInfo, type RouteInputSchema, type RouteManifest, RouteNotFoundError, type RouteOutputSchema, type RouteParamSchema, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type SseEvent, type SseWriter, type TestServer, type TestServerOptions, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, type WsTestClient, type WsTestClientOptions, collectRouteSchemaSources, connectWs, cors, createProdApp as createApp, createContext, createDevApp, createProdApp, createProgram, createTestServer, extractTypeInfo, getInputTypeForMethod, helmet, invalidateProgramCache, invokeHandler, loadConfig, loadEnv, logger, resolveTypeNode, waitForWsOpen };
+export { type ProdApp as App, CorsOptions, type CreateAppOptions, type DevApp, type FaapiConfig, FaapiContext, FaapiError, FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, HelmetOptions, type InjectOptions, type InjectResponse, InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, collectRouteSchemaSources, createProdApp as createApp, createDevApp, createProdApp, createProgram, extractTypeInfo, getApp, getInputTypeForMethod, invalidateProgramCache, loadConfig, loadEnv, resolveTypeNode };