@faapi/faapi 0.0.0-canary.0e994fe → 0.0.0-canary.22b65a2

package/dist/index.d.ts

@@ -99,6 +99,14 @@ interface FaapiContext {
     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;
     /** 解析后的所有 cookie 键值对 */
     cookies: Record<string, string>;
     /** 配置文件中的自定义业务配置（类型可通过 declare module '@faapi/faapi' 增强 FaapiContextConfig） */
@@ -111,6 +119,19 @@ interface FaapiContext {
      * 设置响应头
      */
     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）
      *
@@ -264,15 +285,24 @@ interface CorsOptions {
  */
 declare function cors(options?: CorsOptions): FaapiMiddleware;
 
+type LoggerFn = (messageOrObj: string | Record<string, unknown>, message?: string) => void;
 interface LoggerOptions {
-    /** 自定义日志输出函数，默认 console.log */
-    log?: (message: string) => void;
+    /**
+     * 自定义日志函数
+     *
+     * - 传入 `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: ...
+ * 日志格式（文本模式）：GET /api/users 200 12ms
+ * 错误格式（文本模式）：POST /api/users 400 45ms - Error: ...
+ *
+ * 结构化模式：传入 pino/winston 等 logger 实例时，会自动传递结构化字段。
  *
  * before/after 一体，闭包变量共享开始时间，无需污染 ctx。
  * 错误用 try/catch 捕获，记录后重新抛出（让上层处理）。
@@ -280,6 +310,23 @@ interface LoggerOptions {
  */
 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];
 
@@ -296,7 +343,26 @@ interface RouteRecord {
     /** 路由对应的注入器映射表（从根到路由目录合并，构建时加载） */
     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;
+    /** 路由对应的中间件集合（握手阶段执行，复用鉴权/CORS/日志） */
+    middlewares?: FaapiMiddleware[];
+    /** 路由对应的注入器映射表 */
+    injectors?: InjectorMap;
+}
 type RouteManifest = RouteRecord[];
+type WsRouteManifest = WsRouteRecord[];
 /**
  * 路由单个参数的 schema 描述
  *
@@ -416,6 +482,11 @@ type PluginDeclaration = string | [string, unknown] | {
     options?: unknown;
 };
 
+interface Http2Options {
+    key?: string;
+    cert?: string;
+}
+
 /**
  * 统一响应格式化函数
  *
@@ -434,7 +505,7 @@ type ErrorFormatFn = (error: unknown, ctx?: FaapiContext) => Response | null | u
  * 生命周期钩子
  */
 interface LifecycleHooks {
-    /** 路由加载完成、服务器启动前调用（适合初始化数据库连接等） */
+    /** 服务器启动后调用（适合初始化数据库连接等） */
     onReady?: (ctx: LifecycleContext) => Promise<void> | void;
     /** 服务器关闭时调用（适合清理资源、优雅关闭） */
     onClose?: (ctx: LifecycleContext) => Promise<void> | void;
@@ -471,7 +542,6 @@ interface LifecycleContext {
  * ```ts
  * import type { FaapiConfig } from '@faapi/faapi';
  * export default {
- *   port: 3000,
  *   cors: { origin: '*' },
  * } satisfies FaapiConfig;
  * ```
@@ -480,7 +550,6 @@ interface LifecycleContext {
  * ```ts
  * import type { FaapiConfig } from '@faapi/faapi';
  * export default {
- *   port: 3000,
  *   cors: { origin: '*' },
  *   // 自定义业务配置（任意 key）
  *   db: { host: 'localhost', port: 5432 },
@@ -488,12 +557,13 @@ interface LifecycleContext {
  * ```
  *
  * 环境覆盖通过 faapi.config.{NODE_ENV}.ts 实现（如 faapi.config.production.ts）
+ *
+ * 框架元信息通过环境变量配置（不放在 config 内）：
+ * - `FAAPI_APP_DIR`：源码目录前缀，默认 'src'，设为 '.' 表示源码在项目根目录
+ * - `PORT`：服务端口，默认 3000
+ * - `FAAPI_OUT_DIR`：产物输出目录，dev 固定为 '.faapi/dev'，prod 默认 'dist'
  */
 interface FaapiConfig {
-    /** 服务端口，默认 3000（可被 --port / PORT 环境变量覆盖） */
-    port?: number;
-    /** 静态文件目录 */
-    staticDir?: string;
     /** CORS 配置，false 禁用 */
     cors?: CorsOptions | boolean;
     /** 统一响应格式化函数 */
@@ -502,6 +572,14 @@ interface FaapiConfig {
     errorFormat?: ErrorFormatFn;
     /** 生命周期钩子 */
     lifecycle?: LifecycleHooks;
+    /** 安全头配置，false 禁用 */
+    helmet?: HelmetOptions | boolean;
+    /** 请求体大小限制（字节），默认 10MB（10 * 1024 * 1024） */
+    bodyLimit?: number;
+    /** 日志中间件配置 */
+    logger?: LoggerOptions | boolean;
+    /** HTTP/2 配置，false 禁用（默认 http/1.1） */
+    http2?: Http2Options | boolean;
     /**
      * 全局中间件：对所有路由（HTTP + WebSocket 握手）生效
      *
@@ -664,6 +742,15 @@ interface WsContext {
  */
 type WsHandler = (ctx: WsContext) => WsEventHandlers | void;
 
+/**
+ * 清理所有 Program 缓存（watch 模式下文件变化时调用）
+ *
+ * 全量清理而非增量清理，理由：
+ * - 简单可靠，无状态一致性问题
+ * - 跨文件类型引用需要所有文件的 Program 同步更新
+ * - dev 模式文件量有限，全量重建在百毫秒级
+ */
+declare function invalidateProgramCache(): void;
 /**
  * 为指定文件创建 TypeScript Program（带缓存）
  *
@@ -780,48 +867,150 @@ declare function extractTypeInfo(program: ts.Program, filePath: string, typeName
 declare function getInputTypeForMethod(method: string): 'query' | 'body';
 
 /**
- * 单个参数的 schema 描述（简化版，供扩展包消费）
+ * 单个路由的 schema 提取结果
+ *
+ * key 使用 urlPath（如 '/api/hello'）而非 filePath，因为 urlPath 在 dev/prod 完全一致，
+ * 无需 remapManifestKeys 桥接 .ts/.js 路径差异。
  */
-interface SchemaPropertyDescriptor {
-    name: string;
-    type: string;
-    required: boolean;
+interface RouteSchemaSource {
+    /** 路由 URL 路径（如 '/api/hello'），作为 schema key */
+    urlPath: string;
+    /** 源文件绝对路径（用于 generateSchemaFiles 按文件分组生成 zod.js） */
+    filePath: string;
+    schemaName: string;
+    typeInfo: HandlerTypeInfo | null;
 }
 /**
- * 单个输入源的 schema 描述
+ * 从路由清单收集 schema 提取所需的原始数据
+ *
+ * dev 和 prd 共享的核心提取流程：
+ * 1. 按文件分组遍历路由
+ * 2. 对每个文件 createProgram + extractAllTypes 收集所有类型
+ * 3. 用 analyzeInjection + extractTypeInfo 提取每个路由的 schema 类型
+ * 4. 同时返回按文件分组的 allTypesMap 和合并后的全局 allTypes
+ *
+ * 调用方基于返回的 sources 和 allTypes 各自做最终转换：
+ * - dev：生成 JS 模块文件 → import 加载（用 allTypesByFile）
+ * - prd：生成 JS 模块代码 → SchemaModuleEntry[]（用 allTypesByFile）
  */
-interface InputSchemaDescriptor {
-    /** 输入源类型名（如 'Query'、'CreateUserBody'），无类型声明时 null */
-    schemaName: string | null;
-    /** 参数列表 */
-    properties: SchemaPropertyDescriptor[];
+declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: string): {
+    sources: RouteSchemaSource[];
+    /** 按文件分组的类型映射（prd writeSchemaModule 用） */
+    allTypesByFile: Map<string, Map<string, HandlerTypeInfo>>;
+    /** 合并后的全局类型映射（兼容旧调用方保留，新路径使用 allTypesByFile） */
+    mergedAllTypes: Map<string, HandlerTypeInfo>;
+};
+
+/**
+ * 加载 faapi 配置文件
+ *
+ * 统一读取 `<outDir>/faapi-config.js` 产物：
+ * - dev 模式：`faapi dev` 启动时由 `compileConfig` 生成 `.faapi/dev/faapi-config.js`
+ * - prod 模式：`faapi build` 时由 `compileConfig` 生成 `dist/faapi-config.js`
+ *
+ * 产物由 `compileConfig` 在构建阶段合并 env 后固化，运行时不读源码、不现场编译、不按 env 合并。
+ *
+ * - 产物存在 → import 并返回 default
+ * - 产物不存在但源码有配置文件 → 抛错（强制 rebuild）
+ * - 源码也无配置文件 → 返回 `null`（配置可选）
+ *
+ * @param rootDir 项目根目录
+ * @param outDir 产物目录（如 'dist' 或 '.faapi/dev'）
+ * @returns 配置对象，无配置文件时返回 null
+ */
+declare function loadConfig(rootDir: string, outDir: string): Promise<Partial<FaapiConfig> | null>;
+
+interface InjectOptions {
+    method?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    body?: unknown;
+}
+interface InjectResponse {
+    status: number;
+    headers: Headers;
+    body: unknown;
+}
+interface CreateAppOptions {
+    /** 项目根目录，默认 process.cwd() */
+    rootDir?: string;
+    /** 源码目录前缀，覆盖环境变量 FAAPI_APP_DIR，默认 'src' */
+    appDir?: string;
+    /** 端口号，也可在 listen() 时传入；默认环境变量 PORT 或 3000 */
+    port?: number;
+}
+/** 应用基础接口（dev/prod 共用，不含 reloadRoutes） */
+interface AppBase {
+    /** Node.js Server 实例（listen 后可用，close 后置 null） */
+    server: Server | null;
+    /** 排序后的路由清单 */
+    routes: RouteManifest;
+    /** WebSocket 路由清单 */
+    wsRoutes: WsRouteManifest;
+    /** 项目根目录 */
+    rootDir: string;
+    /** 启动 HTTP server，打印路由表，执行 onReady 钩子 */
+    listen(port?: number): Promise<Server>;
+    /** 关闭 server，执行 onClose 钩子 */
+    close(): Promise<void>;
+    /**
+     * 无服务器测试注入
+     *
+     * 构建一个模拟请求直接走完整请求链路，不绑定端口。
+     * 需要在 listen() 之前调用（server 未启动时）。
+     */
+    inject(options?: InjectOptions): Promise<InjectResponse>;
+}
+
+/** dev 应用接口（AppBase + reloadRoutes 热替换） */
+interface DevApp extends AppBase {
+    /** 重新水合路由清单 + 清 schema 缓存 + 更新 server 路由引用（dev 热替换用） */
+    reloadRoutes(): Promise<void>;
 }
 /**
- * 查询指定路由 handler 的输入参数 schema
+ * dev 模式应用启动 API
+ *
+ * 在 createAppBase（共享逻辑）基础上增加 `reloadRoutes` 热替换能力，供 `faapi dev` watcher 调用。
  *
- * 复用 schemaRegistry 已有的类型提取结果，避免重复 AST 分析。
- * 在 schema 尚未注册时返回 undefined。
+ * 与 createProdApp 的区别：
+ * - dev：含 reloadRoutes（重新扫描路由 + 重新生成 schema + 清缓存 + 更新 server 路由引用）
+ * - prod：精简，无 reloadRoutes（产物已固化，运行时不重建）
  *
- * @param filePath handler 文件绝对路径
- * @param method HTTP 方法（GET/POST 等）
- * @param inputType 输入源类型（query/body/params）
+ * 由 `devCommand` 直接调用，devCommand 持有 app 引用并传给 watcher。
+ *
+ * @example
+ * ```ts
+ * // devCommand 内部
+ * const app = await createDevApp();
+ * await app.listen();
+ * startWatcher({ rootDir, appDir, app });
+ * ```
  */
-declare function getSchemaProperties(filePath: string, method: string, inputType: 'query' | 'body' | 'params'): InputSchemaDescriptor | undefined;
+declare function createDevApp(options?: CreateAppOptions): Promise<DevApp>;
+
+/** prod 应用接口（AppBase，无 reloadRoutes） */
+type ProdApp = AppBase;
 
 /**
- * 加载 faapi 配置文件
+ * prod 模式应用启动 API
  *
- * 查找顺序：
- * 1. 指定的 configPath
- * 2. faapi.config.ts / faapi.config.js（基础配置）
- * 3. faapi.config.{env}.ts / faapi.config.{env}.js（环境覆盖，深度合并）
+ * 直接返回 createAppBase 结果（共享逻辑），不含 dev 专用能力（reloadRoutes、缓存失效）。
+ * 产物在 `faapi build` 阶段已固化，运行时不重建。
  *
- * 环境由 NODE_ENV 或 FAAPI_ENV 决定，默认 'development'
+ * 框架采用零入口设计——用户无需编写 main.ts：
+ * - `faapi build` 自动生成 `dist/main.js` 启动入口，内部调用 `createProdApp()` + `listen()` 启动生产服务器
+ * - 用户自定义启动逻辑通过 `faapi.config.ts` 的 `lifecycle.onReady` / `onClose` 钩子实现
  *
- * @param rootDir 项目根目录
- * @param configPath 指定的配置文件路径（可选）
- * @returns 合并后的配置，如果无配置文件则返回 null
+ * 编程式调用场景（如自定义 CLI 启动器）也可直接调用：
+ *
+ * @example
+ * ```ts
+ * import { createProdApp } from '@faapi/faapi';
+ * const app = await createProdApp();
+ * await app.listen();
+ * ```
  */
-declare function loadConfig(rootDir: string, configPath?: string): Promise<Partial<FaapiConfig> | null>;
+declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-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 RequestHandler, type ResponseFormatFn, type RouteInfo, type RouteInputSchema, type RouteManifest, type RouteParamSchema, type RuntimeType, SchemaExtractionError, type SchemaPropertyDescriptor, type SseEvent, type SseWriter, type UpgradeHandler, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, cors, createProgram, extractTypeInfo, getInputTypeForMethod, getSchemaProperties, loadConfig, logger };
+export { type ProdApp as App, type CorsOptions, type CreateAppOptions, type DevApp, type ErrorFormatFn, type FaapiConfig, type FaapiContext, type FaapiContextConfig, type FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, type HelmetOptions, type InjectOptions, type InjectResponse, type Injector, type InjectorMap, type LifecycleContext, type LifecycleHooks, type LoggerOptions, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseFormatFn, type RouteInfo, type RouteInputSchema, type RouteManifest, type RouteParamSchema, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type SseEvent, type SseWriter, type UpgradeHandler, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, collectRouteSchemaSources, cors, createProdApp as createApp, createDevApp, createProdApp, createProgram, extractTypeInfo, getInputTypeForMethod, helmet, invalidateProgramCache, loadConfig, logger };