@route-forge/core 1.2.2 → 1.3.0

package/README.md

@@ -210,26 +210,69 @@ const forge = createRouteForge({
 })
 ```
 
-### `forge.ready` Promise
+### `forge.ready()` 方法
 
-auto-discovery + eager load 完成后 resolve，适合 async/await 风格：
+auto-discovery + eager load 完成后 resolve，返回 `Promise<RouteForge>`（resolve 值为 forge 自身），适合 async/await 风格：
 
 ```ts
 const forge = createRouteForge({ endpoint: '/_forge/routes' })
-await forge.ready
+
+// 无参模式：直接 await
+await forge.ready()
 // 路由数据已就绪，可安全调用 route() / hasRoute()
+
+// 回调模式：onFulfilled / onRejected
+forge.ready(
+  (f) => { console.log('ready!', f) },
+  (err) => { console.error(err) }
+)
+
+// 链式调用：ready 返回 forge 自身
+const bound = await forge.ready().then(f => f.use('admin'))
 ```
 
-### `onLevelLoaded` 订阅
+### `forge.use(level?, prefix?)` 层级绑定
 
-订阅指定 level 加载完成事件：
+`forge.use()` 是 core 层唯一的 level 绑定入口，返回 `BoundForge` 对象：
 
 ```ts
