@route-forge/core 2.1.0 → 2.2.1

package/dist/route-forge.global.js

@@ -64,12 +64,28 @@ var RouteForge = (function (exports) {
       }
       return entry;
     }
-    set(resp) {
+    /**
+     * 写入某层级缓存。后端 TTL 唯一来源为摘要 config.cache_ttl（全局），经参数 backendTtl 传入：
+     * - null      → 后端声明"不缓存"：不写 storage，仅留内存镜像供 route() 同步读（load 层"每次重取"由调用方跳过 get 短路实现）
+     * - 0         → 永久缓存（内存 + storage）
+     * - undefined  → 后端未下发该字段：用前端兜底 TTL（options.cache.ttl）
+     * - 正整数     → min(后端, 前端兜底)：后端为上限，前端只能缩短不能延长（SPEC §5.3）
+     */
+    set(resp, backendTtl) {
       let ttl;
-      if (resp.cache !== void 0 && resp.cache !== null) {
-        ttl = resp.cache > 0 ? Math.min(resp.cache, this.fallbackTtl) : resp.cache;
-      } else {
+      let persist;
+      if (backendTtl === null) {
+        ttl = 0;
+        persist = false;
+      } else if (backendTtl === void 0) {
         ttl = this.fallbackTtl;
+        persist = true;
+      } else if (backendTtl === 0) {
+        ttl = 0;
+        persist = true;
+      } else {
+        ttl = Math.min(backendTtl, this.fallbackTtl);
+        persist = true;
       }
       const entry = {
         level: resp.level,
@@ -78,7 +94,7 @@ var RouteForge = (function (exports) {
         cachedAt: Date.now()
       };
       this.memory.set(resp.level, entry);
-      if (this.storage === "memory" || !this.backend) {
+      if (!persist || this.storage === "memory" || !this.backend) {
         return;
       }
       try {
@@ -658,9 +674,11 @@ var RouteForge = (function (exports) {
   }
 
   // src/auto-discovery.ts
-  var UNASSIGNED_LEVEL = "unassigned";
   async function fetchSummary(inputs, baseURL, fetchMeta) {
     const { explicitLevels, explicitEndpoint } = inputs;
+    if (!explicitEndpoint) {
+      throw new UnknownLevelError("(auto-discovery)");
+    }
     try {
       const base = baseURL.endsWith("/") ? baseURL.slice(0, -1) : baseURL;
       const ep = explicitEndpoint.startsWith("/") ? explicitEndpoint : `/${explicitEndpoint}`;
@@ -676,35 +694,42 @@ var RouteForge = (function (exports) {
       throw new UnknownLevelError("(auto-discovery)");
     }
   }
+  function normalizeCacheTtl(raw) {
+    if (typeof raw === "number" && raw < 0) return null;
+    return raw;
+  }
   function applySummaryToState(summary, state, inputs) {
     const { explicitLevels, explicitEager, explicitEndpoint } = inputs;
-    const schemaVersion = summary.schemaVersion ?? 1;
-    if (schemaVersion > 1) {
+    const schemeVersion = summary.schemeVersion ?? 1;
+    if (schemeVersion > 1) {
       console.warn(
-        `[route-forge] backend schemaVersion=${schemaVersion} > client supported 1; some features may be unavailable`
+        `[route-forge] backend schemeVersion=${schemeVersion} > client supported 1; some features may be unavailable`
       );
     }
     if (summary.config.endpoint_prefix && summary.config.endpoint_prefix !== explicitEndpoint) {
-      console.warn(
-        `[route-forge] backend endpoint_prefix "${summary.config.endpoint_prefix}" overrides frontend endpoint "${explicitEndpoint}"`
-      );
+      if (explicitEndpoint) {
+        console.warn(
+          `[route-forge] backend endpoint_prefix "${summary.config.endpoint_prefix}" overrides frontend endpoint "${explicitEndpoint}"`
+        );
+      }
       state.endpoint = summary.config.endpoint_prefix;
     }
     if (summary.config.url_prefix) {
       state.urlPrefix = summary.config.url_prefix.endsWith("/") ? summary.config.url_prefix.slice(0, -1) : summary.config.url_prefix;
     }
+    state.cacheTtl = normalizeCacheTtl(summary.config.cache_ttl);
     const backendLevels = Object.keys(summary.levels);
-    state.backendHasUnassignedLevel = backendLevels.includes(UNASSIGNED_LEVEL);
-    if (Array.isArray(summary.unassigned) && summary.unassigned.length > 0 && !state.backendHasUnassignedLevel) {
-      state.summaryUnassigned = summary.unassigned;
-    }
-    const availableLevels = backendLevels.slice();
-    if (state.summaryUnassigned && !state.backendHasUnassignedLevel) {
-      availableLevels.push(UNASSIGNED_LEVEL);
+    const levelRoutes = {};
+    for (const lvl of backendLevels) {
+      const r = summary.levels[lvl]?.route;
+      if (r && typeof r.uri === "string") {
+        levelRoutes[lvl] = { uri: r.uri, methods: r.methods ?? ["GET", "HEAD"] };
+      }
     }
+    state.levelRoutes = levelRoutes;
     if (explicitLevels && explicitLevels.length > 0) {
-      const intersection = explicitLevels.filter((l) => availableLevels.includes(l));
-      const removed = explicitLevels.filter((l) => !availableLevels.includes(l));
+      const intersection = explicitLevels.filter((l) => backendLevels.includes(l));
+      const removed = explicitLevels.filter((l) => !backendLevels.includes(l));
       if (removed.length > 0) {
         console.warn(
           `[route-forge] levels not in backend summary and dropped: ${removed.join(", ")}`
@@ -712,7 +737,7 @@ var RouteForge = (function (exports) {
       }
       state.levels = intersection;
     } else {
-      state.levels = availableLevels;
+      state.levels = backendLevels.slice();
     }
     const backendEager = backendLevels.filter((lvl) => summary.levels[lvl]?.load === "eager");
     if (!explicitEager) {
@@ -723,6 +748,25 @@ var RouteForge = (function (exports) {
     }
   }
 
+  // src/embedded-summary.ts
+  var EMBEDDED_GLOBAL_KEY = "__ROUTE_FORGE__";
+  var memo;
+  function readEmbeddedSummary() {
+    if (memo !== void 0) return memo;
+    if (typeof window === "undefined") {
+      memo = null;
+      return null;
+    }
+    let raw;
+    try {
+      raw = window[EMBEDDED_GLOBAL_KEY];
+    } catch {
+      raw = void 0;
+    }
+    memo = raw !== null && typeof raw === "object" ? raw : null;
+    return memo;
+  }
+
   // src/route-store.ts
   var RouteStore = class {
     constructor(deps) {
@@ -742,33 +786,30 @@ var RouteForge = (function (exports) {
       }
     }
     async fetchLevel(level) {
-      return await this.fetchMeta(
-        `__forge__.load.${level}`,
-        buildUrl(level, { baseURL: this.baseURL, endpoint: this.state.endpoint }),
-        level
-      );
+      const uri = this.state.levelRoutes[level]?.uri;
+      const url = uri ? this.joinBaseAndPath(this.baseURL, uri) : buildUrl(level, { baseURL: this.baseURL, endpoint: this.state.endpoint });
+      return await this.fetchMeta(`route-forge.${level}`, url, level);
+    }
+    /** baseURL 与后端下发的绝对 path 拼接（规范化斜杠），与 buildUrl 的 base 处理一致 */
+    joinBaseAndPath(baseURL, path) {
+      const base = baseURL.endsWith("/") ? baseURL.slice(0, -1) : baseURL;
+      const p = path.startsWith("/") ? path : `/${path}`;
+      return `${base}${p}`;
     }
     async loadOne(level) {
       const autoDiscoveryError = this.getAutoDiscoveryError();
       if (autoDiscoveryError) throw autoDiscoveryError;
       this.assertLevelDeclared(level);
-      if (this.cache.get(level)) return;
+      const noCache = this.state.cacheTtl === null;
+      if (!noCache && this.cache.get(level)) return;
       const existing = this.inflight.get(level);
       if (existing) return existing;
       const gen = this.invalidationGens.get(level) ?? 0;
       const p = (async () => {
         try {
-          if (level === UNASSIGNED_LEVEL && !this.state.backendHasUnassignedLevel && this.state.summaryUnassigned) {
-            const routes = {};
-            for (const r of this.state.summaryUnassigned) {
-              routes[r.name] = { ...r, level: UNASSIGNED_LEVEL };
-            }
-            this.cache.set({ level: UNASSIGNED_LEVEL, routes, cache: null });
-            return;
-          }
           const resp = await this.fetchLevel(level);
           if ((this.invalidationGens.get(level) ?? 0) === gen) {
-            this.cache.set(resp);
+            this.cache.set(resp, this.state.cacheTtl);
           }
         } finally {
           this.inflight.delete(level);
@@ -1051,8 +1092,13 @@ var RouteForge = (function (exports) {
   // src/forge.ts
   var DEFAULT_TIMEOUT = 3e4;
   var DEFAULT_CACHE_TTL = 3600;
-  function createRouteForge(options) {
-    if (!options.endpoint) throw new TypeError("options.endpoint is required");
+  function createRouteForge(options = {}) {
+    const bootstrapSummary = readEmbeddedSummary() ?? options.summary ?? null;
+    if (!bootstrapSummary && !options.endpoint) {
+      throw new TypeError(
+        "createRouteForge: \u9700\u8981 options.endpoint\uFF0C\u6216 options.summary\uFF0C\u6216\u9875\u9762\u5185\u5D4C window.__ROUTE_FORGE__"
+      );
+    }
     const {
       adapter = "auto",
       timeout = DEFAULT_TIMEOUT,
@@ -1067,10 +1113,10 @@ var RouteForge = (function (exports) {
     const discoveryState = {
       levels: explicitLevels ?? [],
       eager: explicitEager ?? [],
-      endpoint: explicitEndpoint,
+      endpoint: explicitEndpoint ?? bootstrapSummary?.config?.endpoint_prefix ?? "",
       urlPrefix: "",
-      summaryUnassigned: void 0,
-      backendHasUnassignedLevel: false
+      cacheTtl: void 0,
+      levelRoutes: {}
     };
     const discoveryInputs = { explicitLevels, explicitEager, explicitEndpoint };
     let autoDiscoveryCompleted = false;
@@ -1162,12 +1208,19 @@ var RouteForge = (function (exports) {
       }
       return resp.data;
     }
-    const autoDiscoveryPromise = fetchSummary(discoveryInputs, baseURL, fetchMeta).then((summary) => {
-      if (summary === null) {
-        return;
-      }
-      applySummaryToState(summary, discoveryState, discoveryInputs);
-    });
+    let autoDiscoveryPromise;
+    if (bootstrapSummary) {
+      applySummaryToState(bootstrapSummary, discoveryState, discoveryInputs);
+      autoDiscoveryCompleted = true;
+      autoDiscoveryPromise = Promise.resolve();
+    } else {
+      autoDiscoveryPromise = fetchSummary(discoveryInputs, baseURL, fetchMeta).then((summary) => {
+        if (summary === null) {
+          return;
+        }
+        applySummaryToState(summary, discoveryState, discoveryInputs);
+      });
+    }
     let autoDiscoveryError = null;
     autoDiscoveryPromise.catch((e) => {
       autoDiscoveryError = e;