@route-forge/core 1.3.1 → 2.0.0

package/README.md

@@ -196,18 +196,22 @@ unsub()
 | Level load     | 拉取某层级路由元数据           | `forge.isLoaded(level)`     |
 | API request    | 业务接口请求                   | `forge.isLoading()`         |
 
-### `onSummaryReady` 回调
+### `ready()` 后挂载应用
 
-推荐在回调中挂载应用，确保路由数据就绪：
+推荐在 `ready()` resolve 后挂载应用（auto-discovery + eager 层级全部完成），
+失败走 `catch`（onSummaryReady 回调已移除，统一走 ready——完整成功/失败语义链）：
 
 ```ts
 const forge = createRouteForge({
   endpoint: '/_forge/routes',
-  onSummaryReady: () => {
-    // 摘要端点完成，路由数据已可用
-    app.mount('#app')
-  },
 })
+// 成功：摘要 + eager 完成后挂载；失败：接住 reject，避免静默白屏
+forge.ready()
+  .then(() => app.mount('#app'))
+  .catch((err) => {
+    console.error('[route-forge] init failed', err)
+    // 按业务需要降级：渲染错误页 / 重试 / 上报
+  })
 ```
 
 ### `forge.ready()` 方法
@@ -281,6 +285,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-Cd1c1OdJ.cjs';
+import { R as RouteMeta } from './types-BvLdl02f.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-Cd1c1OdJ.js';
+import { R as RouteMeta } from './types-BvLdl02f.js';
 
 /**
  * @route-forge/core codegen CLI

package/dist/index.cjs

@@ -16,9 +16,18 @@ function pickStorage(storage) {
 var RouteCache = class {
   constructor(opts) {
     this.memory = /* @__PURE__ */ new Map();
+    /** 其他 tab 修改 storage 时失效对应镜像（storage 事件：自己的写不触发，自己的写经 set/del 已同步） */
+    this.onStorageEvent = (e) => {
+      if (!e.key) return;
+      if (!e.key.startsWith(KEY_PREFIX)) return;
+      this.memory.delete(e.key.slice(KEY_PREFIX.length));
+    };
     this.storage = opts.storage;
     this.fallbackTtl = opts.ttl;
     this.backend = pickStorage(opts.storage);
