vafast 0.2.3 → 0.3.1

package/dist/node-server/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @vafast/node-server
+ * Node.js 适配器 - 为 Vafast 提供高性能 Node.js 运行时支持
+ *
+ * @example
+ * ```ts
+ * import { serve } from "@vafast/node-server";
+ * import { Server } from "vafast";
+ *
+ * const app = new Server([
+ *   { method: "GET", path: "/", handler: () => "Hello World" },
+ * ]);
+ *
+ * serve({ fetch: app.fetch, port: 3000 }, () => {
+ *   console.log("Server running on http://localhost:3000");
+ * });
+ * ```
+ */
+export { serve, createAdaptorServer } from "./serve";
+export type { ServeOptions, ServeResult, FetchHandler } from "./serve";
+export { createProxyRequest } from "./request";
+export { writeResponse, writeResponseSimple } from "./response";

package/dist/node-server/index.js

@@ -0,0 +1,21 @@
+/**
+ * @vafast/node-server
+ * Node.js 适配器 - 为 Vafast 提供高性能 Node.js 运行时支持
+ *
+ * @example
+ * ```ts
+ * import { serve } from "@vafast/node-server";
+ * import { Server } from "vafast";
+ *
+ * const app = new Server([
+ *   { method: "GET", path: "/", handler: () => "Hello World" },
+ * ]);
+ *
+ * serve({ fetch: app.fetch, port: 3000 }, () => {
+ *   console.log("Server running on http://localhost:3000");
+ * });
+ * ```
+ */
+export { serve, createAdaptorServer } from "./serve";
+export { createProxyRequest } from "./request";
+export { writeResponse, writeResponseSimple } from "./response";

package/dist/node-server/request.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 优化的 Request 代理
+ * 延迟创建真实 Request，减少不必要的对象分配
+ */
+import type { IncomingMessage } from "node:http";
+/**
+ * 创建代理 Request
+ * @param incoming Node.js IncomingMessage
+ * @param defaultHost 默认主机名
+ */
+export declare function createProxyRequest(incoming: IncomingMessage, defaultHost: string): Request;

package/dist/node-server/request.js

