@route-forge/core 1.3.0 → 1.4.0

package/README.md

@@ -281,6 +281,46 @@ const prefixed = bound.useRoutePrefix('posts')  // 追加前缀
 `ForgeError (RF_FE_010)`， 防止在路由数据未就绪时返回错误结果。`api()` 不受影响（内部自动 await
 discovery）。
 
+## 工具导出
+
+除 `createRouteForge` 外，core 包还导出以下工具件，供高级场景按需使用：
+
+| 导出                        | 说明                                                                                   |
+|-----------------------------|----------------------------------------------------------------------------------------|
+| `createInterceptorManager`  | 创建拦截器管理器（`use`/`eject`/`clear`），供自定义 Fetcher 复用统一拦截器实现   |
+| `RouteCache`                | 按层级隔离的路由缓存类（memory / sessionStorage / localStorage，TTL 过期），可独立使用 |
+| `LoadingTracker`            | 加载状态跟踪器（引用计数 + 订阅），框架适配层可基于它实现全局加载指示                |
+| `resolveRouteName`          | 前缀歧义异步消解（`prefix.suffix` 优先，回退后缀本身），`api()` 调用路径使用      |
+| `resolveRouteNameSync`      | 前缀歧义同步消解（基于已加载缓存），`route()` / `url()` 调用路径使用              |
+
+## 错误参考
+
+所有错误均为 `ForgeError` 子类，携带稳定的 `code` 字段，可按 `code` 分支处理：
+
+| 错误类                        | code        | 触发场景                                             |
+|-------------------------------|-------------|------------------------------------------------------|
+| `UnknownRouteError`         | `RF_FE_001` | 路由名不存在于已加载层级中                           |
+| `UnknownLevelError`         | `RF_FE_002` | 层级未在 levels 声明（前端校验始终开启）             |
+| `MissingRouteParamError`    | `RF_FE_003` | 必填路径参数缺失（无后端默认值）                     |
+| `AdapterNotFoundError`      | `RF_FE_005` | `adapter: 'axios'` 但宿主未安装/无有效 axios       |
+| `InvalidInterceptorReturnError` | `RF_FE_006` | 请求拦截器未返回 RequestConfig 对象               |
+| `NetworkError`              | `RF_FE_007` | 网络层失败（DNS、连接被拒等），`cause` 保留原始错误 |
+| `HTTPError`                 | `RF_FE_008` | HTTP 非 2xx，`context.status` 为状态码             |
+| `RequestAbortedError`       | `RF_FE_009` | 请求被 `abort()` / AbortSignal 取消               |
+| `ForgeError`（守卫）        | `RF_FE_010` | auto-discovery 未完成时调用 `route()`/`hasRoute()` |
+
+错误对象结构：
+
+```ts
+{
+  code: 'RF_FE_008',          // 稳定错误码
+  route?: string,             // 关联路由名
+  level?: string,             // 关联层级
+  context?: Record<string, unknown>,  // 附加上下文（如 HTTP 状态码）
+  cause?: unknown,            // 原始底层错误
+}
+```
+
 ## 文档
 
 - 仓库主页: https://github.com/route-forge/route-forge

