@faapi/faapi 0.0.0-canary.4e89b9b → 0.0.0-canary.856e11f

package/dist/index.d.ts

@@ -54,6 +54,17 @@ interface SseEvent {
 interface SseWriter {
     /** 推送一个 SSE 事件 */
     send(event: SseEvent): void;
+    /**
+     * 直接写入原始字节/字符串,不做任何 SSE 序列化
+     *
+     * 用于透传上游已有的 SSE 原文(如 LLM 中转平台逐 chunk 转发 OpenAI 响应)。
+     * 调用方负责保证内容符合 HTML5 SSE 规范;`send` 会再次加 `data: ` 前缀,
+     * 不适用于原文透传场景。
+     *
+     * 接受 string 或 Uint8Array(Buffer 是 Uint8Array 子类,自然兼容)。
+     * 与 `send` 一致:close/aborted 后静默忽略,不抛错。
+     */
+    sendRaw(chunk: string | Uint8Array): void;
     /** 推送一个 error 事件并关闭流（用于流式输出中报错的优雅终止） */
     sendError(error: unknown): void;
     /** 关闭流（多次调用安全） */
@@ -550,17 +561,19 @@ interface LifecycleContext {
  * } satisfies FaapiConfig;
  * ```
  *
- * 多环境配置：
+ * 自定义业务配置（任意 key）：
  * ```ts
  * import type { FaapiConfig } from '@faapi/faapi';
  * export default {
  *   cors: { origin: '*' },
- *   // 自定义业务配置（任意 key）
- *   db: { host: 'localhost', port: 5432 },
+ *   // 通过 process.env.XXX 读取 .env 文件加载的环境变量
+ *   db: { host: process.env.DB_HOST ?? 'localhost', port: 5432 },
  * } satisfies FaapiConfig;
  * ```
  *
- * 环境覆盖通过 faapi.config.{NODE_ENV}.ts 实现（如 faapi.config.production.ts）
+ * 多环境差异通过 `.env` 系列文件实现（见 `loadEnv`）：
+ * - `.env` / `.env.local` / `.env.{env}` / `.env.{env}.local`
+ * - 环境由 `NODE_ENV > 'development'` 决定
  *
  * 框架元信息通过环境变量配置（不放在 config 内）：
  * - `PORT`：服务端口，默认 3000
@@ -998,7 +1011,8 @@ declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: stri
  * - dev 模式：`faapi dev` 启动时由 `compileConfig` 生成 `.faapi/faapi-config.js`
  * - prod 模式：`faapi build` 时由 `compileConfig` 生成 `dist/faapi-config.js`
  *
- * 产物由 `compileConfig` 在构建阶段合并 env 后固化，运行时不读源码、不现场编译、不按 env 合并。
+ * 产物由 `compileConfig` 在构建阶段编译，运行时不读源码、不现场编译。
+ * 环境变量由 `loadEnv` 从 `.env` 系列文件加载到 `process.env`，配置文件中通过 `process.env.XXX` 读取。
  *
  * - 产物存在 → import 并返回 default
  * - 产物不存在但源码有配置文件 → 抛错（强制 rebuild）
@@ -1010,6 +1024,26 @@ declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: stri
  */
 declare function loadConfig(rootDir: string, dist: string): Promise<Partial<FaapiConfig> | null>;
 
+/**
+ * 加载 `.env` 系列文件到 `process.env`
+ *
+ * 按 Next.js 约定加载四级文件（从低到高）：
+ * 1. `.env` — 所有环境共享
+ * 2. `.env.local` — 本地覆盖
+ * 3. `.env.{env}` — 按环境覆盖
+ * 4. `.env.{env}.local` — 按环境本地覆盖
+ *
+ * env 由 `NODE_ENV || 'development'` 决定。调用方应在调 loadEnv 之前自行兜底 NODE_ENV
+ * （dev 设 'development'，prod 设 'production'）。
+ *
+ * 合并规则：
+ * - 后加载的文件覆盖先加载的同名变量
+ * - **shell 已设置的变量不被覆盖**（`process.env` 已有的值优先）
+ *
+ * @param rootDir 项目根目录（`.env` 文件所在目录）
+ */
+declare function loadEnv(rootDir: string): void;
+
 declare const VALIDATION_ERROR = "VALIDATION_ERROR";
 declare const ROUTE_NOT_FOUND = "ROUTE_NOT_FOUND";
 declare const METHOD_NOT_ALLOWED = "METHOD_NOT_ALLOWED";
@@ -1181,4 +1215,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, createContext, createDevApp, createProdApp, createProgram, extractTypeInfo, getInputTypeForMethod, helmet, invalidateProgramCache, invokeHandler, 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, loadEnv, logger, resolveTypeNode };

package/dist/index.js

@@ -1043,6 +1043,87 @@ async function loadConfig(rootDir, dist) {
   return null;
 }
 
+// src/cli/loadEnv.ts
+import fs2 from "fs";
+import path3 from "path";
+function resolveEnv() {
+  return process.env.NODE_ENV || "development";
+}
+function getEnvFiles(env) {
+  return [".env", ".env.local", `.env.${env}`, `.env.${env}.local`];
+}
+function parseEnvFile(content, fileVars) {
+  const result = {};
+  const lines = content.replace(/\r\n/g, "\n").split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(trimmed);
+    if (!match) continue;
+    const [, key, rawValue] = match;
+    const value = parseValue(rawValue, { ...fileVars, ...result });
+    result[key] = value;
+  }
+  return result;
+}
+function parseValue(raw, env) {
+  if (raw === "") return "";
+  if (raw[0] === "'") {
+    const end = raw.indexOf("'", 1);
+    return end === -1 ? raw.slice(1) : raw.slice(1, end);
+  }
+  if (raw[0] === '"') {
+    const match = /^"((?:\\.|[^"\\])*)"/.exec(raw);
+    const inner = match ? match[1] : raw.slice(1);
+    return expandEscapesAndVars(inner, env);
+  }
+  const commentMatch = /^(.*?)(\s+#.*)$/.exec(raw);
+  const value = commentMatch ? commentMatch[1] : raw;
+  return value.trim();
+}
+function expandEscapesAndVars(str, env) {
+  const escaped = str.replace(/\\(.)/g, (_, ch) => {
+    switch (ch) {
+      case "n":
+        return "\n";
+      case "r":
+        return "\r";
+      case "t":
+        return "	";
+      case "\\":
+        return "\\";
+      case '"':
+        return '"';
+      default:
+        return ch;
+    }
+  });
+  return escaped.replace(
+    /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g,
+    (_, braced, plain) => {
+      const varName = braced || plain;
+      return env[varName] ?? process.env[varName] ?? "";
+    }
+  );
+}
+function loadEnv(rootDir) {
+  const env = resolveEnv();
+  const files = getEnvFiles(env);
+  const merged = {};
+  for (const file of files) {
+    const filePath = path3.join(rootDir, file);
+    if (!fs2.existsSync(filePath)) continue;
+    const content = fs2.readFileSync(filePath, "utf-8");
+    const parsed = parseEnvFile(content, merged);
+    Object.assign(merged, parsed);
+  }
+  for (const [key, value] of Object.entries(merged)) {
+    if (process.env[key] === void 0) {
+      process.env[key] = value;
+    }
+  }
+}
+
 // src/errors/FaapiError.ts
 var FaapiError = class extends Error {
   constructor(code, message, statusCode) {
@@ -1069,14 +1150,14 @@ var ValidationError = class extends FaapiError {
   issues;
 };
 var RouteNotFoundError = class extends FaapiError {
-  constructor(path9) {
-    super("ROUTE_NOT_FOUND", `Route not found: ${path9}`, 404);
+  constructor(path10) {
+    super("ROUTE_NOT_FOUND", `Route not found: ${path10}`, 404);
     this.name = "RouteNotFoundError";
   }
 };
 var MethodNotAllowedError = class extends FaapiError {
-  constructor(method, path9, allowedMethods) {
-    super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path9}`, 405);
+  constructor(method, path10, allowedMethods) {
+    super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path10}`, 405);
     this.allowedMethods = allowedMethods;
     this.name = "MethodNotAllowedError";
   }
@@ -1161,6 +1242,11 @@ function createSseWriter() {
       const text = encodeSseEvent(event);
       controller.enqueue(encoder.encode(text));
     },
+    sendRaw(chunk) {
+      if (closed || !controller) return;
+      const bytes = typeof chunk === "string" ? encoder.encode(chunk) : chunk;
+      controller.enqueue(bytes);
+    },
     sendError(error) {
       if (closed || !controller) return;
       const message = error instanceof Error ? error.message : String(error);
@@ -1549,8 +1635,8 @@ async function invokeHandler(handler, ctx, body, middlewares, injectors) {
 }
 
 // src/cli/createAppCore.ts
-import fs4 from "fs";
-import path7 from "path";
+import fs5 from "fs";
+import path8 from "path";
 import { PassThrough } from "stream";
 
 // src/router/sortRoutes.ts
@@ -1603,45 +1689,45 @@ import {
 import { createSecureServer as createHttp2SecureServer } from "http2";
 import { readFileSync } from "fs";
 import { Readable as Readable2 } from "stream";
-import path5 from "path";
+import path6 from "path";
 
 // src/router/matchRoute.ts
-function matchRoute(routes, method, path9) {
+function matchRoute(routes, method, path10) {
   for (const route of routes) {
     if (route.method !== method) {
       continue;
     }
     if (!route.isDynamic) {
-      if (route.urlPath === path9) {
+      if (route.urlPath === path10) {
         return { route, params: {} };
       }
       continue;
     }
-    const params = matchDynamicPath(route.urlPath, path9, route.paramNames, route.isCatchAll);
+    const params = matchDynamicPath(route.urlPath, path10, route.paramNames, route.isCatchAll);
     if (params !== null) {
       return { route, params };
     }
   }
   return null;
 }
-function matchWsRoute(wsRoutes, path9) {
+function matchWsRoute(wsRoutes, path10) {
   for (const route of wsRoutes) {
     if (!route.isDynamic) {
-      if (route.urlPath === path9) {
+      if (route.urlPath === path10) {
         return { route, params: {} };
       }
       continue;
     }
-    const params = matchDynamicPath(route.urlPath, path9, route.paramNames, route.isCatchAll);
+    const params = matchDynamicPath(route.urlPath, path10, route.paramNames, route.isCatchAll);
     if (params !== null) {
       return { route, params };
     }
   }
   return null;
 }
-function matchDynamicPath(pattern, path9, paramNames, isCatchAll) {
+function matchDynamicPath(pattern, path10, paramNames, isCatchAll) {
   const patternSegments = pattern.split("/").filter(Boolean);
-  const pathSegments = path9.split("/").filter(Boolean);
+  const pathSegments = path10.split("/").filter(Boolean);
   if (isCatchAll) {
     const nonCatchAllCount = patternSegments.length - 1;
     if (pathSegments.length <= nonCatchAllCount) {
@@ -1872,9 +1958,9 @@ async function validateInput(schemaPath, method, inputType, input) {
 function mapZodIssues(error) {
   return error.issues.map((issue) => {
     const code = mapZodCode(issue.code, issue.message);
-    const path9 = issue.path.map(String).join(".") || "";
+    const path10 = issue.path.map(String).join(".") || "";
     return {
-      path: path9,
+      path: path10,
       code,
       expected: issue.expected ?? mapExpectedFromMessage(issue.message),
       received: issue.received ?? mapReceivedFromMessage(issue.message),
@@ -1934,7 +2020,7 @@ function getClientIp(req) {
 
 // src/server/handleWsUpgrade.ts
 import { WebSocketServer, WebSocket } from "ws";
-import path3 from "path";
+import path4 from "path";
 
 // src/errors/formatErrorResponse.ts
 function formatErrorResponse(error) {
@@ -2107,7 +2193,7 @@ function attachWebSocket(options) {
     const finalHandler = async () => {
       let handlers;
       try {
-        const absoluteFilePath = path3.resolve(rootDir, route.filePath);
+        const absoluteFilePath = path4.resolve(rootDir, route.filePath);
         handlers = await loadWsHandler(absoluteFilePath, ctx);
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -2153,8 +2239,8 @@ function attachWebSocket(options) {
 }
 
 // src/cli/generateSchemaFiles.ts
-import path4 from "path";
-import fs2 from "fs/promises";
+import path5 from "path";
+import fs3 from "fs/promises";
 
 // src/ast/generateZodSchema.ts
 var CodeGenContext = class {
@@ -2463,7 +2549,7 @@ function getSchemaOutputPath(sourceFile, dist, rootDir) {
   }
   const idx = rel.lastIndexOf("/");
   const relDir = idx >= 0 ? rel.slice(0, idx) : "";
-  return path4.resolve(rootDir, dist, relDir, "zod.js");
+  return path5.resolve(rootDir, dist, relDir, "zod.js");
 }
 function getRuntimeSchemaPath(filePath, dist, rootDir) {
   let rel = filePath.replace(/\\/g, "/");
@@ -2474,7 +2560,7 @@ function getRuntimeSchemaPath(filePath, dist, rootDir) {
   }
   const idx = rel.lastIndexOf("/");
   const relDir = idx >= 0 ? rel.slice(0, idx) : "";
-  return path4.resolve(rootDir, dist, relDir, "zod.js");
+  return path5.resolve(rootDir, dist, relDir, "zod.js");
 }
 function getHelpersImportPath(relDir) {
   if (!relDir) return `./${HELPERS_FILENAME}`;
@@ -2524,7 +2610,7 @@ async function generateSchemaFiles(routes, rootDir, dist) {
   }
   const fileEntries = [];
   for (const [filePath, fileSources] of sourcesByFile) {
-    const relFile = path4.relative(rootDir, filePath).replace(/\\/g, "/");
+    const relFile = path5.relative(rootDir, filePath).replace(/\\/g, "/");
     const outputPath = getSchemaOutputPath(relFile, dist, rootDir);
     const allTypes = allTypesByFile.get(filePath) ?? /* @__PURE__ */ new Map();
     let relForDir = relFile;
@@ -2539,7 +2625,7 @@ async function generateSchemaFiles(routes, rootDir, dist) {
   }
   const allSourceCode = fileEntries.map((e) => e.source).join("\n");
   if (usesCoerceHelpers(allSourceCode)) {
-    const helpersPath = path4.resolve(rootDir, dist, HELPERS_FILENAME);
+    const helpersPath = path5.resolve(rootDir, dist, HELPERS_FILENAME);
     await writeSchemaFile(helpersPath, generateHelpersFileSource());
   }
   await Promise.all(
@@ -2547,8 +2633,8 @@ async function generateSchemaFiles(routes, rootDir, dist) {
   );
 }
 async function writeSchemaFile(outputPath, source) {
-  await fs2.mkdir(path4.dirname(outputPath), { recursive: true });
-  await fs2.writeFile(outputPath, source, "utf-8");
+  await fs3.mkdir(path5.dirname(outputPath), { recursive: true });
+  await fs3.writeFile(outputPath, source, "utf-8");
 }
 
 // src/server/createServer.ts
@@ -2596,15 +2682,15 @@ function limitStreamSize(stream, maxSize) {
     }
   });
 }
-function findAllowedMethods(routes, path9) {
+function findAllowedMethods(routes, path10) {
   const methods = /* @__PURE__ */ new Set();
   for (const route of routes) {
-    if (route.urlPath === path9) {
+    if (route.urlPath === path10) {
       methods.add(route.method);
       continue;
     }
     if (route.isDynamic) {
-      const params = matchDynamicPath(route.urlPath, path9, route.paramNames, route.isCatchAll);
+      const params = matchDynamicPath(route.urlPath, path10, route.paramNames, route.isCatchAll);
       if (params !== null) {
         methods.add(route.method);
       }
@@ -2690,7 +2776,7 @@ async function handleRequest(routes, rootDir, dist, req, res, configMiddlewares,
     }
     ctx.params = match.params;
     const { route } = match;
-    const absoluteFilePath = path5.resolve(rootDir, route.filePath);
+    const absoluteFilePath = path6.resolve(rootDir, route.filePath);
     const routeModule = await loadRouteModule(absoluteFilePath, route.method);
     const input = await resolveInput(route.method, request);
     const inputType = getInputTypeForMethod(route.method);
@@ -2764,8 +2850,8 @@ function applyPluginWrappers(server, handlerWrappers, upgradeWrappers) {
 }
 
 // src/cli/generateRoutes.ts
-import fs3 from "fs";
-import path6 from "path";
+import fs4 from "fs";
+import path7 from "path";
 
 // src/middleware/loadMiddlewares.ts
 var middlewareCache = /* @__PURE__ */ new Map();
@@ -2943,8 +3029,8 @@ function isFaapiConfigKey(key) {
 async function createAppBase(options) {
   const rootDir = options?.rootDir ?? process.cwd();
   const dist = options?.dist ?? process.env.FAAPI_DIST ?? DEFAULT_DIST;
-  const routesPath = path7.resolve(rootDir, dist, ROUTES_FILE);
-  if (!fs4.existsSync(routesPath)) {
+  const routesPath = path8.resolve(rootDir, dist, ROUTES_FILE);
+  if (!fs5.existsSync(routesPath)) {
     throw new Error(
       `[faapi] ${dist}/${ROUTES_FILE} \u4E0D\u5B58\u5728\uFF0C\u8BF7\u5148\u6267\u884C \`faapi build\`\uFF08\u6216 \`faapi dev\`\uFF09\u751F\u6210\u4EA7\u7269\u3002`
     );
