@route-forge/core 2.2.1 → 3.0.0

package/dist/index.cjs

@@ -143,30 +143,56 @@ var ForgeError = class extends Error {
     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 {
@@ -199,6 +225,7 @@ var HTTPError = class extends ForgeError {
       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 {
@@ -211,6 +238,14 @@ var RequestAbortedError = class extends ForgeError {
     });
   }
 };
+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 {
@@ -277,6 +312,43 @@ async function runResponseInterceptors(manager, source) {
 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) {
@@ -377,7 +449,10 @@ async function rawFetch(config) {
       level: config.level,
       status: res.status,
       url,
-      method: config.method
+      method: config.method,
+      // 完整 ResponseData 随错误逐段传递（响应拦截器 onRejected 链 → 最终 catch），
+      // 供调用方检查响应体，如 Laravel 422 校验错误 err.response.data.errors
+      response: responseData
     }
   );
 }
@@ -589,7 +664,7 @@ function buildRequestUrl(meta, params, ctx) {
     }
   }
   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("?");
@@ -597,10 +672,7 @@ function buildRequestUrl(meta, params, ctx) {
     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));
     }
@@ -673,24 +745,31 @@ function resolveApiParams(input) {
 }
 
 // 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) {
@@ -698,15 +777,15 @@ function normalizeCacheTtl(raw) {
   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}"`
       );
@@ -729,7 +808,7 @@ function applySummaryToState(summary, state, inputs) {
   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(", ")}`
       );
@@ -781,7 +860,7 @@ var RouteStore = class {
   }
   assertLevelDeclared(level) {
     if (!this.state.levels.includes(level)) {
-      throw new UnknownLevelError(level);
+      throw new UnknownLevelError(level, this.state.levels);
     }
   }
   async fetchLevel(level) {
@@ -855,6 +934,7 @@ var RouteStore = class {
   }
   getRoutes(level) {
     if (level !== void 0) {
+      this.assertLevelDeclared(level);
       const entry = this.cache.get(level);
       const routes = entry?.routes ?? {};
       const result2 = {};
@@ -886,6 +966,7 @@ function createHttpRunner(deps) {
     responseInterceptors,
     load,
     findRouteMeta,
+    getRouteNames,
     baseURL,
     state,
     timeout,
@@ -937,7 +1018,10 @@ function createHttpRunner(deps) {
                 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
               }
             );
           }
@@ -975,7 +1059,7 @@ function createHttpRunner(deps) {
       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);
     })();
@@ -992,22 +1076,31 @@ function createHttpRunner(deps) {
 }
 
 // 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
@@ -1027,7 +1120,7 @@ function defineImmutableProps(target, props) {
 // 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(() => {
@@ -1093,11 +1186,6 @@ var DEFAULT_TIMEOUT = 3e4;
 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,
@@ -1105,6 +1193,7 @@ function createRouteForge(options = {}) {
     interceptors: declarativeInterceptors,
     cache: cacheOpts = {}
   } = options;
+  const warnings = options.warnings ?? true;
   const loadingTracker = new LoadingTracker();
   const explicitLevels = options.levels;
   const explicitEager = options.eager;
@@ -1112,12 +1201,12 @@ function createRouteForge(options = {}) {
   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;
@@ -1127,30 +1216,30 @@ function createRouteForge(options = {}) {
   });
   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,
@@ -1162,6 +1251,11 @@ function createRouteForge(options = {}) {
     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 }
@@ -1173,10 +1267,7 @@ function createRouteForge(options = {}) {
   }
   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 = "") {
@@ -1201,8 +1292,8 @@ function createRouteForge(options = {}) {
     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;
@@ -1239,11 +1330,14 @@ function createRouteForge(options = {}) {
   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 });
   }
@@ -1253,6 +1347,7 @@ function createRouteForge(options = {}) {
     responseInterceptors,
     load,
     findRouteMeta,
+    getRouteNames: (lvl) => Object.keys(store.getRoutes(lvl)),
     baseURL,
     state: discoveryState,
     timeout,
@@ -1308,7 +1403,10 @@ function createRouteForge(options = {}) {
     isLoaded,
     hasRoute,
     getRoutes,
+    getLevels,
+    warnings,
     isLoading: () => loadingTracker.isLoading(),
+    isReady: () => readySettledOk,
     onLoadingChange: (cb) => loadingTracker.subscribe(cb),
     interceptors: {
       request: requestInterceptors,
@@ -1324,10 +1422,12 @@ function createRouteForge(options = {}) {
 }
 
 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;