@route-forge/core 0.1.1 → 0.3.0

package/dist/{types-UxdZAlmW.d.cts → types-CBurRtGK.d.cts}

@@ -14,6 +14,8 @@ interface RouteMeta {
     methods: string[];
     /** 路径参数名列表，如 ['user'] */
     parameters: string[];
+    /** 路径参数默认值（Laravel ->defaults()），key 为参数名，value 为默认值 */
+    parameter_defaults?: Record<string, unknown>;
     /** 所属层级（前端填充，便于隔离缓存） */
     level?: string;
     /** 后端下发的缓存 TTL（秒），优先级高于本地 cache.ttl */
@@ -42,12 +44,15 @@ interface SummaryResponse {
     config: {
         strict_mode: boolean;
         endpoint_prefix: string;
+        /** 后端下发的 URL 前缀，生成 URL 时自动拼接到路由 URI 前面（SPEC §3.1.6） */
+        url_prefix?: string;
     };
     unassigned: Array<{
         name: string;
         uri: string;
         methods: string[];
         parameters: string[];
+        parameter_defaults?: Record<string, unknown>;
     }>;
 }
 /**
@@ -81,11 +86,24 @@ interface ResponseData {
     config: RequestConfig;
 }
 /**
- * forge.api(name, params) 调用参数
+ * forge.api(level, name, params) 调用参数
+ *
+ * 参数解析规则（智能消解）：
+ *   1. `params` — 显式指定路径参数，优先级最高
+ *   2. 平铺的 string | number 值 — 作为路径参数（含与 query/body/headers 同名的 key）
+ *   3. `query` (对象) — 查询参数，序列化到 URL query string
+ *   4. `body` (非 string/number) — 请求体
+ *   5. `headers` (对象) — 自定义请求头
+ *
+ * 当路径参数名与 query/body/headers 冲突时：
+ *   - 值为 string | number → 智能识别为路径参数
+ *   - 同时提供 params 显式指定 → params 优先，固定 key 按原定义处理
  */
 interface ApiCallParams {
     /** 路径参数：填充到 URI 模板的 {name} 占位符 */
     [paramName: string]: unknown;
+    /** 显式指定路径参数（优先级最高，解决路径参数名与 query/body/headers 冲突的场景） */
+    params?: Record<string, unknown>;
     /** 查询参数，序列化到 URL query string */
     query?: Record<string, unknown>;
     /** 请求体，按 method 决定是否发送 */
@@ -139,14 +157,27 @@ interface InterceptorHandler<TIn, TOut = TIn> {
  * forge 顶层 API 形状
  */
 interface RouteForge {
-    /** 通过路由名调用 API */
-    api(name: string, params?: ApiCallParams): Promise<unknown>;
+    /** 通过层级 + 路由名调用 API；level 用于确定加载哪个层级的路由元信息 */
+    api(level: string, name: string, params?: ApiCallParams): Promise<unknown>;
     /** 拉取一个或多个层级（自动并发去重） */
     load(level: string | string[]): Promise<void>;
-    /** 仅生成 URL，不发请求 */
-    route(name: string, params?: Record<string, unknown>): string;
+    /** 仅生成 URL，不发请求；level 用于定位路由所在的层级缓存 */
+    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;
+    /** 检查指定层级路由是否已加载并缓存；不传参检查全部 */
+    isLoaded(level?: string): boolean;
+    /** 检查指定层级下某条路由是否存在（需该层级缓存已加载） */
+    hasRoute(level: string, name: string): boolean;
+    /**
+     * 获取路由元信息快照（深拷贝，修改返回值不影响内部缓存）。
+     * - getRoutes(level)：返回指定层级下全部路由
+     * - getRoutes()：返回全部层级的路由（按 level 分组）
+     */
+    getRoutes(level: string): Record<string, RouteMeta>;
+    getRoutes(): Record<string, Record<string, RouteMeta>>;
     /** 拦截器入口（请求 / 响应） */
     interceptors: {
         request: InterceptorManager<RequestConfig, RequestConfig>;
@@ -181,7 +212,40 @@ interface RouteForgeOptions {
     strict?: boolean;
     timeout?: number;
     baseURL?: string;
-    nameSeparator?: string;
 }
+/**
+ * 二级路由类型映射（可由 codegen 生成或通过 module augmentation 增强）
+ *
+ * @example
+ * declare module '@route-forge/core' {
+ *   interface ForgeRouteMap {
+ *     admin: {
+ *       'users.show': { method: 'GET'; params: { user: string | number }; response: User };
+ *       'users.index': { method: 'GET'; params: {}; response: User[] };
+ *     };
+ *     public: {
+ *       'login.show': { method: 'GET'; params: {}; response: unknown };
+ *     };
+ *   }
+ * }
+ */
+interface ForgeRouteMap {
+}
+/** 从 ForgeRouteMap 推断指定层级下的路由名；未定义时回退 string */
+type ForgeRouteName<L extends string> = [
+    keyof ForgeRouteMap
+] extends [never] ? string : L extends keyof ForgeRouteMap ? keyof ForgeRouteMap[L] & string : string;
+/** 从 ForgeRouteMap 推断指定路由的 params 类型；未定义时回退 ApiCallParams */
+type ForgeApiParams<L extends string, N extends string> = [
+    keyof ForgeRouteMap
+] extends [never] ? ApiCallParams : L extends keyof ForgeRouteMap ? N extends keyof ForgeRouteMap[L] ? (ForgeRouteMap[L][N] extends {
+    params: infer P;
+} ? P & ApiCallParams : ApiCallParams) : ApiCallParams : ApiCallParams;
+/** 从 ForgeRouteMap 推断指定路由的响应类型；未定义时回退 unknown */
+type ForgeApiResponse<L extends string, N extends string> = [
+    keyof ForgeRouteMap
+] extends [never] ? unknown : L extends keyof ForgeRouteMap ? N extends keyof ForgeRouteMap[L] ? (ForgeRouteMap[L][N] extends {
+    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, RequestConfig as e, ResponseData as f };
+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 };

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

@@ -14,6 +14,8 @@ interface RouteMeta {
     methods: string[];
     /** 路径参数名列表，如 ['user'] */
     parameters: string[];
+    /** 路径参数默认值（Laravel ->defaults()），key 为参数名，value 为默认值 */
+    parameter_defaults?: Record<string, unknown>;
     /** 所属层级（前端填充，便于隔离缓存） */
     level?: string;
     /** 后端下发的缓存 TTL（秒），优先级高于本地 cache.ttl */
@@ -42,12 +44,15 @@ interface SummaryResponse {
     config: {
         strict_mode: boolean;
         endpoint_prefix: string;
+        /** 后端下发的 URL 前缀，生成 URL 时自动拼接到路由 URI 前面（SPEC §3.1.6） */
+        url_prefix?: string;
     };
     unassigned: Array<{
         name: string;
         uri: string;
         methods: string[];
         parameters: string[];
+        parameter_defaults?: Record<string, unknown>;
     }>;
 }
 /**
@@ -81,11 +86,24 @@ interface ResponseData {
     config: RequestConfig;
 }
 /**
- * forge.api(name, params) 调用参数
+ * forge.api(level, name, params) 调用参数
+ *
+ * 参数解析规则（智能消解）：
+ *   1. `params` — 显式指定路径参数，优先级最高
+ *   2. 平铺的 string | number 值 — 作为路径参数（含与 query/body/headers 同名的 key）
+ *   3. `query` (对象) — 查询参数，序列化到 URL query string
+ *   4. `body` (非 string/number) — 请求体
+ *   5. `headers` (对象) — 自定义请求头
+ *
+ * 当路径参数名与 query/body/headers 冲突时：
+ *   - 值为 string | number → 智能识别为路径参数
+ *   - 同时提供 params 显式指定 → params 优先，固定 key 按原定义处理
  */
 interface ApiCallParams {
     /** 路径参数：填充到 URI 模板的 {name} 占位符 */
     [paramName: string]: unknown;
+    /** 显式指定路径参数（优先级最高，解决路径参数名与 query/body/headers 冲突的场景） */
+    params?: Record<string, unknown>;
     /** 查询参数，序列化到 URL query string */
     query?: Record<string, unknown>;
     /** 请求体，按 method 决定是否发送 */
@@ -139,14 +157,27 @@ interface InterceptorHandler<TIn, TOut = TIn> {
  * forge 顶层 API 形状
  */
 interface RouteForge {
-    /** 通过路由名调用 API */
-    api(name: string, params?: ApiCallParams): Promise<unknown>;
+    /** 通过层级 + 路由名调用 API；level 用于确定加载哪个层级的路由元信息 */
+    api(level: string, name: string, params?: ApiCallParams): Promise<unknown>;
     /** 拉取一个或多个层级（自动并发去重） */
     load(level: string | string[]): Promise<void>;
-    /** 仅生成 URL，不发请求 */
-    route(name: string, params?: Record<string, unknown>): string;
+    /** 仅生成 URL，不发请求；level 用于定位路由所在的层级缓存 */
+    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;
+    /** 检查指定层级路由是否已加载并缓存；不传参检查全部 */
+    isLoaded(level?: string): boolean;
+    /** 检查指定层级下某条路由是否存在（需该层级缓存已加载） */
+    hasRoute(level: string, name: string): boolean;
+    /**
+     * 获取路由元信息快照（深拷贝，修改返回值不影响内部缓存）。
+     * - getRoutes(level)：返回指定层级下全部路由
+     * - getRoutes()：返回全部层级的路由（按 level 分组）
+     */
+    getRoutes(level: string): Record<string, RouteMeta>;
+    getRoutes(): Record<string, Record<string, RouteMeta>>;
     /** 拦截器入口（请求 / 响应） */
     interceptors: {
         request: InterceptorManager<RequestConfig, RequestConfig>;
@@ -181,7 +212,40 @@ interface RouteForgeOptions {
     strict?: boolean;
     timeout?: number;
     baseURL?: string;
-    nameSeparator?: string;
 }
+/**
+ * 二级路由类型映射（可由 codegen 生成或通过 module augmentation 增强）
+ *
+ * @example
+ * declare module '@route-forge/core' {
+ *   interface ForgeRouteMap {
+ *     admin: {
+ *       'users.show': { method: 'GET'; params: { user: string | number }; response: User };
+ *       'users.index': { method: 'GET'; params: {}; response: User[] };
+ *     };
+ *     public: {
+ *       'login.show': { method: 'GET'; params: {}; response: unknown };
+ *     };
+ *   }
+ * }
+ */
+interface ForgeRouteMap {
+}
+/** 从 ForgeRouteMap 推断指定层级下的路由名；未定义时回退 string */
+type ForgeRouteName<L extends string> = [
+    keyof ForgeRouteMap
+] extends [never] ? string : L extends keyof ForgeRouteMap ? keyof ForgeRouteMap[L] & string : string;
+/** 从 ForgeRouteMap 推断指定路由的 params 类型；未定义时回退 ApiCallParams */
+type ForgeApiParams<L extends string, N extends string> = [
+    keyof ForgeRouteMap
+] extends [never] ? ApiCallParams : L extends keyof ForgeRouteMap ? N extends keyof ForgeRouteMap[L] ? (ForgeRouteMap[L][N] extends {
+    params: infer P;
+} ? P & ApiCallParams : ApiCallParams) : ApiCallParams : ApiCallParams;
+/** 从 ForgeRouteMap 推断指定路由的响应类型；未定义时回退 unknown */
+type ForgeApiResponse<L extends string, N extends string> = [
+    keyof ForgeRouteMap
+] extends [never] ? unknown : L extends keyof ForgeRouteMap ? N extends keyof ForgeRouteMap[L] ? (ForgeRouteMap[L][N] extends {
+    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, RequestConfig as e, ResponseData as f };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@route-forge/core",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "框架无关的命名路由客户端核心：分级懒加载、隔离缓存、并发去重、登录态感知、拦截器",
   "license": "MIT",
   "author": "阿杰很厉害 <506907958@qq.com>",
@@ -50,6 +50,7 @@
   },
   "scripts": {
     "build": "tsup",
+    "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "tsc --noEmit",