@route-forge/core 0.3.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.md +91 -2
  2. package/dist/codegen.d.cts +1 -1
  3. package/dist/codegen.d.ts +1 -1
  4. package/dist/index.cjs +119 -54
  5. package/dist/index.cjs.map +1 -1
  6. package/dist/index.d.cts +4 -10
  7. package/dist/index.d.ts +4 -10
  8. package/dist/index.js +119 -54
  9. package/dist/index.js.map +1 -1
  10. package/dist/{types-CBurRtGK.d.cts → types-yzY9-FWd.d.cts} +92 -13
  11. package/dist/{types-CBurRtGK.d.ts → types-yzY9-FWd.d.ts} +92 -13
  12. package/package.json +1 -1
package/dist/{types-CBurRtGK.d.cts → types-yzY9-FWd.d.cts} RENAMED
@@ -1,7 +1,64 @@
1
+ /**
2
+ * LoadingTracker：加载中标识状态管理
3
+ *
4
+ * 通过引用计数器跟踪并发请求数。
5
+ * - start()：计数器 +1，进入加载状态
6
+ * - stop()：计数器 -1，归零时退出加载状态
7
+ * - isLoading()：查询当前是否处于加载中
8
+ * - subscribe(cb)：监听状态变化，返回取消订阅函数
9
+ *
10
+ * @see .docs/SPEC.md §4.1.8
11
+ */
12
+ /** 状态变更回调签名 */
13
+ type LoadingChangeCallback = (event: LoadingChangeEvent) => void;
14
+ /** 状态变更事件 */
15
+ interface LoadingChangeEvent {
16
+ /** 当前是否仍处于加载中 */
17
+ loading: boolean;
18
+ /** 当前并发请求数 */
19
+ count: number;
20
+ }
21
+ /**
22
+ * 加载状态跟踪器
23
+ *
24
+ * 单一计数器，跟踪所有 API 请求的并发数。
25
+ * 不绑定任何 UI 样式，仅提供状态供框架层或业务层消费。
26
+ */
27
+ declare class LoadingTracker {
28
+ /** 当前并发请求计数 */
29
+ private count;
30
+ /** 订阅者集合 */
31
+ private subscribers;
32
+ /**
33
+ * 开始一次加载（计数器 +1）
34
+ */
35
+ start(): void;
36
+ /**
37
+ * 结束一次加载（计数器 -1）
38
+ */
39
+ stop(): void;
40
+ /**
41
+ * 查询当前是否处于加载中
42
+ */
43
+ isLoading(): boolean;
44
+ /**
45
+ * 获取当前并发计数
46
+ */
47
+ getCount(): number;
48
+ /**
49
+ * 订阅加载状态变更
50
+ * @returns 取消订阅函数
51
+ */
52
+ subscribe(cb: LoadingChangeCallback): () => void;
53
+ /** 通知所有订阅者 */
54
+ private notify;
55
+ }
56
+
1
57
  /**
2
58
  * @route-forge/core 核心类型定义
3
59
  * @see .docs/SPEC.md §4.1.3a, §4.1.1
4
60
  */
61
+
5
62
  /**
6
63
  * 路由元信息（后端 /_forge/routes/{level} 返回的单条路由结构）
7
64
  */
@@ -104,12 +161,19 @@ interface ApiCallParams {
104
161
  [paramName: string]: unknown;
105
162
  /** 显式指定路径参数（优先级最高，解决路径参数名与 query/body/headers 冲突的场景） */
106
163
  params?: Record<string, unknown>;
107
- /** 查询参数，序列化到 URL query string */
108
- query?: Record<string, unknown>;
109
- /** 请求体，按 method 决定是否发送 */
164
+ /**
165
+ * 查询参数（对象 → query string）或路径参数（string | number → 填充 {query} 占位符）
166
+ * @see .docs/SPEC.md §4.1.3 参数智能解析
167
+ */
168
+ query?: Record<string, unknown> | string | number;
169
+ /**
170
+ * 请求体（非基元值 → body）或路径参数（string | number → 填充 {body} 占位符）
171
+ */
110
172
  body?: unknown;
111
- /** 自定义请求头（与拦截器叠加） */
112
- headers?: Record<string, string>;
173
+ /**
174
+ * 自定义请求头（对象 → headers）或路径参数（string | number → 填充 {headers} 占位符）
175
+ */
176
+ headers?: Record<string, string> | string | number;
113
177
  }
114
178
  /**
115
179
  * 缓存存储介质
@@ -169,8 +233,17 @@ interface RouteForge {
169
233
  invalidate(level?: string): void;
170
234
  /** 检查指定层级路由是否已加载并缓存；不传参检查全部 */
