@faapi/faapi 6.24.0 → 6.26.0

package/dist/routeTypes-DlD6nnbT.d.ts

@@ -0,0 +1,204 @@
+import { F as FaapiContext } from './contextTypes-gYf84EXF.js';
+
+/**
+ * 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 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 FaapiMiddleware as F, type HelmetOptions as H, type InjectorMap as I, type RouteManifest as R, type WsRouteManifest as W, type Injector as a, type RouteInfo as b, type RouteInputSchema as c, type RouteOutputSchema as d, type RouteParamSchema as e, cors as f, helmet as h };

package/dist/testing.d.ts

@@ -1,4 +1,5 @@
-import { a as FaapiContext, F as FaapiMiddleware, I as InjectorMap, R as RouteManifest, W as WsRouteManifest, C as CorsOptions, H as HelmetOptions } from './routeTypes-D1swYDVC.js';
+import { F as FaapiContext } from './contextTypes-gYf84EXF.js';
+import { F as FaapiMiddleware, I as InjectorMap, R as RouteManifest, W as WsRouteManifest, C as CorsOptions, H as HelmetOptions } from './routeTypes-DlD6nnbT.js';
 import { Server } from 'node:http';
 import { WebSocket } from 'ws';
 
@@ -25,7 +26,12 @@ declare function createTestContext(options: CreateTestContextOptions): FaapiCont
 interface CreateTestContextOptions {
     /** app 级注册表（测试 handler 声明 agent/agents 参数时注入用，可选） */
     registries?: FaapiContext['registries'];
-    /** 运行时资源根目录（测试 handler 读 ctx.resourcesDir 时传入，可选） */
+    /**
+     * 运行时资源根目录（可选）
+     *
+     * 传入时同时做两件事：绑定全局 readResource 读取根（handler 直调
+     * `readResource('x.md')` 依赖）+ 挂到 ctx.resourcesDir 数据字段
+     */
     resourcesDir?: string;
     /** 请求方法，默认 'GET' */
     method?: string;