@route-forge/core 2.2.0 → 3.0.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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';
+import { a as RouteForgeOptions, b as RouteForge, I as InterceptorManager, c as InterceptorHandler, C as CacheStorage, R as RouteMeta, L as LevelRoutesResponse, d as ResponseData } from './types-B_vdcRqx.cjs';
+export { A as AdapterOption, e as ApiCallParams, B as BoundForge, F as Fetcher, f as ForgeApiParams, g as ForgeApiResponse, h as ForgeRequest, i as ForgeRouteMap, j as ForgeRouteName, k as LoadingChangeCallback, l as LoadingChangeEvent, m as LoadingTracker, n as RequestConfig, S as SummaryResponse, U as UseForgeApiBoundCall, o as UseForgeApiBoundReturn, p as UseForgeApiCall, q as UseForgeApiReturn } from './types-B_vdcRqx.cjs';
 
 /**
  * Route Forge 主入口：createRouteForge
@@ -13,7 +13,7 @@ export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher,
  *   - Adapter auto 检测 / builtin / axios / 自定义 Fetcher（§4.3）
  */
 
-declare function createRouteForge(options: RouteForgeOptions): RouteForge;
+declare function createRouteForge(options?: RouteForgeOptions): RouteForge;
 
 /**
  * 拦截器管理器实现
@@ -118,6 +118,8 @@ declare class RouteCache {
 interface RouteResolver {
     load(level: string | string[]): Promise<void>;
     hasRoute(level: string, name: string): boolean;
+    /** 可选：该层级当前已加载的路由名列表（UnknownRouteError 附候选值用） */
+    getRouteNames?(level: string): string[];
 }
 /**
  * 异步版本：先确保层级已加载，再做歧义消解。
@@ -134,6 +136,7 @@ declare function resolveRouteNameSync(forge: RouteResolver, level: string, prefi
  * Route Forge 错误基类与具体错误类
  * @see .docs/SPEC.md §6
  */
+
 interface ForgeErrorContext {
     [key: string]: unknown;
 }
@@ -158,15 +161,19 @@ declare class ForgeError extends Error {
 }
 /** RF_FE_001：路由名不存在于已加载层级中 */
 declare class UnknownRouteError extends ForgeError {
-    constructor(route: string, level?: string);
+    constructor(route: string, level?: string, candidates?: string[]);
 }
 /** RF_FE_002：路由所在层级未在 levels 声明 */
 declare class UnknownLevelError extends ForgeError {
-    constructor(level: string);
+    constructor(level: string, candidates?: string[]);
 }
