@faapi/faapi 0.0.0-canary.ede2e84 → 0.0.0-canary.f08a14e

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;
     /** 关闭流（多次调用安全） */
@@ -1064,6 +1075,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;
@@ -1157,4 +1192,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, logger, resolveTypeNode };

package/dist/index.js

@@ -1095,182 +1095,6 @@ var ModuleLoadError = class extends FaapiError {
   }
 };
 
-// src/cli/createAppCore.ts
-import fs4 from "fs";
-import path7 from "path";
-import { PassThrough } from "stream";
-
-// src/router/sortRoutes.ts
-function sortRoutes(routes) {
-  return [...routes].sort((a, b) => {
-    if (a.isDynamic !== b.isDynamic) {
-      return a.isDynamic ? 1 : -1;
-    }
-    if (a.isCatchAll !== b.isCatchAll) {
-      return a.isCatchAll ? 1 : -1;
-    }
-    const aSegments = a.urlPath.split("/").filter(Boolean).length;
-    const bSegments = b.urlPath.split("/").filter(Boolean).length;
-    if (aSegments !== bSegments) {
-      return aSegments - bSegments;
-    }
-    return a.urlPath.localeCompare(b.urlPath);
-  });
-}
-
-// src/router/detectRouteConflicts.ts
-function detectRouteConflicts(routes) {
-  const map = /* @__PURE__ */ new Map();
-  for (const route of routes) {
-    const key = `${route.method} ${route.urlPath}`;
-    const existing = map.get(key);
-    if (existing) {
-      existing.files.push(route.filePath);
-    } else {
-      map.set(key, {
-        method: route.method,
-        urlPath: route.urlPath,
-        files: [route.filePath]
-      });
-    }
-  }
-  const conflicts = [];
-  for (const conflict of map.values()) {
-    if (conflict.files.length > 1) {
-      conflicts.push(conflict);
-    }
-  }
-  return conflicts;
-}
-
-// src/server/createServer.ts
-import {
-  createServer as createHttpServer
-} from "http";
-import { createSecureServer as createHttp2SecureServer } from "http2";
-import { readFileSync } from "fs";
-import { Readable as Readable2 } from "stream";
-import path5 from "path";
-
-// src/router/matchRoute.ts
-function matchRoute(routes, method, path9) {
-  for (const route of routes) {
-    if (route.method !== method) {
-      continue;
-    }
-    if (!route.isDynamic) {
-      if (route.urlPath === path9) {
-        return { route, params: {} };
-      }
-      continue;
-    }
-    const params = matchDynamicPath(route.urlPath, path9, route.paramNames, route.isCatchAll);
-    if (params !== null) {
-      return { route, params };
-    }
-  }
-  return null;
-}
-function matchWsRoute(wsRoutes, path9) {
-  for (const route of wsRoutes) {
-    if (!route.isDynamic) {
-      if (route.urlPath === path9) {
-        return { route, params: {} };
-      }
-      continue;
-    }
-    const params = matchDynamicPath(route.urlPath, path9, route.paramNames, route.isCatchAll);
-    if (params !== null) {
-      return { route, params };
-    }
-  }
-  return null;
-}
-function matchDynamicPath(pattern, path9, paramNames, isCatchAll) {
-  const patternSegments = pattern.split("/").filter(Boolean);
-  const pathSegments = path9.split("/").filter(Boolean);
-  if (isCatchAll) {
-    const nonCatchAllCount = patternSegments.length - 1;
-    if (pathSegments.length <= nonCatchAllCount) {
-      return null;
-    }
-    const params2 = {};
-    for (let i = 0; i < nonCatchAllCount; i++) {
-      const patternSeg = patternSegments[i];
-      const pathSeg = pathSegments[i];
-      if (patternSeg.startsWith(":")) {
-        const paramName = patternSeg.slice(1);
-        params2[paramName] = pathSeg;
-      } else if (patternSeg !== pathSeg) {
-        return null;
-      }
-    }
-    const catchAllValue = pathSegments.slice(nonCatchAllCount).join("/");
-    const catchAllParamName = patternSegments[nonCatchAllCount].slice(4);
-    params2[catchAllParamName] = catchAllValue;
-    if (Object.keys(params2).length !== paramNames.length) {
-      return null;
-    }
-    return params2;
-  }
-  if (patternSegments.length !== pathSegments.length) {
-    return null;
-  }
-  const params = {};
-  for (let i = 0; i < patternSegments.length; i++) {
-    const patternSeg = patternSegments[i];
-    const pathSeg = pathSegments[i];
-    if (patternSeg.startsWith(":")) {
-      const paramName = patternSeg.slice(1);
-      params[paramName] = pathSeg;
-    } else if (patternSeg !== pathSeg) {
-      return null;
-    }
-  }
-  if (Object.keys(params).length !== paramNames.length) {
-    return null;
-  }
-  return params;
-}
-
-// src/loader/resolveExports.ts
-function resolveExport(module, exportName) {
-  if (exportName in module && typeof module[exportName] !== "undefined") {
-    return module[exportName];
-  }
-  const defaultExport = module.default;
-  if (defaultExport !== null && typeof defaultExport === "object") {
-    const value = defaultExport[exportName];
-    if (value !== void 0) {
-      return value;
-    }
-  }
-  return void 0;
-}
-
-// src/loader/validateRouteModule.ts
-function validateRouteModule(value, method, filePath) {
-  if (typeof value !== "function") {
-    throw new Error(
-      `Route module "${filePath}" does not export a valid handler for method "${method}". Expected a function, got ${typeof value}.`
-    );
-  }
-}
-
-// src/loader/loadRouteModule.ts
-async function loadRouteModule(filePath, method) {
-  let module;
-  try {
-    module = await importWithCacheBust(filePath);
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
-    throw new Error(`Failed to load route module "${filePath}": ${reason}`, { cause: err });
-  }
-  const handler = resolveExport(module, method);
-  validateRouteModule(handler, method, filePath);
-  return { handler, method };
-}
-
 // src/runtime/sse.ts
 function encodeSseEvent(event) {
   let out = "";
@@ -1337,6 +1161,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);
@@ -1475,119 +1304,30 @@ function createContext(request, params, config = {}, ip = "") {
   return ctx;
 }
 
