@route-forge/core 1.4.0 → 2.1.0

package/dist/index.d.cts

@@ -1,5 +1,19 @@
-import { I as InterceptorManager, a as InterceptorHandler, C as CacheStorage, R as RouteMeta, L as LevelRoutesResponse, b as RouteForgeOptions, c as RouteForge } from './types-BFlrOTrN.cjs';
-export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher, e as ForgeApiParams, f as ForgeApiResponse, g as ForgeRequest, h as ForgeRouteMap, i as ForgeRouteName, j as LoadingChangeCallback, k as LoadingChangeEvent, l as LoadingTracker, m as RequestConfig, n as ResponseData, S as SummaryResponse, U as UseForgeApiBoundCall, o as UseForgeApiBoundReturn, p as UseForgeApiCall, q as UseForgeApiReturn, r as UseForgeByPrefixReturn } from './types-BFlrOTrN.cjs';
+import { a as RouteForgeOptions, b as RouteForge, I as InterceptorManager, c as InterceptorHandler, C as CacheStorage, R as RouteMeta, L as LevelRoutesResponse } from './types-C51rXaiY.cjs';
+export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher, e as ForgeApiParams, f as ForgeApiResponse, g as ForgeRequest, h as ForgeRouteMap, i as ForgeRouteName, j as LoadingChangeCallback, k as LoadingChangeEvent, l as LoadingTracker, m as RequestConfig, n as ResponseData, S as SummaryResponse, U as UseForgeApiBoundCall, o as UseForgeApiBoundReturn, p as UseForgeApiCall, q as UseForgeApiReturn } from './types-C51rXaiY.cjs';
+
+/**
+ * Route Forge 主入口：createRouteForge
+ * @see .docs/SPEC.md §4.1.1 ~ §4.1.4
+ *
+ * 能力清单（v1.0 MVP）：
+ *   - 按层级懒加载与隔离缓存（§4.1.2）
+ *   - 并发去重（§4.1.4）
+ *   - 通过路由名调用 API（§4.1.3）
+ *   - 拦截器（§4.1.3a）
+ *   - Adapter auto 检测 / builtin / axios / 自定义 Fetcher（§4.3）
+ */
+
+declare function createRouteForge(options: RouteForgeOptions): RouteForge;
 
 /**
  * 拦截器管理器实现
@@ -45,6 +59,10 @@ declare function createInterceptorManager<TIn, TOut = TIn>(): InterceptorManager
  * - 每层级独立条目，互不污染（cache key = `route-forge:${level}`）
  * - TTL 优先用后端响应里的 cache 字段，本地 cache.ttl 仅作兜底
  * - storage: 'memory' | 'sessionStorage' | 'localStorage'
+ * - storage 模式下维护内存镜像：首次读盘解析后驻留内存，后续 get 直接命中
+ *   （读盘 + JSON.parse 整层路由表是同步阻塞操作，热路径重复执行代价高）；
+ *   写操作（set/del/clear）同步更新镜像，并通过 storage 事件感知其他
+ *   tab 的写入/失效，保证跨 tab 新鲜度与无镜像时一致
  */
 
 interface CacheEntry {
@@ -58,6 +76,8 @@ declare class RouteCache {
     private readonly fallbackTtl;
     private readonly backend;
     private readonly memory;
+    /** 其他 tab 修改 storage 时失效对应镜像（storage 事件：自己的写不触发，自己的写经 set/del 已同步） */
+    private readonly onStorageEvent;
     constructor(opts: {
         storage: CacheStorage;
         ttl: number;
@@ -71,6 +91,37 @@ declare class RouteCache {
     private isExpired;
 }
 
+/**
+ * 智能路由名前缀解析
+ *
+ * 当前缀与后缀拼接产生歧义时（后缀本身已以前缀开头），
+ * 通过查询已加载路由表来判定正确名称：
+ *   - 优先尝试 prefix + sep + suffix（完整拼接）
+ *   - 若不存在则回退到 suffix（视为已含前缀）
+ *   - 均不存在则抛 UnknownRouteError
+ *
+ * @see .docs/SPEC.md §4.1.7
+ */
+/**
+ * 路由名解析所需的最小 forge 接口。
+ * 仅依赖 load() 和 hasRoute()，不依赖拦截器等完整能力。
+ * 兼容 RouteForge、BoundForgeTyped、ForgeInstanceTyped 等所有形态。
+ */
+interface RouteResolver {
+    load(level: string | string[]): Promise<void>;
+    hasRoute(level: string, name: string): boolean;
+}
+/**
+ * 异步版本：先确保层级已加载，再做歧义消解。
+ * 适用于 api() 调用路径。
+ */
+declare function resolveRouteName(forge: RouteResolver, level: string, prefix: string, suffix: string, separator?: string): Promise<string>;
+/**
+ * 同步版本：基于已加载缓存做歧义消解。
+ * 适用于 route() / url() 调用路径（要求层级已加载）。
+ */
+declare function resolveRouteNameSync(forge: RouteResolver, level: string, prefix: string, suffix: string, separator?: string): string;
+
 /**
  * Route Forge 错误基类与具体错误类
  * @see .docs/SPEC.md §6
@@ -78,14 +129,19 @@ declare class RouteCache {
 interface ForgeErrorContext {
     [key: string]: unknown;
 }
+/**
+ * Route Forge 错误码字面量联合。
+ * 用户侧 `switch (e.code)` 可获得穷尽检查（漏分支编译报错）。
+ */
+type ForgeErrorCode = 'RF_FE_001' | 'RF_FE_002' | 'RF_FE_003' | 'RF_FE_005' | 'RF_FE_006' | 'RF_FE_007' | 'RF_FE_008' | 'RF_FE_009' | 'RF_FE_010';
 declare class ForgeError extends Error {
-    readonly code: string;
+    readonly code: ForgeErrorCode;
     readonly route?: string;
     readonly level?: string;
     readonly context?: ForgeErrorContext;
     readonly cause?: unknown;
     constructor(message: string, opts: {
-        code: string;
+        code: ForgeErrorCode;
         route?: string;
         level?: string;
         context?: ForgeErrorContext;
@@ -132,49 +188,4 @@ declare class RequestAbortedError extends ForgeError {
     constructor(route?: string, level?: string, cause?: unknown);
 }
 
-/**
- * Route Forge 主入口：createRouteForge
- * @see .docs/SPEC.md §4.1.1 ~ §4.1.4
- *
- * 能力清单（v1.0 MVP）：
- *   - 按层级懒加载与隔离缓存（§4.1.2）
- *   - 并发去重（§4.1.4）
- *   - 通过路由名调用 API（§4.1.3）
- *   - 拦截器（§4.1.3a）
- *   - Adapter auto 检测 / builtin / axios / 自定义 Fetcher（§4.3）
- */
-
-declare function createRouteForge(options: RouteForgeOptions): RouteForge;
-
-/**
- * 智能路由名前缀解析
- *
- * 当前缀与后缀拼接产生歧义时（后缀本身已以前缀开头），
- * 通过查询已加载路由表来判定正确名称：
- *   - 优先尝试 prefix + sep + suffix（完整拼接）
- *   - 若不存在则回退到 suffix（视为已含前缀）
- *   - 均不存在则抛 UnknownRouteError
- *
- * @see .docs/SPEC.md §4.1.7
- */
-/**
- * 路由名解析所需的最小 forge 接口。
- * 仅依赖 load() 和 hasRoute()，不依赖拦截器等完整能力。
- * 兼容 RouteForge、BoundForgeTyped、ForgeInstanceTyped 等所有形态。
- */
-interface RouteResolver {
-    load(level: string | string[]): Promise<void>;
-    hasRoute(level: string, name: string): boolean;
-}
-/**
- * 异步版本：先确保层级已加载，再做歧义消解。
- * 适用于 api() 调用路径。
- */
-declare function resolveRouteName(forge: RouteResolver, level: string, prefix: string, suffix: string, separator?: string): Promise<string>;
-/**
- * 同步版本：基于已加载缓存做歧义消解。
- * 适用于 route() / url() 调用路径（要求层级已加载）。
- */
-declare function resolveRouteNameSync(forge: RouteResolver, level: string, prefix: string, suffix: string, separator?: string): string;
-
-export { AdapterNotFoundError, CacheStorage, ForgeError, HTTPError, InterceptorHandler, InterceptorManager, InterceptorManagerImpl, InvalidInterceptorReturnError, LevelRoutesResponse, MissingRouteParamError, NetworkError, RequestAbortedError, RouteCache, RouteForge, RouteForgeOptions, RouteMeta, type RouteResolver, UnknownLevelError, UnknownRouteError, createInterceptorManager, createRouteForge, resolveRouteName, resolveRouteNameSync };
+export { AdapterNotFoundError, CacheStorage, ForgeError, type ForgeErrorCode, HTTPError, InterceptorHandler, InterceptorManager, InterceptorManagerImpl, InvalidInterceptorReturnError, LevelRoutesResponse, MissingRouteParamError, NetworkError, RequestAbortedError, RouteCache, RouteForge, RouteForgeOptions, RouteMeta, type RouteResolver, UnknownLevelError, UnknownRouteError, createInterceptorManager, createRouteForge, resolveRouteName, resolveRouteNameSync };

package/dist/index.d.ts

@@ -1,5 +1,19 @@
-import { I as InterceptorManager, a as InterceptorHandler, C as CacheStorage, R as RouteMeta, L as LevelRoutesResponse, b as RouteForgeOptions, c as RouteForge } from './types-BFlrOTrN.js';
-export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher, e as ForgeApiParams, f as ForgeApiResponse, g as ForgeRequest, h as ForgeRouteMap, i as ForgeRouteName, j as LoadingChangeCallback, k as LoadingChangeEvent, l as LoadingTracker, m as RequestConfig, n as ResponseData, S as SummaryResponse, U as UseForgeApiBoundCall, o as UseForgeApiBoundReturn, p as UseForgeApiCall, q as UseForgeApiReturn, r as UseForgeByPrefixReturn } from './types-BFlrOTrN.js';
+import { a as RouteForgeOptions, b as RouteForge, I as InterceptorManager, c as InterceptorHandler, C as CacheStorage, R as RouteMeta, L as LevelRoutesResponse } from './types-C51rXaiY.js';
+export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher, e as ForgeApiParams, f as ForgeApiResponse, g as ForgeRequest, h as ForgeRouteMap, i as ForgeRouteName, j as LoadingChangeCallback, k as LoadingChangeEvent, l as LoadingTracker, m as RequestConfig, n as ResponseData, S as SummaryResponse, U as UseForgeApiBoundCall, o as UseForgeApiBoundReturn, p as UseForgeApiCall, q as UseForgeApiReturn } from './types-C51rXaiY.js';
+
+/**
+ * Route Forge 主入口：createRouteForge
+ * @see .docs/SPEC.md §4.1.1 ~ §4.1.4
+ *
+ * 能力清单（v1.0 MVP）：
+ *   - 按层级懒加载与隔离缓存（§4.1.2）
+ *   - 并发去重（§4.1.4）
+ *   - 通过路由名调用 API（§4.1.3）
+ *   - 拦截器（§4.1.3a）
+ *   - Adapter auto 检测 / builtin / axios / 自定义 Fetcher（§4.3）
+ */
+
+declare function createRouteForge(options: RouteForgeOptions): RouteForge;
 
 /**
  * 拦截器管理器实现
@@ -45,6 +59,10 @@ declare function createInterceptorManager<TIn, TOut = TIn>(): InterceptorManager
  * - 每层级独立条目，互不污染（cache key = `route-forge:${level}`）
  * - TTL 优先用后端响应里的 cache 字段，本地 cache.ttl 仅作兜底
  * - storage: 'memory' | 'sessionStorage' | 'localStorage'
+ * - storage 模式下维护内存镜像：首次读盘解析后驻留内存，后续 get 直接命中
+ *   （读盘 + JSON.parse 整层路由表是同步阻塞操作，热路径重复执行代价高）；
+ *   写操作（set/del/clear）同步更新镜像，并通过 storage 事件感知其他
+ *   tab 的写入/失效，保证跨 tab 新鲜度与无镜像时一致
  */
 
 interface CacheEntry {
@@ -58,6 +76,8 @@ declare class RouteCache {
     private readonly fallbackTtl;
     private readonly backend;
     private readonly memory;
+    /** 其他 tab 修改 storage 时失效对应镜像（storage 事件：自己的写不触发，自己的写经 set/del 已同步） */
+    private readonly onStorageEvent;
     constructor(opts: {
         storage: CacheStorage;
         ttl: number;
@@ -71,6 +91,37 @@ declare class RouteCache {
     private isExpired;
 }
 
+/**
+ * 智能路由名前缀解析
+ *
+ * 当前缀与后缀拼接产生歧义时（后缀本身已以前缀开头），
+ * 通过查询已加载路由表来判定正确名称：
+ *   - 优先尝试 prefix + sep + suffix（完整拼接）
+ *   - 若不存在则回退到 suffix（视为已含前缀）
+ *   - 均不存在则抛 UnknownRouteError
+ *
+ * @see .docs/SPEC.md §4.1.7
+ */
+/**
+ * 路由名解析所需的最小 forge 接口。
+ * 仅依赖 load() 和 hasRoute()，不依赖拦截器等完整能力。
+ * 兼容 RouteForge、BoundForgeTyped、ForgeInstanceTyped 等所有形态。
+ */
+interface RouteResolver {
+    load(level: string | string[]): Promise<void>;
+    hasRoute(level: string, name: string): boolean;
+}
+/**
+ * 异步版本：先确保层级已加载，再做歧义消解。
+ * 适用于 api() 调用路径。
+ */
+declare function resolveRouteName(forge: RouteResolver, level: string, prefix: string, suffix: string, separator?: string): Promise<string>;
+/**
+ * 同步版本：基于已加载缓存做歧义消解。
+ * 适用于 route() / url() 调用路径（要求层级已加载）。
+ */
+declare function resolveRouteNameSync(forge: RouteResolver, level: string, prefix: string, suffix: string, separator?: string): string;
+
 /**
  * Route Forge 错误基类与具体错误类
  * @see .docs/SPEC.md §6
@@ -78,14 +129,19 @@ declare class RouteCache {
 interface ForgeErrorContext {
     [key: string]: unknown;
 }
+/**
+ * Route Forge 错误码字面量联合。
+ * 用户侧 `switch (e.code)` 可获得穷尽检查（漏分支编译报错）。
+ */
+type ForgeErrorCode = 'RF_FE_001' | 'RF_FE_002' | 'RF_FE_003' | 'RF_FE_005' | 'RF_FE_006' | 'RF_FE_007' | 'RF_FE_008' | 'RF_FE_009' | 'RF_FE_010';
 declare class ForgeError extends Error {
-    readonly code: string;
+    readonly code: ForgeErrorCode;
     readonly route?: string;
     readonly level?: string;
     readonly context?: ForgeErrorContext;
     readonly cause?: unknown;
     constructor(message: string, opts: {
-        code: string;
+        code: ForgeErrorCode;
         route?: string;
         level?: string;
         context?: ForgeErrorContext;
@@ -132,49 +188,4 @@ declare class RequestAbortedError extends ForgeError {
     constructor(route?: string, level?: string, cause?: unknown);
 }
 
-/**
- * Route Forge 主入口：createRouteForge
- * @see .docs/SPEC.md §4.1.1 ~ §4.1.4
- *
- * 能力清单（v1.0 MVP）：
- *   - 按层级懒加载与隔离缓存（§4.1.2）
- *   - 并发去重（§4.1.4）
- *   - 通过路由名调用 API（§4.1.3）
- *   - 拦截器（§4.1.3a）
- *   - Adapter auto 检测 / builtin / axios / 自定义 Fetcher（§4.3）
- */
-
-declare function createRouteForge(options: RouteForgeOptions): RouteForge;
-
-/**
- * 智能路由名前缀解析
- *
- * 当前缀与后缀拼接产生歧义时（后缀本身已以前缀开头），
- * 通过查询已加载路由表来判定正确名称：
- *   - 优先尝试 prefix + sep + suffix（完整拼接）
- *   - 若不存在则回退到 suffix（视为已含前缀）
- *   - 均不存在则抛 UnknownRouteError
- *
- * @see .docs/SPEC.md §4.1.7
- */
-/**
- * 路由名解析所需的最小 forge 接口。
- * 仅依赖 load() 和 hasRoute()，不依赖拦截器等完整能力。
- * 兼容 RouteForge、BoundForgeTyped、ForgeInstanceTyped 等所有形态。
- */
-interface RouteResolver {
-    load(level: string | string[]): Promise<void>;
-    hasRoute(level: string, name: string): boolean;
-}
-/**
- * 异步版本：先确保层级已加载，再做歧义消解。
- * 适用于 api() 调用路径。
- */
-declare function resolveRouteName(forge: RouteResolver, level: string, prefix: string, suffix: string, separator?: string): Promise<string>;
-/**
- * 同步版本：基于已加载缓存做歧义消解。
- * 适用于 route() / url() 调用路径（要求层级已加载）。
- */
-declare function resolveRouteNameSync(forge: RouteResolver, level: string, prefix: string, suffix: string, separator?: string): string;
-
-export { AdapterNotFoundError, CacheStorage, ForgeError, HTTPError, InterceptorHandler, InterceptorManager, InterceptorManagerImpl, InvalidInterceptorReturnError, LevelRoutesResponse, MissingRouteParamError, NetworkError, RequestAbortedError, RouteCache, RouteForge, RouteForgeOptions, RouteMeta, type RouteResolver, UnknownLevelError, UnknownRouteError, createInterceptorManager, createRouteForge, resolveRouteName, resolveRouteNameSync };
+export { AdapterNotFoundError, CacheStorage, ForgeError, type ForgeErrorCode, HTTPError, InterceptorHandler, InterceptorManager, InterceptorManagerImpl, InvalidInterceptorReturnError, LevelRoutesResponse, MissingRouteParamError, NetworkError, RequestAbortedError, RouteCache, RouteForge, RouteForgeOptions, RouteMeta, type RouteResolver, UnknownLevelError, UnknownRouteError, createInterceptorManager, createRouteForge, resolveRouteName, resolveRouteNameSync };