171
235
  isLoaded(level?: string): boolean;
172
- /** 检查指定层级下某条路由是否存在（需该层级缓存已加载） */
236
+ /** 检查指定层级下某路由是否存在（需该层级缓存已加载） */
173
237
  hasRoute(level: string, name: string): boolean;
238
+ /**
239
+ * 查询加载中标识状态
240
+ */
241
+ isLoading(): boolean;
242
+ /**
243
+ * 订阅加载状态变更
244
+ * @returns 取消订阅函数
245
+ */
246
+ onLoadingChange(cb: LoadingChangeCallback): () => void;
174
247
  /**
175
248
  * 获取路由元信息快照（深拷贝，修改返回值不影响内部缓存）。
176
249
  * - getRoutes(level)：返回指定层级下全部路由
@@ -201,13 +274,19 @@ interface RouteForgeOptions {
201
274
  ttl?: number;
202
275
  storage?: CacheStorage;
203
276
  };
204
- auth?: {
205
- state?: () => boolean;
206
- levels?: Record<string, boolean>;
207
- };
208
277
  interceptors?: {
209
- request?: Array<[((c: RequestConfig) => RequestConfig | Promise<RequestConfig>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
210
- response?: Array<[((r: ResponseData) => unknown | Promise<unknown>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
278
+ /**
279
+ * 声明式请求拦截器列表，支持两种形式（SPEC §4.1.1）：
280
+ * - 单一函数 → 视为 onFulfilled
281
+ * - [onFulfilled?, onRejected?] 元组 → 完整拦截器定义
282
+ */
283
+ request?: Array<((c: RequestConfig) => RequestConfig | Promise<RequestConfig>) | [((c: RequestConfig) => RequestConfig | Promise<RequestConfig>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
284
+ /**
285
+ * 声明式响应拦截器列表，支持两种形式（SPEC §4.1.1）：
286
+ * - 单一函数 → 视为 onFulfilled
287
+ * - [onFulfilled?, onRejected?] 元组 → 完整拦截器定义
288
+ */
289
+ response?: Array<((r: ResponseData) => unknown | Promise<unknown>) | [((r: ResponseData) => unknown | Promise<unknown>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
211
290
  };
212
291
  strict?: boolean;
213
292
  timeout?: number;
@@ -248,4 +327,4 @@ type ForgeApiResponse<L extends string, N extends string> = [
248
327
  response: infer R;
249
328
  } ? R : unknown) : unknown : unknown;
250
329
 
251
- 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 };
330
+ 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/dist/{types-CBurRtGK.d.ts → types-yzY9-FWd.d.ts} RENAMED
@@ -1,7 +1,64 @@
1
+ /**
2
+ * LoadingTracker：加载中标识状态管理
3
+ *
4
+ * 通过引用计数器跟踪并发请求数。
5
+ * - start()：计数器 +1，进入加载状态
6
+ * - stop()：计数器 -1，归零时退出加载状态
7
+ * - isLoading()：查询当前是否处于加载中
8
+ * - subscribe(cb)：监听状态变化，返回取消订阅函数
9
+ *
10
+ * @see .docs/SPEC.md §4.1.8
11
+ */
12
+ /** 状态变更回调签名 */
13
+ type LoadingChangeCallback = (event: LoadingChangeEvent) => void;
14
+ /** 状态变更事件 */
15
+ interface LoadingChangeEvent {
16
+ /** 当前是否仍处于加载中 */
17
+ loading: boolean;
18
+ /** 当前并发请求数 */
19
+ count: number;
20
+ }
21
+ /**
22
+ * 加载状态跟踪器
23
+ *
24
+ * 单一计数器，跟踪所有 API 请求的并发数。
25
+ * 不绑定任何 UI 样式，仅提供状态供框架层或业务层消费。
26
+ */
27
+ declare class LoadingTracker {
28
+ /** 当前并发请求计数 */
29
+ private count;
30
+ /** 订阅者集合 */
31
+ private subscribers;
32
+ /**
33
+ * 开始一次加载（计数器 +1）
34
+ */
35
+ start(): void;
36
+ /**
37
+ * 结束一次加载（计数器 -1）
38
+ */
39
+ stop(): void;
40
+ /**
41
+ * 查询当前是否处于加载中
42
+ */
43
+ isLoading(): boolean;
44
+ /**
45
+ * 获取当前并发计数
46
+ */
47
+ getCount(): number;
48
+ /**
49
+ * 订阅加载状态变更
50
+ * @returns 取消订阅函数
51
+ */
52
+ subscribe(cb: LoadingChangeCallback): () => void;
53
+ /** 通知所有订阅者 */
54
+ private notify;
55
+ }
56
+
1
57
  /**
2
58
  * @route-forge/core 核心类型定义
3
59
  * @see .docs/SPEC.md §4.1.3a, §4.1.1
4
60
  */
61
+
5
62
  /**
6
63
  * 路由元信息（后端 /_forge/routes/{level} 返回的单条路由结构）
7
64
  */
@@ -104,12 +161,19 @@ interface ApiCallParams {
104
161
  [paramName: string]: unknown;
105
162
  /** 显式指定路径参数（优先级最高，解决路径参数名与 query/body/headers 冲突的场景） */
106
163
  params?: Record<string, unknown>;
107
- /** 查询参数，序列化到 URL query string */
108
- query?: Record<string, unknown>;
109
- /** 请求体，按 method 决定是否发送 */
164
+ /**
165
+ * 查询参数（对象 → query string）或路径参数（string | number → 填充 {query} 占位符）
166
+ * @see .docs/SPEC.md §4.1.3 参数智能解析
167
+ */
168
+ query?: Record<string, unknown> | string | number;
169
+ /**
170
+ * 请求体（非基元值 → body）或路径参数（string | number → 填充 {body} 占位符）
171
+ */
110
172
  body?: unknown;
111
- /** 自定义请求头（与拦截器叠加） */
112
- headers?: Record<string, string>;
173
+ /**
174
+ * 自定义请求头（对象 → headers）或路径参数（string | number → 填充 {headers} 占位符）
175
+ */
176
+ headers?: Record<string, string> | string | number;
113
177
  }
114
178
  /**
115
179
  * 缓存存储介质
@@ -169,8 +233,17 @@ interface RouteForge {
169
233
  invalidate(level?: string): void;
170
234
  /** 检查指定层级路由是否已加载并缓存；不传参检查全部 */
171
235
  isLoaded(level?: string): boolean;
172
- /** 检查指定层级下某条路由是否存在（需该层级缓存已加载） */
236
+ /** 检查指定层级下某路由是否存在（需该层级缓存已加载） */
173
237
  hasRoute(level: string, name: string): boolean;
238
+ /**
239
+ * 查询加载中标识状态
240
+ */
241
+ isLoading(): boolean;
242
+ /**
243
+ * 订阅加载状态变更
244
+ * @returns 取消订阅函数
245
+ */
246
+ onLoadingChange(cb: LoadingChangeCallback): () => void;
174
247
  /**
175
248
  * 获取路由元信息快照（深拷贝，修改返回值不影响内部缓存）。
176
249
  * - getRoutes(level)：返回指定层级下全部路由
@@ -201,13 +274,19 @@ interface RouteForgeOptions {
201
274
  ttl?: number;
202
275
  storage?: CacheStorage;
203
276
  };
204
- auth?: {
205
- state?: () => boolean;
206
- levels?: Record<string, boolean>;
207
- };
208
277
  interceptors?: {
209
- request?: Array<[((c: RequestConfig) => RequestConfig | Promise<RequestConfig>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
210
- response?: Array<[((r: ResponseData) => unknown | Promise<unknown>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
278
+ /**
279
+ * 声明式请求拦截器列表，支持两种形式（SPEC §4.1.1）：
280
+ * - 单一函数 → 视为 onFulfilled
281
+ * - [onFulfilled?, onRejected?] 元组 → 完整拦截器定义
282
+ */
283
+ request?: Array<((c: RequestConfig) => RequestConfig | Promise<RequestConfig>) | [((c: RequestConfig) => RequestConfig | Promise<RequestConfig>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
284
+ /**
285
+ * 声明式响应拦截器列表，支持两种形式（SPEC §4.1.1）：
286
+ * - 单一函数 → 视为 onFulfilled
287
+ * - [onFulfilled?, onRejected?] 元组 → 完整拦截器定义
288
+ */
289
+ response?: Array<((r: ResponseData) => unknown | Promise<unknown>) | [((r: ResponseData) => unknown | Promise<unknown>) | undefined, ((e: unknown) => unknown | Promise<unknown>) | undefined]>;
211
290
  };
212
291
  strict?: boolean;
213
292
  timeout?: number;
@@ -248,4 +327,4 @@ type ForgeApiResponse<L extends string, N extends string> = [
248
327
  response: infer R;
249
328
  } ? R : unknown) : unknown : unknown;
250
329
 
251
- 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 };
330
+ 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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@route-forge/core",
3
- "version": "0.3.0",
3
+ "version": "1.0.0",
4
4
  "description": "框架无关的命名路由客户端核心：分级懒加载、隔离缓存、并发去重、登录态感知、拦截器",
5
5
  "license": "MIT",
6
6
  "author": "阿杰很厉害 <506907958@qq.com>",