vafast 0.1.9 → 0.1.10

package/dist/index.d.ts

@@ -0,0 +1,459 @@
+import { Static, TSchema } from "@sinclair/typebox";
+
+//#region src/types.d.ts
+type Method = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD";
+type Handler = (req: Request, params?: Record<string, string>, user?: Record<string, any>) => Response | Promise<Response>;
+type Middleware = (req: Request, next: () => Promise<Response>) => Promise<Response>;
+interface Route {
+  method: Method;
+  path: string;
+  handler: Handler;
+  middleware?: Middleware[];
+}
+interface NestedRoute {
+  path: string;
+  middleware?: Middleware[];
+  children?: (NestedRoute | Route)[];
+}
+interface FlattenedRoute extends Route {
+  fullPath: string;
+  middlewareChain: Middleware[];
+}
+//#endregion
+//#region src/server/base-server.d.ts
+/**
+ * 服务器基类
+ * 包含所有服务器类型的公共逻辑
+ */
+declare abstract class BaseServer {
+  protected globalMiddleware: Middleware[];
+  use(mw: Middleware): void;
+  /**
+   * 打印扁平化后的路由信息，用于调试
+   */
+  protected logFlattenedRoutes(routes: any[], type?: string): void;
+  /**
+   * 检测路由冲突
+   * 检查是否有路径相同但方法不同的路由，以及潜在的路径冲突
+   */
+  protected detectRouteConflicts(routes: any[]): void;
+  /**
+   * 检测动态路由的潜在冲突
+   */
+  private detectDynamicRouteConflicts;
+  /**
+   * 判断两个路径是否可能冲突
+   */
+  private pathsMayConflict;
+  /**
+   * 路径匹配
+   */
+  protected matchPath(pattern: string, path: string): boolean;
+  /**
+   * 提取路径参数
+   */
+  protected extractParams(pattern: string, path: string): Record<string, string>;
+  /**
+   * 处理 OPTIONS 请求
+   */
+  protected handleOptions(pathname: string, routes: any[]): Response;
+}
+//#endregion
+//#region src/server/server.d.ts
+declare class Server extends BaseServer {
+  private routes;
+  constructor(routes: (Route | NestedRoute)[]);
+  fetch: (req: Request) => Promise<Response>;
+}
+//#endregion
+//#region src/types/route.d.ts
+interface Middleware$1 {
+  (req: Request, next: () => Promise<Response>): Promise<Response>;
+}
+//#endregion
+//#region src/types/component-route.d.ts
+/**
+ * 组件路由配置
+ * 支持声明式的组件关联
+ */
+interface ComponentRoute {
+  path: string;
+  component: () => Promise<any>;
+  middleware?: Middleware$1[];
+}
+/**
+ * 嵌套组件路由配置
+ */
+interface NestedComponentRoute {
+  path: string;
+  middleware?: Middleware$1[];
+  children?: (ComponentRoute | NestedComponentRoute)[];
+}
+/**
+ * 扁平化后的组件路由
+ */
+//#endregion
+//#region src/utils/dependency-manager.d.ts
+/**
+ * 依赖管理器
+ * 负责按需加载和管理框架依赖
+ */
+declare class DependencyManager {
+  private dependencyCache;
+  /**
+   * 按需获取框架依赖
+   */
+  getFrameworkDeps(framework: "vue" | "react"): Promise<any>;
+  /**
+   * 检测组件类型
+   */
+  detectComponentType(component: any): "vue" | "react";
+  /**
+   * 清除缓存
+   */
+  clearCache(): void;
+  /**
+   * 获取缓存状态
+   */
+  getCacheStatus(): Record<string, boolean>;
+}
+//#endregion
+//#region src/server/component-server.d.ts
+/**
+ * 组件路由服务器
+ * 专门处理声明式组件路由
+ */
+declare class ComponentServer extends BaseServer {
+  private routes;
+  private dependencyManager;
+  constructor(routes: (ComponentRoute | NestedComponentRoute)[]);
+  /**
+   * 处理请求
+   */
+  fetch(req: Request): Promise<Response>;
+  /**
+   * 执行中间件链
+   */
+  private executeMiddlewareChain;
+  /**
+   * 渲染 Vue 组件
+   */
+  private renderVueComponent;
+  /**
+   * 渲染 React 组件
+   */
+  private renderReactComponent;
+  /**
+   * 获取依赖管理器（用于外部访问）
+   */
+  getDependencyManager(): DependencyManager;
+}
+//#endregion
+//#region src/server/server-factory.d.ts
+/**
+ * 服务器工厂类
+ * 用于创建和管理不同类型的服务器
+ */
+declare class ServerFactory {
+  private servers;
+  /**
+   * 创建标准REST API服务器
+   */
+  createRestServer(routes: (Route | NestedRoute)[]): Server;
+  /**
+   * 创建组件服务器
+   */
+  createComponentServer(routes: (ComponentRoute | NestedComponentRoute)[]): ComponentServer;
+  /**
+   * 获取指定类型的服务器
+   */
+  getServer(type: "rest" | "component"): Server | ComponentServer | undefined;
+  /**
+   * 获取所有服务器
+   */
+  getAllServers(): Map<string, Server | ComponentServer>;
+  /**
+   * 移除指定类型的服务器
+   */
+  removeServer(type: string): boolean;
+  /**
+   * 清除所有服务器
+   */
+  clearServers(): void;
+  /**
+   * 获取服务器状态信息
+   */
+  getServerStatus(): Record<string, {
+    type: string;
+    routes: number;
+  }>;
+}
+//#endregion
+//#region src/utils/path-matcher.d.ts
+/**
+ * 路径匹配工具类
+ * 提供统一的路径匹配和参数提取功能
+ */
+declare class PathMatcher {
+  /**
+   * 路径匹配
+   */
+  static matchPath(pattern: string, path: string): boolean;
+  /**
+   * 提取路径参数
+   */
+  static extractParams(pattern: string, path: string): Record<string, string>;
+  /**
+   * 计算路径特异性分数
+   * 用于路由排序：静态 > 动态(:param) > 通配符(*)
+   */
+  static calculatePathScore(path: string): number;
+  /**
+   * 判断两个路径是否可能冲突
+   */
+  static pathsMayConflict(path1: string, path2: string): boolean;
+}
+//#endregion
+//#region src/utils/html-renderer.d.ts
+/**
+ * HTML渲染工具类
+ * 提供统一的HTML模板生成功能
+ */
+declare class HtmlRenderer {
+  /**
+   * 生成基础HTML模板
+   */
+  static generateBaseHtml(content: string, context: any, clientScriptPath?: string): string;
+  /**
+   * 生成Vue组件HTML
+   */
+  static generateVueHtml(content: string, context: any, clientScriptPath?: string): string;
+  /**
+   * 生成React组件HTML
+   */
+  static generateReactHtml(content: string, context: any, clientScriptPath?: string): string;
+}
+//#endregion
+//#region src/middleware.d.ts
+/** 中间件类型：使用 next() 传递给下一个处理 */
+/** Vafast 自定义错误类型 */
+declare class VafastError extends Error {
+  status: number;
+  type: string;
+  expose: boolean;
+  constructor(message: string, options?: {
+    status?: number;
+    type?: string;
+    expose?: boolean;
+    cause?: unknown;
+  });
+}
+/**
+ * 组合类型: 自动注入错误处理器进行中间件组合
+ */
+declare function composeMiddleware(middleware: Middleware[], finalHandler: Handler): Handler;
+//#endregion
+//#region src/utils/parsers.d.ts
+interface FileInfo {
+  name: string;
+  type: string;
+  size: number;
+  data: ArrayBuffer;
+}
+interface FormData {
+  fields: Record<string, string>;
+  files: Record<string, FileInfo>;
+}
+/**
+ * 简化的请求体解析函数
+ * 优先简洁性，处理最常见的场景
+ */
+declare function parseBody(req: Request): Promise<unknown>;
+/**
+ * 解析请求体为特定类型
+ * 提供类型安全的解析方法
+ */
+declare function parseBodyAs<T>(req: Request): Promise<T>;
+/**
+ * 解析请求体为表单数据
+ * 专门用于处理 multipart/form-data
+ */
+declare function parseFormData(req: Request): Promise<FormData>;
+/**
+ * 解析请求体为文件
+ * 专门用于处理文件上传
+ */
+declare function parseFile(req: Request): Promise<FileInfo>;
+/** 获取查询字符串，直接返回对象 */
+declare function parseQuery(req: Request): Record<string, any>;
+/** 解析请求头，返回对象 */
+declare function parseHeaders(req: Request): Record<string, string>;
+/** 使用cookie库解析Cookie，保证可靠性 */
+declare function parseCookies(req: Request): Record<string, string>;
+//#endregion
+//#region src/utils/response.d.ts
+/** 生成 JSON 响应 */
+declare function json(data: unknown, status?: number, headers?: HeadersInit): Response;
+/** 生成重定向响应 */
+declare function redirect(location: string, status?: 301 | 302): Response;
+/** 生成纯文本响应 */
+declare function text(content: string, status?: number, headers?: HeadersInit): Response;
+/** 生成HTML响应 */
+declare function html(content: string, status?: number, headers?: HeadersInit): Response;
+/** 生成空响应（204 No Content） */
+declare function empty(status?: number, headers?: HeadersInit): Response;
+/** 生成流式响应 */
+declare function stream(stream: ReadableStream, status?: number, headers?: HeadersInit): Response;
+//#endregion
+//#region src/router.d.ts
+interface MatchResult {
+  matched: boolean;
+  params: Record<string, string>;
+}
+/**
+ * 扁平化嵌套路由，计算完整路径和中间件链
+ */
+declare function flattenNestedRoutes(routes: (Route | NestedRoute)[]): FlattenedRoute[];
+/**
+ * 标准化路径：去重斜杠、解码URL、处理结尾斜杠
+ */
+declare function normalizePath(path: string): string;
+/**
+ * 匹配函数：支持动态路由和路径标准化
+ */
+declare function matchPath(pattern: string, path: string): MatchResult;
+//#endregion
+//#region src/middleware/authMiddleware.d.ts
+declare const requireAuth: Middleware;
+//#endregion
+//#region src/middleware/rateLimit.d.ts
+interface RateLimitOptions {
+  windowMs?: number;
+  max?: number;
+  keyFn?: (req: Request) => string;
+}
+declare function rateLimit(options?: RateLimitOptions): Middleware;
+//#endregion
+//#region src/middleware/cors.d.ts
+interface CORSOptions {
+  origin?: string[] | "*";
+  methods?: string[];
+  headers?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+}
+declare function createCORS(options?: CORSOptions): Middleware;
+//#endregion
+//#region src/auth/token.d.ts
+interface TokenPayload {
+  [key: string]: any;
+  exp?: number;
+  iat?: number;
+  sub?: string;
+  aud?: string;
+  iss?: string;
+}
+interface TokenResult {
+  payload: TokenPayload;
+  token: string;
+  expiresAt: number;
+}
+interface TokenOptions {
+  expiresIn?: number;
+  issuer?: string;
+  audience?: string;
+  subject?: string;
+}
+declare class TokenError extends Error {
+  code: "INVALID_TOKEN" | "EXPIRED_TOKEN" | "INVALID_SIGNATURE" | "MALFORMED_TOKEN" | "INVALID_PAYLOAD";
+  constructor(message: string, code: "INVALID_TOKEN" | "EXPIRED_TOKEN" | "INVALID_SIGNATURE" | "MALFORMED_TOKEN" | "INVALID_PAYLOAD");
+}
+/** 生成令牌 */
+declare function generateToken(payload: TokenPayload, secret: string, options?: TokenOptions): Promise<TokenResult>;
+/** 验证令牌 */
+declare function verifyToken(token: string, secret: string): Promise<TokenPayload | null>;
+/** 解析令牌（不验证签名） */
+declare function parseToken(token: string): TokenPayload | null;
+/** 检查令牌是否过期 */
+declare function isTokenExpired(token: string): boolean;
+/** 获取令牌剩余有效时间（秒） */
+declare function getTokenTimeRemaining(token: string): number;
+/** 刷新令牌 */
+declare function refreshToken(token: string, secret: string, options?: TokenOptions): Promise<TokenResult | null>;
+/** 创建访问令牌和刷新令牌对 */
+declare function createTokenPair(payload: TokenPayload, secret: string, options?: TokenOptions): Promise<{
+  accessToken: TokenResult;
+  refreshToken: TokenResult;
+}>;
+//#endregion
+//#region src/middleware/auth.d.ts
+interface AuthOptions {
+  secret: string;
+  cookieName?: string;
+  headerName?: string;
+  required?: boolean;
+  roles?: string[];
+  permissions?: string[];
+}
+declare function createAuth(options: AuthOptions): Middleware;
+declare function createOptionalAuth(options: Omit<AuthOptions, "required">): Middleware;
+declare function createRoleAuth(roles: string[], options: Omit<AuthOptions, "roles">): Middleware;
+declare function createPermissionAuth(permissions: string[], options: Omit<AuthOptions, "permissions">): Middleware;
+//#endregion
+//#region src/utils/base64url.d.ts
+declare function base64urlEncode(str: string): string;
+declare function base64urlDecode(str: string): string;
+//#endregion
+//#region src/defineRoute.d.ts
+declare function defineRoutes(routes: Route[]): Route[];
+//#endregion
+//#region src/utils/validators/schema-validators-ultra.d.ts
+interface SchemaConfig {
+  body?: TSchema;
+  query?: TSchema;
+  params?: TSchema;
+  headers?: TSchema;
+  cookies?: TSchema;
+}
+//#endregion
+//#region src/utils/route-handler-factory.d.ts
+interface TypedConfig extends SchemaConfig {
+  docs?: any;
+  timeout?: number;
+  maxBodySize?: string;
+  validationErrorHandler?: ValidationErrorHandler;
+  [key: string]: any;
+}
+type ValidationErrorHandler = (error: Error, field: string, value: any, schema: any) => Response | Promise<Response>;
+type TypedHandler<TBody = any, TQuery = any, TParams = any, THeaders = any, TCookies = any, TExtra extends object = {}> = (ctx: {
+  req: Request;
+  body: TBody;
+  query: TQuery;
+  params: TParams;
+  headers: THeaders;
+  cookies: TCookies;
+} & TExtra) => Response | Promise<Response> | any | Promise<any>;
+declare function createRouteHandler<TConfig extends TypedConfig, TBody = (TConfig extends {
+  body: any;
+} ? Static<TConfig["body"]> : any), TQuery = (TConfig extends {
+  query: any;
+} ? Static<TConfig["query"]> : any), TParams = (TConfig extends {
+  params: any;
+} ? Static<TConfig["params"]> : any), THeaders = (TConfig extends {
+  headers: any;
+} ? Static<TConfig["headers"]> : any), TCookies = (TConfig extends {
+  cookies: any;
+} ? Static<TConfig["cookies"]> : any), TExtra extends object = {}>(handler: TypedHandler<TBody, TQuery, TParams, THeaders, TCookies, TExtra>, config?: TConfig): (req: Request) => Promise<Response>;
+declare function withExtra<TExtra extends object = {}>(): <TConfig extends TypedConfig>(config: TConfig, handler: TypedHandler<TConfig extends {
+  body: any;
+} ? Static<TConfig["body"]> : any, TConfig extends {
+  query: any;
+} ? Static<TConfig["query"]> : any, TConfig extends {
+  params: any;
+} ? Static<TConfig["params"]> : any, TConfig extends {
+  headers: any;
+} ? Static<TConfig["headers"]> : any, TConfig extends {
+  cookies: any;
+} ? Static<TConfig["cookies"]> : any, TExtra>) => (req: Request) => Promise<Response>;
+//#endregion
+export { BaseServer, CORSOptions, ComponentServer, DependencyManager, FileInfo, FlattenedRoute, FormData, Handler, HtmlRenderer, MatchResult, Method, Middleware, NestedRoute, PathMatcher, Route, Server, ServerFactory, TokenError, TokenOptions, TokenPayload, TokenResult, TypedConfig, TypedHandler, VafastError, ValidationErrorHandler, base64urlDecode, base64urlEncode, composeMiddleware, createAuth, createCORS, createOptionalAuth, createPermissionAuth, createRoleAuth, createRouteHandler, createTokenPair, defineRoutes, empty, flattenNestedRoutes, generateToken, getTokenTimeRemaining, html, isTokenExpired, json, matchPath, normalizePath, parseBody, parseBodyAs, parseCookies, parseFile, parseFormData, parseHeaders, parseQuery, parseToken, rateLimit, redirect, refreshToken, requireAuth, stream, text, verifyToken, withExtra };