@route-forge/core 0.3.0 → 1.0.2

package/dist/{types-CBurRtGK.d.ts → types-DExMMUu1.d.ts}

@@ -1,7 +1,64 @@
+/**
+ * LoadingTracker：加载中标识状态管理
+ *
+ * 通过引用计数器跟踪并发请求数。
+ * - start()：计数器 +1，进入加载状态
+ * - stop()：计数器 -1，归零时退出加载状态
+ * - isLoading()：查询当前是否处于加载中
+ * - subscribe(cb)：监听状态变化，返回取消订阅函数
+ *
+ * @see .docs/SPEC.md §4.1.8
+ */
+/** 状态变更回调签名 */
+type LoadingChangeCallback = (event: LoadingChangeEvent) => void;
+/** 状态变更事件 */
+interface LoadingChangeEvent {
+    /** 当前是否仍处于加载中 */
+    loading: boolean;
+    /** 当前并发请求数 */
+    count: number;
+}
+/**
+ * 加载状态跟踪器
+ *
+ * 单一计数器，跟踪所有 API 请求的并发数。
+ * 不绑定任何 UI 样式，仅提供状态供框架层或业务层消费。
+ */
+declare class LoadingTracker {
+    /** 当前并发请求计数 */
+    private count;
+    /** 订阅者集合 */
+    private subscribers;
+    /**
+     * 开始一次加载（计数器 +1）
+     */
+    start(): void;
+    /**
+     * 结束一次加载（计数器 -1）
+     */
+    stop(): void;
+    /**
+     * 查询当前是否处于加载中
+     */
+    isLoading(): boolean;
+    /**
+     * 获取当前并发计数
+     */
+    getCount(): number;
+    /**
+     * 订阅加载状态变更
+     * @returns 取消订阅函数
+     */
+    subscribe(cb: LoadingChangeCallback): () => void;
+    /** 通知所有订阅者 */
+    private notify;
+}
+
 /**
  * @route-forge/core 核心类型定义
  * @see .docs/SPEC.md §4.1.3a, §4.1.1
  */
+
 /**
  * 路由元信息（后端 /_forge/routes/{level} 返回的单条路由结构）
  */
@@ -35,6 +92,8 @@ interface LevelRoutesResponse {
  * GET /_forge/routes 返回此结构
  */
 interface SummaryResponse {
+    /** manifest 协议版本号（DESIGN.md §6.3），默认 1；前端可据此做向前兼容 */
+    schemaVersion?: number;
     levels: Record<string, {
         description: string;
         load: 'lazy' | 'eager';
@@ -104,12 +163,23 @@ interface ApiCallParams {
     [paramName: string]: unknown;
     /** 显式指定路径参数（优先级最高，解决路径参数名与 query/body/headers 冲突的场景） */
     params?: Record<string, unknown>;
-    /** 查询参数，序列化到 URL query string */
-    query?: Record<string, unknown>;
-    /** 请求体，按 method 决定是否发送 */
+    /**
+     * 查询参数（对象 → query string）或路径参数（string | number → 填充 {query} 占位符）
+     * @see .docs/SPEC.md §4.1.3 参数智能解析
+     */
+    query?: Record<string, unknown> | string | number;
+    /**
+     * 请求体（非基元值 → body）或路径参数（string | number → 填充 {body} 占位符）
+     */
     body?: unknown;
-    /** 自定义请求头（与拦截器叠加） */
-    headers?: Record<string, string>;
+    /**
+     * 自定义请求头（对象 → headers）或路径参数（string | number → 填充 {headers} 占位符）
+     */
+    headers?: Record<string, string> | string | number;
+    /**
+     * 单次请求超时覆盖（毫秒）；不传时使用 createRouteForge({ timeout }) 全局值
+     */
+    timeout?: number;
 }
 /**
  * 缓存存储介质
@@ -165,12 +235,26 @@ interface RouteForge {
     route(level: string, name: string, params?: Record<string, unknown>): string;
     /** route() 的语义别名，适用于链接生成等场景 */
     url(level: string, name: string, params?: Record<string, unknown>): string;
-    /** 失效指定层级缓存；不传参失效全部 */
-    invalidate(level?: string): void;
+    /**
+     * 失效缓存：
+     * - invalidate()：失效全部层级
+     * - invalidate('admin')：失效指定层级
+     * - invalidate(['admin', 'manage'])：批量失效指定层级
+     */
+    invalidate(level?: string | string[]): void;
     /** 检查指定层级路由是否已加载并缓存；不传参检查全部 */
     isLoaded(level?: string): boolean;
-    /** 检查指定层级下某条路由是否存在（需该层级缓存已加载） */
+    /** 检查指定层级下某路由是否存在（需该层级缓存已加载） */
     hasRoute(level: string, name: string): boolean;
+    /**
+     * 查询加载中标识状态
+     */
+    isLoading(): boolean;
+    /**
+     * 订阅加载状态变更
+     * @returns 取消订阅函数
+     */
+    onLoadingChange(cb: LoadingChangeCallback): () => void;
     /**
      * 获取路由元信息快照（深拷贝，修改返回值不影响内部缓存）。
      * - getRoutes(level)：返回指定层级下全部路由
@@ -201,13 +285,19 @@ interface RouteForgeOptions {
         ttl?: number;
         storage?: CacheStorage;
     };
-    auth?: {
-        state?: () => boolean;
-        levels?: Record<string, boolean>;
-    };
     interceptors?: {
-        request?: Array<[((c: RequestConfig) => RequestConfig | Promise<RequestConfig>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
-        response?: Array<[((r: ResponseData) => unknown | Promise<unknown>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
+        /**
+         * 声明式请求拦截器列表，支持两种形式（SPEC §4.1.1）：
+         * - 单一函数 → 视为 onFulfilled
+         * - [onFulfilled?, onRejected?] 元组 → 完整拦截器定义
+         */
+        request?: Array<((c: RequestConfig) => RequestConfig | Promise<RequestConfig>) | [((c: RequestConfig) => RequestConfig | Promise<RequestConfig>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
+        /**
+         * 声明式响应拦截器列表，支持两种形式（SPEC §4.1.1）：
+         * - 单一函数 → 视为 onFulfilled
+         * - [onFulfilled?, onRejected?] 元组 → 完整拦截器定义
+         */
+        response?: Array<((r: ResponseData) => unknown | Promise<unknown>) | [((r: ResponseData) => unknown | Promise<unknown>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
     };
     strict?: boolean;
     timeout?: number;
@@ -248,4 +338,4 @@ type ForgeApiResponse<L extends string, N extends string> = [
     response: infer R;
 } ? R : unknown) : unknown : unknown;
 
-export type { AdapterOption as A, CacheStorage as C, Fetcher as F, InterceptorManager as I, LevelRoutesResponse as L, RouteMeta as R, SummaryResponse as S, InterceptorHandler as a, RouteForgeOptions as b, RouteForge as c, ApiCallParams as d, ForgeApiParams as e, ForgeApiResponse as f, ForgeRouteMap as g, ForgeRouteName as h, RequestConfig as i, ResponseData as j };
+export { type AdapterOption as A, 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 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 };

package/package.json

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