@route-forge/core 1.1.0 → 1.2.0

package/README.md

@@ -186,11 +186,63 @@ 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
-- 设计文档: https://github.com/xyj2156/route-forge/blob/main/.docs/DESIGN.md
-- 规范: https://github.com/xyj2156/route-forge/blob/main/.docs/SPEC.md
+- 仓库主页: https://github.com/route-forge/route-forge
+- 设计文档: https://github.com/route-forge/route-forge/blob/main/.docs/DESIGN.md
+- 规范: https://github.com/route-forge/route-forge/blob/main/.docs/SPEC.md
 
 ## License
 

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-CMouq7zD.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-CMouq7zD.js';
 
 /**
  * @route-forge/core codegen CLI

package/dist/defineImmutableProps.cjs

@@ -0,0 +1,19 @@
+'use strict';
+
+// 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;
+}
+
+exports.defineImmutableProps = defineImmutableProps;
+//# sourceMappingURL=defineImmutableProps.cjs.map
+//# sourceMappingURL=defineImmutableProps.cjs.map

package/dist/defineImmutableProps.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/defineImmutableProps.ts"],"names":[],"mappings":";;;AAOO,SAAS,oBAAA,CAAuC,QAAW,KAAA,EAAmC;AACnG,EAAA,KAAA,MAAW,GAAA,IAAO,MAAA,CAAO,IAAA,CAAK,KAAK,CAAA,EAAG;AACpC,IAAA,MAAM,GAAA,GAAM,MAAM,GAAG,CAAA;AACrB,IAAA,MAAA,CAAO,cAAA,CAAe,QAAQ,GAAA,EAAK;AAAA,MACjC,KAAA,EAAO,QAAQ,IAAA,IAAQ,OAAO,QAAQ,QAAA,GAAW,MAAA,CAAO,MAAA,CAAO,GAAG,CAAA,GAAI,GAAA;AAAA,MACtE,QAAA,EAAU,KAAA;AAAA,MACV,UAAA,EAAY,KAAA;AAAA,MACZ,YAAA,EAAc;AAAA,KACf,CAAA;AAAA,EACH;AACA,EAAA,OAAO,MAAA;AACT","file":"defineImmutableProps.cjs","sourcesContent":["/**\n * 以不可变、不可枚举、不可重配置的方式将属性挂载到目标对象上。\n * 相比 Object.assign 更安全——外部无法通过遍历/删除/重写篡改这些方法。\n * 对象类型的值会浅冻结（Object.freeze），防止内部键被增删改。\n *\n * @internal 仅供框架适配层（vue/react）内部使用，不作为公共 API 导出\n */\nexport function defineImmutableProps<T extends object>(target: T, props: Record<string, unknown>): T {\n  for (const key of Object.keys(props)) {\n    const val = props[key];\n    Object.defineProperty(target, key, {\n      value: val !== null && typeof val === 'object' ? Object.freeze(val) : val,\n      writable: false,\n      enumerable: false,\n      configurable: false,\n    });\n  }\n  return target;\n}\n"]}

package/dist/defineImmutableProps.d.cts

@@ -0,0 +1,10 @@
+/**
+ * 以不可变、不可枚举、不可重配置的方式将属性挂载到目标对象上。
+ * 相比 Object.assign 更安全——外部无法通过遍历/删除/重写篡改这些方法。
+ * 对象类型的值会浅冻结（Object.freeze），防止内部键被增删改。
+ *
+ * @internal 仅供框架适配层（vue/react）内部使用，不作为公共 API 导出
+ */
+declare function defineImmutableProps<T extends object>(target: T, props: Record<string, unknown>): T;
+
+export { defineImmutableProps };

package/dist/defineImmutableProps.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 以不可变、不可枚举、不可重配置的方式将属性挂载到目标对象上。
+ * 相比 Object.assign 更安全——外部无法通过遍历/删除/重写篡改这些方法。
+ * 对象类型的值会浅冻结（Object.freeze），防止内部键被增删改。
+ *
+ * @internal 仅供框架适配层（vue/react）内部使用，不作为公共 API 导出
+ */
+declare function defineImmutableProps<T extends object>(target: T, props: Record<string, unknown>): T;
+
+export { defineImmutableProps };

package/dist/defineImmutableProps.js

@@ -0,0 +1,17 @@
+// 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;
+}
+
+export { defineImmutableProps };
+//# sourceMappingURL=defineImmutableProps.js.map
+//# sourceMappingURL=defineImmutableProps.js.map

package/dist/defineImmutableProps.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/defineImmutableProps.ts"],"names":[],"mappings":";AAOO,SAAS,oBAAA,CAAuC,QAAW,KAAA,EAAmC;AACnG,EAAA,KAAA,MAAW,GAAA,IAAO,MAAA,CAAO,IAAA,CAAK,KAAK,CAAA,EAAG;AACpC,IAAA,MAAM,GAAA,GAAM,MAAM,GAAG,CAAA;AACrB,IAAA,MAAA,CAAO,cAAA,CAAe,QAAQ,GAAA,EAAK;AAAA,MACjC,KAAA,EAAO,QAAQ,IAAA,IAAQ,OAAO,QAAQ,QAAA,GAAW,MAAA,CAAO,MAAA,CAAO,GAAG,CAAA,GAAI,GAAA;AAAA,MACtE,QAAA,EAAU,KAAA;AAAA,MACV,UAAA,EAAY,KAAA;AAAA,MACZ,YAAA,EAAc;AAAA,KACf,CAAA;AAAA,EACH;AACA,EAAA,OAAO,MAAA;AACT","file":"defineImmutableProps.js","sourcesContent":["/**\n * 以不可变、不可枚举、不可重配置的方式将属性挂载到目标对象上。\n * 相比 Object.assign 更安全——外部无法通过遍历/删除/重写篡改这些方法。\n * 对象类型的值会浅冻结（Object.freeze），防止内部键被增删改。\n *\n * @internal 仅供框架适配层（vue/react）内部使用，不作为公共 API 导出\n */\nexport function defineImmutableProps<T extends object>(target: T, props: Record<string, unknown>): T {\n  for (const key of Object.keys(props)) {\n    const val = props[key];\n    Object.defineProperty(target, key, {\n      value: val !== null && typeof val === 'object' ? Object.freeze(val) : val,\n      writable: false,\n      enumerable: false,\n      configurable: false,\n    });\n  }\n  return target;\n}\n"]}

package/dist/index.cjs

@@ -389,10 +389,11 @@ function toHeaders(raw) {
 }
 async function wrapAxiosAdapter() {
   let axios;
+  const axiosModule = "axios";
   try {
     const mod = await import(
       /* @vite-ignore */
-      'axios'
+      axiosModule
     );
     axios = mod.default ?? mod;
   } catch {
@@ -623,8 +624,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 +676,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 +724,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 +738,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 +761,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 +792,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 +900,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 +921,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 +930,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 +940,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 +948,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 +973,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);
     }
   };
 }
@@ -993,6 +1050,25 @@ function isAbortError2(err, signal) {
   return false;
 }
 
+// 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);
+}
+
 exports.AdapterNotFoundError = AdapterNotFoundError;
 exports.ForgeError = ForgeError;
 exports.HTTPError = HTTPError;
@@ -1007,5 +1083,7 @@ exports.UnknownLevelError = UnknownLevelError;
 exports.UnknownRouteError = UnknownRouteError;
 exports.createInterceptorManager = createInterceptorManager;
 exports.createRouteForge = createRouteForge;
+exports.resolveRouteName = resolveRouteName;
+exports.resolveRouteNameSync = resolveRouteNameSync;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map