@@ -0,0 +1,157 @@
+/**
+ * 优化的 Request 代理
+ * 延迟创建真实 Request，减少不必要的对象分配
+ */
+import { Readable } from "node:stream";
+// 内部 Symbol
+const requestCache = Symbol("requestCache");
+const incomingKey = Symbol("incoming");
+const urlKey = Symbol("url");
+const headersKey = Symbol("headers");
+/**
+ * 从 rawHeaders 高效解析 Headers
+ */
+function parseHeaders(rawHeaders) {
+    const headers = new Headers();
+    for (let i = 0; i < rawHeaders.length; i += 2) {
+        const key = rawHeaders[i];
+        const value = rawHeaders[i + 1];
+        // 跳过 HTTP/2 伪头 (以 : 开头)
+        if (key.charCodeAt(0) !== 58) {
+            headers.append(key, value);
+        }
+    }
+    return headers;
+}
+/**
+ * 将 Node.js ReadableStream 转换为 Web 标准 ReadableStream
+ * Node.js 和 Web 标准的 ReadableStream 在运行时兼容，但 TypeScript 类型不同
+ */
+function toWebStream(nodeStream) {
+    // Node.js ReadableStream 和 Web ReadableStream 在运行时是兼容的
+    // 这里使用类型断言是安全的，因为 Node.js >= 18 的 stream/web 完全实现了 WHATWG Streams 标准
+    return nodeStream;
+}
+/**
+ * 创建真实的 Request 对象
+ */
+function createRealRequest(proxy) {
+    const incoming = proxy[incomingKey];
+    const method = incoming.method || "GET";
+    const init = {
+        method,
+        headers: proxy[headersKey] || parseHeaders(incoming.rawHeaders),
+    };
+    // 只有非 GET/HEAD 请求才有 body
+    if (method !== "GET" && method !== "HEAD") {
+        // 使用 Node.js 原生流转换，避免收集 chunks
+        const nodeWebStream = Readable.toWeb(incoming);
+        init.body = toWebStream(nodeWebStream);
+        init.duplex = "half";
+    }
+    return new Request(proxy[urlKey], init);
+}
+/**
+ * Request 代理原型
+ * 使用 Object.defineProperty 定义属性以支持 this 绑定
+ */
+const requestPrototype = {};
+// 定义 method 属性
+Object.defineProperty(requestPrototype, "method", {
+    get() {
+        const self = this;
+        return self[incomingKey].method || "GET";
+    },
+    enumerable: true,
+});
+// 定义 url 属性
+Object.defineProperty(requestPrototype, "url", {
+    get() {
+        const self = this;
+        return self[urlKey];
+    },
+    enumerable: true,
+});
+// 定义 headers 属性（延迟解析）
+Object.defineProperty(requestPrototype, "headers", {
+    get() {
+        const self = this;
+        if (!self[headersKey]) {
+            self[headersKey] = parseHeaders(self[incomingKey].rawHeaders);
+        }
+        return self[headersKey];
+    },
+    enumerable: true,
+});
+// 定义 _getRequest 方法（获取或创建真实 Request）
+Object.defineProperty(requestPrototype, "_getRequest", {
+    value: function () {
+        const self = this;
+        if (!self[requestCache]) {
+            self[requestCache] = createRealRequest(self);
+        }
+        return self[requestCache];
+    },
+    enumerable: false,
+});
+// 代理需要访问真实 Request 的属性
+const proxyGetters = [
+    "body",
+    "bodyUsed",
+    "signal",
+    "cache",
+    "credentials",
+    "destination",
+    "integrity",
+    "mode",
+    "redirect",
+    "referrer",
+    "referrerPolicy",
+    "keepalive",
+];
+proxyGetters.forEach((key) => {
+    Object.defineProperty(requestPrototype, key, {
+        get() {
+            const self = this;
+            return self._getRequest()[key];
+        },
+        enumerable: true,
+    });
+});
+// 代理需要调用真实 Request 的方法
+const proxyMethods = [
+    "arrayBuffer",
+    "blob",
+    "clone",
+    "formData",
+    "json",
+    "text",
+];
+proxyMethods.forEach((key) => {
+    Object.defineProperty(requestPrototype, key, {
+        value: function () {
+            const self = this;
+            const req = self._getRequest();
+            return req[key].call(req);
+        },
+        enumerable: true,
+    });
+});
+// 设置原型链
+Object.setPrototypeOf(requestPrototype, Request.prototype);
+/**
+ * 创建代理 Request
+ * @param incoming Node.js IncomingMessage
+ * @param defaultHost 默认主机名
+ */
+export function createProxyRequest(incoming, defaultHost) {
+    const req = Object.create(requestPrototype);
+    req[incomingKey] = incoming;
+    // 构建 URL
+    const host = incoming.headers.host || defaultHost;
+    const protocol = incoming.socket.encrypted
+        ? "https"
+        : "http";
+    req[urlKey] = `${protocol}://${host}${incoming.url || "/"}`;
+    return req;
+}

package/dist/node-server/response.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 优化的 Response 写入
+ * 流式写入，避免内存拷贝
+ */
+import type { ServerResponse } from "node:http";
+/**
+ * 将 Web Response 写入 Node.js ServerResponse
+ * 流式写入，零拷贝
+ */
+export declare function writeResponse(response: Response, outgoing: ServerResponse): Promise<void>;
+/**
+ * 简化版写入（用于已知小体积响应）
+ * 直接 arrayBuffer 转换，适用于确定的小响应
+ */
+export declare function writeResponseSimple(response: Response, outgoing: ServerResponse): Promise<void>;

