@route-forge/core 2.1.0 → 2.2.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { a as RouteForgeOptions, b as RouteForge, I as InterceptorManager, c as InterceptorHandler, C as CacheStorage, R as RouteMeta, L as LevelRoutesResponse } from './types-C51rXaiY.cjs';
-export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher, e as ForgeApiParams, f as ForgeApiResponse, g as ForgeRequest, h as ForgeRouteMap, i as ForgeRouteName, j as LoadingChangeCallback, k as LoadingChangeEvent, l as LoadingTracker, m as RequestConfig, n as ResponseData, S as SummaryResponse, U as UseForgeApiBoundCall, o as UseForgeApiBoundReturn, p as UseForgeApiCall, q as UseForgeApiReturn } from './types-C51rXaiY.cjs';
+import { a as RouteForgeOptions, b as RouteForge, I as InterceptorManager, c as InterceptorHandler, C as CacheStorage, R as RouteMeta, L as LevelRoutesResponse } from './types-CDKE8rw-.cjs';
+export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher, e as ForgeApiParams, f as ForgeApiResponse, g as ForgeRequest, h as ForgeRouteMap, i as ForgeRouteName, j as LoadingChangeCallback, k as LoadingChangeEvent, l as LoadingTracker, m as RequestConfig, n as ResponseData, S as SummaryResponse, U as UseForgeApiBoundCall, o as UseForgeApiBoundReturn, p as UseForgeApiCall, q as UseForgeApiReturn } from './types-CDKE8rw-.cjs';
 
 /**
  * Route Forge 主入口：createRouteForge
@@ -13,7 +13,7 @@ export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher,
  *   - Adapter auto 检测 / builtin / axios / 自定义 Fetcher（§4.3）
  */
 
-declare function createRouteForge(options: RouteForgeOptions): RouteForge;
+declare function createRouteForge(options?: RouteForgeOptions): RouteForge;
 
 /**
  * 拦截器管理器实现
@@ -57,7 +57,8 @@ declare function createInterceptorManager<TIn, TOut = TIn>(): InterceptorManager
  *
  * 规则：
  * - 每层级独立条目，互不污染（cache key = `route-forge:${level}`）
- * - TTL 优先用后端响应里的 cache 字段，本地 cache.ttl 仅作兜底
+ * - 后端 TTL 唯一来源为摘要 config.cache_ttl（全局，经 set 的 backendTtl 参数传入）：
+ *   null=不缓存（只留内存镜像、不落存储）、0=永久、正整数=min(后端, 前端 cache.ttl 兜底)
  * - storage: 'memory' | 'sessionStorage' | 'localStorage'
  * - storage 模式下维护内存镜像：首次读盘解析后驻留内存，后续 get 直接命中
  *   （读盘 + JSON.parse 整层路由表是同步阻塞操作，热路径重复执行代价高）；
@@ -85,7 +86,14 @@ declare class RouteCache {
     private key;
     get(level: string): CacheEntry | undefined;
     private getFromMemory;
-    set(resp: LevelRoutesResponse): void;
+    /**
+     * 写入某层级缓存。后端 TTL 唯一来源为摘要 config.cache_ttl（全局），经参数 backendTtl 传入：
+     * - null      → 后端声明"不缓存"：不写 storage，仅留内存镜像供 route() 同步读（load 层"每次重取"由调用方跳过 get 短路实现）
+     * - 0         → 永久缓存（内存 + storage）
+     * - undefined  → 后端未下发该字段：用前端兜底 TTL（options.cache.ttl）
+     * - 正整数     → min(后端, 前端兜底)：后端为上限，前端只能缩短不能延长（SPEC §5.3）
+     */
+    set(resp: LevelRoutesResponse, backendTtl: number | null | undefined): void;
     del(level: string): void;
     clear(): void;
     private isExpired;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as RouteForgeOptions, b as RouteForge, I as InterceptorManager, c as InterceptorHandler, C as CacheStorage, R as RouteMeta, L as LevelRoutesResponse } from './types-C51rXaiY.js';
