@route-forge/core 2.0.0 → 2.2.0

package/dist/index.cjs

@@ -63,12 +63,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,
@@ -77,7 +93,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 {
@@ -490,39 +506,6 @@ async function resolveAdapter(opts) {
   return createBuiltinHttp(opts.forgeInterceptors);
 }
 
-// src/resolveRouteName.ts
-async function resolveRouteName(forge, level, prefix, suffix, separator = ".") {
-  if (!suffix) return prefix;
-  const joined = `${prefix}${separator}${suffix}`;
-  if (!suffix.startsWith(`${prefix}${separator}`)) return joined;
-  await forge.load(level);
-  if (forge.hasRoute(level, joined)) return joined;
-  if (forge.hasRoute(level, suffix)) return suffix;
-  throw new UnknownRouteError(joined, level);
-}
-function resolveRouteNameSync(forge, level, prefix, suffix, separator = ".") {
-  if (!suffix) return prefix;
-  const joined = `${prefix}${separator}${suffix}`;
-  if (!suffix.startsWith(`${prefix}${separator}`)) return joined;
-  if (forge.hasRoute(level, joined)) return joined;
-  if (forge.hasRoute(level, suffix)) return suffix;
-  throw new UnknownRouteError(joined, level);
-}
-
-// src/defineImmutableProps.ts
-function defineImmutableProps(target, props) {
-  for (const key of Object.keys(props)) {
-    const val = props[key];
-    Object.defineProperty(target, key, {
-      value: val !== null && typeof val === "object" ? Object.freeze(val) : val,
-      writable: false,
-      enumerable: false,
-      configurable: false
-    });
-  }
-  return target;
-}
-
 // src/loading.ts
 var LoadingTracker = class {
   constructor() {
@@ -582,328 +565,333 @@ var LoadingTracker = class {
   }
 };
 
-// src/forge.ts
-var DEFAULT_TIMEOUT = 3e4;
-var DEFAULT_CACHE_TTL = 3600;
-var UNASSIGNED_LEVEL = "unassigned";
-function createRouteForge(options) {
-  if (!options.endpoint) throw new TypeError("options.endpoint is required");
-  const {
-    adapter = "auto",
-    timeout = DEFAULT_TIMEOUT,
-    baseURL = "",
-    interceptors: declarativeInterceptors,
-    cache: cacheOpts = {}
-  } = options;
-  const loadingTracker = new LoadingTracker();
-  const explicitLevels = options.levels;
-  const explicitEager = options.eager;
-  const explicitEndpoint = options.endpoint;
-  let effectiveLevels = explicitLevels ?? [];
-  let effectiveEager = explicitEager ?? [];
-  let effectiveEndpoint = explicitEndpoint;
-  let effectiveUrlPrefix = "";
-  let summaryUnassigned;
-  let backendHasUnassignedLevel = false;
-  const fetchSummary = async () => {
-    try {
-      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(
-          `[route-forge] summary endpoint unreachable: ${e.message}; using explicit levels`
-        );
-        return null;
-      }
-      throw new UnknownLevelError("(auto-discovery)");
-    }
-  };
-  let summaryPromise;
-  const summaryWaiters = [];
-  const whenSummary = () => summaryPromise ?? new Promise((resolve) => summaryWaiters.push(resolve));
-  const autoDiscoveryPromise = whenSummary().then((summary) => {
-    if (summary === null) {
-      return;
-    }
-    const schemaVersion = summary.schemaVersion ?? 1;
-    if (schemaVersion > 1) {
-      console.warn(
-        `[route-forge] backend schemaVersion=${schemaVersion} > 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}"`
-      );
-      effectiveEndpoint = summary.config.endpoint_prefix;
-    }
-    if (summary.config.url_prefix) {
-      effectiveUrlPrefix = summary.config.url_prefix.endsWith("/") ? summary.config.url_prefix.slice(0, -1) : summary.config.url_prefix;
-    }
-    const backendLevels = Object.keys(summary.levels);
-    backendHasUnassignedLevel = backendLevels.includes(UNASSIGNED_LEVEL);
-    if (Array.isArray(summary.unassigned) && summary.unassigned.length > 0 && !backendHasUnassignedLevel) {
-      summaryUnassigned = summary.unassigned;
-    }
-    const availableLevels = backendLevels.slice();
-    if (summaryUnassigned && !backendHasUnassignedLevel) {
-      availableLevels.push(UNASSIGNED_LEVEL);
+// src/url-builder.ts
+function buildUrl(level, ctx) {
+  const base = ctx.baseURL.endsWith("/") ? ctx.baseURL.slice(0, -1) : ctx.baseURL;
+  const ep = ctx.endpoint.startsWith("/") ? ctx.endpoint : `/${ctx.endpoint}`;
+  return `${base}${ep}/${encodeURIComponent(level)}`;
+}
+function buildRequestUrl(meta, params, ctx) {
+  const defaults = meta.parameter_defaults ?? {};
+  const missingRequired = [];
+  const values = {};
+  for (const p of meta.parameters) {
+    let v = params[p];
+    if ((v === void 0 || v === null) && p in defaults) {
+      v = defaults[p];
     }
-    if (explicitLevels && explicitLevels.length > 0) {
-      const intersection = explicitLevels.filter((l) => availableLevels.includes(l));
-      const removed = explicitLevels.filter((l) => !availableLevels.includes(l));
-      if (removed.length > 0) {
-        console.warn(
-          `[route-forge] levels not in backend summary and dropped: ${removed.join(", ")}`
-        );
+    if (v === void 0 || v === null) {
+      if (!meta.uri.includes(`{${p}?}`)) {
+        missingRequired.push(p);
       }
-      effectiveLevels = intersection;
     } else {
-      effectiveLevels = availableLevels;
+      values[p] = v;
     }
-    const backendEager = backendLevels.filter((lvl) => summary.levels[lvl]?.load === "eager");
-    if (!explicitEager) {
-      effectiveEager = backendEager;
-    } else {
-      const union = /* @__PURE__ */ new Set([...backendEager, ...explicitEager]);
-      effectiveEager = [...union];
+  }
+  if (missingRequired.length > 0) {
+    throw new MissingRouteParamError(meta.name, missingRequired);
+  }
+  let uri = meta.uri.replace(/\{([^{}]+)\}/g, (match, raw) => {
+    const optional = raw.endsWith("?");
+    const name = optional ? raw.slice(0, -1) : raw;
+    if (values[name] !== void 0) {
+      const val = values[name];
+      if (typeof val === "object") {
+        throw new ForgeError(
+          `Path parameter "${name}" must be a primitive value (string, number, boolean), got ${typeof val}`,
+          { code: "RF_FE_003", route: meta.name, context: { param: name, value: val } }
+        );
+      }
+      return encodeURIComponent(String(val));
     }
+    return optional ? "" : match;
   });
-  let autoDiscoveryError = null;
-  autoDiscoveryPromise.catch((e) => {
-    autoDiscoveryError = e;
-  });
-  let autoDiscoveryCompleted = false;
-  let resolveReady;
-  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";
-  const cache = new RouteCache({ storage: cacheStorage, ttl: cacheTtl });
-  const requestInterceptors = new InterceptorManagerImpl();
-  const responseInterceptors = new InterceptorManagerImpl();
-  if (declarativeInterceptors?.request) {
-    for (const entry of declarativeInterceptors.request) {
-      if (typeof entry === "function") {
-        requestInterceptors.use(entry);
-      } else {
-        const [onFulfilled, onRejected] = entry;
-        requestInterceptors.use(onFulfilled, onRejected);
-      }
+  uri = uri.replace(/\/+/g, "/").replace(/\/$/, "");
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(ctx.urlPrefix)) {
+    const prefix2 = ctx.urlPrefix.endsWith("/") ? ctx.urlPrefix.slice(0, -1) : ctx.urlPrefix;
+    return uri.startsWith("/") ? `${prefix2}${uri}` : `${prefix2}/${uri}`;
+  }
+  const base = ctx.baseURL.endsWith("/") ? ctx.baseURL.slice(0, -1) : ctx.baseURL;
+  const prefix = ctx.urlPrefix;
+  return uri.startsWith("/") ? `${base}${prefix}${uri}` : `${base}${prefix}/${uri}`;
+}
+function pickMethod(meta) {
+  const m = meta.methods.find((x) => x.toUpperCase() !== "HEAD");
+  return (m ?? meta.methods[0] ?? "GET").toUpperCase();
+}
+function appendQuery(url, query) {
+  if (!query) return url;
+  const usp = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v === void 0 || v === null) continue;
+    usp.append(k, String(v));
+  }
+  const qs = usp.toString();
+  if (!qs) return url;
+  return url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
+}
+function resolveApiParams(input) {
+  const {
+    params: explicitParams,
+    query: rawQuery,
+    body: rawBody,
+    headers: rawHeaders,
+    timeout: perCallTimeout,
+    ...flatRest
+  } = input;
+  const pathParams = explicitParams ? { ...explicitParams } : {};
+  for (const [k, v] of Object.entries(flatRest)) {
+    if (!(k in pathParams)) {
+      pathParams[k] = v;
     }
   }
-  if (declarativeInterceptors?.response) {
-    for (const entry of declarativeInterceptors.response) {
-      if (typeof entry === "function") {
-        responseInterceptors.use(entry);
-      } else {
-        const [onFulfilled, onRejected] = entry;
-        responseInterceptors.use(onFulfilled, onRejected);
-      }
+  let query;
+  let body;
+  let headers;
+  if (rawQuery !== void 0) {
+    if (typeof rawQuery === "object" && rawQuery !== null) {
+      query = rawQuery;
+    } else if (!("query" in pathParams)) {
+      pathParams.query = rawQuery;
     }
   }
-  const adapterPromise = resolveAdapter({
-    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",
-          forgeInterceptors: { request: requestInterceptors, response: responseInterceptors }
-        });
-      });
-      adapterResolved = true;
+  if (rawBody !== void 0) {
+    if (typeof rawBody !== "string" && typeof rawBody !== "number") {
+      body = rawBody;
+    } else if (!("body" in pathParams)) {
+      pathParams.body = rawBody;
     }
-    return adapterObj;
   }
-  const inflight = /* @__PURE__ */ new Map();
-  const invalidationGens = /* @__PURE__ */ new Map();
-  function assertLevelDeclared(level) {
-    if (!effectiveLevels.includes(level)) {
-      throw new UnknownLevelError(level);
+  if (rawHeaders !== void 0) {
+    if (typeof rawHeaders === "object" && rawHeaders !== null) {
+      headers = rawHeaders;
+    } else if (!("headers" in pathParams)) {
+      pathParams.headers = rawHeaders;
     }
   }
-  function assertDiscoveryReady() {
-    if (!autoDiscoveryCompleted && !explicitLevels?.length) {
-      throw new ForgeError(
-        "Route data not available. Auto-discovery has not completed. Use forge.ready() or forge.use(level) first.",
-        { code: "RF_FE_010" }
+  return { pathParams, query, body, headers, timeout: perCallTimeout };
+}
+
+// src/auto-discovery.ts
+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}`;
+    const data = await fetchMeta("__forge__.summary", `${base}${ep}`);
+    return data;
+  } catch (e) {
+    if (explicitLevels && explicitLevels.length > 0) {
+      console.warn(
+        `[route-forge] summary endpoint unreachable: ${e.message}; using explicit levels`
       );
+      return null;
     }
+    throw new UnknownLevelError("(auto-discovery)");
   }
-  function buildUrl(level) {
-    const base = baseURL.endsWith("/") ? baseURL.slice(0, -1) : baseURL;
-    const ep = effectiveEndpoint.startsWith("/") ? effectiveEndpoint : `/${effectiveEndpoint}`;
-    return `${base}${ep}/${encodeURIComponent(level)}`;
+}
+function normalizeCacheTtl(raw) {
+  if (typeof raw === "number" && raw < 0) return null;
+  return raw;
+}
+function applySummaryToState(summary, state, inputs) {
+  const { explicitLevels, explicitEager, explicitEndpoint } = inputs;
+  const schemeVersion = summary.schemeVersion ?? 1;
+  if (schemeVersion > 1) {
+    console.warn(
+      `[route-forge] backend schemeVersion=${schemeVersion} > client supported 1; some features may be unavailable`
+    );
   }
-  async function fetchMeta(routeTag, url, level = "") {
-    const adp = await ensureAdapter();
-    const config = {
-      route: routeTag,
-      level,
-      method: "GET",
-      url,
-      headers: { Accept: "application/json" },
-      params: {},
-      timeout,
-      meta: {
-        name: routeTag,
-        uri: url,
-        methods: ["GET"],
-        parameters: [],
-        level
-      }
-    };
-    const doRawRequest = adp.requestRaw ?? adp.request;
-    const resp = await doRawRequest(config);
-    if (!resp || resp.status < 200 || resp.status >= 300) {
-      throw new HTTPError(
-        `Failed to fetch "${routeTag}": HTTP ${resp?.status}`,
-        { level, status: resp?.status, url, method: "GET" }
+  if (summary.config.endpoint_prefix && summary.config.endpoint_prefix !== explicitEndpoint) {
+    if (explicitEndpoint) {
+      console.warn(
+        `[route-forge] backend endpoint_prefix "${summary.config.endpoint_prefix}" overrides frontend endpoint "${explicitEndpoint}"`
       );
     }
-    return resp.data;
+    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);
+  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) => 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(", ")}`
+      );
+    }
+    state.levels = intersection;
+  } else {
+    state.levels = backendLevels.slice();
+  }
+  const backendEager = backendLevels.filter((lvl) => summary.levels[lvl]?.load === "eager");
+  if (!explicitEager) {
+    state.eager = backendEager;
+  } else {
+    const union = /* @__PURE__ */ new Set([...backendEager, ...explicitEager]);
+    state.eager = [...union];
+  }
+}
+
+// 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) {
+    this.inflight = /* @__PURE__ */ new Map();
+    /** 每个层级的失效代数，用于检测 loadOne 期间是否发生了 invalidate */
+    this.invalidationGens = /* @__PURE__ */ new Map();
+    this.cache = deps.cache;
+    this.state = deps.state;
+    this.baseURL = deps.baseURL;
+    this.fetchMeta = deps.fetchMeta;
+    this.autoDiscoveryPromise = deps.autoDiscoveryPromise;
+    this.getAutoDiscoveryError = deps.getAutoDiscoveryError;
+  }
+  assertLevelDeclared(level) {
+    if (!this.state.levels.includes(level)) {
+      throw new UnknownLevelError(level);
+    }
   }
-  async function fetchLevel(level) {
-    return await fetchMeta(`__forge__.load.${level}`, buildUrl(level), level);
+  async fetchLevel(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 function loadOne(level) {
+  async loadOne(level) {
+    const autoDiscoveryError = this.getAutoDiscoveryError();
     if (autoDiscoveryError) throw autoDiscoveryError;
-    assertLevelDeclared(level);
-    if (cache.get(level)) return;
-    const existing = inflight.get(level);
+    this.assertLevelDeclared(level);
+    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 = invalidationGens.get(level) ?? 0;
+    const gen = this.invalidationGens.get(level) ?? 0;
     const p = (async () => {
       try {
-        if (level === UNASSIGNED_LEVEL && !backendHasUnassignedLevel && summaryUnassigned) {
-          const routes = {};
-          for (const r of summaryUnassigned) {
-            routes[r.name] = { ...r, level: UNASSIGNED_LEVEL };
-          }
-          cache.set({ level: UNASSIGNED_LEVEL, routes, cache: null });
-          return;
-        }
-        const resp = await fetchLevel(level);
-        if ((invalidationGens.get(level) ?? 0) === gen) {
-          cache.set(resp);
+        const resp = await this.fetchLevel(level);
+        if ((this.invalidationGens.get(level) ?? 0) === gen) {
+          this.cache.set(resp, this.state.cacheTtl);
         }
       } finally {
-        inflight.delete(level);
+        this.inflight.delete(level);
       }
     })();
-    inflight.set(level, p);
+    this.inflight.set(level, p);
     return p;
   }
-  async function load(level) {
-    await autoDiscoveryPromise;
+  async load(level) {
+    await this.autoDiscoveryPromise;
     const list = Array.isArray(level) ? level : [level];
-    await Promise.all(list.map(loadOne));
+    await Promise.all(list.map((l) => this.loadOne(l)));
   }
-  function route(level, name, params) {
-    assertDiscoveryReady();
-    const meta = findRouteMeta(level, name);
-    if (!meta) {
-      throw new UnknownRouteError(name, level);
-    }
-    return buildRequestUrl(meta, params ?? {});
-  }
-  function buildRequestUrl(meta, params) {
-    const defaults = meta.parameter_defaults ?? {};
-    const missingRequired = [];
-    const values = {};
-    for (const p of meta.parameters) {
-      let v = params[p];
-      if ((v === void 0 || v === null) && p in defaults) {
-        v = defaults[p];
+  invalidate(level) {
+    if (level === void 0) {
+      this.cache.clear();
+      this.inflight.clear();
+      for (const lvl of this.state.levels) {
+        this.invalidationGens.set(lvl, (this.invalidationGens.get(lvl) ?? 0) + 1);
       }
-      if (v === void 0 || v === null) {
-        if (!meta.uri.includes(`{${p}?}`)) {
-          missingRequired.push(p);
-        }
-      } else {
-        values[p] = v;
+    } else if (Array.isArray(level)) {
+      for (const lvl of level) {
+        this.cache.del(lvl);
+        this.inflight.delete(lvl);
+        this.invalidationGens.set(lvl, (this.invalidationGens.get(lvl) ?? 0) + 1);
       }
+    } else {
+      this.cache.del(level);
+      this.inflight.delete(level);
+      this.invalidationGens.set(level, (this.invalidationGens.get(level) ?? 0) + 1);
     }
-    if (missingRequired.length > 0) {
-      throw new MissingRouteParamError(meta.name, missingRequired);
-    }
-    let uri = meta.uri.replace(/\{([^{}]+)\}/g, (match, raw) => {
-      const optional = raw.endsWith("?");
-      const name = optional ? raw.slice(0, -1) : raw;
-      if (values[name] !== void 0) {
-        const val = values[name];
-        if (typeof val === "object") {
-          throw new ForgeError(
-            `Path parameter "${name}" must be a primitive value (string, number, boolean), got ${typeof val}`,
-            { code: "RF_FE_003", route: meta.name, context: { param: name, value: val } }
-          );
-        }
-        return encodeURIComponent(String(val));
-      }
-      return optional ? "" : match;
-    });
-    uri = uri.replace(/\/+/g, "/").replace(/\/$/, "");
-    if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(effectiveUrlPrefix)) {
-      const prefix2 = effectiveUrlPrefix.endsWith("/") ? effectiveUrlPrefix.slice(0, -1) : effectiveUrlPrefix;
-      return uri.startsWith("/") ? `${prefix2}${uri}` : `${prefix2}/${uri}`;
-    }
-    const base = baseURL.endsWith("/") ? baseURL.slice(0, -1) : baseURL;
-    const prefix = effectiveUrlPrefix;
-    return uri.startsWith("/") ? `${base}${prefix}${uri}` : `${base}${prefix}/${uri}`;
   }
-  function findRouteMeta(level, name) {
-    const entry = cache.get(level);
+  isLoaded(level) {
+    if (level) return this.cache.get(level) !== void 0;
+    return this.state.levels.length > 0 && this.state.levels.every((lvl) => this.cache.get(lvl) !== void 0);
+  }
+  findRouteMeta(level, name) {
+    const entry = this.cache.get(level);
     const meta = entry?.routes[name];
     if (meta) {
       return { ...meta, level };
     }
     return void 0;
   }
-  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);
+  getRoutes(level) {
+    if (level !== void 0) {
+      const entry = this.cache.get(level);
+      const routes = entry?.routes ?? {};
+      const result2 = {};
+      for (const [k, v] of Object.entries(routes)) {
+        result2[k] = JSON.parse(JSON.stringify(v));
       }
-      return doApiCall(meta, params, ctrl.signal);
-    })();
-    const request = work;
-    request.abort = () => {
-      if (ctrl) {
-        ctrl.abort();
-      } else {
-        abortedBeforeInit = true;
+      return result2;
+    }
+    const result = {};
+    for (const lvl of this.state.levels) {
+      const entry = this.cache.get(lvl);
+      if (entry) {
+        const levelRoutes = {};
+        for (const [k, v] of Object.entries(entry.routes)) {
+          levelRoutes[k] = JSON.parse(JSON.stringify(v));
+        }
+        result[lvl] = levelRoutes;
       }
-    };
-    return request;
+    }
+    return result;
   }
+};
+
+// src/http-runner.ts
+function createHttpRunner(deps) {
+  const {
+    ensureAdapter,
+    requestInterceptors,
+    responseInterceptors,
+    load,
+    findRouteMeta,
+    baseURL,
+    state,
+    timeout,
+    loadingTracker,
+    autoDiscoveryPromise
+  } = deps;
   async function doApiCall(meta, params, signal) {
     const {
       pathParams,
@@ -916,7 +904,10 @@ function createRouteForge(options) {
       throw new RequestAbortedError(meta.name, meta.level, signal.reason);
     }
     const method = pickMethod(meta);
-    const urlWithQuery = appendQuery(buildRequestUrl(meta, pathParams), query);
+    const urlWithQuery = appendQuery(
+      buildRequestUrl(meta, pathParams, { baseURL, urlPrefix: state.urlPrefix }),
+      query
+    );
     const config = {
       route: meta.name,
       level: meta.level ?? "",
@@ -971,88 +962,77 @@ function createRouteForge(options) {
       loadingTracker.stop();
     }
   }
-  function invalidate(level) {
-    if (level === void 0) {
-      cache.clear();
-      inflight.clear();
-      for (const lvl of effectiveLevels) {
-        invalidationGens.set(lvl, (invalidationGens.get(lvl) ?? 0) + 1);
-      }
-    } else if (Array.isArray(level)) {
-      for (const lvl of level) {
-        cache.del(lvl);
-        inflight.delete(lvl);
-        invalidationGens.set(lvl, (invalidationGens.get(lvl) ?? 0) + 1);
+  return function api(level, name, params = {}) {
+    let ctrl;
+    let abortedBeforeInit = false;
+    let abortReason;
+    const work = (async () => {
+      ctrl = new AbortController();
+      if (abortedBeforeInit) {
+        ctrl.abort(abortReason);
       }
-    } else {
-      cache.del(level);
-      inflight.delete(level);
-      invalidationGens.set(level, (invalidationGens.get(level) ?? 0) + 1);
-    }
-  }
-  function isLoaded(level) {
-    if (level) return cache.get(level) !== void 0;
-    return effectiveLevels.length > 0 && effectiveLevels.every((lvl) => cache.get(lvl) !== void 0);
-  }
-  function hasRoute(level, name) {
-    assertDiscoveryReady();
-    return findRouteMeta(level, name) !== void 0;
-  }
-  function getRoutes(level) {
-    if (level !== void 0) {
-      const entry = cache.get(level);
-      const routes = entry?.routes ?? {};
-      const result2 = {};
-      for (const [k, v] of Object.entries(routes)) {
-        result2[k] = JSON.parse(JSON.stringify(v));
+      await autoDiscoveryPromise;
+      await load(level);
+      const meta = findRouteMeta(level, name);
+      if (!meta) {
+        throw new UnknownRouteError(name, level);
       }
-      return result2;
-    }
-    const result = {};
-    for (const lvl of effectiveLevels) {
-      const entry = cache.get(lvl);
-      if (entry) {
-        const levelRoutes = {};
-        for (const [k, v] of Object.entries(entry.routes)) {
-          levelRoutes[k] = JSON.parse(JSON.stringify(v));
-        }
-        result[lvl] = levelRoutes;
+      return doApiCall(meta, params, ctrl.signal);
+    })();
+    const request = work;
+    request.abort = () => {
+      if (ctrl) {
+        ctrl.abort();
+      } else {
+        abortedBeforeInit = true;
       }
-    }
-    return result;
-  }
-  void autoDiscoveryPromise.then(() => {
-    autoDiscoveryCompleted = true;
-    if (effectiveEager.length > 0) {
-      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((e) => {
-    rejectReady(e);
-  });
-  function ready(onFulfilled, onRejected) {
-    if (onFulfilled) {
-      const p = readyPromise.then(onFulfilled, onRejected);
-      return p.then(() => forgeInstance);
-    }
-    return readyPromise;
+    };
+    return request;
+  };
+}
+
+// src/resolveRouteName.ts
+async function resolveRouteName(forge, level, prefix, suffix, separator = ".") {
+  if (!suffix) return prefix;
+  const joined = `${prefix}${separator}${suffix}`;
+  if (!suffix.startsWith(`${prefix}${separator}`)) return joined;
+  await forge.load(level);
+  if (forge.hasRoute(level, joined)) return joined;
+  if (forge.hasRoute(level, suffix)) return suffix;
+  throw new UnknownRouteError(joined, level);
+}
+function resolveRouteNameSync(forge, level, prefix, suffix, separator = ".") {
+  if (!suffix) return prefix;
+  const joined = `${prefix}${separator}${suffix}`;
+  if (!suffix.startsWith(`${prefix}${separator}`)) return joined;
+  if (forge.hasRoute(level, joined)) return joined;
+  if (forge.hasRoute(level, suffix)) return suffix;
+  throw new UnknownRouteError(joined, level);
+}
+
+// src/defineImmutableProps.ts
+function defineImmutableProps(target, props) {
+  for (const key of Object.keys(props)) {
+    const val = props[key];
+    Object.defineProperty(target, key, {
+      value: val !== null && typeof val === "object" ? Object.freeze(val) : val,
+      writable: false,
+      enumerable: false,
+      configurable: false
+    });
   }
-  const forgeResolver = { load, hasRoute };
+  return target;
+}
+
+// src/bound-forge.ts
+function createBoundForgeFactory(deps) {
+  const { load, api, route, hasRoute, getRoutes, invalidate, isLoaded, loadingTracker } = deps;
+  const resolver = { load, hasRoute };
   function createBoundForge(level, prefix) {
     const levelLoadedPromise = load(level);
     levelLoadedPromise.catch(() => {
     });
-    const apiFn = prefix ? (name, params) => resolveRouteName(forgeResolver, level, prefix, name).then(
+    const apiFn = prefix ? (name, params) => resolveRouteName(resolver, level, prefix, name).then(
       (resolved) => api(level, resolved, params)
     ) : (name, params) => api(level, name, params);
     const callable = apiFn;
@@ -1060,8 +1040,8 @@ function createRouteForge(options) {
       level,
       ...prefix !== void 0 ? { prefix } : {},
       api: apiFn,
-      route: prefix ? (name, params) => route(level, resolveRouteNameSync(forgeResolver, level, prefix, name), params) : (name, params) => route(level, name, params),
-      url: prefix ? (name, params) => route(level, resolveRouteNameSync(forgeResolver, level, prefix, name), params) : (name, params) => route(level, name, params),
+      route: prefix ? (name, params) => route(level, resolveRouteNameSync(resolver, level, prefix, name), params) : (name, params) => route(level, name, params),
+      url: prefix ? (name, params) => route(level, resolveRouteNameSync(resolver, level, prefix, name), params) : (name, params) => route(level, name, params),
       hasRoute: (name) => hasRoute(level, name),
       getRoutes: () => getRoutes(level),
       load: () => load(level),
@@ -1105,6 +1085,220 @@ function createRouteForge(options) {
     attachBoundMethods(bound, levelLoadedPromise, level);
     return bound;
   }
+  return createBoundForgeWithMethods;
+}
+
+// src/forge.ts
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_CACHE_TTL = 3600;
+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,
+    baseURL = "",
+    interceptors: declarativeInterceptors,
+    cache: cacheOpts = {}
+  } = options;
+  const loadingTracker = new LoadingTracker();
+  const explicitLevels = options.levels;
+  const explicitEager = options.eager;
+  const explicitEndpoint = options.endpoint;
+  const discoveryState = {
+    levels: explicitLevels ?? [],
+    eager: explicitEager ?? [],
+    endpoint: explicitEndpoint ?? bootstrapSummary?.config?.endpoint_prefix ?? "",
+    urlPrefix: "",
+    cacheTtl: void 0,
+    levelRoutes: {}
+  };
+  const discoveryInputs = { explicitLevels, explicitEager, explicitEndpoint };
+  let autoDiscoveryCompleted = false;
+  let resolveReady;
+  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";
+  const cache = new RouteCache({ storage: cacheStorage, ttl: cacheTtl });
+  const requestInterceptors = new InterceptorManagerImpl();
+  const responseInterceptors = new InterceptorManagerImpl();
+  if (declarativeInterceptors?.request) {
+    for (const entry of declarativeInterceptors.request) {
+      if (typeof entry === "function") {
+        requestInterceptors.use(entry);
+      } else {
+        const [onFulfilled, onRejected] = entry;
+        requestInterceptors.use(onFulfilled, onRejected);
+      }
+    }
+  }
+  if (declarativeInterceptors?.response) {
+    for (const entry of declarativeInterceptors.response) {
+      if (typeof entry === "function") {
+        responseInterceptors.use(entry);
+      } else {
+        const [onFulfilled, onRejected] = entry;
+        responseInterceptors.use(onFulfilled, onRejected);
+      }
+    }
+  }
+  const adapterPromise = resolveAdapter({
+    adapter,
+    forgeInterceptors: { request: requestInterceptors, response: responseInterceptors }
+  });
+  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",
+          forgeInterceptors: { request: requestInterceptors, response: responseInterceptors }
+        });
+      });
+      adapterResolved = true;
+    }
+    return adapterObj;
+  }
+  function assertDiscoveryReady() {
+    if (!autoDiscoveryCompleted && !explicitLevels?.length) {
+      throw new ForgeError(
+        "Route data not available. Auto-discovery has not completed. Use forge.ready() or forge.use(level) first.",
+        { code: "RF_FE_010" }
+      );
+    }
+  }
+  async function fetchMeta(routeTag, url, level = "") {
+    const adp = await ensureAdapter();
+    const config = {
+      route: routeTag,
+      level,
+      method: "GET",
+      url,
+      headers: { Accept: "application/json" },
+      params: {},
+      timeout,
+      meta: {
+        name: routeTag,
+        uri: url,
+        methods: ["GET"],
+        parameters: [],
+        level
+      }
+    };
+    const doRawRequest = adp.requestRaw ?? adp.request;
+    const resp = await doRawRequest(config);
+    if (!resp || resp.status < 200 || resp.status >= 300) {
+      throw new HTTPError(
+        `Failed to fetch "${routeTag}": HTTP ${resp?.status}`,
+        { level, status: resp?.status, url, method: "GET" }
+      );
+    }
+    return resp.data;
+  }
+  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;
+  });
+  const store = new RouteStore({
+    cache,
+    state: discoveryState,
+    baseURL,
+    fetchMeta,
+    autoDiscoveryPromise,
+    getAutoDiscoveryError: () => autoDiscoveryError
+  });
+  const load = (level) => store.load(level);
+  const findRouteMeta = (level, name) => store.findRouteMeta(level, name);
+  const invalidate = (level) => store.invalidate(level);
+  const isLoaded = (level) => store.isLoaded(level);
+  function getRoutes(level) {
+    return level === void 0 ? store.getRoutes() : store.getRoutes(level);
+  }
+  function route(level, name, params) {
+    assertDiscoveryReady();
+    const meta = findRouteMeta(level, name);
+    if (!meta) {
+      throw new UnknownRouteError(name, level);
+    }
+    return buildRequestUrl(meta, params ?? {}, { baseURL, urlPrefix: discoveryState.urlPrefix });
+  }
+  const api = createHttpRunner({
+    ensureAdapter,
+    requestInterceptors,
+    responseInterceptors,
+    load,
+    findRouteMeta,
+    baseURL,
+    state: discoveryState,
+    timeout,
+    loadingTracker,
+    autoDiscoveryPromise
+  });
+  function hasRoute(level, name) {
+    assertDiscoveryReady();
+    return findRouteMeta(level, name) !== void 0;
+  }
+  void autoDiscoveryPromise.then(() => {
+    autoDiscoveryCompleted = true;
+    if (discoveryState.eager.length > 0) {
+      return Promise.allSettled(discoveryState.eager.map((lvl) => load(lvl))).then((results) => {
+        results.forEach((r, i) => {
+          if (r.status === "rejected") {
+            console.error(
+              `[route-forge] eager load failed for level "${discoveryState.eager[i]}":`,
+              r.reason
+            );
+          }
+        });
+      });
+    }
+  }).then(() => {
+    resolveReady(forgeInstance);
+  }).catch((e) => {
+    rejectReady(e);
+  });
+  function ready(onFulfilled, onRejected) {
+    if (onFulfilled) {
+      const p = readyPromise.then(onFulfilled, onRejected);
+      return p.then(() => forgeInstance);
+    }
+    return readyPromise;
+  }
+  const createBoundForgeWithMethods = createBoundForgeFactory({
+    load,
+    api,
+    route,
+    hasRoute,
+    getRoutes,
+    invalidate,
+    isLoaded,
+    loadingTracker
+  });
   const forgeInstance = {
     api,
     load,
@@ -1128,62 +1322,6 @@ function createRouteForge(options) {
   };
   return forgeInstance;
 }
-function pickMethod(meta) {
-  const m = meta.methods.find((x) => x.toUpperCase() !== "HEAD");
-  return (m ?? meta.methods[0] ?? "GET").toUpperCase();
-}
-function appendQuery(url, query) {
-  if (!query) return url;
-  const usp = new URLSearchParams();
-  for (const [k, v] of Object.entries(query)) {
-    if (v === void 0 || v === null) continue;
-    usp.append(k, String(v));
-  }
-  const qs = usp.toString();
-  if (!qs) return url;
-  return url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
-}
-function resolveApiParams(input) {
-  const {
-    params: explicitParams,
-    query: rawQuery,
-    body: rawBody,
-    headers: rawHeaders,
-    timeout: perCallTimeout,
-    ...flatRest
-  } = input;
-  const pathParams = explicitParams ? { ...explicitParams } : {};
-  for (const [k, v] of Object.entries(flatRest)) {
-    if (!(k in pathParams)) {
-      pathParams[k] = v;
-    }
-  }
-  let query;
-  let body;
-  let headers;
-  if (rawQuery !== void 0) {
-    if (typeof rawQuery === "object" && rawQuery !== null) {
-      query = rawQuery;
-    } else if (!("query" in pathParams)) {
-      pathParams.query = rawQuery;
-    }
-  }
-  if (rawBody !== void 0) {
-    if (typeof rawBody !== "string" && typeof rawBody !== "number") {
-      body = rawBody;
-    } else if (!("body" in pathParams)) {
-      pathParams.body = rawBody;
-    }
-  }
-  if (rawHeaders !== void 0) {
-    if (typeof rawHeaders === "object" && rawHeaders !== null) {
-      headers = rawHeaders;
-    } else if (!("headers" in pathParams)) {
-      pathParams.headers = rawHeaders;
-    }
-  }
-  return { pathParams, query, body, headers, timeout: perCallTimeout };
-}
 
 exports.AdapterNotFoundError = AdapterNotFoundError;
 exports.ForgeError = ForgeError;