@route-forge/core 2.2.1 → 3.0.0

package/dist/route-forge.global.js

@@ -144,30 +144,56 @@ var RouteForge = (function (exports) {
       if (opts.cause !== void 0) this.cause = opts.cause;
     }
   };
+  function formatCandidates(candidates) {
+    if (!candidates || candidates.length === 0) return "";
+    const MAX = 5;
+    const shown = candidates.slice(0, MAX).join(", ");
+    const more = candidates.length > MAX ? ` (+${candidates.length - MAX} more)` : "";
+    return ` Available: ${shown}${more}`;
+  }
   var UnknownRouteError = class extends ForgeError {
-    constructor(route, level) {
-      super(`Route "${route}" not found${level ? ` in level "${level}"` : ""}`, {
-        code: "RF_FE_001",
-        route,
-        level
-      });
+    constructor(route, level, candidates) {
+      super(
+        `Route "${route}" not found${level ? ` in level "${level}"` : ""}.${formatCandidates(candidates)}`,
+        {
+          code: "RF_FE_001",
+          route,
+          level,
+          context: candidates && candidates.length > 0 ? { candidates } : void 0
+        }
+      );
     }
   };
   var UnknownLevelError = class extends ForgeError {
-    constructor(level) {
-      super(`Level "${level}" not declared in options.levels`, {
-        code: "RF_FE_002",
-        level
-      });
+    constructor(level, candidates) {
+      super(
+        `Level "${level}" not declared in options.levels.${formatCandidates(candidates)}`,
+        {
+          code: "RF_FE_002",
+          level,
+          context: candidates && candidates.length > 0 ? { candidates } : void 0
+        }
+      );
     }
   };
   var MissingRouteParamError = class extends ForgeError {
-    constructor(route, missingParams) {
-      super(`Missing path parameter(s) ${missingParams.join(", ")} for route "${route}"`, {
-        code: "RF_FE_003",
-        route,
-        context: { missingParams }
-      });
+    constructor(route, missingParams, uri) {
+      super(
+        `Missing path parameter(s) ${missingParams.join(", ")} for route "${route}"${uri ? ` (${uri})` : ""}`,
+        {
+          code: "RF_FE_003",
+          route,
+          context: { missingParams, ...uri !== void 0 ? { uri } : {} }
+        }
+      );
+    }
+  };
+  var InvalidPathParamError = class extends ForgeError {
+    constructor(route, param, value) {
+      super(
+        `Path parameter "${param}" must be a primitive value (string, number, boolean), got ${typeof value}`,
+        { code: "RF_FE_003", route, context: { param, value } }
+      );
     }
   };
   var AdapterNotFoundError = class extends ForgeError {
@@ -200,6 +226,7 @@ var RouteForge = (function (exports) {
         context: { status: opts.status, url: opts.url, method: opts.method },
         cause: opts.cause
       });
+      if (opts.response !== void 0) this.response = opts.response;
     }
   };
   var RequestAbortedError = class extends ForgeError {
@@ -212,6 +239,14 @@ var RouteForge = (function (exports) {
       });
     }
   };
+  var DiscoveryNotReadyError = class extends ForgeError {
+    constructor() {
+      super(
+        "Route data not available. Auto-discovery has not completed. Use forge.ready() or forge.use(level) first, or await ready() before calling route()/hasRoute().",
+        { code: "RF_FE_010" }
+      );
+    }
+  };
 
   // src/interceptors.ts
   var InterceptorManagerImpl = class {
@@ -278,6 +313,43 @@ var RouteForge = (function (exports) {
   function createInterceptorManager() {
     return new InterceptorManagerImpl();
   }
+  function normalizeInterceptorDeclaration(value) {
+    if (value === null || value === void 0) return {};
+    let rawResolve;
+    let rawReject;
+    if (typeof value === "function") {
+      rawResolve = value;
+    } else if (Array.isArray(value)) {
+      rawResolve = value[0];
+      rawReject = value[1];
+    } else if (typeof value === "object") {
+      const obj = value;
+      rawResolve = obj.resolve;
+      rawReject = obj.reject;
+    } else {
+      throw new TypeError(
+        `Interceptor declaration must be a function, a [resolve, reject] tuple, or a { resolve, reject } object; received ${typeof value}.`
+      );
+    }
+    const handler = {};
+    if (rawResolve !== void 0 && rawResolve !== null) {
+      if (typeof rawResolve !== "function") {
+        throw new TypeError(
+          `Interceptor "resolve" (onFulfilled) must be a function; received ${typeof rawResolve}.`
+        );
+      }
+      handler.onFulfilled = rawResolve;
+    }
+    if (rawReject !== void 0 && rawReject !== null) {
+      if (typeof rawReject !== "function") {
+        throw new TypeError(
+          `Interceptor "reject" (onRejected) must be a function; received ${typeof rawReject}.`
+        );
+      }
+      handler.onRejected = rawReject;
+    }
+    return handler;
+  }
 
   // src/adapters/fetch-core.ts
   function isAbortError(err, signal) {
@@ -378,7 +450,10 @@ var RouteForge = (function (exports) {
         level: config.level,
         status: res.status,
         url,
-        method: config.method
+        method: config.method,
+        // 完整 ResponseData 随错误逐段传递（响应拦截器 onRejected 链 → 最终 catch），
+        // 供调用方检查响应体，如 Laravel 422 校验错误 err.response.data.errors
+        response: responseData
       }
     );
   }
@@ -590,7 +665,7 @@ var RouteForge = (function (exports) {
       }
     }
     if (missingRequired.length > 0) {
-      throw new MissingRouteParamError(meta.name, missingRequired);
+      throw new MissingRouteParamError(meta.name, missingRequired, meta.uri);
     }
     let uri = meta.uri.replace(/\{([^{}]+)\}/g, (match, raw) => {
       const optional = raw.endsWith("?");
@@ -598,10 +673,7 @@ var RouteForge = (function (exports) {
       if (values[name] !== void 0) {
         const val = values[name];
         if (typeof val === "object") {
-          throw new ForgeError(
-            `Path parameter "${name}" must be a primitive value (string, number, boolean), got ${typeof val}`,
-            { code: "RF_FE_003", route: meta.name, context: { param: name, value: val } }
-          );
+          throw new InvalidPathParamError(meta.name, name, val);
         }
         return encodeURIComponent(String(val));
       }
@@ -674,24 +746,31 @@ var RouteForge = (function (exports) {
   }
 
   // src/auto-discovery.ts
+  var DEFAULT_ENDPOINT = "/_forge/routes";
   async function fetchSummary(inputs, baseURL, fetchMeta) {
-    const { explicitLevels, explicitEndpoint } = inputs;
-    if (!explicitEndpoint) {
-      throw new UnknownLevelError("(auto-discovery)");
-    }
+    const { explicitLevels, explicitEndpoint, warnings } = inputs;
+    const endpoint = explicitEndpoint ?? DEFAULT_ENDPOINT;
+    const base = baseURL.endsWith("/") ? baseURL.slice(0, -1) : baseURL;
+    const ep = endpoint.startsWith("/") ? endpoint : `/${endpoint}`;
+    const url = `${base}${ep}`;
     try {
-      const base = baseURL.endsWith("/") ? baseURL.slice(0, -1) : baseURL;
-      const ep = explicitEndpoint.startsWith("/") ? explicitEndpoint : `/${explicitEndpoint}`;
-      const data = await fetchMeta("__forge__.summary", `${base}${ep}`);
+      const data = await fetchMeta("__forge__.summary", url);
       return data;
     } catch (e) {
       if (explicitLevels && explicitLevels.length > 0) {
-        console.warn(
-          `[route-forge] summary endpoint unreachable: ${e.message}; using explicit levels`
-        );
+        if (warnings) {
+          console.warn(
+            `[route-forge] summary endpoint unreachable: ${e.message}; using explicit levels`
+          );
+        }
         return null;
       }
-      throw new UnknownLevelError("(auto-discovery)");
+      throw new NetworkError(
+        `Failed to fetch route summary from "${url}": ${e?.message ?? String(e)}; check the backend manifest endpoint or options.endpoint`,
+        void 0,
+        void 0,
+        e
+      );
     }
   }
   function normalizeCacheTtl(raw) {
@@ -699,15 +778,15 @@ var RouteForge = (function (exports) {
     return raw;
   }
   function applySummaryToState(summary, state, inputs) {
-    const { explicitLevels, explicitEager, explicitEndpoint } = inputs;
+    const { explicitLevels, explicitEager, explicitEndpoint, warnings } = inputs;
     const schemeVersion = summary.schemeVersion ?? 1;
-    if (schemeVersion > 1) {
+    if (schemeVersion > 1 && warnings) {
       console.warn(
         `[route-forge] backend schemeVersion=${schemeVersion} > client supported 1; some features may be unavailable`
       );
     }
     if (summary.config.endpoint_prefix && summary.config.endpoint_prefix !== explicitEndpoint) {
-      if (explicitEndpoint) {
+      if (explicitEndpoint && warnings) {
         console.warn(
           `[route-forge] backend endpoint_prefix "${summary.config.endpoint_prefix}" overrides frontend endpoint "${explicitEndpoint}"`
         );
@@ -730,7 +809,7 @@ var RouteForge = (function (exports) {
     if (explicitLevels && explicitLevels.length > 0) {
       const intersection = explicitLevels.filter((l) => backendLevels.includes(l));
       const removed = explicitLevels.filter((l) => !backendLevels.includes(l));
-      if (removed.length > 0) {
+      if (removed.length > 0 && warnings) {
         console.warn(
           `[route-forge] levels not in backend summary and dropped: ${removed.join(", ")}`
         );
@@ -782,7 +861,7 @@ var RouteForge = (function (exports) {
     }
     assertLevelDeclared(level) {
       if (!this.state.levels.includes(level)) {
-        throw new UnknownLevelError(level);
+        throw new UnknownLevelError(level, this.state.levels);
       }
     }
     async fetchLevel(level) {
@@ -856,6 +935,7 @@ var RouteForge = (function (exports) {
     }
     getRoutes(level) {
       if (level !== void 0) {
+        this.assertLevelDeclared(level);
         const entry = this.cache.get(level);
         const routes = entry?.routes ?? {};
         const result2 = {};
@@ -887,6 +967,7 @@ var RouteForge = (function (exports) {
       responseInterceptors,
       load,
       findRouteMeta,
+      getRouteNames,
       baseURL,
       state,
       timeout,
@@ -938,7 +1019,10 @@ var RouteForge = (function (exports) {
                   level: resp.level,
                   status: resp.status,
                   url: resp.url,
-                  method: resp.method
+                  method: resp.method,
+                  // 完整 ResponseData 随错误逐段传递（响应拦截器 onRejected 链 → 最终 catch），
+                  // 供调用方检查响应体，如 Laravel 422 校验错误 err.response.data.errors
+                  response: resp
                 }
               );
             }
@@ -976,7 +1060,7 @@ var RouteForge = (function (exports) {
         await load(level);
         const meta = findRouteMeta(level, name);
         if (!meta) {
-          throw new UnknownRouteError(name, level);
+          throw new UnknownRouteError(name, level, getRouteNames(level));
         }
         return doApiCall(meta, params, ctrl.signal);
       })();
@@ -993,22 +1077,31 @@ var RouteForge = (function (exports) {
   }
 
   // src/resolveRouteName.ts
+  function stripTrailingSeparator(prefix, separator) {
+    let normalized = prefix;
+    while (normalized.endsWith(separator)) {
+      normalized = normalized.slice(0, -separator.length);
+    }
+    return normalized;
+  }
   async function resolveRouteName(forge, level, prefix, suffix, separator = ".") {
-    if (!suffix) return prefix;
-    const joined = `${prefix}${separator}${suffix}`;
-    if (!suffix.startsWith(`${prefix}${separator}`)) return joined;
+    const normalized = stripTrailingSeparator(prefix, separator);
+    if (!suffix) return normalized;
+    const joined = `${normalized}${separator}${suffix}`;
+    if (!suffix.startsWith(`${normalized}${separator}`)) return joined;
     await forge.load(level);
     if (forge.hasRoute(level, joined)) return joined;
     if (forge.hasRoute(level, suffix)) return suffix;
-    throw new UnknownRouteError(joined, level);
+    throw new UnknownRouteError(joined, level, forge.getRouteNames?.(level));
   }
   function resolveRouteNameSync(forge, level, prefix, suffix, separator = ".") {
-    if (!suffix) return prefix;
-    const joined = `${prefix}${separator}${suffix}`;
-    if (!suffix.startsWith(`${prefix}${separator}`)) return joined;
+    const normalized = stripTrailingSeparator(prefix, separator);
+    if (!suffix) return normalized;
+    const joined = `${normalized}${separator}${suffix}`;
+    if (!suffix.startsWith(`${normalized}${separator}`)) return joined;
     if (forge.hasRoute(level, joined)) return joined;
     if (forge.hasRoute(level, suffix)) return suffix;
-    throw new UnknownRouteError(joined, level);
+    throw new UnknownRouteError(joined, level, forge.getRouteNames?.(level));
   }
 
   // src/defineImmutableProps.ts
@@ -1028,7 +1121,7 @@ var RouteForge = (function (exports) {
   // src/bound-forge.ts
   function createBoundForgeFactory(deps) {
     const { load, api, route, hasRoute, getRoutes, invalidate, isLoaded, loadingTracker } = deps;
-    const resolver = { load, hasRoute };
+    const resolver = { load, hasRoute, getRouteNames: (lvl) => Object.keys(getRoutes(lvl)) };
     function createBoundForge(level, prefix) {
       const levelLoadedPromise = load(level);
       levelLoadedPromise.catch(() => {
@@ -1094,11 +1187,6 @@ var RouteForge = (function (exports) {
   var DEFAULT_CACHE_TTL = 3600;
   function createRouteForge(options = {}) {
     const bootstrapSummary = readEmbeddedSummary() ?? options.summary ?? null;
-    if (!bootstrapSummary && !options.endpoint) {
-      throw new TypeError(
-        "createRouteForge: \u9700\u8981 options.endpoint\uFF0C\u6216 options.summary\uFF0C\u6216\u9875\u9762\u5185\u5D4C window.__ROUTE_FORGE__"
-      );
-    }
     const {
       adapter = "auto",
       timeout = DEFAULT_TIMEOUT,
@@ -1106,6 +1194,7 @@ var RouteForge = (function (exports) {
       interceptors: declarativeInterceptors,
       cache: cacheOpts = {}
     } = options;
+    const warnings = options.warnings ?? true;
     const loadingTracker = new LoadingTracker();
     const explicitLevels = options.levels;
     const explicitEager = options.eager;
@@ -1113,12 +1202,12 @@ var RouteForge = (function (exports) {
     const discoveryState = {
       levels: explicitLevels ?? [],
       eager: explicitEager ?? [],
-      endpoint: explicitEndpoint ?? bootstrapSummary?.config?.endpoint_prefix ?? "",
+      endpoint: explicitEndpoint ?? bootstrapSummary?.config?.endpoint_prefix ?? DEFAULT_ENDPOINT,
       urlPrefix: "",
       cacheTtl: void 0,
       levelRoutes: {}
     };
-    const discoveryInputs = { explicitLevels, explicitEager, explicitEndpoint };
+    const discoveryInputs = { explicitLevels, explicitEager, explicitEndpoint, warnings };
     let autoDiscoveryCompleted = false;
     let resolveReady;
     let rejectReady;
@@ -1128,30 +1217,30 @@ var RouteForge = (function (exports) {
     });
     readyPromise.catch(() => {
     });
+    let readySettledOk = false;
+    readyPromise.then(
+      () => {
+        readySettledOk = true;
+      },
+      () => {
+      }
+    );
     const cacheTtl = cacheOpts.ttl ?? DEFAULT_CACHE_TTL;
     const cacheStorage = cacheOpts.storage ?? "memory";
     const cache = new RouteCache({ storage: cacheStorage, ttl: cacheTtl });
     const requestInterceptors = new InterceptorManagerImpl();
     const responseInterceptors = new InterceptorManagerImpl();
-    if (declarativeInterceptors?.request) {
-      for (const entry of declarativeInterceptors.request) {
-        if (typeof entry === "function") {
-          requestInterceptors.use(entry);
-        } else {
-          const [onFulfilled, onRejected] = entry;
-          requestInterceptors.use(onFulfilled, onRejected);
-        }
-      }
+    const reqDecl = normalizeInterceptorDeclaration(
+      declarativeInterceptors?.request
+    );
+    if (reqDecl.onFulfilled || reqDecl.onRejected) {
+      requestInterceptors.use(reqDecl.onFulfilled, reqDecl.onRejected);
     }
-    if (declarativeInterceptors?.response) {
-      for (const entry of declarativeInterceptors.response) {
-        if (typeof entry === "function") {
-          responseInterceptors.use(entry);
-        } else {
-          const [onFulfilled, onRejected] = entry;
-          responseInterceptors.use(onFulfilled, onRejected);
-        }
-      }
+    const resDecl = normalizeInterceptorDeclaration(
+      declarativeInterceptors?.response
+    );
+    if (resDecl.onFulfilled || resDecl.onRejected) {
+      responseInterceptors.use(resDecl.onFulfilled, resDecl.onRejected);
     }
     const adapterPromise = resolveAdapter({
       adapter,
@@ -1163,6 +1252,11 @@ var RouteForge = (function (exports) {
       if (!adapterResolved) {
         adapterObj = await adapterPromise.catch((e) => {
           if (e instanceof AdapterNotFoundError) throw e;
+          if (warnings) {
+            console.warn(
+              `[route-forge] adapter initialization failed (${e?.message ?? String(e)}); falling back to builtin`
+            );
+          }
           return resolveAdapter({
             adapter: "builtin",
             forgeInterceptors: { request: requestInterceptors, response: responseInterceptors }
@@ -1174,10 +1268,7 @@ var RouteForge = (function (exports) {
     }
     function assertDiscoveryReady() {
       if (!autoDiscoveryCompleted && !explicitLevels?.length) {
-        throw new ForgeError(
-          "Route data not available. Auto-discovery has not completed. Use forge.ready() or forge.use(level) first.",
-          { code: "RF_FE_010" }
-        );
+        throw new DiscoveryNotReadyError();
       }
     }
     async function fetchMeta(routeTag, url, level = "") {
@@ -1202,8 +1293,8 @@ var RouteForge = (function (exports) {
       const resp = await doRawRequest(config);
       if (!resp || resp.status < 200 || resp.status >= 300) {
         throw new HTTPError(
-          `Failed to fetch "${routeTag}": HTTP ${resp?.status}`,
-          { level, status: resp?.status, url, method: "GET" }
+          `Failed to fetch "${routeTag}" (${url}): HTTP ${resp?.status}`,
+          { level, status: resp?.status, url, method: "GET", response: resp ?? void 0 }
         );
       }
       return resp.data;
@@ -1240,11 +1331,14 @@ var RouteForge = (function (exports) {
     function getRoutes(level) {
       return level === void 0 ? store.getRoutes() : store.getRoutes(level);
     }
+    function getLevels() {
+      return [...discoveryState.levels];
+    }
     function route(level, name, params) {
       assertDiscoveryReady();
       const meta = findRouteMeta(level, name);
       if (!meta) {
-        throw new UnknownRouteError(name, level);
+        throw new UnknownRouteError(name, level, Object.keys(store.getRoutes(level)));
       }
       return buildRequestUrl(meta, params ?? {}, { baseURL, urlPrefix: discoveryState.urlPrefix });
     }
@@ -1254,6 +1348,7 @@ var RouteForge = (function (exports) {
       responseInterceptors,
       load,
       findRouteMeta,
+      getRouteNames: (lvl) => Object.keys(store.getRoutes(lvl)),
       baseURL,
       state: discoveryState,
       timeout,
@@ -1309,7 +1404,10 @@ var RouteForge = (function (exports) {
       isLoaded,
       hasRoute,
       getRoutes,
+      getLevels,
+      warnings,
       isLoading: () => loadingTracker.isLoading(),
+      isReady: () => readySettledOk,
       onLoadingChange: (cb) => loadingTracker.subscribe(cb),
       interceptors: {
         request: requestInterceptors,
@@ -1325,10 +1423,12 @@ var RouteForge = (function (exports) {
   }
 
   exports.AdapterNotFoundError = AdapterNotFoundError;
+  exports.DiscoveryNotReadyError = DiscoveryNotReadyError;
   exports.ForgeError = ForgeError;
   exports.HTTPError = HTTPError;
   exports.InterceptorManagerImpl = InterceptorManagerImpl;
   exports.InvalidInterceptorReturnError = InvalidInterceptorReturnError;
+  exports.InvalidPathParamError = InvalidPathParamError;
   exports.LoadingTracker = LoadingTracker;
   exports.MissingRouteParamError = MissingRouteParamError;
   exports.NetworkError = NetworkError;