@route-forge/core 2.0.0 → 2.2.0

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 {
@@ -491,39 +507,6 @@ var RouteForge = (function (exports) {
     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() {
@@ -583,328 +566,333 @@ var RouteForge = (function (exports) {
     }
   };
 
-  // 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,
@@ -917,7 +905,10 @@ var RouteForge = (function (exports) {
         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 ?? "",
@@ -972,88 +963,77 @@ var RouteForge = (function (exports) {
         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;
@@ -1061,8 +1041,8 @@ var RouteForge = (function (exports) {
         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),
@@ -1106,6 +1086,220 @@ var RouteForge = (function (exports) {
       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,
@@ -1129,62 +1323,6 @@ var RouteForge = (function (exports) {
     };
     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;