+    if (this.backend && typeof globalThis.addEventListener === "function") {
+      globalThis.addEventListener("storage", this.onStorageEvent);
+    }
   }
   key(level) {
     return `${KEY_PREFIX}${level}`;
@@ -27,6 +36,8 @@ var RouteCache = class {
     if (this.storage === "memory" || !this.backend) {
       return this.getFromMemory(level);
     }
+    const mirrored = this.getFromMemory(level);
+    if (mirrored) return mirrored;
     const raw = this.backend.getItem(this.key(level));
     if (raw) {
       try {
@@ -35,12 +46,13 @@ var RouteCache = class {
           this.del(level);
           return void 0;
         }
+        this.memory.set(level, entry);
         return entry;
       } catch {
         return void 0;
       }
     }
-    return this.getFromMemory(level);
+    return void 0;
   }
   getFromMemory(level) {
     const entry = this.memory.get(level);
@@ -64,14 +76,13 @@ var RouteCache = class {
       ttl,
       cachedAt: Date.now()
     };
+    this.memory.set(resp.level, entry);
     if (this.storage === "memory" || !this.backend) {
-      this.memory.set(resp.level, entry);
       return;
     }
     try {
       this.backend.setItem(this.key(resp.level), JSON.stringify(entry));
     } catch {
-      this.memory.set(resp.level, entry);
     }
   }
   del(level) {
@@ -251,14 +262,14 @@ function createInterceptorManager() {
   return new InterceptorManagerImpl();
 }
 
-// src/adapters/builtin-http.ts
-function isPassthroughBody(body) {
-  if (body === null) return false;
-  return typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams || typeof Blob !== "undefined" && body instanceof Blob || typeof ArrayBuffer !== "undefined" && (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) || typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
-}
-function isAbortError(err) {
+// src/adapters/fetch-core.ts
+function isAbortError(err, signal) {
+  if (signal?.aborted) return true;
   const e = err;
-  return !!e && e.name === "AbortError";
+  if (!e) return false;
+  if (e.name === "AbortError") return true;
+  if (e.code === "ERR_CANCELED") return true;
+  return false;
 }
 function combineSignals(...signals) {
   const valid = signals.filter((s) => !!s);
@@ -277,81 +288,92 @@ function combineSignals(...signals) {
   }
   return controller.signal;
 }
-function createBuiltinHttp(forgeInterceptors) {
-  const requestMgr = forgeInterceptors?.request ?? createInterceptorManager();
-  const responseMgr = forgeInterceptors?.response ?? createInterceptorManager();
-  async function request(config) {
-    const finalConfig = await runRequestInterceptors(requestMgr, config);
-    const signal = combineSignals(
-      finalConfig.signal,
-      finalConfig.timeout && finalConfig.timeout > 0 ? AbortSignal.timeout(finalConfig.timeout) : void 0
-    );
-    let url = finalConfig.url;
-    if (finalConfig.paramsSerializer && finalConfig.params) {
-      const qs = finalConfig.paramsSerializer(finalConfig.params);
-      if (qs) {
-        url = url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
-      }
+function isPassthroughBody(body) {
+  if (body === null) return false;
+  return typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams || typeof Blob !== "undefined" && body instanceof Blob || typeof ArrayBuffer !== "undefined" && (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) || typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
+}
+async function rawFetch(config) {
+  const signal = combineSignals(
+    config.signal,
+    config.timeout && config.timeout > 0 ? AbortSignal.timeout(config.timeout) : void 0
+  );
+  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 fetchInit = {
-      method: finalConfig.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;
-      } else {
-        fetchInit.body = JSON.stringify(finalConfig.body);
-        if (!headers.has("Content-Type")) {
-          headers.set("Content-Type", "application/json");
-        }
+  }
+  const headers = new Headers(config.headers);
+  const fetchInit = {
+    method: config.method,
+    headers
+  };
+  if (signal) fetchInit.signal = signal;
+  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(config.body);
+      if (!headers.has("Content-Type")) {
+        headers.set("Content-Type", "application/json");
       }
     }
-    let res;
+  }
+  let res;
+  try {
+    res = await fetch(url, fetchInit);
+  } catch (e) {
+    if (isAbortError(e)) throw e;
+    throw new NetworkError(
+      e instanceof Error ? e.message : String(e),
+      config.route,
+      config.level,
+      e
+    );
+  }
+  const text = await res.text();
+  let data = text;
+  const contentType = res.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
     try {
-      res = await fetch(url, fetchInit);
-    } catch (e) {
-      if (isAbortError(e)) throw e;
-      throw new NetworkError(
-        e instanceof Error ? e.message : String(e),
-        finalConfig.route,
-        finalConfig.level,
-        e
-      );
-    }
-    const text = await res.text();
-    let data = text;
-    const contentType = res.headers.get("content-type") ?? "";
-    if (contentType.includes("application/json")) {
-      try {
-        data = JSON.parse(text);
-      } catch {
-      }
+      data = JSON.parse(text);
+    } catch {
     }
-    const responseData = {
-      route: finalConfig.route,
-      level: finalConfig.level,
-      method: finalConfig.method,
-      url,
+  }
+  const responseData = {
+    route: config.route,
+    level: config.level,
+    method: config.method,
+    url,
+    status: res.status,
+    headers: res.headers,
+    data,
+    config
+  };
+  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,
-      headers: res.headers,
-      data,
-      config: finalConfig
-    };
-    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
-        }
-      )
-    );
+      url,
+      method: config.method
+    }
+  );
+}
+
+// src/adapters/builtin-http.ts
+function createBuiltinHttp(forgeInterceptors) {
+  const requestMgr = forgeInterceptors?.request ?? createInterceptorManager();
+  const responseMgr = forgeInterceptors?.response ?? createInterceptorManager();
+  const requestRaw = rawFetch;
+  async function request(config) {
+    const finalConfig = await runRequestInterceptors(requestMgr, config);
+    const source = Promise.resolve(finalConfig).then(requestRaw);
     return runResponseInterceptors(
       responseMgr,
       source
@@ -364,6 +386,7 @@ function createBuiltinHttp(forgeInterceptors) {
   const del = (url, config) => request({ ...config, url, method: "DELETE" });
   return {
     request,
+    requestRaw,
     interceptors: {
       request: requestMgr,
       response: responseMgr
@@ -575,7 +598,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 ?? [];
@@ -583,17 +605,12 @@ function createRouteForge(options) {
   let effectiveUrlPrefix = "";
   let summaryUnassigned;
   let backendHasUnassignedLevel = false;
-  const summaryPromise = (async () => {
+  const fetchSummary = async () => {
     try {
-      const summaryUrl = explicitEndpoint;
-      const resp = await fetch(summaryUrl, { method: "GET" });
-      if (!resp.ok) {
-        console.warn(
-          `[route-forge] summary endpoint ${summaryUrl} unreachable (HTTP ${resp.status}); falling back to explicit options`
-        );
-        return null;
-      }
-      return await resp.json();
+      const base = baseURL.endsWith("/") ? baseURL.slice(0, -1) : baseURL;
+      const ep = explicitEndpoint.startsWith("/") ? explicitEndpoint : `/${explicitEndpoint}`;
+      const data = await fetchMeta("__forge__.summary", `${base}${ep}`);
+      return data;
     } catch (e) {
       if (explicitLevels && explicitLevels.length > 0) {
         console.warn(
@@ -603,8 +620,11 @@ function createRouteForge(options) {
       }
       throw new UnknownLevelError("(auto-discovery)");
     }
-  })();
-  const autoDiscoveryPromise = summaryPromise.then((summary) => {
+  };
+  let summaryPromise;
+  const summaryWaiters = [];
+  const whenSummary = () => summaryPromise ?? new Promise((resolve) => summaryWaiters.push(resolve));
+  const autoDiscoveryPromise = whenSummary().then((summary) => {
     if (summary === null) {
       return;
     }
@@ -623,11 +643,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) {
@@ -663,8 +678,12 @@ function createRouteForge(options) {
   });
   let autoDiscoveryCompleted = false;
   let resolveReady;
-  const readyPromise = new Promise((resolve) => {
+  let rejectReady;
+  const readyPromise = new Promise((resolve, reject) => {
     resolveReady = resolve;
+    rejectReady = reject;
+  });
+  readyPromise.catch(() => {
   });
   const cacheTtl = cacheOpts.ttl ?? DEFAULT_CACHE_TTL;
   const cacheStorage = cacheOpts.storage ?? "memory";
@@ -695,13 +714,20 @@ function createRouteForge(options) {
     adapter,
     forgeInterceptors: { request: requestInterceptors, response: responseInterceptors }
   });
+  Promise.resolve().then(() => {
+    summaryPromise = fetchSummary();
+    for (const resolve of summaryWaiters) resolve(summaryPromise);
+  });
   let adapterResolved = false;
   let adapterObj = null;
   async function ensureAdapter() {
     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;
     }
@@ -727,33 +753,36 @@ function createRouteForge(options) {
     const ep = effectiveEndpoint.startsWith("/") ? effectiveEndpoint : `/${effectiveEndpoint}`;
     return `${base}${ep}/${encodeURIComponent(level)}`;
   }
-  async function fetchLevel(level) {
+  async function fetchMeta(routeTag, url, level = "") {
     const adp = await ensureAdapter();
     const config = {
-      route: `__forge__.load.${level}`,
+      route: routeTag,
       level,
       method: "GET",
-      url: buildUrl(level),
+      url,
       headers: { Accept: "application/json" },
       params: {},
       timeout,
       meta: {
-        name: `__forge__.load.${level}`,
-        uri: buildUrl(level),
+        name: routeTag,
+        uri: url,
         methods: ["GET"],
         parameters: [],
         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}`,
-        { level, status: resp?.status, url: buildUrl(level), method: "GET" }
+        `Failed to fetch "${routeTag}": HTTP ${resp?.status}`,
+        { level, status: resp?.status, url, method: "GET" }
       );
     }
-    const data = resp.data;
-    return data;
+    return resp.data;
+  }
+  async function fetchLevel(level) {
+    return await fetchMeta(`__forge__.load.${level}`, buildUrl(level), level);
   }
   async function loadOne(level) {
     if (autoDiscoveryError) throw autoDiscoveryError;
@@ -925,7 +954,7 @@ function createRouteForge(options) {
         },
         (err) => {
           if (err instanceof ForgeError) throw err;
-          if (isAbortError2(err, signal)) {
+          if (isAbortError(err, signal)) {
             throw new RequestAbortedError(meta.name, meta.level, err);
           }
           throw new NetworkError(
@@ -994,15 +1023,22 @@ function createRouteForge(options) {
   }
   void autoDiscoveryPromise.then(() => {
     autoDiscoveryCompleted = true;
-    options.onSummaryReady?.();
     if (effectiveEager.length > 0) {
-      return Promise.all(effectiveEager.map((lvl) => load(lvl))).catch((e) => {
-        console.warn(`[route-forge] eager load failed: ${e.message}`);
+      return Promise.allSettled(effectiveEager.map((lvl) => load(lvl))).then((results) => {
+        results.forEach((r, i) => {
+          if (r.status === "rejected") {
+            console.error(
+              `[route-forge] eager load failed for level "${effectiveEager[i]}":`,
+              r.reason
+            );
+          }
+        });
       });
     }
   }).then(() => {
     resolveReady(forgeInstance);
-  }).catch(() => {
+  }).catch((e) => {
+    rejectReady(e);
   });
   function ready(onFulfilled, onRejected) {
     if (onFulfilled) {
@@ -1013,7 +1049,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)
@@ -1147,14 +1184,6 @@ function resolveApiParams(input) {
   }
   return { pathParams, query, body, headers, timeout: perCallTimeout };
 }
-function isAbortError2(err, signal) {
-  if (signal?.aborted) return true;
-  const e = err;
-  if (!e) return false;
-  if (e.name === "AbortError") return true;
-  if (e.code === "ERR_CANCELED") return true;
-  return false;
-}
 
 exports.AdapterNotFoundError = AdapterNotFoundError;
 exports.ForgeError = ForgeError;