@route-forge/core 1.0.3 → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 阿杰很厉害
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -186,6 +186,58 @@ unsub()
 
 > 加载状态始终跟踪，用户不使用则不订阅即可。Vue/React 包可通过 `onLoadingChange` 订阅状态变更驱动组件显隐。
 
+## 初始化合时序与推荐模式
+
+### 三种加载状态
+
+| 类型           | 说明                           | 跟踪方式                    |
+|----------------|--------------------------------|-----------------------------|
+| Auto-discovery | 拉取摘要端点发现 levels/config | 内部 `autoDiscoveryPromise` |
+| Level load     | 拉取某层级路由元数据           | `forge.isLoaded(level)`     |
+| API request    | 业务接口请求                   | `forge.isLoading()`         |
+
+### `onSummaryReady` 回调
+
+推荐在回调中挂载应用，确保路由数据就绪：
+
+```ts
+const forge = createRouteForge({
+  endpoint: '/_forge/routes',
+  onSummaryReady: () => {
+    // 摘要端点完成，路由数据已可用
+    app.mount('#app')
+  },
+})
+```
+
+### `forge.ready` Promise
+
+auto-discovery + eager load 完成后 resolve，适合 async/await 风格：
+
+```ts
+const forge = createRouteForge({ endpoint: '/_forge/routes' })
+await forge.ready
+// 路由数据已就绪，可安全调用 route() / hasRoute()
+```
+
+### `onLevelLoaded` 订阅
+
+订阅指定 level 加载完成事件：
+
+```ts
+const unsub = forge.onLevelLoaded('admin', () => {
+  console.log('admin level loaded')
+})
+// 取消订阅
+unsub()
+```
+
+### Auto-discovery 守卫
+
+`route()` / `hasRoute()` 在 auto-discovery 未完成且无 explicit levels 时抛出
+`ForgeError (RF_FE_010)`， 防止在路由数据未就绪时返回错误结果。`api()` 不受影响（内部自动 await
+discovery）。
+
 ## 文档
 
 - 仓库主页: 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-pHQLqpYF.cjs';
+import { R as RouteMeta } from './types-CnZrdSEb.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-pHQLqpYF.js';
+import { R as RouteMeta } from './types-CnZrdSEb.js';
 
 /**
  * @route-forge/core codegen CLI

package/dist/index.cjs

@@ -623,8 +623,16 @@ function createRouteForge(options) {
       effectiveEager = [...union];
     }
   });
-  autoDiscoveryPromise.catch(() => {
+  let autoDiscoveryError = null;
+  autoDiscoveryPromise.catch((e) => {
+    autoDiscoveryError = e;
   });
+  let autoDiscoveryCompleted = false;
+  let resolveReady;
+  const readyPromise = new Promise((resolve) => {
+    resolveReady = resolve;
+  });
+  const levelLoadedListeners = /* @__PURE__ */ new Map();
   const cacheTtl = cacheOpts.ttl ?? DEFAULT_CACHE_TTL;
   const cacheStorage = cacheOpts.storage ?? "memory";
   const cache = new RouteCache({ storage: cacheStorage, ttl: cacheTtl });
@@ -667,11 +675,20 @@ function createRouteForge(options) {
     return adapterObj;
   }
   const inflight = /* @__PURE__ */ new Map();
+  const invalidationGens = /* @__PURE__ */ new Map();
   function assertLevelDeclared(level) {
     if (!effectiveLevels.includes(level)) {
       throw new UnknownLevelError(level);
     }
   }