-export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher, e as ForgeApiParams, f as ForgeApiResponse, g as ForgeRequest, h as ForgeRouteMap, i as ForgeRouteName, j as LoadingChangeCallback, k as LoadingChangeEvent, l as LoadingTracker, m as RequestConfig, n as ResponseData, S as SummaryResponse, U as UseForgeApiBoundCall, o as UseForgeApiBoundReturn, p as UseForgeApiCall, q as UseForgeApiReturn } from './types-C51rXaiY.js';
+import { a as RouteForgeOptions, b as RouteForge, I as InterceptorManager, c as InterceptorHandler, C as CacheStorage, R as RouteMeta, L as LevelRoutesResponse } from './types-CDKE8rw-.js';
+export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher, e as ForgeApiParams, f as ForgeApiResponse, g as ForgeRequest, h as ForgeRouteMap, i as ForgeRouteName, j as LoadingChangeCallback, k as LoadingChangeEvent, l as LoadingTracker, m as RequestConfig, n as ResponseData, S as SummaryResponse, U as UseForgeApiBoundCall, o as UseForgeApiBoundReturn, p as UseForgeApiCall, q as UseForgeApiReturn } from './types-CDKE8rw-.js';
 
 /**
  * Route Forge 主入口：createRouteForge
@@ -13,7 +13,7 @@ export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher,
  *   - Adapter auto 检测 / builtin / axios / 自定义 Fetcher（§4.3）
  */
 
-declare function createRouteForge(options: RouteForgeOptions): RouteForge;
+declare function createRouteForge(options?: RouteForgeOptions): RouteForge;
 
 /**
  * 拦截器管理器实现
@@ -57,7 +57,8 @@ declare function createInterceptorManager<TIn, TOut = TIn>(): InterceptorManager
  *
  * 规则：
  * - 每层级独立条目，互不污染（cache key = `route-forge:${level}`）
- * - TTL 优先用后端响应里的 cache 字段，本地 cache.ttl 仅作兜底
+ * - 后端 TTL 唯一来源为摘要 config.cache_ttl（全局，经 set 的 backendTtl 参数传入）：
+ *   null=不缓存（只留内存镜像、不落存储）、0=永久、正整数=min(后端, 前端 cache.ttl 兜底)
  * - storage: 'memory' | 'sessionStorage' | 'localStorage'
  * - storage 模式下维护内存镜像：首次读盘解析后驻留内存，后续 get 直接命中
  *   （读盘 + JSON.parse 整层路由表是同步阻塞操作，热路径重复执行代价高）；
@@ -85,7 +86,14 @@ declare class RouteCache {
     private key;
     get(level: string): CacheEntry | undefined;
     private getFromMemory;
-    set(resp: LevelRoutesResponse): void;
+    /**
+     * 写入某层级缓存。后端 TTL 唯一来源为摘要 config.cache_ttl（全局），经参数 backendTtl 传入：
+     * - null      → 后端声明"不缓存"：不写 storage，仅留内存镜像供 route() 同步读（load 层"每次重取"由调用方跳过 get 短路实现）
+     * - 0         → 永久缓存（内存 + storage）
+     * - undefined  → 后端未下发该字段：用前端兜底 TTL（options.cache.ttl）
+     * - 正整数     → min(后端, 前端兜底)：后端为上限，前端只能缩短不能延长（SPEC §5.3）
+     */
+    set(resp: LevelRoutesResponse, backendTtl: number | null | undefined): void;
     del(level: string): void;
     clear(): void;
     private isExpired;

package/dist/index.js

@@ -61,12 +61,28 @@ var RouteCache = class {
     }
     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,
@@ -75,7 +91,7 @@ var RouteCache = class {
       cachedAt: Date.now()
     };
     this.memory.set(resp.level, entry);
-    if (this.storage === "memory" || !this.backend) {
+    if (!persist || this.storage === "memory" || !this.backend) {
       return;
     }
     try {
@@ -655,9 +671,11 @@ function resolveApiParams(input) {
 }
 
 // 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}`;
@@ -673,35 +691,42 @@ async function fetchSummary(inputs, baseURL, fetchMeta) {
     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(", ")}`
@@ -709,7 +734,7 @@ function applySummaryToState(summary, state, inputs) {
     }
     state.levels = intersection;
   } else {
-    state.levels = availableLevels;
+    state.levels = backendLevels.slice();
   }
   const backendEager = backendLevels.filter((lvl) => summary.levels[lvl]?.load === "eager");
   if (!explicitEager) {
@@ -720,6 +745,25 @@ function applySummaryToState(summary, state, inputs) {
   }
 }
 
+// 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) {
@@ -739,33 +783,30 @@ var RouteStore = class {
     }
   }
   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);
@@ -1048,8 +1089,13 @@ function createBoundForgeFactory(deps) {
 // 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,
@@ -1064,10 +1110,10 @@ function createRouteForge(options) {
   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;
@@ -1159,12 +1205,19 @@ function createRouteForge(options) {
     }
     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;