@route-forge/core 1.4.0 → 2.1.0

package/dist/route-forge.global.js

@@ -17,9 +17,18 @@ var RouteForge = (function (exports) {
   var RouteCache = class {
     constructor(opts) {
       this.memory = /* @__PURE__ */ new Map();
+      /** 其他 tab 修改 storage 时失效对应镜像（storage 事件：自己的写不触发，自己的写经 set/del 已同步） */
+      this.onStorageEvent = (e) => {
+        if (!e.key) return;
+        if (!e.key.startsWith(KEY_PREFIX)) return;
+        this.memory.delete(e.key.slice(KEY_PREFIX.length));
+      };
       this.storage = opts.storage;
       this.fallbackTtl = opts.ttl;
       this.backend = pickStorage(opts.storage);
+      if (this.backend && typeof globalThis.addEventListener === "function") {
+        globalThis.addEventListener("storage", this.onStorageEvent);
+      }
     }
     key(level) {
       return `${KEY_PREFIX}${level}`;
@@ -28,6 +37,8 @@ var RouteForge = (function (exports) {
       if (this.storage === "memory" || !this.backend) {
         return this.getFromMemory(level);
       }
+      const mirrored = this.getFromMemory(level);
+      if (mirrored) return mirrored;
       const raw = this.backend.getItem(this.key(level));
       if (raw) {
         try {
@@ -36,12 +47,13 @@ var RouteForge = (function (exports) {
             this.del(level);
             return void 0;
           }
+          this.memory.set(level, entry);
           return entry;
         } catch {
           return void 0;
         }
       }
-      return this.getFromMemory(level);
+      return void 0;
     }
     getFromMemory(level) {
       const entry = this.memory.get(level);
@@ -65,14 +77,13 @@ var RouteForge = (function (exports) {
         ttl,
         cachedAt: Date.now()
       };
+      this.memory.set(resp.level, entry);
       if (this.storage === "memory" || !this.backend) {
-        this.memory.set(resp.level, entry);
         return;
       }
       try {
         this.backend.setItem(this.key(resp.level), JSON.stringify(entry));
       } catch {
-        this.memory.set(resp.level, entry);
       }
     }
     del(level) {
@@ -252,14 +263,14 @@ var RouteForge = (function (exports) {
     return new InterceptorManagerImpl();
   }
 
-  // src/adapters/builtin-http.ts
-  function isPassthroughBody(body) {
-    if (body === null) return false;
-    return typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams || typeof Blob !== "undefined" && body instanceof Blob || typeof ArrayBuffer !== "undefined" && (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) || typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
-  }
-  function isAbortError(err) {
+  // src/adapters/fetch-core.ts
+  function isAbortError(err, signal) {
+    if (signal?.aborted) return true;
     const e = err;
-    return !!e && e.name === "AbortError";
+    if (!e) return false;
+    if (e.name === "AbortError") return true;
+    if (e.code === "ERR_CANCELED") return true;
+    return false;
   }
   function combineSignals(...signals) {
     const valid = signals.filter((s) => !!s);
@@ -278,82 +289,89 @@ var RouteForge = (function (exports) {
     }
     return controller.signal;
   }
-  function createBuiltinHttp(forgeInterceptors) {
-    const requestMgr = forgeInterceptors?.request ?? createInterceptorManager();
-    const responseMgr = forgeInterceptors?.response ?? createInterceptorManager();
-    async function requestRaw(config) {
-      const signal = combineSignals(
-        config.signal,
-        config.timeout && config.timeout > 0 ? AbortSignal.timeout(config.timeout) : void 0
-      );
-      let url = config.url;
-      if (config.paramsSerializer && config.params) {
-        const qs = config.paramsSerializer(config.params);
-        if (qs) {
-          url = url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
-        }
+  function isPassthroughBody(body) {
+    if (body === null) return false;
+    return typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams || typeof Blob !== "undefined" && body instanceof Blob || typeof ArrayBuffer !== "undefined" && (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) || typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
+  }
+  async function rawFetch(config) {
+    const signal = combineSignals(
+      config.signal,
+      config.timeout && config.timeout > 0 ? AbortSignal.timeout(config.timeout) : void 0
+    );
+    let url = config.url;
+    if (config.paramsSerializer && config.params) {
+      const qs = config.paramsSerializer(config.params);
+      if (qs) {
+        url = url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
       }
-      const headers = new Headers(config.headers);
-      const fetchInit = {
-        method: config.method,
-        headers
-      };
-      if (signal) fetchInit.signal = signal;
-      if (config.body !== void 0 && !["GET", "HEAD"].includes(config.method.toUpperCase())) {
-        if (typeof config.body === "string" || isPassthroughBody(config.body)) {
-          fetchInit.body = config.body;
-        } else {
-          fetchInit.body = JSON.stringify(config.body);
-          if (!headers.has("Content-Type")) {
-            headers.set("Content-Type", "application/json");
-          }
+    }
+    const headers = new Headers(config.headers);
+    const fetchInit = {
+      method: config.method,
+      headers
+    };
+    if (signal) fetchInit.signal = signal;
+    if (config.body !== void 0 && !["GET", "HEAD"].includes(config.method.toUpperCase())) {
+      if (typeof config.body === "string" || isPassthroughBody(config.body)) {
+        fetchInit.body = config.body;
+      } else {
+        fetchInit.body = JSON.stringify(config.body);
+        if (!headers.has("Content-Type")) {
+          headers.set("Content-Type", "application/json");
         }
       }
-      let res;
+    }
+    let res;
+    try {
+      res = await fetch(url, fetchInit);
+    } catch (e) {
+      if (isAbortError(e)) throw e;
+      throw new NetworkError(
+        e instanceof Error ? e.message : String(e),
+        config.route,
+        config.level,
+        e
+      );
+    }
+    const text = await res.text();
+    let data = text;
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
       try {
-        res = await fetch(url, fetchInit);
-      } catch (e) {
-        if (isAbortError(e)) throw e;
-        throw new NetworkError(
-          e instanceof Error ? e.message : String(e),
-          config.route,
-          config.level,
-          e
-        );
-      }
-      const text = await res.text();
-      let data = text;
-      const contentType = res.headers.get("content-type") ?? "";
-      if (contentType.includes("application/json")) {
-        try {
-          data = JSON.parse(text);
-        } catch {
-        }
+        data = JSON.parse(text);
+      } catch {
       }
-      const responseData = {
+    }
+    const responseData = {
+      route: config.route,
+      level: config.level,
+      method: config.method,
+      url,
+      status: res.status,
+      headers: res.headers,
+      data,
+      config
+    };
+    if (res.status >= 200 && res.status < 300) {
+      return responseData;
+    }
+    throw new HTTPError(
+      `HTTP ${res.status} for route "${config.route}" (${config.method} ${url})`,
+      {
         route: config.route,
         level: config.level,
-        method: config.method,
-        url,
         status: res.status,
-        headers: res.headers,
-        data,
-        config
-      };
-      if (res.status >= 200 && res.status < 300) {
-        return responseData;
+        url,
+        method: config.method
       }
-      throw new HTTPError(
-        `HTTP ${res.status} for route "${config.route}" (${config.method} ${url})`,
-        {
-          route: config.route,
-          level: config.level,
-          status: res.status,
-          url,
-          method: config.method
-        }
-      );
-    }
+    );
+  }
+
+  // src/adapters/builtin-http.ts
+  function createBuiltinHttp(forgeInterceptors) {
+    const requestMgr = forgeInterceptors?.request ?? createInterceptorManager();
+    const responseMgr = forgeInterceptors?.response ?? createInterceptorManager();
+    const requestRaw = rawFetch;
     async function request(config) {
       const finalConfig = await runRequestInterceptors(requestMgr, config);
       const source = Promise.resolve(finalConfig).then(requestRaw);
@@ -473,39 +491,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() {
@@ -565,320 +550,308 @@ 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 summaryPromise = (async () => {
-      try {
-        const summaryUrl = explicitEndpoint;
-        const resp = await fetch(summaryUrl, { method: "GET" });
-        if (!resp.ok) {
-          console.warn(
-            `[route-forge] summary endpoint ${summaryUrl} unreachable (HTTP ${resp.status}); falling back to explicit options`
-          );
-          return null;
-        }
-        return await resp.json();
-      } 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)");
-      }
-    })();
-    const autoDiscoveryPromise = summaryPromise.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;
-    const readyPromise = new Promise((resolve) => {
-      resolveReady = resolve;
-    });
-    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 }
-    });
-    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
+  var UNASSIGNED_LEVEL = "unassigned";
+  async function fetchSummary(inputs, baseURL, fetchMeta) {
+    const { explicitLevels, explicitEndpoint } = inputs;
+    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 applySummaryToState(summary, state, inputs) {
+    const { explicitLevels, explicitEager, explicitEndpoint } = inputs;
+    const schemaVersion = summary.schemaVersion ?? 1;
+    if (schemaVersion > 1) {
+      console.warn(
+        `[route-forge] backend schemaVersion=${schemaVersion} > client supported 1; some features may be unavailable`
+      );
     }
-    async function fetchLevel(level) {
-      const adp = await ensureAdapter();
-      const config = {
-        route: `__forge__.load.${level}`,
-        level,
-        method: "GET",
-        url: buildUrl(level),
-        headers: { Accept: "application/json" },
-        params: {},
-        timeout,
-        meta: {
-          name: `__forge__.load.${level}`,
-          uri: buildUrl(level),
-          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 load level "${level}": HTTP ${resp?.status}`,
-          { level, status: resp?.status, url: buildUrl(level), method: "GET" }
+    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}"`
+      );
+      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;
+    }
+    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);
+    }
+    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(", ")}`
         );
       }
-      const data = resp.data;
-      return data;
+      state.levels = intersection;
+    } else {
+      state.levels = availableLevels;
+    }
+    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];
     }
-    async function loadOne(level) {
+  }
+
+  // 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 fetchLevel(level) {
+      return await this.fetchMeta(
+        `__forge__.load.${level}`,
+        buildUrl(level, { baseURL: this.baseURL, endpoint: this.state.endpoint }),
+        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);
+      if (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) {
+          if (level === UNASSIGNED_LEVEL && !this.state.backendHasUnassignedLevel && this.state.summaryUnassigned) {
             const routes = {};
-            for (const r of summaryUnassigned) {
+            for (const r of this.state.summaryUnassigned) {
               routes[r.name] = { ...r, level: UNASSIGNED_LEVEL };
             }
-            cache.set({ level: UNASSIGNED_LEVEL, routes, cache: null });
+            this.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);
           }
         } 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];
-        }
-        if (v === void 0 || v === null) {
-          if (!meta.uri.includes(`{${p}?}`)) {
-            missingRequired.push(p);
-          }
-        } else {
-          values[p] = v;
+    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 (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));
+      } 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);
         }
-        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}`;
+      } else {
+        this.cache.del(level);
+        this.inflight.delete(level);
+        this.invalidationGens.set(level, (this.invalidationGens.get(level) ?? 0) + 1);
       }
-      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,
@@ -891,7 +864,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 ?? "",
@@ -929,7 +905,7 @@ var RouteForge = (function (exports) {
           },
           (err) => {
             if (err instanceof ForgeError) throw err;
-            if (isAbortError2(err, signal)) {
+            if (isAbortError(err, signal)) {
               throw new RequestAbortedError(meta.name, meta.level, err);
             }
             throw new NetworkError(
@@ -946,81 +922,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;
-      options.onSummaryReady?.();
-      if (effectiveEager.length > 0) {
-        return Promise.all(effectiveEager.map((lvl) => load(lvl))).catch((e) => {
-          console.warn(`[route-forge] eager load failed: ${e.message}`);
-        });
-      }
-    }).then(() => {
-      resolveReady(forgeInstance);
-    }).catch(() => {
-    });
-    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;
@@ -1028,8 +1000,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),
@@ -1073,6 +1045,208 @@ 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) {
+    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;
+    const discoveryState = {
+      levels: explicitLevels ?? [],
+      eager: explicitEager ?? [],
+      endpoint: explicitEndpoint,
+      urlPrefix: "",
+      summaryUnassigned: void 0,
+      backendHasUnassignedLevel: false
+    };
+    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;
+    }
+    const 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,
@@ -1096,70 +1270,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 };
-  }
-  function isAbortError2(err, signal) {
-    if (signal?.aborted) return true;
-    const e = err;
-    if (!e) return false;
-    if (e.name === "AbortError") return true;
-    if (e.code === "ERR_CANCELED") return true;
-    return false;
-  }
 
   exports.AdapterNotFoundError = AdapterNotFoundError;
   exports.ForgeError = ForgeError;