package/dist/node-server/response.js

@@ -0,0 +1,98 @@
+/**
+ * 优化的 Response 写入
+ * 流式写入，避免内存拷贝
+ */
+/**
+ * 构建 Node.js 响应头
+ * 处理 set-cookie 多值情况
+ */
+function buildOutgoingHeaders(headers) {
+    const result = {};
+    const cookies = [];
+    headers.forEach((value, key) => {
+        if (key === "set-cookie") {
+            cookies.push(value);
+        }
+        else {
+            result[key] = value;
+        }
+    });
+    if (cookies.length > 0) {
+        result["set-cookie"] = cookies;
+    }
+    return result;
+}
+/**
+ * 流式写入 Response body 到 ServerResponse
+ * 支持背压处理，避免内存溢出
+ */
+async function writeBodyStream(body, outgoing) {
+    const reader = body.getReader();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            // 背压处理：如果写入返回 false，等待 drain 事件
+            const canContinue = outgoing.write(value);
+            if (!canContinue) {
+                await new Promise((resolve) => {
+                    outgoing.once("drain", resolve);
+                });
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * 将 Web Response 写入 Node.js ServerResponse
+ * 流式写入，零拷贝
+ */
+export async function writeResponse(response, outgoing) {
+    // 设置状态码
+    outgoing.statusCode = response.status;
+    // 设置响应头
+    const headers = buildOutgoingHeaders(response.headers);
+    for (const [key, value] of Object.entries(headers)) {
+        outgoing.setHeader(key, value);
+    }
+    const body = response.body;
+    // 无 body 的情况
+    if (!body) {
+        outgoing.end();
+        return;
+    }
+    // 流式写入 body
+    try {
+        await writeBodyStream(body, outgoing);
+        outgoing.end();
+    }
+    catch (error) {
+        // 处理客户端提前断开等情况
+        if (!outgoing.destroyed) {
+            outgoing.destroy(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+}
+/**
+ * 简化版写入（用于已知小体积响应）
+ * 直接 arrayBuffer 转换，适用于确定的小响应
+ */
+export async function writeResponseSimple(response, outgoing) {
+    outgoing.statusCode = response.status;
+    const headers = buildOutgoingHeaders(response.headers);
+    for (const [key, value] of Object.entries(headers)) {
+        outgoing.setHeader(key, value);
+    }
+    const body = response.body;
+    if (!body) {
+        outgoing.end();
+        return;
+    }
+    // 对于小响应，直接读取全部内容
+    const buffer = await response.arrayBuffer();
+    outgoing.end(Buffer.from(buffer));
+}

package/dist/node-server/serve.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Node.js 服务器适配器
+ * 提供类似 Bun.serve 的 API
+ */
+import { type Server as HttpServer } from "node:http";
+/** fetch 函数类型 */
+export type FetchHandler = (request: Request) => Response | Promise<Response>;
+/** serve 配置选项 */
+export interface ServeOptions {
+    /** fetch 处理函数 */
+    fetch: FetchHandler;
+    /** 端口号，默认 3000 */
+    port?: number;
+    /** 主机名，默认 0.0.0.0 */
+    hostname?: string;
+    /** 错误处理函数 */
+    onError?: (error: Error) => Response | Promise<Response>;
+}
+/** serve 返回的服务器信息 */
+export interface ServeResult {
+    /** Node.js HTTP Server 实例 */
+    server: HttpServer;
+    /** 服务器端口 */
+    port: number;
+    /** 服务器主机名 */
+    hostname: string;
+    /** 关闭服务器 */
+    stop: () => Promise<void>;
+}
+/**
+ * 启动 HTTP 服务器
+ *
+ * @example
+ * ```ts
+ * import { serve } from "@vafast/node-server";
+ * import { Server } from "vafast";
+ *
+ * const app = new Server([
+ *   { method: "GET", path: "/", handler: () => "Hello World" },
+ * ]);
+ *
+ * serve({ fetch: app.fetch, port: 3000 }, () => {
+ *   console.log("Server running on http://localhost:3000");
+ * });
+ * ```
+ */
+export declare function serve(options: ServeOptions, callback?: () => void): ServeResult;
+/**
+ * 创建适配器服务器（不自动启动）
+ * 用于需要更多控制的场景
+ */
+export declare function createAdaptorServer(fetch: FetchHandler, onError?: (error: Error) => Response | Promise<Response>): HttpServer;

package/dist/node-server/serve.js

@@ -0,0 +1,88 @@
+/**
+ * Node.js 服务器适配器
+ * 提供类似 Bun.serve 的 API
+ */
+import { createServer, } from "node:http";
+import { createProxyRequest } from "./request";
+import { writeResponse } from "./response";
+/**
+ * 创建请求处理函数
+ */
+function createRequestHandler(fetch, defaultHost, onError) {
+    return async (incoming, outgoing) => {
+        try {
+            // 创建代理 Request（延迟创建真实 Request）
+            const request = createProxyRequest(incoming, defaultHost);
+            // 调用 fetch handler
+            const response = await fetch(request);
+            // 流式写入 Response
+            await writeResponse(response, outgoing);
+        }
+        catch (error) {
+            // 错误处理
+            const err = error instanceof Error ? error : new Error(String(error));
+            if (onError) {
+                try {
+                    const errorResponse = await onError(err);
+                    await writeResponse(errorResponse, outgoing);
+                    return;
+                }
+                catch {
+                    // onError 也失败了，返回 500
+                }
+            }
+            // 默认错误响应
+            if (!outgoing.headersSent) {
+                outgoing.statusCode = 500;
+                outgoing.setHeader("Content-Type", "text/plain");
+                outgoing.end("Internal Server Error");
+            }
+        }
+    };
+}
+/**
+ * 启动 HTTP 服务器
+ *
+ * @example
+ * ```ts
+ * import { serve } from "@vafast/node-server";
+ * import { Server } from "vafast";
+ *
+ * const app = new Server([
+ *   { method: "GET", path: "/", handler: () => "Hello World" },
+ * ]);
+ *
+ * serve({ fetch: app.fetch, port: 3000 }, () => {
+ *   console.log("Server running on http://localhost:3000");
+ * });
+ * ```
+ */
+export function serve(options, callback) {
+    const { fetch, port = 3000, hostname = "0.0.0.0", onError } = options;
+    const defaultHost = `${hostname === "0.0.0.0" ? "localhost" : hostname}:${port}`;
+    const handler = createRequestHandler(fetch, defaultHost, onError);
+    const server = createServer(handler);
+    // 启动服务器
+    server.listen(port, hostname, callback);
+    return {
+        server,
+        port,
+        hostname,
+        stop: () => new Promise((resolve, reject) => {
+            server.close((err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        }),
+    };
+}
+/**
+ * 创建适配器服务器（不自动启动）
+ * 用于需要更多控制的场景
+ */
+export function createAdaptorServer(fetch, onError) {
+    const handler = createRequestHandler(fetch, "localhost", onError);
+    return createServer(handler);
+}

package/dist/router/radix-tree.d.ts

@@ -9,11 +9,15 @@
  * - 通配符: /files/*, /static/*filepath
  */
 import type { Handler, Middleware, Method } from "../types";
+/** 预编译的处理器类型 */
+type CompiledHandler = (req: Request) => Promise<Response>;
 /** 路由匹配结果 */
 export interface MatchResult {
     handler: Handler;
     middleware: Middleware[];
     params: Record<string, string>;
+    /** 预编译后的完整处理链 */
+    compiled?: CompiledHandler;
 }
 /**
  * Radix Tree 路由器
@@ -32,8 +36,15 @@ export declare class RadixRouter {
     private createNode;
     /** 分割路径 */
     private splitPath;
+    /** 编译器函数 - 用于预编译中间件链 */
+    private compiler?;
+    /** 设置中间件编译器 */
+    setCompiler(compiler: (middleware: Middleware[], handler: Handler) => CompiledHandler): void;
     /** 注册路由 */
     register(method: Method, pattern: string, handler: Handler, middleware?: Middleware[]): void;
+    /** 预编译所有路由（在添加全局中间件后调用） */
+    precompileAll(globalMiddleware: Middleware[]): void;
+    private precompileNode;
     /** 匹配路由 */
     match(method: Method, path: string): MatchResult | null;
     /** 递归匹配节点 (优先级: 静态 > 动态参数 > 通配符) */
@@ -49,3 +60,4 @@ export declare class RadixRouter {
     }>;
     private collectRoutes;
 }
+export {};

package/dist/router/radix-tree.js

@@ -35,6 +35,12 @@ export class RadixRouter {
     splitPath(path) {
         return path.split("/").filter(Boolean);
     }
+    /** 编译器函数 - 用于预编译中间件链 */
+    compiler;
+    /** 设置中间件编译器 */
+    setCompiler(compiler) {
+        this.compiler = compiler;
+    }
     /** 注册路由 */
     register(method, pattern, handler, middleware = []) {
         const segments = this.splitPath(pattern);
@@ -67,7 +73,36 @@ export class RadixRouter {
                 node = node.children[segment];
             }
         }
-        node.handlers[method] = { handler, middleware };
+        const routeHandler = { handler, middleware };
+        // 如果没有全局中间件且设置了编译器，预编译处理链
+        if (this.compiler && middleware.length === 0) {
+            routeHandler.compiled = this.compiler([], handler);
+        }
+        node.handlers[method] = routeHandler;
+    }
+    /** 预编译所有路由（在添加全局中间件后调用） */
+    precompileAll(globalMiddleware) {
+        if (!this.compiler)
+            return;
+        this.precompileNode(this.root, globalMiddleware);
+    }
+    precompileNode(node, globalMiddleware) {
+        for (const method in node.handlers) {
+            const routeHandler = node.handlers[method];
+            if (routeHandler) {
+                const allMiddleware = [...globalMiddleware, ...routeHandler.middleware];
+                routeHandler.compiled = this.compiler(allMiddleware, routeHandler.handler);
+            }
+        }
+        for (const key in node.children) {
+            this.precompileNode(node.children[key], globalMiddleware);
+        }
+        if (node.paramChild) {
+            this.precompileNode(node.paramChild, globalMiddleware);
+        }
+        if (node.wildcardChild) {
+            this.precompileNode(node.wildcardChild, globalMiddleware);
+        }
     }
     /** 匹配路由 */
     match(method, path) {
@@ -83,6 +118,7 @@ export class RadixRouter {
             handler: routeHandler.handler,
             middleware: routeHandler.middleware,
             params,
+            compiled: routeHandler.compiled,
         };
     }
     /** 递归匹配节点 (优先级: 静态 > 动态参数 > 通配符) */

package/dist/serve.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 统一的 serve 函数
+ * 使用 Node.js 原生 http 模块，兼容 Bun 和 Node.js
+ *
+ * 基准测试结果（Bun 环境）：
+ * - Bun.serve: 35,422 req/s
+ * - node:http: 38,075 req/s
+ *
+ * node:http 在 Bun 下性能甚至更好，无需使用 Bun API
+ */
+export { serve, createAdaptorServer } from "./node-server/serve";
+export type { ServeOptions, ServeResult, FetchHandler, } from "./node-server/serve";

package/dist/serve.js

@@ -0,0 +1,11 @@
+/**
+ * 统一的 serve 函数
+ * 使用 Node.js 原生 http 模块，兼容 Bun 和 Node.js
+ *
+ * 基准测试结果（Bun 环境）：
+ * - Bun.serve: 35,422 req/s
+ * - node:http: 38,075 req/s
+ *
+ * node:http 在 Bun 下性能甚至更好，无需使用 Bun API
+ */
+export { serve, createAdaptorServer } from "./node-server/serve";

package/dist/server/server.d.ts

@@ -20,7 +20,16 @@ import { BaseServer } from "./base-server";
 export declare class Server extends BaseServer {
     private router;
     private routes;
+    /** 是否已预编译 */
+    private isCompiled;
+    /** 预编译时的全局中间件数量 */
+    private compiledWithMiddlewareCount;
     constructor(routes?: (Route | NestedRoute)[]);
+    /**
+     * 预编译所有路由处理链
+     * 在添加所有路由和全局中间件后调用，可提升运行时性能
+     */
+    compile(): this;
     private registerRoutes;
     /** 快速提取 pathname */
     private extractPathname;

package/dist/server/server.js

@@ -23,14 +23,30 @@ import { RadixRouter } from "../router/radix-tree";
 export class Server extends BaseServer {
     router;
     routes;
+    /** 是否已预编译 */
+    isCompiled = false;
+    /** 预编译时的全局中间件数量 */
+    compiledWithMiddlewareCount = 0;
     constructor(routes = []) {
         super();
         this.router = new RadixRouter();
         this.routes = [];
+        // 设置中间件编译器
+        this.router.setCompiler((middleware, handler) => composeMiddleware(middleware, handler));
         if (routes.length > 0) {
             this.registerRoutes(routes);
         }
     }
+    /**
+     * 预编译所有路由处理链
+     * 在添加所有路由和全局中间件后调用，可提升运行时性能
+     */
+    compile() {
+        this.router.precompileAll(this.globalMiddleware);
+        this.isCompiled = true;
+        this.compiledWithMiddlewareCount = this.globalMiddleware.length;
+        return this;
+    }
     registerRoutes(routes) {
         const flattened = flattenNestedRoutes(routes);
         this.routes.push(...flattened);
@@ -39,6 +55,10 @@ export class Server extends BaseServer {
         }
         this.detectRouteConflicts(flattened);
         this.logFlattenedRoutes(flattened);
+        // 自动预编译（如果没有全局中间件）
+        if (this.globalMiddleware.length === 0 && !this.isCompiled) {
+            this.compile();
+        }
     }
     /** 快速提取 pathname */
     extractPathname(url) {
@@ -61,7 +81,12 @@ export class Server extends BaseServer {
         const match = this.router.match(method, pathname);
         if (match) {
             req.params = match.params;
-            // 组合全局中间件 + 路由中间件（mapResponse 在 composeMiddleware 内部处理）
+            // 优先使用预编译的处理链（仅当全局中间件未变化时）
+            if (match.compiled &&
+                this.globalMiddleware.length === this.compiledWithMiddlewareCount) {
+                return match.compiled(req);
+            }
+            // 回退：运行时组合中间件
             const allMiddleware = [...this.globalMiddleware, ...match.middleware];
             const handler = composeMiddleware(allMiddleware, match.handler);
             return handler(req);

package/dist/types/types.d.ts

@@ -2,7 +2,12 @@ export type Method = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "
 /** 支持的响应类型 - 由 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>;
+/** 传统 Handler 类型 */
+export type LegacyHandler = (req: Request, params?: Record<string, string>, user?: Record<string, any>) => ResponseBody | Promise<ResponseBody>;
+/** createHandler 返回的类型 */
+export type FactoryHandler = (req: Request) => Promise<Response>;
+/** Handler 联合类型（支持两种风格） */
+export type Handler = LegacyHandler | FactoryHandler;
 /** 中间件（返回值必须是 Response 或 Promise<Response>） */
 export type Middleware = (req: Request, next: () => Promise<Response>) => Response | Promise<Response>;
 export interface Route {