-const unsub = forge.onLevelLoaded('admin', () => {
-  console.log('admin level loaded')
-})
-// 取消订阅
-unsub()
+// 绑定层级 — 自动触发 load，提供快捷方法
+const bound = forge.use('admin')
+bound('users.show', { user: 1 })   // 可直接调用（= bound.api()）
+bound.route('users.show')           // URL 生成
+bound.level                         // → 'admin'
+bound.levelLoaded                   // Promise<void>
+
+// 绑定层级 + 前缀 — 路由名自动拼接
+const bound = forge.use('admin', 'users')
+bound('show', { user: 1 })           // → forge.api('admin', 'users.show', ...)
+
+// BoundForge 独有方法
+await bound.onLevelLoaded()          // 等待 level 加载完成
+const prefixed = bound.useRoutePrefix('posts')  // 追加前缀
+```
+
+### IIFE 浏览器用法
+
+通过 `<script>` 标签引入后，`RouteForge` 全局可用：
+
+```html
+<script src="https://unpkg.com/@route-forge/core"></script>
+<script>
+  const forge = RouteForge.createRouteForge({
+    endpoint: '/_forge/routes',
+  })
+
+  // 等待就绪后绑定层级
+  forge.ready().then(function(f) {
+    const admin = f.use('admin')
+    return admin.onLevelLoaded()
+  }).then(function(bound) {
+    return bound('users.show', { user: 1 })
+  }).then(function(data) {
+    console.log(data)
+  })
+</script>
 ```
 
 ### Auto-discovery 守卫

package/dist/codegen.d.cts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { R as RouteMeta } from './types-BcaNLA_l.cjs';
+import { R as RouteMeta } from './types-D4PMbR4-.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-BcaNLA_l.js';
+import { R as RouteMeta } from './types-D4PMbR4-.js';
 
 /**
  * @route-forge/core codegen CLI

package/dist/index.cjs

@@ -467,6 +467,39 @@ async function resolveAdapter(opts) {
   return createBuiltinHttp(opts.forgeInterceptors);
 }
 
+// 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);
+}
+
+// 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;
+}
+
 // src/loading.ts
 var LoadingTracker = class {
   constructor() {
@@ -633,7 +666,6 @@ function createRouteForge(options) {
   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 });
@@ -685,7 +717,7 @@ function createRouteForge(options) {
   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.",
+        "Route data not available. Auto-discovery has not completed. Use forge.ready() or forge.use(level) first.",
         { code: "RF_FE_010" }
       );
     }
@@ -738,15 +770,11 @@ 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);
         if ((invalidationGens.get(level) ?? 0) === gen) {
           cache.set(resp);
-          const listeners = levelLoadedListeners.get(level);
-          if (listeners) listeners.forEach((cb) => cb());
         }
       } finally {
         inflight.delete(level);
@@ -948,6 +976,7 @@ function createRouteForge(options) {
     return result;
   }
   void autoDiscoveryPromise.then(() => {
+    autoDiscoveryCompleted = true;
     options.onSummaryReady?.();
     if (effectiveEager.length > 0) {
       return Promise.all(effectiveEager.map((lvl) => load(lvl))).catch((e) => {
@@ -955,11 +984,74 @@ function createRouteForge(options) {
       });
     }
   }).then(() => {
-    autoDiscoveryCompleted = true;
-    resolveReady();
+    resolveReady(forgeInstance);
   }).catch(() => {
   });
-  return {
+  function ready(onFulfilled, onRejected) {
+    if (onFulfilled) {
+      const p = readyPromise.then(onFulfilled, onRejected);
+      return p.then(() => forgeInstance);
+    }
+    return readyPromise;
+  }
+  const forgeResolver = { load, hasRoute };
+  function createBoundForge(level, prefix) {
+    const levelLoadedPromise = load(level).catch(() => {
+    });
+    const apiFn = prefix ? (name, params) => resolveRouteName(forgeResolver, level, prefix, name).then(
+      (resolved) => api(level, resolved, params)
+    ) : (name, params) => api(level, name, params);
+    const callable = apiFn;
+    defineImmutableProps(callable, {
+      level,
+      ...prefix !== void 0 ? { prefix } : {},
+      api: apiFn,
+      route: prefix ? (name, params) => route(level, resolveRouteNameSync(forgeResolver, level, prefix, name), params) : (name, params) => route(level, name, params),
+      url: prefix ? (name, params) => route(level, resolveRouteNameSync(forgeResolver, level, prefix, name), params) : (name, params) => route(level, name, params),
+      hasRoute: (name) => hasRoute(level, name),
+      getRoutes: () => getRoutes(level),
+      load: () => load(level),
+      invalidate: () => invalidate(level),
+      isLoaded: () => isLoaded(level),
+      isLoading: () => loadingTracker.isLoading(),
+      onLoadingChange: (cb) => loadingTracker.subscribe(cb)
+    });
+    Object.defineProperty(callable, "levelLoaded", {
+      value: levelLoadedPromise,
+      writable: false,
+      enumerable: true,
+      configurable: true
+    });
+    return callable;
+  }
+  function boundOnLevelLoaded(bound, levelLoadedPromise, onFulfilled, onRejected) {
+    const p = levelLoadedPromise.then(() => bound);
+    if (onFulfilled) {
+      return p.then(onFulfilled, onRejected).then(() => bound);
+    }
+    return p;
+  }
+  function attachBoundMethods(bound, levelLoadedPromise, level) {
+    Object.defineProperty(bound, "onLevelLoaded", {
+      value: (onFulfilled, onRejected) => boundOnLevelLoaded(bound, levelLoadedPromise, onFulfilled, onRejected),
+      writable: false,
+      enumerable: false,
+      configurable: false
+    });
+    Object.defineProperty(bound, "useRoutePrefix", {
+      value: (prefix) => createBoundForgeWithMethods(level, prefix),
+      writable: false,
+      enumerable: false,
+      configurable: false
+    });
+  }
+  function createBoundForgeWithMethods(level, prefix) {
+    const bound = createBoundForge(level, prefix);
+    const levelLoadedPromise = bound.levelLoaded;
+    attachBoundMethods(bound, levelLoadedPromise, level);
+    return bound;
+  }
+  const forgeInstance = {
     api,
     load,
     route,
@@ -974,15 +1066,13 @@ function createRouteForge(options) {
       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);
+    ready,
+    use(level, prefix) {
+      if (level === void 0) return forgeInstance;
+      return createBoundForgeWithMethods(level, prefix);
     }
   };
+  return forgeInstance;
 }
 function pickMethod(meta) {
   const m = meta.methods.find((x) => x.toUpperCase() !== "HEAD");
@@ -1050,25 +1140,6 @@ 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;