@faapi/faapi 1.5.0 → 2.0.1-canary.0

package/dist/routeTypes-FtbRkpVF.d.ts

@@ -0,0 +1,491 @@
+/**
+ * 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;
+}
+
+export { type CorsOptions as C, type FaapiContext as F, type HelmetOptions as H, type InjectorMap as I, type LoggerOptions as L, type RouteManifest as R, type SseEvent as S, type WsRouteManifest as W, type FaapiMiddleware as a, type FaapiContextConfig as b, type FailOptions as c, type Injector as d, type RouteInfo as e, type RouteInputSchema as f, type RouteOutputSchema as g, type RouteParamSchema as h, type SseWriter as i, cors as j, helmet as k, logger as l };