@route-forge/core 0.3.0 → 1.0.0

package/README.md

@@ -1,12 +1,12 @@
 # @route-forge/core
 
-框架无关的命名路由客户端核心：分级懒加载、隔离缓存、并发去重、登录态感知、拦截器。
+框架无关的命名路由客户端核心：分级懒加载、隔离缓存、并发去重、拦截器。
 
 ## 安装
 
 ```bash
 pnpm add @route-forge/core
-# 可选:axios 适配器
+# 可选：axios 适配器
 pnpm add axios
 ```
 
@@ -29,6 +29,13 @@ const url = forge.route('public', 'login.show')
 // url() 是 route() 的语义别名
 const url2 = forge.url('public', 'login.show')
 
+// 检查路由是否存在
+forge.hasRoute('admin', 'users.show')  // true / false
+
+// 获取路由元信息
+const routes = forge.getRoutes('admin')          // 指定层级
+const allRoutes = forge.getRoutes()              // 全部层级
+
 // 检查层级是否已加载
 if (!forge.isLoaded('admin')) {
   await forge.load('admin')
@@ -86,6 +93,88 @@ forge.api('admin', 'search.show', {
 
 规则：`params` 优先 > 平铺 `string|number` → 路径参数 > 对象类型按原定义（`query`/`body`/`headers`）。
 
+## 认证（Authentication）
+
+Route Forge 不内置登录态管理，认证逻辑通过拦截器实现，灵活且完全可控。
+
+### Token 注入
+
+```ts
+// 声明式（初始化时配置）
+const forge = createRouteForge({
+  endpoint: '/_forge/routes',
+  interceptors: {
+    request: [
+      (config) => {
+        const token = authStore.getToken()
+        if (token) {
+          config.headers.Authorization = `Bearer ${token}`
+        }
+        return config
+      },
+    ],
+  },
+})
+
+// 或运行时动态注册
+forge.interceptors.request.use((config) => {
+  const token = authStore.getToken()
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`
+  }
+  return config
+})
+```
+
+### 401 响应处理
+
+```ts
+forge.interceptors.response.use(
+  (res) => res,  // 2xx 正常通过
+  (err) => {
+    if (err instanceof HTTPError && err.context?.status === 401) {
+      authStore.logout()
+      window.location.href = '/login'
+    }
+    return Promise.reject(err)
+  },
+)
+```
+
+### 登出清理
+
+```ts
+function logout() {
+  authStore.clearToken()
+  forge.invalidate()                        // 清空路由缓存
+  forge.interceptors.request.clear()        // 清空拦截器
+  forge.interceptors.response.clear()
+}
+```
+
+> 拦截器 API 与 axios 完全一致（`use` / `eject` / `clear`），如果项目已使用 axios 拦截器，可跳过此节——
+> `adapter: 'auto'` 模式下宿主 axios 的拦截器会自动生效。
+
+## 加载状态跟踪
+
+核心始终跟踪并发 API 请求的加载状态，无需配置。不需要使用时，不调用相关 API 即可。
+
+```ts
+// 查询当前是否处于加载中
+forge.isLoading()  // boolean
+
+// 订阅状态变更
+const unsub = forge.onLoadingChange((event) => {
+  console.log(event.loading)  // true / false
+  console.log(event.count)    // 当前并发请求数
+})
+
+// 取消订阅
+unsub()
+```
+
+> 加载状态始终跟踪，用户不使用则不订阅即可。Vue/React 包可通过 `onLoadingChange` 订阅状态变更驱动组件显隐。
+
 ## 文档
 
 - 仓库主页: https://github.com/xyj2156/route-forge

package/dist/codegen.d.cts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { R as RouteMeta } from './types-CBurRtGK.cjs';
+import { R as RouteMeta } from './types-yzY9-FWd.cjs';
 
 /**
  * @route-forge/core codegen CLI

package/dist/codegen.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { R as RouteMeta } from './types-CBurRtGK.js';
+import { R as RouteMeta } from './types-yzY9-FWd.js';
 
 /**
  * @route-forge/core codegen CLI

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,10 +434,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;
@@ -442,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(() => {
@@ -454,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({
@@ -482,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);
@@ -527,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;
@@ -603,7 +662,6 @@ function createRouteForge(options) {
     return doApiCall(meta, params);
   }
   async function doApiCall(meta, params) {
-    assertAuth(meta.level ?? "");
     const { pathParams, query, body, headers } = resolveApiParams(params);
     const method = pickMethod(meta);
     const urlWithQuery = appendQuery(buildRequestUrl(meta, pathParams), query);
@@ -620,34 +678,39 @@ 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);
@@ -700,6 +763,8 @@ function createRouteForge(options) {
     isLoaded,
     hasRoute,
     getRoutes,
+    isLoading: () => loadingTracker.isLoading(),
+    onLoadingChange: (cb) => loadingTracker.subscribe(cb),
     interceptors: {
       request: requestInterceptors,
       response: responseInterceptors
@@ -765,9 +830,9 @@ function resolveApiParams(input) {
 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;