@route-forge/core 0.2.0 → 1.0.0

package/dist/index.cjs

@@ -50,7 +50,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 +140,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'`, {
@@ -369,6 +366,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,18 +434,18 @@ 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;
   const explicitEndpoint = options.endpoint;
   let effectiveLevels = explicitLevels ?? [];
   let effectiveEager = explicitEager ?? [];
-  let effectiveStrict = explicitStrict;
   let effectiveEndpoint = explicitEndpoint;
+  let effectiveUrlPrefix = "";
   const summaryPromise = (async () => {
     try {
       const summaryUrl = explicitEndpoint;
@@ -421,11 +477,13 @@ function createRouteForge(options) {
       );
       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;
+    }
     if (summary.config.strict_mode && !explicitStrict) {
       console.warn(
         "[route-forge] backend strict_mode=true overrides frontend strict=false; forcing strict=true"
       );
-      effectiveStrict = true;
     }
     const backendLevels = Object.keys(summary.levels);
     if (explicitLevels && explicitLevels.length > 0) {
@@ -440,8 +498,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(() => {
@@ -452,15 +514,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({
@@ -480,14 +550,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);
@@ -525,7 +587,6 @@ function createRouteForge(options) {
   }
   async function loadOne(level) {
     assertLevelDeclared(level);
-    assertAuth(level);
     if (cache.get(level)) return;
     const existing = inflight.get(level);
     if (existing) return existing;
@@ -548,24 +609,40 @@ function createRouteForge(options) {
   function route(level, name, params) {
     const meta = findRouteMeta(level, name);
     if (!meta) {
-      if (effectiveStrict) throw new UnknownRouteError(name, level);
-      return "";
+      throw new UnknownRouteError(name, level);
     }
     return buildRequestUrl(meta, params ?? {});
   }
   function buildRequestUrl(meta, params) {
     let uri = meta.uri;
+    const defaults = meta.parameter_defaults ?? {};
+    const missingRequired = [];
     for (const p of meta.parameters) {
-      const v = params[p];
-      if (v === void 0) {
-        if (effectiveStrict) throw new MissingRouteParamError(meta.name, [p]);
-        uri = uri.replace(`{${p}}`, "");
+      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;
+        }
+        missingRequired.push(p);
       } else {
-        uri = uri.replace(`{${p}}`, encodeURIComponent(String(v)));
+        uri = uri.replace(`{${p}?}`, encodeURIComponent(String(v))).replace(`{${p}}`, encodeURIComponent(String(v)));
       }
     }
+    if (missingRequired.length > 0) {
+      throw new MissingRouteParamError(meta.name, missingRequired);
+    }
+    uri = uri.replace(/\/+/g, "/").replace(/\/$/, "");
+    if (effectiveUrlPrefix.includes("://")) {
+      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;
-    return uri.startsWith("/") ? `${base}${uri}` : `${base}/${uri}`;
+    const prefix = effectiveUrlPrefix;
+    return uri.startsWith("/") ? `${base}${prefix}${uri}` : `${base}${prefix}/${uri}`;
   }
   function findRouteMeta(level, name) {
     const entry = cache.get(level);
@@ -580,19 +657,12 @@ function createRouteForge(options) {
     await load(level);
     const meta = findRouteMeta(level, name);
     if (!meta) {
-      if (effectiveStrict) throw new UnknownRouteError(name, level);
-      return void 0;
+      throw new UnknownRouteError(name, level);
     }
     return doApiCall(meta, params);
   }
   async function doApiCall(meta, params) {
-    assertAuth(meta.level ?? "");
-    const { query, body, headers, ...pathParams } = params;
-    for (const p of meta.parameters) {
-      if (pathParams[p] === void 0) {
-        if (effectiveStrict) throw new MissingRouteParamError(meta.name, [p]);
-      }
-    }
+    const { pathParams, query, body, headers } = resolveApiParams(params);
     const method = pickMethod(meta);
     const urlWithQuery = appendQuery(buildRequestUrl(meta, pathParams), query);
     const config = {
@@ -608,39 +678,74 @@ function createRouteForge(options) {
     };
     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();
   }
+  function isLoaded(level) {
+    if (level) return cache.get(level) !== void 0;
+    return effectiveLevels.every((lvl) => cache.get(lvl) !== void 0);
+  }
+  function hasRoute(level, name) {
+    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] = { ...v };
+      }
+      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] = { ...v };
+        }
+        result[lvl] = levelRoutes;
+      }
+    }
+    return result;
+  }
   void autoDiscoveryPromise.then(() => {
     if (effectiveEager.length > 0) {
       void Promise.all(effectiveEager.map((lvl) => load(lvl))).catch((e) => {
@@ -653,7 +758,13 @@ function createRouteForge(options) {
     api,
     load,
     route,
+    url: route,
     invalidate,
+    isLoaded,
+    hasRoute,
+    getRoutes,
+    isLoading: () => loadingTracker.isLoading(),
+    onLoadingChange: (cb) => loadingTracker.subscribe(cb),
     interceptors: {
       request: requestInterceptors,
       response: responseInterceptors
@@ -675,13 +786,53 @@ function appendQuery(url, query) {
   if (!qs) return url;
   return url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
 }
+function resolveApiParams(input) {
+  const {
+    params: explicitParams,
+    query: rawQuery,
+    body: rawBody,
+    headers: rawHeaders,
+    ...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 };
+}
 
 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;