@route-forge/core 1.2.2 → 1.3.1

package/dist/{types-BcaNLA_l.d.cts → types-Cd1c1OdJ.d.cts}

@@ -146,6 +146,15 @@ interface ResponseData {
     data: unknown;
     config: RequestConfig;
 }
+/**
+ * forge.api() 返回的可取消请求对象。
+ * 继承 Promise，附加 abort() 方法用于取消请求。
+ * 内部自动创建 AbortController，用户无需手动管理。
+ */
+interface ForgeRequest<T = unknown> extends Promise<T> {
+    /** 取消请求。调用后请求将被中止，Promise reject 为 RequestAbortedError */
+    abort(): void;
+}
 /**
  * forge.api(level, name, params) 调用参数
  *
@@ -182,14 +191,6 @@ interface ApiCallParams {
      * 单次请求超时覆盖（毫秒）；不传时使用 createRouteForge({ timeout }) 全局值
      */
     timeout?: number;
-    /**
-     * 请求取消信号（AbortSignal）；调用 AbortController.abort() 即可取消请求
-     * @example
-     * const controller = new AbortController();
-     * forge.api('admin', 'users.index', { signal: controller.signal });
-     * controller.abort(); // 取消请求
-     */
-    signal?: AbortSignal;
 }
 /**
  * 缓存存储介质
@@ -238,7 +239,7 @@ interface InterceptorHandler<TIn, TOut = TIn> {
  */
 interface RouteForge {
     /** 通过层级 + 路由名调用 API；level 用于确定加载哪个层级的路由元信息 */
-    api(level: string, name: string, params?: ApiCallParams): Promise<unknown>;
+    api(level: string, name: string, params?: ApiCallParams): ForgeRequest;
     /** 拉取一个或多个层级（自动并发去重） */
     load(level: string | string[]): Promise<void>;
     /** 仅生成 URL，不发请求；level 用于定位路由所在的层级缓存 */
@@ -256,14 +257,9 @@ interface RouteForge {
     isLoaded(level?: string): boolean;
     /** 检查指定层级下某路由是否存在（需该层级缓存已加载） */
     hasRoute(level: string, name: string): boolean;
-    /**
-     * 查询加载中标识状态
-     */
+    /** 查询加载中标识状态 */
     isLoading(): boolean;
-    /**
-     * 订阅加载状态变更
-     * @returns 取消订阅函数
-     */
+    /** 订阅加载状态变更，返回取消订阅函数 */
     onLoadingChange(cb: LoadingChangeCallback): () => void;
     /**
      * 获取路由元信息快照（深拷贝，修改返回值不影响内部缓存）。
@@ -278,16 +274,24 @@ interface RouteForge {
         response: InterceptorManager<ResponseData, unknown>;
     };
     /**
-     * Promise，auto-discovery + eager load 完成后 resolve。
-     * 推荐用法：await forge.ready 后再调用 route() / hasRoute() 等同步方法。
+     * auto-discovery + eager load 完成后 resolve。
+     * 始终返回 Promise<this>，resolve 值为 forge 实例自身，支持链式调用。
+     *
+     * - 无参：返回 Promise，适合 async/await
+     * - 有参：回调内部走 then/catch，仍返回 Promise
      */
-    ready: Promise<void>;
+    ready(): Promise<RouteForge>;
+    ready(onFulfilled: (forge: RouteForge) => void, onRejected?: (error: unknown) => void): Promise<RouteForge>;
     /**
-     * 订阅指定层级路由元数据加载完成事件。
-     * 框架层（Vue/React）用于驱动响应式状态更新。
-     * @returns 取消订阅函数
+     * 绑定 level（+ 可选 prefix），返回 BoundForge。
+     * 唯一入口 — Vue/React/IIFE 共享同一套 API 表面。
+     *
+     * - use()：不绑定，返回 RouteForge 自身
+     * - use(level)：绑定 level
+     * - use(level, prefix)：绑定 level + prefix
      */
-    onLevelLoaded(level: string, cb: () => void): () => void;
+    use(): RouteForge;
+    use<L extends string>(level: L, prefix?: string): BoundForge;
 }
 /**
  * createRouteForge 配置项
@@ -369,46 +373,35 @@ type ForgeApiResponse<L extends string, N extends string> = [
     response: infer R;
 } ? R : unknown) : unknown : unknown;
 /**
- * 已绑定 level 时的共享方法集。
- * @typeParam L - 层级名（string literal）
- * @typeParam LevelLoaded - 框架层加载状态类型（Vue: Ref<boolean>, React: boolean）
+ * 已绑定 level 的 forge 对象。
+ * 由 `forge.use(level, prefix?)` 返回，Vue/React/IIFE 共享同一 API 表面。
+ *
+ * @typeParam LL - levelLoaded 的类型：core 默认 Promise<void>，Vue 替换为 Ref<boolean>
  */
-interface BoundForgeMethods<L extends string = string, LevelLoaded = unknown> {
-    /** 指定层级的路由元数据是否已加载完成（类型由框架层决定） */
-    levelLoaded: LevelLoaded;
-    api(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<ForgeApiResponse<L, ForgeRouteName<L>>>;
-    route(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): string;
-    url(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): string;
-    load(level: string | string[]): Promise<void>;
-    invalidate(level?: string | string[]): void;
-    isLoaded(level?: string): boolean;
-    hasRoute(level: string, name: string): boolean;
-    /** 查询加载中标识状态 */
-    isLoading(): boolean;
-    /** 订阅加载状态变更，返回取消订阅函数 */
-    onLoadingChange(cb: LoadingChangeCallback): () => void;
-    /** 获取指定层级下全部路由元信息（深拷贝，修改不影响内部缓存） */
-    getRoutes(level: string): Record<string, RouteMeta>;
-}
-/** 已绑定 level — 可直接调用（= api 快捷方式），无需传 level */
-interface BoundForgeTyped<L extends string, LevelLoaded = unknown> extends BoundForgeMethods<L, LevelLoaded> {
-    /** 当前绑定的 level 值 */
-    readonly level: L;
-    /** 路由名前缀（仅在传入 prefix 时存在） */
+interface BoundForge<LL = Promise<void>> {
+    /** 直接调用 = api 快捷方式，自动带绑定的 level */
+    (name: string, params?: ApiCallParams): ForgeRequest;
+    /** 当前绑定的 level */
+    readonly level: string;
+    /** 绑定的路由名前缀（仅传入 prefix 时存在） */
     readonly prefix?: string;
-    /** 直接调用 = forge.api() 快捷方式，自动带绑定的 level */
-    (name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<ForgeApiResponse<L, ForgeRouteName<L>>>;
-}
-/** 未绑定 level — 直接调用需要传 level（不提供 route/url/hasRoute/getRoutes 等同步方法） */
-interface ForgeInstanceTyped {
-    ready: Promise<void>;
-    api(level: string, name: string, params?: ApiCallParams): Promise<unknown>;
-    load(level: string | string[]): Promise<void>;
-    invalidate(level?: string | string[]): void;
-    isLoaded(level?: string): boolean;
+    /** level 加载状态（core: Promise<void>，Vue: Ref<boolean>） */
+    levelLoaded: LL;
+    api(name: string, params?: ApiCallParams): ForgeRequest;
+    route(name: string, params?: Record<string, unknown>): string;
+    url(name: string, params?: Record<string, unknown>): string;
+    hasRoute(name: string): boolean;
+    getRoutes(): Record<string, RouteMeta>;
+    load(): Promise<void>;
+    invalidate(): void;
+    isLoaded(): boolean;
     isLoading(): boolean;
     onLoadingChange(cb: LoadingChangeCallback): () => void;
-    onLevelLoaded(level: string, cb: () => void): () => void;
+    /** 等待绑定的 level 加载完成，resolve 值为自身（BoundForge），保证可安全调用 */
+    onLevelLoaded(): Promise<BoundForge<LL>>;
+    onLevelLoaded(onFulfilled: (bound: BoundForge<LL>) => void, onRejected?: (error: unknown) => void): Promise<BoundForge<LL>>;
+    /** 在已绑定 level 基础上追加/替换 prefix，返回新的 BoundForge */
+    useRoutePrefix(prefix: string): BoundForge<LL>;
 }
 /** call 函数签名 — 未绑定 level，需要显式传入 */
 interface UseForgeApiCall {
@@ -451,4 +444,4 @@ interface UseForgeByPrefixReturn {
     route: (suffix: string, params?: Record<string, unknown>) => string;
 }
 
-export { type AdapterOption as A, type BoundForgeMethods as B, type CacheStorage as C, type Fetcher as F, type InterceptorManager as I, type LevelRoutesResponse as L, type RouteMeta as R, type SummaryResponse as S, type UseForgeApiBoundCall as U, type InterceptorHandler as a, type RouteForgeOptions as b, type RouteForge as c, type ApiCallParams as d, type BoundForgeTyped as e, type ForgeApiParams as f, type ForgeApiResponse as g, type ForgeInstanceTyped as h, type ForgeRouteMap as i, type ForgeRouteName as j, type LoadingChangeCallback as k, type LoadingChangeEvent as l, LoadingTracker as m, type RequestConfig as n, type ResponseData as o, type UseForgeApiBoundReturn as p, type UseForgeApiCall as q, type UseForgeApiReturn as r, type UseForgeByPrefixReturn as s };
+export { type AdapterOption as A, type BoundForge as B, type CacheStorage as C, type Fetcher as F, type InterceptorManager as I, type LevelRoutesResponse as L, type RouteMeta as R, type SummaryResponse as S, type UseForgeApiBoundCall as U, type InterceptorHandler as a, type RouteForgeOptions as b, type RouteForge as c, type ApiCallParams as d, type ForgeApiParams as e, type ForgeApiResponse as f, type ForgeRequest as g, type ForgeRouteMap as h, type ForgeRouteName as i, type LoadingChangeCallback as j, type LoadingChangeEvent as k, LoadingTracker as l, type RequestConfig as m, type ResponseData as n, type UseForgeApiBoundReturn as o, type UseForgeApiCall as p, type UseForgeApiReturn as q, type UseForgeByPrefixReturn as r };

package/dist/{types-BcaNLA_l.d.ts → types-Cd1c1OdJ.d.ts}

@@ -146,6 +146,15 @@ interface ResponseData {
     data: unknown;
     config: RequestConfig;
 }
+/**
+ * forge.api() 返回的可取消请求对象。
+ * 继承 Promise，附加 abort() 方法用于取消请求。
+ * 内部自动创建 AbortController，用户无需手动管理。
+ */
+interface ForgeRequest<T = unknown> extends Promise<T> {
+    /** 取消请求。调用后请求将被中止，Promise reject 为 RequestAbortedError */
+    abort(): void;
+}
 /**
  * forge.api(level, name, params) 调用参数
  *
@@ -182,14 +191,6 @@ interface ApiCallParams {
      * 单次请求超时覆盖（毫秒）；不传时使用 createRouteForge({ timeout }) 全局值
      */
     timeout?: number;
-    /**
-     * 请求取消信号（AbortSignal）；调用 AbortController.abort() 即可取消请求
-     * @example
-     * const controller = new AbortController();
-     * forge.api('admin', 'users.index', { signal: controller.signal });
-     * controller.abort(); // 取消请求
-     */
-    signal?: AbortSignal;
 }
 /**
  * 缓存存储介质
@@ -238,7 +239,7 @@ interface InterceptorHandler<TIn, TOut = TIn> {
  */
 interface RouteForge {
     /** 通过层级 + 路由名调用 API；level 用于确定加载哪个层级的路由元信息 */
-    api(level: string, name: string, params?: ApiCallParams): Promise<unknown>;
+    api(level: string, name: string, params?: ApiCallParams): ForgeRequest;
     /** 拉取一个或多个层级（自动并发去重） */
     load(level: string | string[]): Promise<void>;
     /** 仅生成 URL，不发请求；level 用于定位路由所在的层级缓存 */
@@ -256,14 +257,9 @@ interface RouteForge {
     isLoaded(level?: string): boolean;
     /** 检查指定层级下某路由是否存在（需该层级缓存已加载） */
     hasRoute(level: string, name: string): boolean;
-    /**
-     * 查询加载中标识状态
-     */
+    /** 查询加载中标识状态 */
     isLoading(): boolean;
-    /**
-     * 订阅加载状态变更
-     * @returns 取消订阅函数
-     */
+    /** 订阅加载状态变更，返回取消订阅函数 */
     onLoadingChange(cb: LoadingChangeCallback): () => void;
     /**
      * 获取路由元信息快照（深拷贝，修改返回值不影响内部缓存）。
@@ -278,16 +274,24 @@ interface RouteForge {
         response: InterceptorManager<ResponseData, unknown>;
     };
     /**
-     * Promise，auto-discovery + eager load 完成后 resolve。
-     * 推荐用法：await forge.ready 后再调用 route() / hasRoute() 等同步方法。
+     * auto-discovery + eager load 完成后 resolve。
+     * 始终返回 Promise<this>，resolve 值为 forge 实例自身，支持链式调用。
+     *
+     * - 无参：返回 Promise，适合 async/await
+     * - 有参：回调内部走 then/catch，仍返回 Promise
      */
-    ready: Promise<void>;
+    ready(): Promise<RouteForge>;
+    ready(onFulfilled: (forge: RouteForge) => void, onRejected?: (error: unknown) => void): Promise<RouteForge>;
     /**
-     * 订阅指定层级路由元数据加载完成事件。
-     * 框架层（Vue/React）用于驱动响应式状态更新。
-     * @returns 取消订阅函数
+     * 绑定 level（+ 可选 prefix），返回 BoundForge。
+     * 唯一入口 — Vue/React/IIFE 共享同一套 API 表面。
+     *
+     * - use()：不绑定，返回 RouteForge 自身
+     * - use(level)：绑定 level
+     * - use(level, prefix)：绑定 level + prefix
      */
-    onLevelLoaded(level: string, cb: () => void): () => void;
+    use(): RouteForge;
+    use<L extends string>(level: L, prefix?: string): BoundForge;
 }
 /**
  * createRouteForge 配置项
@@ -369,46 +373,35 @@ type ForgeApiResponse<L extends string, N extends string> = [
     response: infer R;
 } ? R : unknown) : unknown : unknown;
 /**
- * 已绑定 level 时的共享方法集。
- * @typeParam L - 层级名（string literal）
- * @typeParam LevelLoaded - 框架层加载状态类型（Vue: Ref<boolean>, React: boolean）
+ * 已绑定 level 的 forge 对象。
+ * 由 `forge.use(level, prefix?)` 返回，Vue/React/IIFE 共享同一 API 表面。
+ *
+ * @typeParam LL - levelLoaded 的类型：core 默认 Promise<void>，Vue 替换为 Ref<boolean>
  */
-interface BoundForgeMethods<L extends string = string, LevelLoaded = unknown> {
-    /** 指定层级的路由元数据是否已加载完成（类型由框架层决定） */
-    levelLoaded: LevelLoaded;
-    api(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<ForgeApiResponse<L, ForgeRouteName<L>>>;
-    route(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): string;
-    url(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): string;
-    load(level: string | string[]): Promise<void>;
-    invalidate(level?: string | string[]): void;
-    isLoaded(level?: string): boolean;
-    hasRoute(level: string, name: string): boolean;
-    /** 查询加载中标识状态 */
-    isLoading(): boolean;
-    /** 订阅加载状态变更，返回取消订阅函数 */
-    onLoadingChange(cb: LoadingChangeCallback): () => void;
-    /** 获取指定层级下全部路由元信息（深拷贝，修改不影响内部缓存） */
-    getRoutes(level: string): Record<string, RouteMeta>;
-}
-/** 已绑定 level — 可直接调用（= api 快捷方式），无需传 level */
-interface BoundForgeTyped<L extends string, LevelLoaded = unknown> extends BoundForgeMethods<L, LevelLoaded> {
-    /** 当前绑定的 level 值 */
-    readonly level: L;
-    /** 路由名前缀（仅在传入 prefix 时存在） */
+interface BoundForge<LL = Promise<void>> {
+    /** 直接调用 = api 快捷方式，自动带绑定的 level */
+    (name: string, params?: ApiCallParams): ForgeRequest;
+    /** 当前绑定的 level */
+    readonly level: string;
+    /** 绑定的路由名前缀（仅传入 prefix 时存在） */
     readonly prefix?: string;
-    /** 直接调用 = forge.api() 快捷方式，自动带绑定的 level */
-    (name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<ForgeApiResponse<L, ForgeRouteName<L>>>;
-}
-/** 未绑定 level — 直接调用需要传 level（不提供 route/url/hasRoute/getRoutes 等同步方法） */
-interface ForgeInstanceTyped {
-    ready: Promise<void>;
-    api(level: string, name: string, params?: ApiCallParams): Promise<unknown>;
-    load(level: string | string[]): Promise<void>;
-    invalidate(level?: string | string[]): void;
-    isLoaded(level?: string): boolean;
+    /** level 加载状态（core: Promise<void>，Vue: Ref<boolean>） */
+    levelLoaded: LL;
+    api(name: string, params?: ApiCallParams): ForgeRequest;
+    route(name: string, params?: Record<string, unknown>): string;
+    url(name: string, params?: Record<string, unknown>): string;
+    hasRoute(name: string): boolean;
+    getRoutes(): Record<string, RouteMeta>;
+    load(): Promise<void>;
+    invalidate(): void;
+    isLoaded(): boolean;
     isLoading(): boolean;
     onLoadingChange(cb: LoadingChangeCallback): () => void;
-    onLevelLoaded(level: string, cb: () => void): () => void;
+    /** 等待绑定的 level 加载完成，resolve 值为自身（BoundForge），保证可安全调用 */
+    onLevelLoaded(): Promise<BoundForge<LL>>;
+    onLevelLoaded(onFulfilled: (bound: BoundForge<LL>) => void, onRejected?: (error: unknown) => void): Promise<BoundForge<LL>>;
+    /** 在已绑定 level 基础上追加/替换 prefix，返回新的 BoundForge */
+    useRoutePrefix(prefix: string): BoundForge<LL>;
 }
 /** call 函数签名 — 未绑定 level，需要显式传入 */
 interface UseForgeApiCall {
@@ -451,4 +444,4 @@ interface UseForgeByPrefixReturn {
     route: (suffix: string, params?: Record<string, unknown>) => string;
 }
 
-export { type AdapterOption as A, type BoundForgeMethods as B, type CacheStorage as C, type Fetcher as F, type InterceptorManager as I, type LevelRoutesResponse as L, type RouteMeta as R, type SummaryResponse as S, type UseForgeApiBoundCall as U, type InterceptorHandler as a, type RouteForgeOptions as b, type RouteForge as c, type ApiCallParams as d, type BoundForgeTyped as e, type ForgeApiParams as f, type ForgeApiResponse as g, type ForgeInstanceTyped as h, type ForgeRouteMap as i, type ForgeRouteName as j, type LoadingChangeCallback as k, type LoadingChangeEvent as l, LoadingTracker as m, type RequestConfig as n, type ResponseData as o, type UseForgeApiBoundReturn as p, type UseForgeApiCall as q, type UseForgeApiReturn as r, type UseForgeByPrefixReturn as s };
+export { type AdapterOption as A, type BoundForge as B, type CacheStorage as C, type Fetcher as F, type InterceptorManager as I, type LevelRoutesResponse as L, type RouteMeta as R, type SummaryResponse as S, type UseForgeApiBoundCall as U, type InterceptorHandler as a, type RouteForgeOptions as b, type RouteForge as c, type ApiCallParams as d, type ForgeApiParams as e, type ForgeApiResponse as f, type ForgeRequest as g, type ForgeRouteMap as h, type ForgeRouteName as i, type LoadingChangeCallback as j, type LoadingChangeEvent as k, LoadingTracker as l, type RequestConfig as m, type ResponseData as n, type UseForgeApiBoundReturn as o, type UseForgeApiCall as p, type UseForgeApiReturn as q, type UseForgeByPrefixReturn as r };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@route-forge/core",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "description": "框架无关的命名路由客户端核心：分级懒加载、隔离缓存、并发去重、拦截器",
   "license": "MIT",
   "author": "阿杰很厉害 <506907958@qq.com>",