@faapi/faapi 0.0.0-canary.f5b23c6 → 1.0.0-canary.4f644f8

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,21 +561,23 @@ 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
- * - `FAAPI_DIST`：产物输出目录（实际目录），dev 为 <dist>/dev（默认 .faapi/dev），prod 为 <dist>/build（默认 .faapi/build）
+ * - `FAAPI_DIST`：产物输出目录，dev 固定为 `.faapi`（不可修改），prod 默认为 `dist`（可通过 `--dist` 修改）
  */
 interface FaapiConfig {
     /** CORS 配置，false 禁用 */
@@ -995,21 +1008,42 @@ declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: stri
  * 加载 faapi 配置文件
  *
  * 统一读取 `<dist>/faapi-config.js` 产物：
- * - dev 模式：`faapi dev` 启动时由 `compileConfig` 生成 `.faapi/dev/faapi-config.js`
- * - prod 模式：`faapi build` 时由 `compileConfig` 生成 `.faapi/build/faapi-config.js`
+ * - 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）
  * - 源码也无配置文件 → 返回 `null`（配置可选）
  *
  * @param rootDir 项目根目录
- * @param dist 产物目录（如 '.faapi/build' 或 '.faapi/dev'）
+ * @param dist 产物目录（如 'dist' 或 '.faapi'）
  * @returns 配置对象，无配置文件时返回 null
  */
 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";
@@ -1064,6 +1098,30 @@ interface ValidationIssue {
 }
 type ValidationErrorCode = 'TYPE_MISMATCH' | 'MISSING_FIELD' | 'INVALID_FORMAT' | 'INVALID_VALUE' | 'COERCE_FAILED';
 
+/**
+ * 从 Request 对象创建 FaapiContext
+ * @param request Web Request 对象
+ * @param params 动态路由参数
+ * @param config 自定义业务配置（来自 faapi.config.ts）
+ * @param ip 客户端 IP（由调用方从 IncomingMessage 提取，HTTP/WS 握手均通过 utils/getClientIp）
+ */
+declare function createContext(request: Request, params: Record<string, string>, config?: Record<string, unknown>, ip?: string): FaapiContext;
+
+/**
+ * 调用路由 handler 并将返回值转为 Response
+ *
+ * 流程（洋葱模型）：
+ * 1. 中间件按洋葱模型执行：mw1.before → mw2.before → ... → handler → ... → mw2.after → mw1.after
+ * 2. 中间件不调用 next() 即拦截请求（必须返回 Response）
+ * 3. 中间件可用 try/catch 捕获内层错误
+ * 4. 最内层执行注入器（按需）→ handler
+ *
+ * 注入器与中间件解耦：
+ * - 注入器按 handler 参数名匹配，只执行需要的
+ * - 注入器可读取中间件塞进 ctx 的值
+ */
+declare function invokeHandler(handler: (...args: unknown[]) => unknown, ctx: FaapiContext, body?: unknown, middlewares?: FaapiMiddleware[], injectors?: InjectorMap): Promise<Response>;
+
 interface InjectOptions {
     method?: string;
     path?: string;
@@ -1079,7 +1137,7 @@ interface InjectResponse {
 interface CreateAppOptions {
     /** 项目根目录，默认 process.cwd() */
     rootDir?: string;
-    /** 产物输出目录（实际目录，如 .faapi/build 或 .faapi/dev），覆盖环境变量 FAAPI_DIST，默认 '.faapi/build' */
+    /** 产物输出目录（如 dist 或 .faapi），覆盖环境变量 FAAPI_DIST，默认 'dist' */
     dist?: string;
     /** 端口号，也可在 listen() 时传入；默认环境变量 PORT 或 3000 */
     port?: number;
@@ -1157,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, createDevApp, createProdApp, createProgram, extractTypeInfo, getInputTypeForMethod, helmet, invalidateProgramCache, 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 };