@route-forge/core 2.0.0 → 2.2.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-BvLdl02f.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-BvLdl02f.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-CDKE8rw-.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-CDKE8rw-.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;
 
 /**
  * 拦截器管理器实现
@@ -43,7 +57,8 @@ declare function createInterceptorManager<TIn, TOut = TIn>(): InterceptorManager
  *
  * 规则：
  * - 每层级独立条目，互不污染（cache key = `route-forge:${level}`）
- * - TTL 优先用后端响应里的 cache 字段，本地 cache.ttl 仅作兜底
+ * - 后端 TTL 唯一来源为摘要 config.cache_ttl（全局，经 set 的 backendTtl 参数传入）：
+ *   null=不缓存（只留内存镜像、不落存储）、0=永久、正整数=min(后端, 前端 cache.ttl 兜底)
  * - storage: 'memory' | 'sessionStorage' | 'localStorage'
  * - storage 模式下维护内存镜像：首次读盘解析后驻留内存，后续 get 直接命中
  *   （读盘 + JSON.parse 整层路由表是同步阻塞操作，热路径重复执行代价高）；
@@ -71,12 +86,50 @@ declare class RouteCache {
     private key;
     get(level: string): CacheEntry | undefined;
     private getFromMemory;
-    set(resp: LevelRoutesResponse): void;
+    /**
+     * 写入某层级缓存。后端 TTL 唯一来源为摘要 config.cache_ttl（全局），经参数 backendTtl 传入：
+     * - null      → 后端声明"不缓存"：不写 storage，仅留内存镜像供 route() 同步读（load 层"每次重取"由调用方跳过 get 短路实现）
+     * - 0         → 永久缓存（内存 + storage）
+     * - undefined  → 后端未下发该字段：用前端兜底 TTL（options.cache.ttl）
+     * - 正整数     → min(后端, 前端兜底)：后端为上限，前端只能缩短不能延长（SPEC §5.3）
+     */
+    set(resp: LevelRoutesResponse, backendTtl: number | null | undefined): void;
     del(level: string): void;
     clear(): void;
     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
@@ -143,49 +196,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, 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-BvLdl02f.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-BvLdl02f.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-CDKE8rw-.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-CDKE8rw-.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;
 
 /**
  * 拦截器管理器实现
@@ -43,7 +57,8 @@ declare function createInterceptorManager<TIn, TOut = TIn>(): InterceptorManager
  *
  * 规则：
  * - 每层级独立条目，互不污染（cache key = `route-forge:${level}`）
- * - TTL 优先用后端响应里的 cache 字段，本地 cache.ttl 仅作兜底
+ * - 后端 TTL 唯一来源为摘要 config.cache_ttl（全局，经 set 的 backendTtl 参数传入）：
+ *   null=不缓存（只留内存镜像、不落存储）、0=永久、正整数=min(后端, 前端 cache.ttl 兜底)
  * - storage: 'memory' | 'sessionStorage' | 'localStorage'
  * - storage 模式下维护内存镜像：首次读盘解析后驻留内存，后续 get 直接命中
  *   （读盘 + JSON.parse 整层路由表是同步阻塞操作，热路径重复执行代价高）；
@@ -71,12 +86,50 @@ declare class RouteCache {
     private key;
     get(level: string): CacheEntry | undefined;
     private getFromMemory;
-    set(resp: LevelRoutesResponse): void;
+    /**
+     * 写入某层级缓存。后端 TTL 唯一来源为摘要 config.cache_ttl（全局），经参数 backendTtl 传入：
+     * - null      → 后端声明"不缓存"：不写 storage，仅留内存镜像供 route() 同步读（load 层"每次重取"由调用方跳过 get 短路实现）
+     * - 0         → 永久缓存（内存 + storage）
+     * - undefined  → 后端未下发该字段：用前端兜底 TTL（options.cache.ttl）
+     * - 正整数     → min(后端, 前端兜底)：后端为上限，前端只能缩短不能延长（SPEC §5.3）
+     */
+    set(resp: LevelRoutesResponse, backendTtl: number | null | undefined): void;
     del(level: string): void;
     clear(): void;
     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
@@ -143,49 +196,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, type ForgeErrorCode, HTTPError, InterceptorHandler, InterceptorManager, InterceptorManagerImpl, InvalidInterceptorReturnError, LevelRoutesResponse, MissingRouteParamError, NetworkError, RequestAbortedError, RouteCache, RouteForge, RouteForgeOptions, RouteMeta, type RouteResolver, UnknownLevelError, UnknownRouteError, createInterceptorManager, createRouteForge, resolveRouteName, resolveRouteNameSync };