vafast 0.1.13 → 0.2.1

package/dist/server/server.js

@@ -1,73 +1,97 @@
-import { matchPath, flattenNestedRoutes } from "../router";
+/**
+ * Vafast 核心服务器
+ *
+ * 基于 Radix Tree 的高性能路由匹配
+ * 时间复杂度: O(k)，k 为路径段数
+ */
+import { flattenNestedRoutes } from "../router";
 import { composeMiddleware } from "../middleware";
 import { json } from "../utils/response";
 import { BaseServer } from "./base-server";
-import { PathMatcher } from "../utils/path-matcher";
+import { RadixRouter } from "../router/radix-tree";
+/**
+ * Vafast 服务器
+ *
+ * @example
+ * ```typescript
+ * const server = new Server([
+ *   { method: "GET", path: "/", handler: () => new Response("Hello") },
+ * ]);
+ * export default { fetch: server.fetch };
+ * ```
+ */
 export class Server extends BaseServer {
+    router;
     routes;
-    constructor(routes) {
+    constructor(routes = []) {
         super();
-        // 扁平化嵌套路由，计算完整的中间件链
-        this.routes = flattenNestedRoutes(routes);
-        // 在构造时按路由"特异性"排序：静态 > 动态(:param) > 通配符(*)
-        this.routes = this.routes.sort((a, b) => PathMatcher.calculatePathScore(b.fullPath) -
-            PathMatcher.calculatePathScore(a.fullPath));
-        // 检测路由冲突
-        this.detectRouteConflicts(this.routes);
-        // 打印扁平化后的路由信息
-        this.logFlattenedRoutes(this.routes);
+        this.router = new RadixRouter();
+        this.routes = [];
+        if (routes.length > 0) {
+            this.registerRoutes(routes);
+        }
+    }
+    registerRoutes(routes) {
+        const flattened = flattenNestedRoutes(routes);
+        this.routes.push(...flattened);
+        for (const route of flattened) {
+            this.router.register(route.method, route.fullPath, route.handler, route.middlewareChain || []);
+        }
+        this.detectRouteConflicts(flattened);
+        this.logFlattenedRoutes(flattened);
     }
+    /** 快速提取 pathname */
+    extractPathname(url) {
+        let start = url.indexOf("://");
+        start = start === -1 ? 0 : start + 3;
+        const pathStart = url.indexOf("/", start);
+        if (pathStart === -1)
+            return "/";
+        let end = url.indexOf("?", pathStart);
+        if (end === -1)
+            end = url.indexOf("#", pathStart);
+        if (end === -1)
+            end = url.length;
+        return url.substring(pathStart, end) || "/";
+    }
+    /** 处理请求 */
     fetch = async (req) => {
-        const { pathname } = new URL(req.url);
+        const pathname = this.extractPathname(req.url);
         const method = req.method;
-        // 自动处理 OPTIONS 请求
-        if (method === "OPTIONS") {
-            return this.handleOptions(pathname, this.routes);
+        const match = this.router.match(method, pathname);
+        if (match) {
+            req.params = match.params;
+            // 组合全局中间件 + 路由中间件（mapResponse 在 composeMiddleware 内部处理）
+            const allMiddleware = [...this.globalMiddleware, ...match.middleware];
+            const handler = composeMiddleware(allMiddleware, match.handler);
+            return handler(req);
         }
-        let matched;
-        let params = {};
-        let availableMethods = [];
-        for (const route of this.routes) {
-            const result = matchPath(route.fullPath, pathname);
-            if (result.matched) {
-                if (route.method === method) {
-                    matched = route;
-                    params = result.params;
-                    break;
-                }
-                else {
-                    // 路径匹配但方法不匹配，收集可用方法
-                    availableMethods.push(route.method);
-                }
-            }
+        // 405 Method Not Allowed
+        const allowedMethods = this.router.getAllowedMethods(pathname);
+        if (allowedMethods.length > 0) {
+            return json({
+                success: false,
+                error: "Method Not Allowed",
+                message: `Method ${method} not allowed for this endpoint`,
+                allowedMethods,
+            }, 405, { Allow: allowedMethods.join(", ") });
         }
-        const handler = async (req) => {
-            if (matched) {
-                // 将路径参数设置到 req 对象上，以便 TypedRoute 处理器能够访问
-                req.params = params;
-                return await matched.handler(req);
-            }
-            else if (availableMethods.length > 0) {
-                // 路径存在但方法不匹配，返回 405 Method Not Allowed
-                return json({
-                    success: false,
-                    error: "Method Not Allowed",
-                    message: `Method ${method} not allowed for this endpoint`,
-                    allowedMethods: availableMethods,
-                }, 405, {
-                    Allow: availableMethods.join(", "),
-                });
-            }
-            else {
-                // 路径不存在，返回 404 Not Found
-                return json({ success: false, error: "Not Found" }, 404);
-            }
-        };
-        const middlewareChain = matched?.middlewareChain
-            ? [...this.globalMiddleware, ...matched.middlewareChain]
-            : this.globalMiddleware;
-        // 使用 composeMiddleware 来确保错误处理中间件被应用
-        const composedHandler = composeMiddleware(middlewareChain, handler);
-        return await composedHandler(req);
+        // 404 Not Found
+        return json({ success: false, error: "Not Found" }, 404);
     };
+    addRoute(route) {
+        const flattenedRoute = {
+            ...route,
+            fullPath: route.path,
+            middlewareChain: route.middleware || [],
+        };
+        this.routes.push(flattenedRoute);
+        this.router.register(route.method, route.path, route.handler, route.middleware || []);
+    }
+    addRoutes(routes) {
+        this.registerRoutes(routes);
+    }
+    getRoutes() {
+        return this.router.getRoutes();
+    }
 }

package/dist/types/index.d.ts

@@ -1,3 +1,5 @@
-export * from "./route";
+export type { Method, Handler, Route, NestedRoute, Middleware, FlattenedRoute, ResponseBody, } from "./types";
+export type { BaseRouteConfig, ExtendedRouteConfig, NestedRouteConfig, TypedRoute, CompatibleRoute, } from "./route";
+export { createTypedRoute, isTypedRoute } from "./route";
 export * from "./component-route";
-export type { Method, Handler, Route, NestedRoute } from "./types";
+export * from "./schema";

package/dist/types/index.js

@@ -1,3 +1,4 @@
-// 导出所有类型定义
-export * from "./route";
+export { createTypedRoute, isTypedRoute } from "./route";
+// 组件路由和 Schema 类型
 export * from "./component-route";
+export * from "./schema";

package/dist/types/route.d.ts

@@ -1,11 +1,11 @@
-import { Route } from "./types";
+import { Route, ResponseBody } from "./types";
 export interface Middleware {
     (req: Request, next: () => Promise<Response>): Promise<Response>;
 }
 export interface BaseRouteConfig {
     method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD";
     path: string;
-    handler: (req: Request) => Response | Promise<Response>;
+    handler: (req: Request) => ResponseBody | Promise<ResponseBody>;
 }
 export interface ExtendedRouteConfig extends BaseRouteConfig {
     middleware?: Middleware[];

package/dist/types/schema.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Schema 类型定义
+ *
+ * 使用 TSchema 约束替代 any，提供完整的类型安全
+ *
+ * @author Framework Team
+ * @version 1.0.0
+ * @license MIT
+ */
+import type { TSchema, Static } from "@sinclair/typebox";
+/**
+ * 路由 Schema 配置
+ * 所有 schema 字段使用 TSchema 约束
+ */
+export interface RouteSchema {
+    body?: TSchema;
+    query?: TSchema;
+    params?: TSchema;
+    headers?: TSchema;
+    cookies?: TSchema;
+}
+/**
+ * 从 Schema 配置推导出具体类型
+ */
+export type InferSchema<T extends RouteSchema> = {
+    body: T["body"] extends TSchema ? Static<T["body"]> : unknown;
+    query: T["query"] extends TSchema ? Static<T["query"]> : Record<string, string>;
+    params: T["params"] extends TSchema ? Static<T["params"]> : Record<string, string>;
+    headers: T["headers"] extends TSchema ? Static<T["headers"]> : Record<string, string>;
+    cookies: T["cookies"] extends TSchema ? Static<T["cookies"]> : Record<string, string>;
+};
+/**
+ * Handler 上下文类型
+ */
+export interface HandlerContext<T extends RouteSchema = RouteSchema> {
+    /** 原始请求对象 */
+    req: Request;
+    /** 请求体 (经过 schema 验证) */
+    body: InferSchema<T>["body"];
+    /** 查询参数 (经过 schema 验证) */
+    query: InferSchema<T>["query"];
+    /** 路径参数 (经过 schema 验证) */
+    params: InferSchema<T>["params"];
+    /** 请求头 (经过 schema 验证) */
+    headers: InferSchema<T>["headers"];
+    /** Cookie (经过 schema 验证) */
+    cookies: InferSchema<T>["cookies"];
+}
+/**
+ * 带额外上下文的 Handler 上下文类型
+ * 用于中间件注入额外数据
+ */
+export type HandlerContextWithExtra<T extends RouteSchema = RouteSchema, TExtra extends Record<string, unknown> = Record<string, never>> = HandlerContext<T> & TExtra;
+/**
+ * Handler 函数类型
+ */
+export type TypedHandler<T extends RouteSchema = RouteSchema, TExtra extends Record<string, unknown> = Record<string, never>, TReturn = unknown> = (ctx: HandlerContextWithExtra<T, TExtra>) => TReturn | Promise<TReturn>;
+/**
+ * 扩展的路由配置 (包含 schema)
+ */
+export interface TypedRouteConfig<T extends RouteSchema = RouteSchema> {
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD";
+    path: string;
+    schema?: T;
+    handler: (req: Request) => Response | Promise<Response>;
+    middleware?: Array<(req: Request, next: () => Promise<Response>) => Promise<Response>>;
+    docs?: {
+        description?: string;
+        tags?: string[];
+        security?: unknown[];
+        responses?: Record<string, unknown>;
+    };
+    timeout?: number;
+    maxBodySize?: string;
+}

package/dist/types/schema.js

@@ -0,0 +1,10 @@
+/**
+ * Schema 类型定义
+ *
+ * 使用 TSchema 约束替代 any，提供完整的类型安全
+ *
+ * @author Framework Team
+ * @version 1.0.0
+ * @license MIT
+ */
+export {};

package/dist/types/types.d.ts

@@ -1,6 +1,10 @@
 export type Method = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD";
-export type Handler = (req: Request, params?: Record<string, string>, user?: Record<string, any>) => Response | Promise<Response>;
-export type Middleware = (req: Request, next: () => Promise<Response>) => Promise<Response>;
+/** 支持的响应类型 - 由 mapResponse 自动转换 */
+export type ResponseBody = Response | string | number | boolean | object | null | undefined | ReadableStream | Blob | ArrayBuffer;
+/** Handler 返回值（支持同步/异步，任意类型） */
+export type Handler = (req: Request, params?: Record<string, string>, user?: Record<string, any>) => ResponseBody | Promise<ResponseBody>;
+/** 中间件（返回值必须是 Response 或 Promise<Response>） */
+export type Middleware = (req: Request, next: () => Promise<Response>) => Response | Promise<Response>;
 export interface Route {
     method: Method;
     path: string;

package/dist/utils/create-handler.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 类型安全的路由处理器工厂
+ *
+ * 非柯里化设计，API 更简洁
+ *
+ * @author Framework Team
+ * @version 3.0.0
+ * @license MIT
+ */
+import type { RouteSchema, HandlerContext, HandlerContextWithExtra } from "../types/schema";
+/** 空 schema 的上下文类型 */
+type EmptySchemaContext = {
+    req: Request;
+    body: unknown;
+    query: Record<string, string>;
+    params: Record<string, string>;
+    headers: Record<string, string>;
+    cookies: Record<string, string>;
+};
+/**
+ * 创建类型安全的路由处理器
+ *
+ * @example
+ * ```typescript
+ * // 无 schema - 直接传入 handler
+ * createHandler(({ params }) => `User: ${params.id}`)
+ *
+ * // 有 schema - 传入 schema 和 handler
+ * createHandler(
+ *   { body: Type.Object({ name: Type.String() }) },
+ *   ({ body }) => ({ hello: body.name })
+ * )
+ * ```
+ */
+export declare function createHandler<R>(handler: (ctx: EmptySchemaContext) => R | Promise<R>): (req: Request) => Promise<Response>;
+export declare function createHandler<const T extends RouteSchema, R>(schema: T, handler: (ctx: HandlerContext<T>) => R | Promise<R>): (req: Request) => Promise<Response>;
+/**
+ * 创建带额外上下文的路由处理器
+ *
+ * 用于中间件注入额外数据的场景
+ *
+ * @example
+ * ```typescript
+ * // 定义中间件注入的类型
+ * type AuthContext = { user: { id: string; role: string } };
+ *
+ * // 无 schema
+ * createHandlerWithExtra<AuthContext>(({ user }) => {
+ *   return { userId: user.id };
+ * })
+ *
+ * // 有 schema
+ * createHandlerWithExtra<AuthContext>(
+ *   { body: Type.Object({ action: Type.String() }) },
+ *   ({ body, user }) => ({ success: true, userId: user.id })
+ * )
+ * ```
+ */
+export declare function createHandlerWithExtra<TExtra extends Record<string, unknown> = Record<string, never>, R = unknown>(handler: (ctx: EmptySchemaContext & TExtra) => R | Promise<R>): (req: Request) => Promise<Response>;
+export declare function createHandlerWithExtra<TExtra extends Record<string, unknown> = Record<string, never>, const T extends RouteSchema = RouteSchema, R = unknown>(schema: T, handler: (ctx: HandlerContextWithExtra<T, TExtra>) => R | Promise<R>): (req: Request) => Promise<Response>;
+/**
+ * 简单的路由处理器 (无 schema 验证，只有 req)
+ *
+ * @example
+ * ```typescript
+ * simpleHandler(({ req }) => {
+ *   return { message: "Hello World" };
+ * })
+ * ```
+ */
+export declare function simpleHandler<R>(handler: (ctx: {
+    req: Request;
+}) => R | Promise<R>): (req: Request) => Promise<Response>;
+export {};

package/dist/utils/create-handler.js

@@ -0,0 +1,234 @@
+/**
+ * 类型安全的路由处理器工厂
+ *
+ * 非柯里化设计，API 更简洁
+ *
+ * @author Framework Team
+ * @version 3.0.0
+ * @license MIT
+ */
+import { parseBody, parseQuery, parseHeaders, parseCookies } from "./parsers";
+import { goAwait } from "./go-await";
+import { json } from "./response";
+import { validateAllSchemasUltra, precompileSchemasUltra, } from "./validators/schema-validators-ultra";
+/**
+ * 自动响应转换
+ * 将各种返回值类型转换为 Response 对象
+ */
+function autoResponse(result) {
+    // 已经是 Response
+    if (result instanceof Response) {
+        return result;
+    }
+    // null/undefined -> 204
+    if (result === null || result === undefined) {
+        return new Response(null, { status: 204 });
+    }
+    // 字符串 -> text/plain
+    if (typeof result === "string") {
+        return new Response(result, {
+            headers: { "Content-Type": "text/plain; charset=utf-8" },
+        });
+    }
+    // 数字/布尔 -> text/plain
+    if (typeof result === "number" || typeof result === "boolean") {
+        return new Response(String(result), {
+            headers: { "Content-Type": "text/plain; charset=utf-8" },
+        });
+    }
+    // 对象 -> 检查是否是 { data, status, headers } 格式
+    if (typeof result === "object") {
+        const obj = result;
+        if ("data" in obj && ("status" in obj || "headers" in obj)) {
+            const { data, status = 200, headers = {} } = obj;
+            if (data === null || data === undefined) {
+                return new Response(null, {
+                    status: status === 200 ? 204 : status,
+                    headers: headers,
+                });
+            }
+            if (typeof data === "string" ||
+                typeof data === "number" ||
+                typeof data === "boolean") {
+                return new Response(String(data), {
+                    status: status,
+                    headers: {
+                        "Content-Type": "text/plain; charset=utf-8",
+                        ...headers,
+                    },
+                });
+            }
+            return json(data, status, headers);
+        }
+        // 普通对象 -> JSON
+        return json(result);
+    }
+    // 其他类型 -> 204
+    return new Response(null, { status: 204 });
+}
+/**
+ * 处理验证错误
+ */
+function handleValidationError(error) {
+    return json({
+        success: false,
+        error: "Validation Error",
+        message: error.message,
+        timestamp: new Date().toISOString(),
+    }, 400);
+}
+/**
+ * 处理内部错误
+ */
+function handleInternalError(error) {
+    return json({
+        success: false,
+        error: "Internal Error",
+        message: error instanceof Error ? error.message : "未知错误",
+    }, 500);
+}
+/**
+ * 判断是否为 handler 函数
+ */
+function isHandler(value) {
+    return typeof value === "function";
+}
+// 实现
+export function createHandler(schemaOrHandler, maybeHandler) {
+    // 判断调用方式
+    const hasSchema = !isHandler(schemaOrHandler);
+    const schema = hasSchema ? schemaOrHandler : {};
+    const handler = hasSchema
+        ? maybeHandler
+        : schemaOrHandler;
+    // 预编译 schema
+    if (schema.body ||
+        schema.query ||
+        schema.params ||
+        schema.headers ||
+        schema.cookies) {
+        precompileSchemasUltra(schema);
+    }
+    return async (req) => {
+        try {
+            // 解析请求数据
+            const query = parseQuery(req);
+            const headers = parseHeaders(req);
+            const cookies = parseCookies(req);
+            const params = req.params || {};
+            // 解析请求体
+            let body = undefined;
+            if (req.method !== "GET" && req.method !== "HEAD") {
+                const [, parsedBody] = await goAwait(parseBody(req));
+                body = parsedBody;
+            }
+            // 验证 schema
+            const data = { body, query, params, headers, cookies };
+            if (schema.body ||
+                schema.query ||
+                schema.params ||
+                schema.headers ||
+                schema.cookies) {
+                validateAllSchemasUltra(schema, data);
+            }
+            // 调用 handler
+            const result = await handler({
+                req,
+                body: body,
+                query: query,
+                params: params,
+                headers: headers,
+                cookies: cookies,
+            });
+            return autoResponse(result);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes("验证失败")) {
+                return handleValidationError(error);
+            }
+            return handleInternalError(error);
+        }
+    };
+}
+// 实现
+export function createHandlerWithExtra(schemaOrHandler, maybeHandler) {
+    // 判断调用方式
+    const hasSchema = !isHandler(schemaOrHandler);
+    const schema = hasSchema ? schemaOrHandler : {};
+    const handler = hasSchema
+        ? maybeHandler
+        : schemaOrHandler;
+    // 预编译 schema
+    if (schema.body ||
+        schema.query ||
+        schema.params ||
+        schema.headers ||
+        schema.cookies) {
+        precompileSchemasUltra(schema);
+    }
+    return async (req) => {
+        try {
+            // 解析请求数据
+            const query = parseQuery(req);
+            const headers = parseHeaders(req);
+            const cookies = parseCookies(req);
+            const params = req.params || {};
+            // 解析请求体
+            let body = undefined;
+            if (req.method !== "GET" && req.method !== "HEAD") {
+                const [, parsedBody] = await goAwait(parseBody(req));
+                body = parsedBody;
+            }
+            // 验证 schema
+            const data = { body, query, params, headers, cookies };
+            if (schema.body ||
+                schema.query ||
+                schema.params ||
+                schema.headers ||
+                schema.cookies) {
+                validateAllSchemasUltra(schema, data);
+            }
+            // 获取中间件注入的额外数据
+            const extras = (req.__locals ??
+                {});
+            // 调用 handler
+            const result = await handler({
+                req,
+                body: body,
+                query: query,
+                params: params,
+                headers: headers,
+                cookies: cookies,
+                ...extras,
+            });
+            return autoResponse(result);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes("验证失败")) {
+                return handleValidationError(error);
+            }
+            return handleInternalError(error);
+        }
+    };
+}
+/**
+ * 简单的路由处理器 (无 schema 验证，只有 req)
+ *
+ * @example
+ * ```typescript
+ * simpleHandler(({ req }) => {
+ *   return { message: "Hello World" };
+ * })
+ * ```
+ */
+export function simpleHandler(handler) {
+    return async (req) => {
+        try {
+            const result = await handler({ req });
+            return autoResponse(result);
+        }
+        catch (error) {
+            return handleInternalError(error);
+        }
+    };
+}

package/dist/utils/dependency-manager.js

@@ -16,10 +16,16 @@ export class DependencyManager {
             let deps;
             switch (framework) {
                 case "vue":
-                    deps = await Promise.all([import("vue"), import("@vue/server-renderer")]);
+                    deps = await Promise.all([
+                        import("vue"),
+                        import("@vue/server-renderer"),
+                    ]);
                     break;
                 case "react":
-                    deps = await Promise.all([import("react"), import("react-dom/server")]);
+                    deps = await Promise.all([
+                        import("react"),
+                        import("react-dom/server"),
+                    ]);
                     break;
                 default:
                     throw new Error(`不支持的框架: ${framework}`);

package/dist/utils/go-await.js

@@ -26,8 +26,5 @@
 export function goAwait(promise) {
     return promise
         .then((data) => [null, data])
-        .catch((err) => [
-        err instanceof Error ? err : new Error(String(err)),
-        undefined,
-    ]);
+        .catch((err) => [err instanceof Error ? err : new Error(String(err)), undefined]);
 }

package/dist/utils/handle.d.ts

@@ -8,3 +8,4 @@ export declare function setCookie(key: string, value: string, options?: {
     secure?: boolean;
 }): string;
 export declare function setLocals<T extends object>(req: Request, extras: T): void;
+export declare function getLocals<T extends object>(req: Request): T;

package/dist/utils/handle.js

@@ -22,3 +22,8 @@ export function setLocals(req, extras) {
     const target = req;
     target.__locals = { ...(target.__locals ?? {}), ...extras };
 }
+// 获取中间件注入的局部上下文
+export function getLocals(req) {
+    const target = req;
+    return (target.__locals ?? {});
+}

package/dist/utils/index.d.ts

@@ -1,10 +1,12 @@
-export * from "./handle";
-export * from "./parsers";
-export * from "./response";
-export * from "./base64url";
-export * from "./go-await";
-export * from "./route-handler-factory";
-export * from "./path-matcher";
-export * from "./html-renderer";
-export * from "./dependency-manager";
-export * from "./request-validator";
+/**
+ * 工具函数模块导出
+ */
+export { createHandler, createHandlerWithExtra, simpleHandler, } from "./create-handler";
+export { parseBody, parseQuery, parseHeaders, parseCookies } from "./parsers";
+export { json, text, html, redirect, empty, stream } from "./response";
+export { goAwait } from "./go-await";
+export { base64urlEncode, base64urlDecode } from "./base64url";
+export { setLocals, getLocals } from "./handle";
+export { parseRequest, validateRequest, parseAndValidateRequest, createRequestValidator, } from "./request-validator";
+export { HtmlRenderer } from "./html-renderer";
+export { DependencyManager } from "./dependency-manager";