-/** RF_FE_003：路径参数缺失（strict=true 时） */
+/** RF_FE_003：必填路径参数缺失（无后端 default 时，前端校验恒开） */
 declare class MissingRouteParamError extends ForgeError {
-    constructor(route: string, missingParams: string[]);
+    constructor(route: string, missingParams: string[], uri?: string);
+}
+/** RF_FE_003：路径参数收到非原始值（对象/数组等，无法安全插入 URI） */
+declare class InvalidPathParamError extends ForgeError {
+    constructor(route: string, param: string, value: unknown);
 }
 /** RF_FE_005：adapter: 'axios' 但未检测到 axios */
 declare class AdapterNotFoundError extends ForgeError {
@@ -180,8 +187,15 @@ declare class InvalidInterceptorReturnError extends ForgeError {
 declare class NetworkError extends ForgeError {
     constructor(message: string, route?: string, level?: string, cause?: unknown);
 }
-/** RF_FE_008：HTTP 非 2xx 且未被 onRejected 拦截器恢复 */
+/**
+ * RF_FE_008：HTTP 非 2xx 且未被 onRejected 拦截器恢复。
+ *
+ * `response` 携带完整的 ResponseData（status/headers/data/config），
+ * 供响应拦截器 onRejected 链与最终 catch 逐段检查响应体——典型场景：
+ * Laravel 422 校验错误回显（`err.response.data.errors`）。
+ */
 declare class HTTPError extends ForgeError {
+    readonly response?: ResponseData;
     constructor(message: string, opts: {
         route?: string;
         level?: string;
@@ -189,11 +203,16 @@ declare class HTTPError extends ForgeError {
         url?: string;
         method?: string;
         cause?: unknown;
+        response?: ResponseData;
     });
 }
 /** RF_FE_009：请求被 AbortSignal 取消 */
 declare class RequestAbortedError extends ForgeError {
     constructor(route?: string, level?: string, cause?: unknown);
 }
+/** RF_FE_010：auto-discovery 未完成时调用 route()/hasRoute() 的同步守卫（api() 内部 await discovery，不受此限） */
+declare class DiscoveryNotReadyError extends ForgeError {
+    constructor();
+}
 
-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 };
+export { AdapterNotFoundError, CacheStorage, DiscoveryNotReadyError, ForgeError, type ForgeErrorCode, HTTPError, InterceptorHandler, InterceptorManager, InterceptorManagerImpl, InvalidInterceptorReturnError, InvalidPathParamError, LevelRoutesResponse, MissingRouteParamError, NetworkError, RequestAbortedError, ResponseData, RouteCache, RouteForge, RouteForgeOptions, RouteMeta, type RouteResolver, UnknownLevelError, UnknownRouteError, createInterceptorManager, createRouteForge, resolveRouteName, resolveRouteNameSync };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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';
+import { a as RouteForgeOptions, b as RouteForge, I as InterceptorManager, c as InterceptorHandler, C as CacheStorage, R as RouteMeta, L as LevelRoutesResponse, d as ResponseData } from './types-B_vdcRqx.js';
+export { A as AdapterOption, e as ApiCallParams, B as BoundForge, F as Fetcher, f as ForgeApiParams, g as ForgeApiResponse, h as ForgeRequest, i as ForgeRouteMap, j as ForgeRouteName, k as LoadingChangeCallback, l as LoadingChangeEvent, m as LoadingTracker, n as RequestConfig, S as SummaryResponse, U as UseForgeApiBoundCall, o as UseForgeApiBoundReturn, p as UseForgeApiCall, q as UseForgeApiReturn } from './types-B_vdcRqx.js';
 
 /**
  * Route Forge 主入口：createRouteForge
@@ -13,7 +13,7 @@ export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher,
  *   - Adapter auto 检测 / builtin / axios / 自定义 Fetcher（§4.3）
  */
 
-declare function createRouteForge(options: RouteForgeOptions): RouteForge;
+declare function createRouteForge(options?: RouteForgeOptions): RouteForge;
 
 /**
  * 拦截器管理器实现
@@ -118,6 +118,8 @@ declare class RouteCache {
 interface RouteResolver {
     load(level: string | string[]): Promise<void>;
     hasRoute(level: string, name: string): boolean;
+    /** 可选：该层级当前已加载的路由名列表（UnknownRouteError 附候选值用） */
+    getRouteNames?(level: string): string[];
 }
 /**
  * 异步版本：先确保层级已加载，再做歧义消解。
@@ -134,6 +136,7 @@ declare function resolveRouteNameSync(forge: RouteResolver, level: string, prefi
  * Route Forge 错误基类与具体错误类
  * @see .docs/SPEC.md §6
  */
+
 interface ForgeErrorContext {
     [key: string]: unknown;
 }
@@ -158,15 +161,19 @@ declare class ForgeError extends Error {
 }
 /** RF_FE_001：路由名不存在于已加载层级中 */
 declare class UnknownRouteError extends ForgeError {
-    constructor(route: string, level?: string);
+    constructor(route: string, level?: string, candidates?: string[]);
 }
 /** RF_FE_002：路由所在层级未在 levels 声明 */
 declare class UnknownLevelError extends ForgeError {
-    constructor(level: string);
+    constructor(level: string, candidates?: string[]);
 }
-/** RF_FE_003：路径参数缺失（strict=true 时） */
+/** RF_FE_003：必填路径参数缺失（无后端 default 时，前端校验恒开） */
 declare class MissingRouteParamError extends ForgeError {
-    constructor(route: string, missingParams: string[]);
+    constructor(route: string, missingParams: string[], uri?: string);
+}
+/** RF_FE_003：路径参数收到非原始值（对象/数组等，无法安全插入 URI） */
+declare class InvalidPathParamError extends ForgeError {
+    constructor(route: string, param: string, value: unknown);
 }
 /** RF_FE_005：adapter: 'axios' 但未检测到 axios */
 declare class AdapterNotFoundError extends ForgeError {
@@ -180,8 +187,15 @@ declare class InvalidInterceptorReturnError extends ForgeError {
 declare class NetworkError extends ForgeError {
     constructor(message: string, route?: string, level?: string, cause?: unknown);
 }
-/** RF_FE_008：HTTP 非 2xx 且未被 onRejected 拦截器恢复 */
+/**
+ * RF_FE_008：HTTP 非 2xx 且未被 onRejected 拦截器恢复。
+ *
+ * `response` 携带完整的 ResponseData（status/headers/data/config），
+ * 供响应拦截器 onRejected 链与最终 catch 逐段检查响应体——典型场景：
+ * Laravel 422 校验错误回显（`err.response.data.errors`）。
+ */
 declare class HTTPError extends ForgeError {
+    readonly response?: ResponseData;
     constructor(message: string, opts: {
         route?: string;
         level?: string;
@@ -189,11 +203,16 @@ declare class HTTPError extends ForgeError {
         url?: string;
         method?: string;
         cause?: unknown;
+        response?: ResponseData;
     });
 }
 /** RF_FE_009：请求被 AbortSignal 取消 */
 declare class RequestAbortedError extends ForgeError {
     constructor(route?: string, level?: string, cause?: unknown);
 }
+/** RF_FE_010：auto-discovery 未完成时调用 route()/hasRoute() 的同步守卫（api() 内部 await discovery，不受此限） */
+declare class DiscoveryNotReadyError extends ForgeError {
+    constructor();
+}
 
-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 };
+export { AdapterNotFoundError, CacheStorage, DiscoveryNotReadyError, ForgeError, type ForgeErrorCode, HTTPError, InterceptorHandler, InterceptorManager, InterceptorManagerImpl, InvalidInterceptorReturnError, InvalidPathParamError, LevelRoutesResponse, MissingRouteParamError, NetworkError, RequestAbortedError, ResponseData, RouteCache, RouteForge, RouteForgeOptions, RouteMeta, type RouteResolver, UnknownLevelError, UnknownRouteError, createInterceptorManager, createRouteForge, resolveRouteName, resolveRouteNameSync };