@route-forge/core 0.3.0 → 1.0.2

package/dist/index.cjs

@@ -28,17 +28,19 @@ var RouteCache = class {
       return this.getFromMemory(level);
     }
     const raw = this.backend.getItem(this.key(level));
-    if (!raw) return void 0;
-    try {
-      const entry = JSON.parse(raw);
-      if (this.isExpired(entry)) {
-        this.del(level);
+    if (raw) {
+      try {
+        const entry = JSON.parse(raw);
+        if (this.isExpired(entry)) {
+          this.del(level);
+          return void 0;
+        }
+        return entry;
+      } catch {
         return void 0;
       }
-      return entry;
-    } catch {
-      return void 0;
     }
+    return this.getFromMemory(level);
   }
   getFromMemory(level) {
     const entry = this.memory.get(level);
@@ -50,7 +52,12 @@ var RouteCache = class {
     return entry;
   }
   set(resp) {
-    const ttl = resp.cache !== void 0 && resp.cache !== null ? resp.cache : this.fallbackTtl;
+    let ttl;
+    if (resp.cache !== void 0 && resp.cache !== null) {
+      ttl = resp.cache > 0 ? Math.min(resp.cache, this.fallbackTtl) : resp.cache;
+    } else {
+      ttl = this.fallbackTtl;
+    }
     const entry = {
       level: resp.level,
       routes: resp.routes,
@@ -135,14 +142,6 @@ var MissingRouteParamError = class extends ForgeError {
     });
   }
 };
-var InsufficientAuthError = class extends ForgeError {
-  constructor(level) {
-    super(`Insufficient auth: level "${level}" requires login`, {
-      code: "RF_FE_004",
-      level
-    });
-  }
-};
 var AdapterNotFoundError = class extends ForgeError {
   constructor(adapter) {
     super(`Adapter "${adapter}" not available; install axios or use 'builtin'`, {
@@ -243,6 +242,10 @@ function createInterceptorManager() {
 }
 
 // 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 createBuiltinHttp(forgeInterceptors) {
   const requestMgr = forgeInterceptors?.request ?? createInterceptorManager();
   const responseMgr = forgeInterceptors?.response ?? createInterceptorManager();
@@ -256,15 +259,33 @@ function createBuiltinHttp(forgeInterceptors) {
         url = url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
       }
     }
+    const headers = new Headers(finalConfig.headers);
     const fetchInit = {
       method: finalConfig.method,
-      headers: new Headers(finalConfig.headers)
+      headers
     };
     if (signal) fetchInit.signal = signal;
     if (finalConfig.body !== void 0 && !["GET", "HEAD"].includes(finalConfig.method.toUpperCase())) {
-      fetchInit.body = typeof finalConfig.body === "string" ? finalConfig.body : JSON.stringify(finalConfig.body);
+      if (typeof finalConfig.body === "string" || isPassthroughBody(finalConfig.body)) {
+        fetchInit.body = finalConfig.body;
+      } else {
+        fetchInit.body = JSON.stringify(finalConfig.body);
+        if (!headers.has("Content-Type")) {
+          headers.set("Content-Type", "application/json");
+        }
+      }
+    }
+    let res;
+    try {
+      res = await fetch(url, fetchInit);
+    } catch (e) {
+      throw new NetworkError(
+        e instanceof Error ? e.message : String(e),
+        finalConfig.route,
+        finalConfig.level,
+        e
+      );
     }
-    const res = await fetch(url, fetchInit);
     const text = await res.text();
     let data = text;
     const contentType = res.headers.get("content-type") ?? "";
@@ -284,9 +305,21 @@ function createBuiltinHttp(forgeInterceptors) {
       data,
       config: finalConfig
     };
+    const source = res.status >= 200 && res.status < 300 ? Promise.resolve(responseData) : Promise.reject(
+      new HTTPError(
+        `HTTP ${res.status} for route "${finalConfig.route}" (${finalConfig.method} ${url})`,
+        {
+          route: finalConfig.route,
+          level: finalConfig.level,
+          status: res.status,
+          url,
+          method: finalConfig.method
+        }
+      )
+    );
     return runResponseInterceptors(
       responseMgr,
-      Promise.resolve(responseData)
+      source
     );
   }
   const get = (url, config) => request({ ...config, url, method: "GET" });
@@ -310,6 +343,15 @@ function createBuiltinHttp(forgeInterceptors) {
 }
 
 // src/adapters/axios.ts
+function toHeaders(raw) {
+  if (!raw) return new Headers();
+  const init = typeof raw.toJSON === "function" ? raw.toJSON() : raw;
+  try {
+    return new Headers(init);
+  } catch {
+    return new Headers();
+  }
+}
 async function wrapAxiosAdapter() {
   let axios;
   try {
@@ -326,23 +368,41 @@ async function wrapAxiosAdapter() {
   if (!axios || typeof axios.request !== "function") return null;
   async function request(config) {
     const headers = { ...config.headers };
-    const res = await axios.request({
-      url: config.url,
-      method: config.method,
-      headers,
-      data: config.body
-      // axios 会处理 baseURL/transformRequest 等 defaults
-    });
-    return {
-      route: config.route,
-      level: config.level,
-      method: config.method,
-      url: config.url,
-      status: res.status,
-      headers: new Headers(res.headers ?? {}),
-      data: res.data,
-      config
-    };
+    try {
+      const res = await axios.request({
+        url: config.url,
+        method: config.method,
+        headers,
+        data: config.body,
+        // axios 会处理 baseURL/transformRequest 等 defaults；timeout 透传保证超时语义与 builtin 一致
+        timeout: config.timeout
+      });
+      return {
+        route: config.route,
+        level: config.level,
+        method: config.method,
+        url: config.url,
+        status: res.status,
+        headers: toHeaders(res.headers),
+        data: res.data,
+        config
+      };
+    } catch (e) {
+      if (e && e.response) {
+        const resp = e.response;
+        return {
+          route: config.route,
+          level: config.level,
+          method: config.method,
+          url: config.url,
+          status: resp.status,
+          headers: toHeaders(resp.headers),
+          data: resp.data,
+          config
+        };
+      }
+      throw e;
+    }
   }
   return { request, interceptors: void 0 };
 }
@@ -369,6 +429,65 @@ async function resolveAdapter(opts) {
   return createBuiltinHttp(opts.forgeInterceptors);
 }
 
+// src/loading.ts
+var LoadingTracker = class {
+  constructor() {
+    /** 当前并发请求计数 */
+    this.count = 0;
+    /** 订阅者集合 */
+    this.subscribers = /* @__PURE__ */ new Set();
+  }
+  /**
+   * 开始一次加载（计数器 +1）
+   */
+  start() {
+    this.count++;
+    this.notify();
+  }
+  /**
+   * 结束一次加载（计数器 -1）
+   */
+  stop() {
+    this.count = Math.max(0, this.count - 1);
+    this.notify();
+  }
+  /**
+   * 查询当前是否处于加载中
+   */
+  isLoading() {
+    return this.count > 0;
+  }
+  /**
+   * 获取当前并发计数
+   */
+  getCount() {
+    return this.count;
+  }
+  /**
+   * 订阅加载状态变更
+   * @returns 取消订阅函数
+   */
+  subscribe(cb) {
+    this.subscribers.add(cb);
+    return () => {
+      this.subscribers.delete(cb);
+    };
+  }
+  /** 通知所有订阅者 */
+  notify() {
+    const event = {
+      loading: this.count > 0,
+      count: this.count
+    };
+    for (const cb of this.subscribers) {
+      try {
+        cb(event);
+      } catch {
+      }
+    }
+  }
+};
+
 // src/forge.ts
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_CACHE_TTL = 3600;
@@ -378,10 +497,10 @@ function createRouteForge(options) {
     adapter = "auto",
     timeout = DEFAULT_TIMEOUT,
     baseURL = "",
-    auth,
     interceptors: declarativeInterceptors,
     cache: cacheOpts = {}
   } = options;
+  const loadingTracker = new LoadingTracker();
   const explicitLevels = options.levels;
   const explicitEager = options.eager;
   const explicitStrict = options.strict ?? false;
@@ -415,6 +534,12 @@ function createRouteForge(options) {
     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}"`
@@ -442,8 +567,12 @@ function createRouteForge(options) {
     } else {
       effectiveLevels = backendLevels;
     }
+    const backendEager = backendLevels.filter((lvl) => summary.levels[lvl]?.load === "eager");
     if (!explicitEager) {
-      effectiveEager = backendLevels.filter((lvl) => summary.levels[lvl]?.load === "eager");
+      effectiveEager = backendEager;
+    } else {
+      const union = /* @__PURE__ */ new Set([...backendEager, ...explicitEager]);
+      effectiveEager = [...union];
     }
   });
   autoDiscoveryPromise.catch(() => {
@@ -454,15 +583,23 @@ function createRouteForge(options) {
   const requestInterceptors = new InterceptorManagerImpl();
   const responseInterceptors = new InterceptorManagerImpl();
   if (declarativeInterceptors?.request) {
-    for (const pair of declarativeInterceptors.request) {
-      const [onFulfilled, onRejected] = pair;
-      requestInterceptors.use(onFulfilled, onRejected);
+    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 pair of declarativeInterceptors.response) {
-      const [onFulfilled, onRejected] = pair;
-      responseInterceptors.use(onFulfilled, onRejected);
+    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({
@@ -482,14 +619,6 @@ function createRouteForge(options) {
     return adapterObj;
   }
   const inflight = /* @__PURE__ */ new Map();
-  function isAuthRequired(level) {
-    return Boolean(auth?.levels?.[level]);
-  }
-  function assertAuth(level) {
-    if (isAuthRequired(level) && auth?.state && !auth.state()) {
-      throw new InsufficientAuthError(level);
-    }
-  }
   function assertLevelDeclared(level) {
     if (!effectiveLevels.includes(level)) {
       throw new UnknownLevelError(level);
@@ -520,14 +649,16 @@ function createRouteForge(options) {
     };
     const resp = await adp.request(config);
     if (!resp || resp.status < 200 || resp.status >= 300) {
-      throw new Error(`Failed to load level ${level}: HTTP ${resp?.status}`);
+      throw new HTTPError(
+        `Failed to load level "${level}": HTTP ${resp?.status}`,
+        { level, status: resp?.status, url: buildUrl(level), method: "GET" }
+      );
     }
     const data = resp.data;
     return data;
   }
   async function loadOne(level) {
     assertLevelDeclared(level);
-    assertAuth(level);
     if (cache.get(level)) return;
     const existing = inflight.get(level);
     if (existing) return existing;
@@ -555,27 +686,33 @@ function createRouteForge(options) {
     return buildRequestUrl(meta, params ?? {});
   }
   function buildRequestUrl(meta, params) {
-    let uri = meta.uri;
     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 (uri.includes(`{${p}?}`)) {
-          uri = uri.replace(`{${p}?}`, "");
-          continue;
+        if (!meta.uri.includes(`{${p}?}`)) {
+          missingRequired.push(p);
         }
-        missingRequired.push(p);
       } else {
-        uri = uri.replace(`{${p}?}`, encodeURIComponent(String(v))).replace(`{${p}}`, encodeURIComponent(String(v)));
+        values[p] = v;
       }
     }
     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) {
+        return encodeURIComponent(String(values[name]));
+      }
+      return optional ? "" : match;
+    });
     uri = uri.replace(/\/+/g, "/").replace(/\/$/, "");
     if (effectiveUrlPrefix.includes("://")) {
       const prefix2 = effectiveUrlPrefix.endsWith("/") ? effectiveUrlPrefix.slice(0, -1) : effectiveUrlPrefix;
@@ -603,8 +740,7 @@ function createRouteForge(options) {
     return doApiCall(meta, params);
   }
   async function doApiCall(meta, params) {
-    assertAuth(meta.level ?? "");
-    const { pathParams, query, body, headers } = resolveApiParams(params);
+    const { pathParams, query, body, headers, timeout: perCallTimeout } = resolveApiParams(params);
     const method = pickMethod(meta);
     const urlWithQuery = appendQuery(buildRequestUrl(meta, pathParams), query);
     const config = {
@@ -615,47 +751,57 @@ function createRouteForge(options) {
       headers: { Accept: "application/json", ...headers ?? {} },
       body,
       params: pathParams,
-      timeout,
+      timeout: perCallTimeout ?? timeout,
       meta
     };
     const adp = await ensureAdapter();
     const finalConfig = adp.runsInterceptors ? config : await runRequestInterceptors(requestInterceptors, config);
-    const source = adp.request(finalConfig).then(
-      (resp) => {
-        if (resp.status < 200 || resp.status >= 300) {
-          throw new HTTPError(
-            `HTTP ${resp.status} for route "${resp.route}" (${resp.method} ${resp.url})`,
-            {
-              route: resp.route,
-              level: resp.level,
-              status: resp.status,
-              url: resp.url,
-              method: resp.method
-            }
+    loadingTracker.start();
+    try {
+      const source = adp.request(finalConfig).then(
+        (resp) => {
+          if (resp.status < 200 || resp.status >= 300) {
+            throw new HTTPError(
+              `HTTP ${resp.status} for route "${resp.route}" (${resp.method} ${resp.url})`,
+              {
+                route: resp.route,
+                level: resp.level,
+                status: resp.status,
+                url: resp.url,
+                method: resp.method
+              }
+            );
+          }
+          return resp;
+        },
+        (err) => {
+          if (err instanceof ForgeError) throw err;
+          throw new NetworkError(
+            err instanceof Error ? err.message : String(err),
+            meta.name,
+            meta.level,
+            err
           );
         }
-        return resp;
-      },
-      (err) => {
-        if (err instanceof ForgeError) throw err;
-        throw new NetworkError(
-          err instanceof Error ? err.message : String(err),
-          meta.name,
-          meta.level,
-          err
-        );
-      }
-    );
-    if (adp.runsInterceptors) return source;
-    return runResponseInterceptors(responseInterceptors, source);
+      );
+      const result = adp.runsInterceptors ? await source : await runResponseInterceptors(responseInterceptors, source);
+      return result;
+    } finally {
+      loadingTracker.stop();
+    }
   }
   function invalidate(level) {
-    if (level) cache.del(level);
-    else cache.clear();
+    if (level === void 0) {
+      cache.clear();
+    } else if (Array.isArray(level)) {
+      for (const lvl of level) cache.del(lvl);
+    } else {
+      cache.del(level);
+    }
   }
   function isLoaded(level) {
     if (level) return cache.get(level) !== void 0;
-    return effectiveLevels.every((lvl) => cache.get(lvl) !== void 0);
+    return effectiveLevels.length > 0 && effectiveLevels.every((lvl) => cache.get(lvl) !== void 0);
   }
   function hasRoute(level, name) {
     return findRouteMeta(level, name) !== void 0;
@@ -700,6 +846,8 @@ function createRouteForge(options) {
     isLoaded,
     hasRoute,
     getRoutes,
+    isLoading: () => loadingTracker.isLoading(),
+    onLoadingChange: (cb) => loadingTracker.subscribe(cb),
     interceptors: {
       request: requestInterceptors,
       response: responseInterceptors
@@ -727,6 +875,7 @@ function resolveApiParams(input) {
     query: rawQuery,
     body: rawBody,
     headers: rawHeaders,
+    timeout: perCallTimeout,
     ...flatRest
   } = input;
   const pathParams = explicitParams ? { ...explicitParams } : {};
@@ -759,15 +908,15 @@ function resolveApiParams(input) {
       pathParams.headers = rawHeaders;
     }
   }
-  return { pathParams, query, body, headers };
+  return { pathParams, query, body, headers, timeout: perCallTimeout };
 }
 
 exports.AdapterNotFoundError = AdapterNotFoundError;
 exports.ForgeError = ForgeError;
 exports.HTTPError = HTTPError;
-exports.InsufficientAuthError = InsufficientAuthError;
 exports.InterceptorManagerImpl = InterceptorManagerImpl;
 exports.InvalidInterceptorReturnError = InvalidInterceptorReturnError;
+exports.LoadingTracker = LoadingTracker;
 exports.MissingRouteParamError = MissingRouteParamError;
 exports.NetworkError = NetworkError;
 exports.RouteCache = RouteCache;