@route-forge/core 1.4.0 → 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()` 方法

package/dist/codegen.d.cts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { R as RouteMeta } from './types-BFlrOTrN.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-BFlrOTrN.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,82 +288,89 @@ function combineSignals(...signals) {
   }
   return controller.signal;
 }
-function createBuiltinHttp(forgeInterceptors) {
-  const requestMgr = forgeInterceptors?.request ?? createInterceptorManager();
-  const responseMgr = forgeInterceptors?.response ?? createInterceptorManager();
-  async function requestRaw(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}`;
-      }
+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(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");
-        }
+  }
+  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),
-        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 {
-        data = JSON.parse(text);
-      } catch {
-      }
+      data = JSON.parse(text);
+    } catch {
     }
-    const responseData = {
+  }
+  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,
-      method: config.method,
-      url,
       status: res.status,
-      headers: res.headers,
-      data,
-      config
-    };
-    if (res.status >= 200 && res.status < 300) {
-      return responseData;
+      url,
+      method: config.method
     }
-    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
-      }
-    );
-  }
+  );
+}
+
+// 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);
@@ -587,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(
@@ -607,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;
     }
@@ -662,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";
@@ -694,6 +714,10 @@ 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() {
@@ -729,19 +753,19 @@ 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
@@ -751,12 +775,14 @@ function createRouteForge(options) {
     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;
@@ -928,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(
@@ -997,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) {
@@ -1151,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;