-// src/utils/queryToObject.ts
-function queryToObject(params) {
-  const result = {};
-  for (const [key, value] of params) {
-    result[key] = value;
+// src/utils/isPlainObject.ts
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
   }
-  return result;
-}
-
-// src/utils/parseJsonBody.ts
-function parseJsonBody(text) {
-  try {
-    const data = JSON.parse(text);
-    return { success: true, data };
-  } catch {
-    return { success: false, error: "Invalid JSON body" };
+  if (Array.isArray(value)) {
+    return false;
   }
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
 }
 
-// src/utils/parseMultipart.ts
-async function parseMultipart(request) {
-  const formData = await request.formData();
-  const fields = {};
-  const files = [];
-  for (const [key, value] of formData.entries()) {
-    if (value instanceof File) {
-      files.push({
-        name: key,
-        filename: value.name,
-        type: value.type,
-        size: value.size,
-        arrayBuffer: () => value.arrayBuffer()
-      });
-    } else {
-      if (key in fields) {
-        const existing = fields[key];
-        if (Array.isArray(existing)) {
-          existing.push(value);
-        } else {
-          fields[key] = [existing, value];
-        }
-      } else {
-        fields[key] = value;
-      }
-    }
+// src/response/toResponse.ts
+async function toResponse(value, meta) {
+  if (value instanceof Promise) {
+    return toResponse(await value, meta);
   }
-  return { fields, files };
-}
-
-// src/runtime/resolveInput.ts
-async function resolveInput(method, request) {
-  const inputType = getInputTypeForMethod(method);
-  if (inputType === "body") {
-    const contentType = request.headers.get("content-type") ?? "";
-    if (contentType.includes("multipart/form-data")) {
-      return parseMultipart(request);
+  const applyMeta = (headers2) => {
+    if (!meta) return;
+    for (const [key, val] of Object.entries(meta.headers)) {
+      headers2.set(key, val);
     }
-    if (contentType.includes("application/x-www-form-urlencoded")) {
-      const text2 = await request.text();
-      if (text2.trim() === "") return null;
-      const params = new URLSearchParams(text2);
-      const obj = {};
-      for (const [key, value] of params) {
-        obj[key] = value;
-      }
-      return obj;
-    }
-    const text = await request.text();
-    if (text.trim() === "") {
-      return null;
-    }
-    const result = parseJsonBody(text);
-    if (!result.success) {
-      throw new ValidationError("\u8BF7\u6C42\u4F53\u4E0D\u662F\u5408\u6CD5\u7684 JSON", [
-        {
-          path: "body",
-          code: "INVALID_FORMAT",
-          expected: "JSON",
-          received: "text",
-          message: "\u8BF7\u6C42\u4F53\u4E0D\u662F\u5408\u6CD5\u7684 JSON"
-        }
-      ]);
-    }
-    return result.data;
-  }
-  const url = new URL(request.url);
-  return queryToObject(url.searchParams);
-}
-
-// src/utils/isPlainObject.ts
-function isPlainObject(value) {
-  if (value === null || typeof value !== "object") {
-    return false;
-  }
-  if (Array.isArray(value)) {
-    return false;
-  }
-  const proto = Object.getPrototypeOf(value);
-  return proto === null || proto === Object.prototype;
-}
-
-// src/response/toResponse.ts
-async function toResponse(value, meta) {
-  if (value instanceof Promise) {
-    return toResponse(await value, meta);
-  }
-  const applyMeta = (headers2) => {
-    if (!meta) return;
-    for (const [key, val] of Object.entries(meta.headers)) {
-      headers2.set(key, val);
-    }
-    for (const cookie of meta.setCookies ?? []) {
-      headers2.append("set-cookie", cookie);
+    for (const cookie of meta.setCookies ?? []) {
+      headers2.append("set-cookie", cookie);
     }
   };
   if (value instanceof Response) {
@@ -1665,6 +1405,15 @@ async function toResponse(value, meta) {
   });
 }
 
+// src/utils/queryToObject.ts
+function queryToObject(params) {
+  const result = {};
+  for (const [key, value] of params) {
+    result[key] = value;
+  }
+  return result;
+}
+
 // src/injection/injectParams.ts
 function getBuiltinInjectionValue(type, ctx, body) {
   switch (type) {
@@ -1804,6 +1553,262 @@ async function invokeHandler(handler, ctx, body, middlewares, injectors) {
   return await compose(middlewares, ctx, finalHandler);
 }
 
+// src/cli/createAppCore.ts
+import fs4 from "fs";
+import path7 from "path";
+import { PassThrough } from "stream";
+
+// src/router/sortRoutes.ts
+function sortRoutes(routes) {
+  return [...routes].sort((a, b) => {
+    if (a.isDynamic !== b.isDynamic) {
+      return a.isDynamic ? 1 : -1;
+    }
+    if (a.isCatchAll !== b.isCatchAll) {
+      return a.isCatchAll ? 1 : -1;
+    }
+    const aSegments = a.urlPath.split("/").filter(Boolean).length;
+    const bSegments = b.urlPath.split("/").filter(Boolean).length;
+    if (aSegments !== bSegments) {
+      return aSegments - bSegments;
+    }
+    return a.urlPath.localeCompare(b.urlPath);
+  });
+}
+
+// src/router/detectRouteConflicts.ts
+function detectRouteConflicts(routes) {
+  const map = /* @__PURE__ */ new Map();
+  for (const route of routes) {
+    const key = `${route.method} ${route.urlPath}`;
+    const existing = map.get(key);
+    if (existing) {
+      existing.files.push(route.filePath);
+    } else {
+      map.set(key, {
+        method: route.method,
+        urlPath: route.urlPath,
+        files: [route.filePath]
+      });
+    }
+  }
+  const conflicts = [];
+  for (const conflict of map.values()) {
+    if (conflict.files.length > 1) {
+      conflicts.push(conflict);
+    }
+  }
+  return conflicts;
+}
+
+// src/server/createServer.ts
+import {
+  createServer as createHttpServer
+} from "http";
+import { createSecureServer as createHttp2SecureServer } from "http2";
+import { readFileSync } from "fs";
+import { Readable as Readable2 } from "stream";
+import path5 from "path";
+
+// src/router/matchRoute.ts
+function matchRoute(routes, method, path9) {
+  for (const route of routes) {
+    if (route.method !== method) {
+      continue;
+    }
+    if (!route.isDynamic) {
+      if (route.urlPath === path9) {
+        return { route, params: {} };
+      }
+      continue;
+    }
+    const params = matchDynamicPath(route.urlPath, path9, route.paramNames, route.isCatchAll);
+    if (params !== null) {
+      return { route, params };
+    }
+  }
+  return null;
+}
+function matchWsRoute(wsRoutes, path9) {
+  for (const route of wsRoutes) {
+    if (!route.isDynamic) {
+      if (route.urlPath === path9) {
+        return { route, params: {} };
+      }
+      continue;
+    }
+    const params = matchDynamicPath(route.urlPath, path9, route.paramNames, route.isCatchAll);
+    if (params !== null) {
+      return { route, params };
+    }
+  }
+  return null;
+}
+function matchDynamicPath(pattern, path9, paramNames, isCatchAll) {
+  const patternSegments = pattern.split("/").filter(Boolean);
+  const pathSegments = path9.split("/").filter(Boolean);
+  if (isCatchAll) {
+    const nonCatchAllCount = patternSegments.length - 1;
+    if (pathSegments.length <= nonCatchAllCount) {
+      return null;
+    }
+    const params2 = {};
+    for (let i = 0; i < nonCatchAllCount; i++) {
+      const patternSeg = patternSegments[i];
+      const pathSeg = pathSegments[i];
+      if (patternSeg.startsWith(":")) {
+        const paramName = patternSeg.slice(1);
+        params2[paramName] = pathSeg;
+      } else if (patternSeg !== pathSeg) {
+        return null;
+      }
+    }
+    const catchAllValue = pathSegments.slice(nonCatchAllCount).join("/");
+    const catchAllParamName = patternSegments[nonCatchAllCount].slice(4);
+    params2[catchAllParamName] = catchAllValue;
+    if (Object.keys(params2).length !== paramNames.length) {
+      return null;
+    }
+    return params2;
+  }
+  if (patternSegments.length !== pathSegments.length) {
+    return null;
+  }
+  const params = {};
+  for (let i = 0; i < patternSegments.length; i++) {
+    const patternSeg = patternSegments[i];
+    const pathSeg = pathSegments[i];
+    if (patternSeg.startsWith(":")) {
+      const paramName = patternSeg.slice(1);
+      params[paramName] = pathSeg;
+    } else if (patternSeg !== pathSeg) {
+      return null;
+    }
+  }
+  if (Object.keys(params).length !== paramNames.length) {
+    return null;
+  }
+  return params;
+}
+
+// src/loader/resolveExports.ts
+function resolveExport(module, exportName) {
+  if (exportName in module && typeof module[exportName] !== "undefined") {
+    return module[exportName];
+  }
+  const defaultExport = module.default;
+  if (defaultExport !== null && typeof defaultExport === "object") {
+    const value = defaultExport[exportName];
+    if (value !== void 0) {
+      return value;
+    }
+  }
+  return void 0;
+}
+
+// src/loader/validateRouteModule.ts
+function validateRouteModule(value, method, filePath) {
+  if (typeof value !== "function") {
+    throw new Error(
+      `Route module "${filePath}" does not export a valid handler for method "${method}". Expected a function, got ${typeof value}.`
+    );
+  }
+}
+
+// src/loader/loadRouteModule.ts
+async function loadRouteModule(filePath, method) {
+  let module;
+  try {
+    module = await importWithCacheBust(filePath);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to load route module "${filePath}": ${reason}`, { cause: err });
+  }
+  const handler = resolveExport(module, method);
+  validateRouteModule(handler, method, filePath);
+  return { handler, method };
+}
+
+// src/utils/parseJsonBody.ts
+function parseJsonBody(text) {
+  try {
+    const data = JSON.parse(text);
+    return { success: true, data };
+  } catch {
+    return { success: false, error: "Invalid JSON body" };
+  }
+}
+
+// src/utils/parseMultipart.ts
+async function parseMultipart(request) {
+  const formData = await request.formData();
+  const fields = {};
+  const files = [];
+  for (const [key, value] of formData.entries()) {
+    if (value instanceof File) {
+      files.push({
+        name: key,
+        filename: value.name,
+        type: value.type,
+        size: value.size,
+        arrayBuffer: () => value.arrayBuffer()
+      });
+    } else {
+      if (key in fields) {
+        const existing = fields[key];
+        if (Array.isArray(existing)) {
+          existing.push(value);
+        } else {
+          fields[key] = [existing, value];
+        }
+      } else {
+        fields[key] = value;
+      }
+    }
+  }
+  return { fields, files };
+}
+
+// src/runtime/resolveInput.ts
+async function resolveInput(method, request) {
+  const inputType = getInputTypeForMethod(method);
+  if (inputType === "body") {
+    const contentType = request.headers.get("content-type") ?? "";
+    if (contentType.includes("multipart/form-data")) {
+      return parseMultipart(request);
+    }
+    if (contentType.includes("application/x-www-form-urlencoded")) {
+      const text2 = await request.text();
+      if (text2.trim() === "") return null;
+      const params = new URLSearchParams(text2);
+      const obj = {};
+      for (const [key, value] of params) {
+        obj[key] = value;
+      }
+      return obj;
+    }
+    const text = await request.text();
+    if (text.trim() === "") {
+      return null;
+    }
+    const result = parseJsonBody(text);
+    if (!result.success) {
+      throw new ValidationError("\u8BF7\u6C42\u4F53\u4E0D\u662F\u5408\u6CD5\u7684 JSON", [
+        {
+          path: "body",
+          code: "INVALID_FORMAT",
+          expected: "JSON",
+          received: "text",
+          message: "\u8BF7\u6C42\u4F53\u4E0D\u662F\u5408\u6CD5\u7684 JSON"
+        }
+      ]);
+    }
+    return result.data;
+  }
+  const url = new URL(request.url);
+  return queryToObject(url.searchParams);
+}
+
 // src/response/sendNodeResponse.ts
 import { Readable } from "stream";
 async function sendNodeResponse(response, res) {
@@ -3373,6 +3378,7 @@ export {
   collectRouteSchemaSources,
   cors,
   createProdApp as createApp,
+  createContext,
   createDevApp,
   createProdApp,
   createProgram,
@@ -3380,6 +3386,7 @@ export {
   getInputTypeForMethod,
   helmet,
   invalidateProgramCache,
+  invokeHandler,
   loadConfig,
   logger,
   resolveTypeNode