@@ -3147,8 +3233,8 @@ async function createAppBase(options) {
 
 // src/router/scanRoutes.ts
 import fg from "fast-glob";
-import path8 from "path";
-import fs5 from "fs";
+import path9 from "path";
+import fs6 from "fs";
 
 // src/router/constants.ts
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
@@ -3158,9 +3244,9 @@ function isHttpMethod(value) {
 }
 
 // src/utils/normalizePath.ts
-function normalizePath(path9) {
-  if (!path9) return "";
-  let result = path9.replace(/\\/g, "/");
+function normalizePath(path10) {
+  if (!path10) return "";
+  let result = path10.replace(/\\/g, "/");
   result = result.replace(/\/+/g, "/");
   result = result.replace(/\/+$/, "");
   if (result && !result.startsWith("/")) {
@@ -3209,38 +3295,38 @@ function filePathToUrlPath(filePath) {
 // src/router/scanRoutes.ts
 var APP_DIR = "src";
 function toProdAbsPath(sourceAbsPath, rootDir, dist) {
-  let rel = path8.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
+  let rel = path9.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
   if (rel.startsWith(`${APP_DIR}/`)) {
     rel = rel.slice(APP_DIR.length + 1);
   }
   const prodRel = `${dist}/${rel.replace(/\.ts$/, ".js")}`;
-  return path8.resolve(rootDir, prodRel);
+  return path9.resolve(rootDir, prodRel);
 }
 async function findMergedMiddlewares(routeFilePath, rootDir, dist) {
-  const routeDir = path8.dirname(routeFilePath);
-  const resolvedRoot = path8.resolve(rootDir);
+  const routeDir = path9.dirname(routeFilePath);
+  const resolvedRoot = path9.resolve(rootDir);
   const mwPaths = [];
-  let currentDir = path8.resolve(rootDir, routeDir);
+  let currentDir = path9.resolve(rootDir, routeDir);
   while (true) {
     if (dist) {
-      const mwPath = path8.join(currentDir, "middlewares.js");
-      const absMwPath = path8.resolve(rootDir, mwPath);
+      const mwPath = path9.join(currentDir, "middlewares.js");
+      const absMwPath = path9.resolve(rootDir, mwPath);
       const prodAbsMwPath = toProdAbsPath(absMwPath, rootDir, dist);
-      if (fs5.existsSync(prodAbsMwPath)) {
+      if (fs6.existsSync(prodAbsMwPath)) {
         mwPaths.push(prodAbsMwPath);
       }
     } else {
       for (const ext of [".ts", ".js"]) {
-        const mwPath = path8.join(currentDir, `middlewares${ext}`);
-        const absMwPath = path8.resolve(rootDir, mwPath);
-        if (fs5.existsSync(absMwPath)) {
+        const mwPath = path9.join(currentDir, `middlewares${ext}`);
+        const absMwPath = path9.resolve(rootDir, mwPath);
+        if (fs6.existsSync(absMwPath)) {
           mwPaths.push(absMwPath);
           break;
         }
       }
     }
     if (currentDir === resolvedRoot) break;
-    const parentDir = path8.dirname(currentDir);
+    const parentDir = path9.dirname(currentDir);
     if (parentDir === currentDir) break;
     currentDir = parentDir;
   }
@@ -3302,7 +3388,7 @@ async function scanRoutes(rootDir, patterns, dist) {
     const normalizedFile = file.replace(/\\/g, "/");
     const fileName = normalizedFile.split("/").pop();
     if (fileName === "handler.ts" || fileName === "handler.js") {
-      const absPath = path8.resolve(rootDir, normalizedFile);
+      const absPath = path9.resolve(rootDir, normalizedFile);
       const importPath = dist ? toProdAbsPath(absPath, rootDir, dist) : absPath;
       const urlPath = filePathToUrlPath(normalizedFile);
       const paramNames = extractParamNames(urlPath);
@@ -3383,6 +3469,7 @@ export {
   invalidateProgramCache,
   invokeHandler,
   loadConfig,
+  loadEnv,
   logger,
   resolveTypeNode
 };