@faapi/faapi 0.0.0-canary.2a7b6a3 → 0.0.0-canary.4e89b9b

package/dist/index.d.ts

@@ -307,6 +307,8 @@ interface LoggerOptions {
  * before/after 一体，闭包变量共享开始时间，无需污染 ctx。
  * 错误用 try/catch 捕获，记录后重新抛出（让上层处理）。
  * 成功时从 next() 返回的 Response 读取状态码。
+ *
+ * log 函数每次请求时读取（options.log ?? console.log），运行时替换 console.log 会生效。
  */
 declare function logger(options?: LoggerOptions): FaapiMiddleware;
 
@@ -561,9 +563,8 @@ 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'
+ * - `FAAPI_DIST`：产物输出目录，dev 固定为 `.faapi`（不可修改），prod 默认为 `dist`（可通过 `--dist` 修改）
  */
 interface FaapiConfig {
     /** CORS 配置，false 禁用 */
@@ -810,6 +811,13 @@ type RuntimeType = {
     kind: 'record';
     key: RuntimeType;
     value: RuntimeType;
+} | {
+    kind: 'map';
+    key: RuntimeType;
+    value: RuntimeType;
+} | {
+    kind: 'set';
+    element: RuntimeType;
 } | {
     kind: 'ref';
     name: string;
@@ -949,6 +957,18 @@ interface RouteSchemaSource {
     filePath: string;
     schemaName: string;
     typeInfo: HandlerTypeInfo | null;
+    /**
+     * 是否对 number/boolean 字段生成 z.preprocess 字符串转换（coerce）。
+     *
+     * - query/params：始终 coerce=true（URL 来源均为 string）
+     * - body：始终 coerce=false（JSON 解析已是天然 JS 类型）
+     * - form：coerce=true（form-urlencoded 来源均为 string），由本函数在提取时
+     *   检测到 handler 声明 `form` 参数时显式设置。schema 名仍为 `POSTBody`
+     *   （与 body 共享运行时 schema key），运行时 validateInput 无需感知 form/body 差异。
+     *
+     * 未设置时由 generateSchemaFileSource 回退到 schemaName 后缀正则推断（Query/Params → true）。
+     */
+    coerce?: boolean;
 }
 /**
  * 从路由清单收集 schema 提取所需的原始数据
@@ -974,8 +994,8 @@ declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: stri
 /**
  * 加载 faapi 配置文件
  *
- * 统一读取 `<outDir>/faapi-config.js` 产物：
- * - dev 模式：`faapi dev` 启动时由 `compileConfig` 生成 `.faapi/dev/faapi-config.js`
+ * 统一读取 `<dist>/faapi-config.js` 产物：
+ * - dev 模式：`faapi dev` 启动时由 `compileConfig` 生成 `.faapi/faapi-config.js`
  * - prod 模式：`faapi build` 时由 `compileConfig` 生成 `dist/faapi-config.js`
  *
  * 产物由 `compileConfig` 在构建阶段合并 env 后固化，运行时不读源码、不现场编译、不按 env 合并。
@@ -985,10 +1005,10 @@ declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: stri
  * - 源码也无配置文件 → 返回 `null`（配置可选）
  *
  * @param rootDir 项目根目录
- * @param outDir 产物目录（如 'dist' 或 '.faapi/dev'）
+ * @param dist 产物目录（如 'dist' 或 '.faapi'）
  * @returns 配置对象，无配置文件时返回 null
  */
-declare function loadConfig(rootDir: string, outDir: string): Promise<Partial<FaapiConfig> | null>;
+declare function loadConfig(rootDir: string, dist: string): Promise<Partial<FaapiConfig> | null>;
 
 declare const VALIDATION_ERROR = "VALIDATION_ERROR";
 declare const ROUTE_NOT_FOUND = "ROUTE_NOT_FOUND";
@@ -1044,6 +1064,30 @@ 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）
+ */
+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>;
+
 interface InjectOptions {
     method?: string;
     path?: string;
@@ -1059,8 +1103,8 @@ interface InjectResponse {
 interface CreateAppOptions {
     /** 项目根目录，默认 process.cwd() */
     rootDir?: string;
-    /** 源码目录前缀，覆盖环境变量 FAAPI_APP_DIR，默认 'src' */
-    appDir?: string;
+    /** 产物输出目录（如 dist 或 .faapi），覆盖环境变量 FAAPI_DIST，默认 'dist' */
+    dist?: string;
     /** 端口号，也可在 listen() 时传入；默认环境变量 PORT 或 3000 */
     port?: number;
 }
@@ -1108,7 +1152,7 @@ interface DevApp extends AppBase {
  * // devCommand 内部
  * const app = await createDevApp();
  * await app.listen();
- * startWatcher({ rootDir, appDir, app });
+ * startWatcher({ rootDir, app, devDist });
  * ```
  */
 declare function createDevApp(options?: CreateAppOptions): Promise<DevApp>;
@@ -1137,4 +1181,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 HandlerTypeInfo, type HelmetOptions, type InjectOptions, type InjectResponse, type Injector, type InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type RouteInfo, type RouteInputSchema, type RouteManifest, RouteNotFoundError, type RouteOutputSchema, type RouteParamSchema, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type SseEvent, type SseWriter, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, collectRouteSchemaSources, cors, createProdApp as createApp, createDevApp, createProdApp, createProgram, extractTypeInfo, getInputTypeForMethod, helmet, invalidateProgramCache, loadConfig, logger, resolveTypeNode };
+export { type ProdApp as App, type CorsOptions, type CreateAppOptions, type DevApp, type FaapiConfig, type FaapiContext, type FaapiContextConfig, FaapiError, type FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, type HelmetOptions, type InjectOptions, type InjectResponse, type Injector, type InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type RouteInfo, type RouteInputSchema, type RouteManifest, RouteNotFoundError, type RouteOutputSchema, type RouteParamSchema, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type SseEvent, type SseWriter, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, collectRouteSchemaSources, cors, createProdApp as createApp, createContext, createDevApp, createProdApp, createProgram, extractTypeInfo, getInputTypeForMethod, helmet, invalidateProgramCache, invokeHandler, loadConfig, logger, resolveTypeNode };