@faapi/faapi 0.0.0-canary.22b65a2 → 0.0.0-canary.a3f7014

package/dist/index.d.ts

@@ -381,6 +381,18 @@ interface RouteInputSchema {
     schemaName: string | null;
     properties: RouteParamSchema[];
 }
+/**
+ * 路由响应类型的 schema 描述
+ *
+ * 由 @faapi/schema 扩展包的 buildRouteSchemas 生成。
+ * output 为 null 表示无显式返回类型注解、void/Promise<void>、或解析失败降级。
+ */
+interface RouteOutputSchema {
+    /** 命名类型名(如 'UserResponse'),内联类型为 null */
+    schemaName: string | null;
+    /** 顶层属性列表 */
+    properties: RouteParamSchema[];
+}
 /**
  * 路由的完整 schema 描述
  *
@@ -393,6 +405,8 @@ interface RouteInfo {
     filePath: string;
     isDynamic: boolean;
     inputs: RouteInputSchema[];
+    /** 响应类型描述(null 表示无返回类型注解/void/解析失败) */
+    output: RouteOutputSchema | null;
 }
 
 /** HTTP 请求 handler 类型 */
@@ -410,8 +424,10 @@ type UpgradeHandler = (req: IncomingMessage, socket: Socket, head: Buffer) => vo
 interface PluginContext {
     /** 项目根目录 */
     rootDir: string;
-    /** 当前路由清单 */
+    /** 当前路由清单（setup 时的快照，reloadRoutes 后不会更新；需最新路由用 getRoutes()） */
     routes: RouteManifest;
+    /** 获取最新路由清单（reloadRoutes 后返回更新后的数组） */
+    getRoutes: () => RouteManifest;
     /** HTTP 服务器实例（未 listen） */
     server: Server;
     /** 自定义业务配置（faapi.config.ts 中的自定义 key） */
@@ -487,20 +503,6 @@ interface Http2Options {
     cert?: string;
 }
 
-/**
- * 统一响应格式化函数
- *
- * 当配置了 responseFormat 时，handler 返回的非 Response 值会经过此函数包装
- * 例如：{ code: 0, data, message: 'success' }
- */
-type ResponseFormatFn = (data: unknown, ctx: FaapiContext) => unknown;
-/**
- * 错误响应格式化函数
- *
- * 优先于内置 formatErrorResponse 处理错误。返回 Response 表示已处理；
- * 返回 null/undefined 表示不处理，由内置 formatErrorResponse 兜底。
- */
-type ErrorFormatFn = (error: unknown, ctx?: FaapiContext) => Response | null | undefined;
 /**
  * 生命周期钩子
  */
@@ -510,17 +512,17 @@ interface LifecycleHooks {
     /** 服务器关闭时调用（适合清理资源、优雅关闭） */
     onClose?: (ctx: LifecycleContext) => Promise<void> | void;
     /**
-     * 请求错误已被 errorFormat 处理为响应后调用（参考 Fastify onError 语义）
+     * 请求错误已被处理为响应后调用(参考 Fastify onError 语义)
      *
-     * 时机：handler 抛错 → errorFormat 生成错误响应（失败则由框架内置 formatErrorResponse 兜底）
+     * 时机:handler 抛错 → 全局中间件 try/catch(若有) → 框架内置 formatErrorResponse 兜底
      *      → 响应发出后 → onError 触发副作用
      *
-     * 职责：日志上报、告警、链路追踪等副作用。**不修改、不替换已生成的响应**。
-     * 自身抛错会被捕获并忽略，不影响响应已发送的事实。
+     * 职责:日志上报、告警、链路追踪等副作用。**不修改、不替换已生成的响应**。
+     * 自身抛错会被捕获并忽略,不影响响应已发送的事实。
      *
-     * 与 errorFormat 的区别：
-     * - errorFormat：把 error 翻译成 Response（主入口，决定响应内容）
-     * - onError：响应发出后的副作用（不能改响应）
+     * 与全局错误中间件的区别:
+     * - 全局错误中间件:把 error 翻译成 Response(主入口,决定响应内容)
+     * - onError:响应发出后的副作用(不能改响应)
      */
     onError?: (error: unknown, ctx: FaapiContext) => Promise<void> | void;
 }
@@ -566,10 +568,6 @@ interface LifecycleContext {
 interface FaapiConfig {
     /** CORS 配置，false 禁用 */
     cors?: CorsOptions | boolean;
-    /** 统一响应格式化函数 */
-    responseFormat?: ResponseFormatFn;
-    /** 错误响应格式化函数 */
-    errorFormat?: ErrorFormatFn;
     /** 生命周期钩子 */
     lifecycle?: LifecycleHooks;
     /** 安全头配置，false 禁用 */
@@ -831,7 +829,79 @@ interface PropertyType {
     name: string;
     type: RuntimeType;
     optional: boolean;
+    /**
+     * 字段级 JSDoc 约束标签（@max/@min/@maxLength 等）
+     *
+     * 来自字段 JSDoc 注释，由 generateZodSchema 转为 zod 链式调用。
+     * 约束与字段类型不匹配时在提取阶段抛 SchemaExtractionError。
+     */
+    constraints?: TypeConstraint[];
 }
+/**
+ * JSDoc 约束标签的运行时描述
+ *
+ * 由字段 JSDoc 注释提取，对应 zod schema 的链式约束方法。
+ * 仅在 PropertyType.constraints 中出现，不挂在嵌套类型（array 元素、tuple 元素等）上。
+ */
+type TypeConstraint = {
+    kind: 'max';
+    value: number;
+} | {
+    kind: 'min';
+    value: number;
+} | {
+    kind: 'int';
+} | {
+    kind: 'positive';
+} | {
+    kind: 'negative';
+} | {
+    kind: 'nonnegative';
+} | {
+    kind: 'nonpositive';
+} | {
+    kind: 'maxLength';
+    value: number;
+} | {
+    kind: 'minLength';
+    value: number;
+} | {
+    kind: 'length';
+    value: number;
+} | {
+    kind: 'regex';
+    pattern: string;
+    flags?: string;
+} | {
+    kind: 'email';
+} | {
+    kind: 'url';
+} | {
+    kind: 'uuid';
+};
+/**
+ * 将 TypeScript 类型节点解析为运行时类型描述
+ *
+ * 支持的类型：
+ * - 基础类型：string / number / boolean / null / undefined / any / unknown / void
+ * - bigint：不支持（HTTP/JSON 不能传输），AST 提取阶段抛 SchemaExtractionError
+ * - 字面量类型：'foo' / 42 / true
+ * - 数组类型：T[] / Array<T> / ReadonlyArray<T> / readonly T[]
+ * - 元组类型：[string, number] / [string, number?] / [string, ...number[]] / readonly [T, U]（按位置校验）
+ * - 对象类型：{ name: string; age?: number }（含 readonly 字段修饰符，忽略 readonly）
+ * - 联合类型：string | null
+ * - 交叉类型：A & B（按对象合并处理）
+ * - 引用类型：Date / 其他 interface（递归解析）
+ * - 工具类型：Record<K, V> / Partial<T> / Readonly<T>（best effort）
+ * - Pick<T, K> / Omit<T, K>：K 支持字面量联合、类型别名、keyof T
+ *
+ * readonly 是编译期约束，运行时不产生校验语义，所有 readonly 修饰符统一忽略。
+ *
+ * @param typeNode TypeScript 类型节点
+ * @param checker  类型 checker（用于解析引用类型）
+ * @param visited  防止递归循环
+ */
+declare function resolveTypeNode(typeNode: ts.TypeNode, checker?: ts.TypeChecker, visited?: Set<string>): RuntimeType;
 
 interface HandlerTypeInfo {
     name: string;
@@ -920,6 +990,60 @@ declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: stri
  */
 declare function loadConfig(rootDir: string, outDir: string): Promise<Partial<FaapiConfig> | null>;
 
+declare const VALIDATION_ERROR = "VALIDATION_ERROR";
+declare const ROUTE_NOT_FOUND = "ROUTE_NOT_FOUND";
+declare const METHOD_NOT_ALLOWED = "METHOD_NOT_ALLOWED";
+declare const INTERNAL_ERROR = "INTERNAL_ERROR";
+declare const MODULE_LOAD_ERROR = "MODULE_LOAD_ERROR";
+type ErrorCode = typeof VALIDATION_ERROR | typeof ROUTE_NOT_FOUND | typeof METHOD_NOT_ALLOWED | typeof INTERNAL_ERROR | typeof MODULE_LOAD_ERROR;
+
+declare class FaapiError extends Error {
+    readonly code: ErrorCode;
+    readonly statusCode: number;
+    constructor(code: ErrorCode, message: string, statusCode: number);
+}
+
+declare class ValidationError extends FaapiError {
+    readonly issues: ValidationIssue[];
+    constructor(message: string, issues: ValidationIssue[]);
+}
+declare class RouteNotFoundError extends FaapiError {
+    constructor(path: string);
+}
+declare class MethodNotAllowedError extends FaapiError {
+    readonly allowedMethods: string[];
+    constructor(method: string, path: string, allowedMethods: string[]);
+}
+declare class InternalError extends FaapiError {
+    constructor(message: string);
+}
+declare class ModuleLoadError extends FaapiError {
+    constructor(filePath: string, reason: string);
+}
+/**
+ * 校验问题类型
+ *
+ * 结构化错误信息,便于上层(全局错误中间件/前端)按 code 做不同处理,
+ * 不依赖字符串解析。message 仅为人类可读的兜底描述。
+ *
+ * code 与 HTTP 状态码的映射（由 ValidationError 推导）：
+ * - INVALID_FORMAT / MISSING_FIELD → 400 Bad Request
+ * - TYPE_MISMATCH / INVALID_VALUE / COERCE_FAILED → 422 Unprocessable Entity
+ */
+interface ValidationIssue {
+    /** 字段路径,如 'user.address.city' */
+    path: string;
+    /** 错误码,机器可读的契约 */
+    code: ValidationErrorCode;
+    /** 期望类型/值,如 'number' / '"admin" | "user"' */
+    expected: string;
+    /** 实际类型/值,如 'string' / 'undefined' */
+    received: string;
+    /** 人类可读的本地化消息(兜底,不保证稳定) */
+    message: string;
+}
+type ValidationErrorCode = 'TYPE_MISMATCH' | 'MISSING_FIELD' | 'INVALID_FORMAT' | 'INVALID_VALUE' | 'COERCE_FAILED';
+
 interface InjectOptions {
     method?: string;
     path?: string;
@@ -1013,4 +1137,4 @@ type ProdApp = AppBase;
  */
 declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-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 };
+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 };