+  function assertDiscoveryReady() {
+    if (!autoDiscoveryCompleted && !explicitLevels?.length) {
+      throw new ForgeError(
+        "Route data not available. Auto-discovery has not completed. Use onSummaryReady callback to mount app, or await forge.ready / forge.load(level) first.",
+        { code: "RF_FE_010" }
+      );
+    }
+  }
   function buildUrl(level) {
     const base = baseURL.endsWith("/") ? baseURL.slice(0, -1) : baseURL;
     const ep = effectiveEndpoint.startsWith("/") ? effectiveEndpoint : `/${effectiveEndpoint}`;
@@ -706,10 +723,12 @@ function createRouteForge(options) {
     return data;
   }
   async function loadOne(level) {
+    if (autoDiscoveryError) throw autoDiscoveryError;
     assertLevelDeclared(level);
     if (cache.get(level)) return;
     const existing = inflight.get(level);
     if (existing) return existing;
+    const gen = invalidationGens.get(level) ?? 0;
     const p = (async () => {
       try {
         if (level === UNASSIGNED_LEVEL && !backendHasUnassignedLevel && summaryUnassigned) {
@@ -718,10 +737,16 @@ function createRouteForge(options) {
             routes[r.name] = { ...r, level: UNASSIGNED_LEVEL };
           }
           cache.set({ level: UNASSIGNED_LEVEL, routes, cache: null });
+          const listeners = levelLoadedListeners.get(level);
+          if (listeners) listeners.forEach((cb) => cb());
           return;
         }
         const resp = await fetchLevel(level);
-        cache.set(resp);
+        if ((invalidationGens.get(level) ?? 0) === gen) {
+          cache.set(resp);
+          const listeners = levelLoadedListeners.get(level);
+          if (listeners) listeners.forEach((cb) => cb());
+        }
       } finally {
         inflight.delete(level);
       }
@@ -735,6 +760,7 @@ function createRouteForge(options) {
     await Promise.all(list.map(loadOne));
   }
   function route(level, name, params) {
+    assertDiscoveryReady();
     const meta = findRouteMeta(level, name);
     if (!meta) {
       throw new UnknownRouteError(name, level);
@@ -765,12 +791,19 @@ function createRouteForge(options) {
       const optional = raw.endsWith("?");
       const name = optional ? raw.slice(0, -1) : raw;
       if (values[name] !== void 0) {
-        return encodeURIComponent(String(values[name]));
+        const val = values[name];
+        if (typeof val === "object") {
+          throw new ForgeError(
+            `Path parameter "${name}" must be a primitive value (string, number, boolean), got ${typeof val}`,
+            { code: "RF_FE_003", route: meta.name, context: { param: name, value: val } }
+          );
+        }
+        return encodeURIComponent(String(val));
       }
       return optional ? "" : match;
     });
     uri = uri.replace(/\/+/g, "/").replace(/\/$/, "");
-    if (effectiveUrlPrefix.includes("://")) {
+    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}`;
     }
@@ -866,10 +899,20 @@ function createRouteForge(options) {
   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);
+      for (const lvl of level) {
+        cache.del(lvl);
+        inflight.delete(lvl);
+        invalidationGens.set(lvl, (invalidationGens.get(lvl) ?? 0) + 1);
+      }
     } else {
       cache.del(level);
+      inflight.delete(level);
+      invalidationGens.set(level, (invalidationGens.get(level) ?? 0) + 1);
     }
   }
   function isLoaded(level) {
@@ -877,6 +920,7 @@ function createRouteForge(options) {
     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) {
@@ -885,7 +929,7 @@ function createRouteForge(options) {
       const routes = entry?.routes ?? {};
       const result2 = {};
       for (const [k, v] of Object.entries(routes)) {
-        result2[k] = { ...v };
+        result2[k] = JSON.parse(JSON.stringify(v));
       }
       return result2;
     }
@@ -895,7 +939,7 @@ function createRouteForge(options) {
       if (entry) {
         const levelRoutes = {};
         for (const [k, v] of Object.entries(entry.routes)) {
-          levelRoutes[k] = { ...v };
+          levelRoutes[k] = JSON.parse(JSON.stringify(v));
         }
         result[lvl] = levelRoutes;
       }
@@ -903,11 +947,15 @@ function createRouteForge(options) {
     return result;
   }
   void autoDiscoveryPromise.then(() => {
+    options.onSummaryReady?.();
     if (effectiveEager.length > 0) {
-      void Promise.all(effectiveEager.map((lvl) => load(lvl))).catch((e) => {
+      return Promise.all(effectiveEager.map((lvl) => load(lvl))).catch((e) => {
         console.warn(`[route-forge] eager load failed: ${e.message}`);
       });
     }
+  }).then(() => {
+    autoDiscoveryCompleted = true;
+    resolveReady();
   }).catch(() => {
   });
   return {
@@ -924,6 +972,14 @@ function createRouteForge(options) {
     interceptors: {
       request: requestInterceptors,
       response: responseInterceptors
+    },
+    ready: readyPromise,
+    onLevelLoaded(level, cb) {
+      if (!levelLoadedListeners.has(level)) {
+        levelLoadedListeners.set(level, /* @__PURE__ */ new Set());
+      }
+      levelLoadedListeners.get(level).add(cb);
+      return () => levelLoadedListeners.get(level)?.delete(cb);
     }
   };
 }