package/dist/codegen.d.cts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { R as RouteMeta } from './types-D4PMbR4-.cjs';
+import { R as RouteMeta } from './types-BFlrOTrN.cjs';
 
 /**
  * @route-forge/core codegen CLI

package/dist/codegen.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { R as RouteMeta } from './types-D4PMbR4-.js';
+import { R as RouteMeta } from './types-BFlrOTrN.js';
 
 /**
  * @route-forge/core codegen CLI

package/dist/index.cjs

@@ -280,30 +280,29 @@ function combineSignals(...signals) {
 function createBuiltinHttp(forgeInterceptors) {
   const requestMgr = forgeInterceptors?.request ?? createInterceptorManager();
   const responseMgr = forgeInterceptors?.response ?? createInterceptorManager();
-  async function request(config) {
-    const finalConfig = await runRequestInterceptors(requestMgr, config);
+  async function requestRaw(config) {
     const signal = combineSignals(
-      finalConfig.signal,
-      finalConfig.timeout && finalConfig.timeout > 0 ? AbortSignal.timeout(finalConfig.timeout) : void 0
+      config.signal,
+      config.timeout && config.timeout > 0 ? AbortSignal.timeout(config.timeout) : void 0
     );
-    let url = finalConfig.url;
-    if (finalConfig.paramsSerializer && finalConfig.params) {
-      const qs = finalConfig.paramsSerializer(finalConfig.params);
+    let url = config.url;
+    if (config.paramsSerializer && config.params) {
+      const qs = config.paramsSerializer(config.params);
       if (qs) {
         url = url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
       }
     }
-    const headers = new Headers(finalConfig.headers);
+    const headers = new Headers(config.headers);
     const fetchInit = {
-      method: finalConfig.method,
+      method: config.method,
       headers
     };
     if (signal) fetchInit.signal = signal;
-    if (finalConfig.body !== void 0 && !["GET", "HEAD"].includes(finalConfig.method.toUpperCase())) {
-      if (typeof finalConfig.body === "string" || isPassthroughBody(finalConfig.body)) {
-        fetchInit.body = finalConfig.body;
+    if (config.body !== void 0 && !["GET", "HEAD"].includes(config.method.toUpperCase())) {
+      if (typeof config.body === "string" || isPassthroughBody(config.body)) {
+        fetchInit.body = config.body;
       } else {
-        fetchInit.body = JSON.stringify(finalConfig.body);
+        fetchInit.body = JSON.stringify(config.body);
         if (!headers.has("Content-Type")) {
           headers.set("Content-Type", "application/json");
         }
@@ -316,8 +315,8 @@ function createBuiltinHttp(forgeInterceptors) {
       if (isAbortError(e)) throw e;
       throw new NetworkError(
         e instanceof Error ? e.message : String(e),
-        finalConfig.route,
-        finalConfig.level,
+        config.route,
+        config.level,
         e
       );
     }
@@ -331,27 +330,32 @@ function createBuiltinHttp(forgeInterceptors) {
       }
     }
     const responseData = {
-      route: finalConfig.route,
-      level: finalConfig.level,
-      method: finalConfig.method,
+      route: config.route,
+      level: config.level,
+      method: config.method,
       url,
       status: res.status,
       headers: res.headers,
       data,
-      config: finalConfig
+      config
     };
-    const source = res.status >= 200 && res.status < 300 ? Promise.resolve(responseData) : Promise.reject(
-      new HTTPError(
-        `HTTP ${res.status} for route "${finalConfig.route}" (${finalConfig.method} ${url})`,
-        {
-          route: finalConfig.route,
-          level: finalConfig.level,
-          status: res.status,
-          url,
-          method: finalConfig.method
-        }
-      )
+    if (res.status >= 200 && res.status < 300) {
+      return responseData;
+    }
+    throw new HTTPError(
+      `HTTP ${res.status} for route "${config.route}" (${config.method} ${url})`,
+      {
+        route: config.route,
+        level: config.level,
+        status: res.status,
+        url,
+        method: config.method
+      }
     );
+  }
+  async function request(config) {
+    const finalConfig = await runRequestInterceptors(requestMgr, config);
+    const source = Promise.resolve(finalConfig).then(requestRaw);
     return runResponseInterceptors(
       responseMgr,
       source
@@ -364,6 +368,7 @@ function createBuiltinHttp(forgeInterceptors) {
   const del = (url, config) => request({ ...config, url, method: "DELETE" });
   return {
     request,
+    requestRaw,
     interceptors: {
       request: requestMgr,
       response: responseMgr
@@ -575,7 +580,6 @@ function createRouteForge(options) {
   const loadingTracker = new LoadingTracker();
   const explicitLevels = options.levels;
   const explicitEager = options.eager;
-  const explicitStrict = options.strict ?? false;
   const explicitEndpoint = options.endpoint;
   let effectiveLevels = explicitLevels ?? [];
   let effectiveEager = explicitEager ?? [];
@@ -623,11 +627,6 @@ function createRouteForge(options) {
     if (summary.config.url_prefix) {
       effectiveUrlPrefix = summary.config.url_prefix.endsWith("/") ? summary.config.url_prefix.slice(0, -1) : summary.config.url_prefix;
     }
-    if (summary.config.strict_mode && !explicitStrict) {
-      console.warn(
-        "[route-forge] backend strict_mode=true overrides frontend strict=false; forcing strict=true"
-      );
-    }
     const backendLevels = Object.keys(summary.levels);
     backendHasUnassignedLevel = backendLevels.includes(UNASSIGNED_LEVEL);
     if (Array.isArray(summary.unassigned) && summary.unassigned.length > 0 && !backendHasUnassignedLevel) {
@@ -701,7 +700,10 @@ function createRouteForge(options) {
     if (!adapterResolved) {
       adapterObj = await adapterPromise.catch((e) => {
         if (e instanceof AdapterNotFoundError) throw e;
-        return resolveAdapter({ adapter: "builtin" });
+        return resolveAdapter({
+          adapter: "builtin",
+          forgeInterceptors: { request: requestInterceptors, response: responseInterceptors }
+        });
       });
       adapterResolved = true;
     }
@@ -745,7 +747,8 @@ function createRouteForge(options) {
         level
       }
     };
-    const resp = await adp.request(config);
+    const doRawRequest = adp.requestRaw ?? adp.request;
+    const resp = await doRawRequest(config);
     if (!resp || resp.status < 200 || resp.status >= 300) {
       throw new HTTPError(
         `Failed to load level "${level}": HTTP ${resp?.status}`,
@@ -848,23 +851,40 @@ function createRouteForge(options) {
     }
     return void 0;
   }
-  async function api(level, name, params = {}) {
-    await autoDiscoveryPromise;
-    await load(level);
-    const meta = findRouteMeta(level, name);
-    if (!meta) {
-      throw new UnknownRouteError(name, level);
-    }
-    return doApiCall(meta, params);
+  function api(level, name, params = {}) {
+    let ctrl;
+    let abortedBeforeInit = false;
+    let abortReason;
+    const work = (async () => {
+      ctrl = new AbortController();
+      if (abortedBeforeInit) {
+        ctrl.abort(abortReason);
+      }
+      await autoDiscoveryPromise;
+      await load(level);
+      const meta = findRouteMeta(level, name);
+      if (!meta) {
+        throw new UnknownRouteError(name, level);
+      }
+      return doApiCall(meta, params, ctrl.signal);
+    })();
+    const request = work;
+    request.abort = () => {
+      if (ctrl) {
+        ctrl.abort();
+      } else {
+        abortedBeforeInit = true;
+      }
+    };
+    return request;
   }
-  async function doApiCall(meta, params) {
+  async function doApiCall(meta, params, signal) {
     const {
       pathParams,
       query,
       body,
       headers,
-      timeout: perCallTimeout,
-      signal
+      timeout: perCallTimeout
     } = resolveApiParams(params);
     if (signal?.aborted) {
       throw new RequestAbortedError(meta.name, meta.level, signal.reason);
@@ -908,7 +928,7 @@ function createRouteForge(options) {
         },
         (err) => {
           if (err instanceof ForgeError) throw err;
-          if (isAbortError2(err, finalConfig.signal)) {
+          if (isAbortError2(err, signal)) {
             throw new RequestAbortedError(meta.name, meta.level, err);
           }
           throw new NetworkError(
@@ -996,7 +1016,8 @@ function createRouteForge(options) {
   }
   const forgeResolver = { load, hasRoute };
   function createBoundForge(level, prefix) {
-    const levelLoadedPromise = load(level).catch(() => {
+    const levelLoadedPromise = load(level);
+    levelLoadedPromise.catch(() => {
     });
     const apiFn = prefix ? (name, params) => resolveRouteName(forgeResolver, level, prefix, name).then(
       (resolved) => api(level, resolved, params)
@@ -1096,7 +1117,6 @@ function resolveApiParams(input) {
     body: rawBody,
     headers: rawHeaders,
     timeout: perCallTimeout,
-    signal,
     ...flatRest
   } = input;
   const pathParams = explicitParams ? { ...explicitParams } : {};
@@ -1129,7 +1149,7 @@ function resolveApiParams(input) {
       pathParams.headers = rawHeaders;
     }
   }
-  return { pathParams, query, body, headers, timeout: perCallTimeout, signal };
+  return { pathParams, query, body, headers, timeout: perCallTimeout };
 }
 function isAbortError2(err, signal) {
   if (signal?.aborted) return true;