@route-forge/core 1.3.0 → 1.4.0

package/dist/{types-D4PMbR4-.d.cts → types-BFlrOTrN.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 用于定位路由所在的层级缓存 */
@@ -323,6 +324,13 @@ interface RouteForgeOptions {
          */
         response?: Array<((r: ResponseData) => unknown | Promise<unknown>) | [((r: ResponseData) => unknown | Promise<unknown>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
     };
+    /**
+     * @deprecated 前端校验始终开启，此选项不再被消费。
+     * 前端在层级未声明时始终抛 `UnknownLevelError`、路由名不存在始终抛 `UnknownRouteError`、
+     * 必填路径参数缺失始终抛 `MissingRouteParamError` —— 校验行为与 strict 无关，静默忽略会掩盖拼写错误、难以排查。
+     * 后端 `strict_mode` 的宽松/严格语义（未命中层级路由是否归入 unassigned/fallback）由后端在生成 manifest 时决定。
+     * 字段保留仅为向后兼容，传入不会有任何效果。
+     */
     strict?: boolean;
     timeout?: number;
     baseURL?: string;
@@ -379,14 +387,14 @@ type ForgeApiResponse<L extends string, N extends string> = [
  */
 interface BoundForge<LL = Promise<void>> {
     /** 直接调用 = api 快捷方式，自动带绑定的 level */
-    (name: string, params?: ApiCallParams): Promise<unknown>;
+    (name: string, params?: ApiCallParams): ForgeRequest;
     /** 当前绑定的 level */
     readonly level: string;
     /** 绑定的路由名前缀（仅传入 prefix 时存在） */
     readonly prefix?: string;
     /** level 加载状态（core: Promise<void>，Vue: Ref<boolean>） */
     levelLoaded: LL;
-    api(name: string, params?: ApiCallParams): Promise<unknown>;
+    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;
@@ -443,4 +451,4 @@ interface UseForgeByPrefixReturn {
     route: (suffix: string, params?: Record<string, unknown>) => string;
 }
 
-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 ForgeRouteMap as g, type ForgeRouteName as h, type LoadingChangeCallback as i, type LoadingChangeEvent as j, LoadingTracker as k, type RequestConfig as l, type ResponseData as m, type UseForgeApiBoundReturn as n, type UseForgeApiCall as o, type UseForgeApiReturn as p, type UseForgeByPrefixReturn as q };
+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-D4PMbR4-.d.ts → types-BFlrOTrN.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 用于定位路由所在的层级缓存 */
@@ -323,6 +324,13 @@ interface RouteForgeOptions {
          */
         response?: Array<((r: ResponseData) => unknown | Promise<unknown>) | [((r: ResponseData) => unknown | Promise<unknown>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
     };
+    /**
+     * @deprecated 前端校验始终开启，此选项不再被消费。
+     * 前端在层级未声明时始终抛 `UnknownLevelError`、路由名不存在始终抛 `UnknownRouteError`、
+     * 必填路径参数缺失始终抛 `MissingRouteParamError` —— 校验行为与 strict 无关，静默忽略会掩盖拼写错误、难以排查。
+     * 后端 `strict_mode` 的宽松/严格语义（未命中层级路由是否归入 unassigned/fallback）由后端在生成 manifest 时决定。
+     * 字段保留仅为向后兼容，传入不会有任何效果。
+     */
     strict?: boolean;
     timeout?: number;
     baseURL?: string;
@@ -379,14 +387,14 @@ type ForgeApiResponse<L extends string, N extends string> = [
  */
 interface BoundForge<LL = Promise<void>> {
     /** 直接调用 = api 快捷方式，自动带绑定的 level */
-    (name: string, params?: ApiCallParams): Promise<unknown>;
+    (name: string, params?: ApiCallParams): ForgeRequest;
     /** 当前绑定的 level */
     readonly level: string;
     /** 绑定的路由名前缀（仅传入 prefix 时存在） */
     readonly prefix?: string;
     /** level 加载状态（core: Promise<void>，Vue: Ref<boolean>） */
     levelLoaded: LL;
-    api(name: string, params?: ApiCallParams): Promise<unknown>;
+    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;
@@ -443,4 +451,4 @@ interface UseForgeByPrefixReturn {
     route: (suffix: string, params?: Record<string, unknown>) => string;
 }
 
-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 ForgeRouteMap as g, type ForgeRouteName as h, type LoadingChangeCallback as i, type LoadingChangeEvent as j, LoadingTracker as k, type RequestConfig as l, type ResponseData as m, type UseForgeApiBoundReturn as n, type UseForgeApiCall as o, type UseForgeApiReturn as p, type UseForgeByPrefixReturn as q };
+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.3.0",
+  "version": "1.4.0",
   "description": "框架无关的命名路由客户端核心：分级懒加载、隔离缓存、并发去重、拦截器",
   "license": "MIT",
   "author": "阿杰很厉害 <506907958@qq.com>",