@route-forge/core 1.0.0 → 1.0.3

package/dist/index.cjs

@@ -28,17 +28,19 @@ var RouteCache = class {
       return this.getFromMemory(level);
     }
     const raw = this.backend.getItem(this.key(level));
-    if (!raw) return void 0;
-    try {
-      const entry = JSON.parse(raw);
-      if (this.isExpired(entry)) {
-        this.del(level);
+    if (raw) {
+      try {
+        const entry = JSON.parse(raw);
+        if (this.isExpired(entry)) {
+          this.del(level);
+          return void 0;
+        }
+        return entry;
+      } catch {
         return void 0;
       }
-      return entry;
-    } catch {
-      return void 0;
     }
+    return this.getFromMemory(level);
   }
   getFromMemory(level) {
     const entry = this.memory.get(level);
@@ -172,6 +174,16 @@ var HTTPError = class extends ForgeError {
     });
   }
 };
+var RequestAbortedError = class extends ForgeError {
+  constructor(route, level, cause) {
+    super(`Request aborted${route ? ` for route "${route}"` : ""}`, {
+      code: "RF_FE_009",
+      route,
+      level,
+      cause
+    });
+  }
+};
 
 // src/interceptors.ts
 var InterceptorManagerImpl = class {
@@ -240,12 +252,40 @@ function createInterceptorManager() {
 }
 
 // src/adapters/builtin-http.ts
+function isPassthroughBody(body) {
+  if (body === null) return false;
+  return typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams || typeof Blob !== "undefined" && body instanceof Blob || typeof ArrayBuffer !== "undefined" && (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) || typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
+}
+function isAbortError(err) {
+  const e = err;
+  return !!e && e.name === "AbortError";
+}
+function combineSignals(...signals) {
+  const valid = signals.filter((s) => !!s);
+  if (valid.length === 0) return void 0;
+  if (valid.length === 1) return valid[0];
+  if (typeof AbortSignal !== "undefined" && typeof AbortSignal.any === "function") {
+    return AbortSignal.any(valid);
+  }
+  const controller = new AbortController();
+  for (const s of valid) {
+    if (s.aborted) {
+      controller.abort(s.reason);
+      return controller.signal;
+    }
+    s.addEventListener("abort", () => controller.abort(s.reason), { once: true });
+  }
+  return controller.signal;
+}
 function createBuiltinHttp(forgeInterceptors) {
   const requestMgr = forgeInterceptors?.request ?? createInterceptorManager();
   const responseMgr = forgeInterceptors?.response ?? createInterceptorManager();
   async function request(config) {
     const finalConfig = await runRequestInterceptors(requestMgr, config);
-    const signal = finalConfig.timeout && finalConfig.timeout > 0 ? AbortSignal.timeout(finalConfig.timeout) : void 0;
+    const signal = combineSignals(
+      finalConfig.signal,
+      finalConfig.timeout && finalConfig.timeout > 0 ? AbortSignal.timeout(finalConfig.timeout) : void 0
+    );
     let url = finalConfig.url;
     if (finalConfig.paramsSerializer && finalConfig.params) {
       const qs = finalConfig.paramsSerializer(finalConfig.params);
@@ -253,15 +293,34 @@ function createBuiltinHttp(forgeInterceptors) {
         url = url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
       }
     }
+    const headers = new Headers(finalConfig.headers);
     const fetchInit = {
       method: finalConfig.method,
-      headers: new Headers(finalConfig.headers)
+      headers
     };
     if (signal) fetchInit.signal = signal;
     if (finalConfig.body !== void 0 && !["GET", "HEAD"].includes(finalConfig.method.toUpperCase())) {
-      fetchInit.body = typeof finalConfig.body === "string" ? finalConfig.body : JSON.stringify(finalConfig.body);
+      if (typeof finalConfig.body === "string" || isPassthroughBody(finalConfig.body)) {
+        fetchInit.body = finalConfig.body;
+      } else {
+        fetchInit.body = JSON.stringify(finalConfig.body);
+        if (!headers.has("Content-Type")) {
+          headers.set("Content-Type", "application/json");
+        }
+      }
+    }
+    let res;
+    try {
+      res = await fetch(url, fetchInit);
+    } catch (e) {
+      if (isAbortError(e)) throw e;
+      throw new NetworkError(
+        e instanceof Error ? e.message : String(e),
+        finalConfig.route,
+        finalConfig.level,
+        e
+      );
     }
-    const res = await fetch(url, fetchInit);
     const text = await res.text();
     let data = text;
     const contentType = res.headers.get("content-type") ?? "";
@@ -281,9 +340,21 @@ function createBuiltinHttp(forgeInterceptors) {
       data,
       config: finalConfig
     };
+    const source = res.status >= 200 && res.status < 300 ? Promise.resolve(responseData) : Promise.reject(
+      new HTTPError(
+        `HTTP ${res.status} for route "${finalConfig.route}" (${finalConfig.method} ${url})`,
+        {
+          route: finalConfig.route,
+          level: finalConfig.level,
+          status: res.status,
+          url,
+          method: finalConfig.method
+        }
+      )
+    );
     return runResponseInterceptors(
       responseMgr,
-      Promise.resolve(responseData)
+      source
     );
   }
   const get = (url, config) => request({ ...config, url, method: "GET" });
@@ -307,6 +378,15 @@ function createBuiltinHttp(forgeInterceptors) {
 }
 
 // src/adapters/axios.ts
+function toHeaders(raw) {
+  if (!raw) return new Headers();
+  const init = typeof raw.toJSON === "function" ? raw.toJSON() : raw;
+  try {
+    return new Headers(init);
+  } catch {
+    return new Headers();
+  }
+}
 async function wrapAxiosAdapter() {
   let axios;
   try {
@@ -323,23 +403,43 @@ async function wrapAxiosAdapter() {
   if (!axios || typeof axios.request !== "function") return null;
   async function request(config) {
     const headers = { ...config.headers };
-    const res = await axios.request({
-      url: config.url,
-      method: config.method,
-      headers,
-      data: config.body
-      // axios 会处理 baseURL/transformRequest 等 defaults
-    });
-    return {
-      route: config.route,
-      level: config.level,
-      method: config.method,
-      url: config.url,
-      status: res.status,
-      headers: new Headers(res.headers ?? {}),
-      data: res.data,
-      config
-    };
+    try {
+      const res = await axios.request({
+        url: config.url,
+        method: config.method,
+        headers,
+        data: config.body,
+        // axios 会处理 baseURL/transformRequest 等 defaults；timeout 透传保证超时语义与 builtin 一致
+        timeout: config.timeout,
+        signal: config.signal
+        // 请求取消信号（AbortSignal）
+      });
+      return {
+        route: config.route,
+        level: config.level,
+        method: config.method,
+        url: config.url,
+        status: res.status,
+        headers: toHeaders(res.headers),
+        data: res.data,
+        config
+      };
+    } catch (e) {
+      if (e && e.response) {
+        const resp = e.response;
+        return {
+          route: config.route,
+          level: config.level,
+          method: config.method,
+          url: config.url,
+          status: resp.status,
+          headers: toHeaders(resp.headers),
+          data: resp.data,
+          config
+        };
+      }
+      throw e;
+    }
   }
   return { request, interceptors: void 0 };
 }
@@ -428,6 +528,7 @@ var LoadingTracker = class {
 // src/forge.ts
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_CACHE_TTL = 3600;
+var UNASSIGNED_LEVEL = "unassigned";
 function createRouteForge(options) {
   if (!options.endpoint) throw new TypeError("options.endpoint is required");
   const {
@@ -446,6 +547,8 @@ function createRouteForge(options) {
   let effectiveEager = explicitEager ?? [];
   let effectiveEndpoint = explicitEndpoint;
   let effectiveUrlPrefix = "";
+  let summaryUnassigned;
+  let backendHasUnassignedLevel = false;
   const summaryPromise = (async () => {
     try {
       const summaryUrl = explicitEndpoint;
@@ -471,6 +574,12 @@ function createRouteForge(options) {
     if (summary === null) {
       return;
     }
+    const schemaVersion = summary.schemaVersion ?? 1;
+    if (schemaVersion > 1) {
+      console.warn(
+        `[route-forge] backend schemaVersion=${schemaVersion} > client supported 1; some features may be unavailable`
+      );
+    }
     if (summary.config.endpoint_prefix && summary.config.endpoint_prefix !== explicitEndpoint) {
       console.warn(
         `[route-forge] backend endpoint_prefix "${summary.config.endpoint_prefix}" overrides frontend endpoint "${explicitEndpoint}"`
@@ -486,9 +595,17 @@ function createRouteForge(options) {
       );
     }
     const backendLevels = Object.keys(summary.levels);
+    backendHasUnassignedLevel = backendLevels.includes(UNASSIGNED_LEVEL);
+    if (Array.isArray(summary.unassigned) && summary.unassigned.length > 0 && !backendHasUnassignedLevel) {
+      summaryUnassigned = summary.unassigned;
+    }
+    const availableLevels = backendLevels.slice();
+    if (summaryUnassigned && !backendHasUnassignedLevel) {
+      availableLevels.push(UNASSIGNED_LEVEL);
+    }
     if (explicitLevels && explicitLevels.length > 0) {
-      const intersection = explicitLevels.filter((l) => backendLevels.includes(l));
-      const removed = explicitLevels.filter((l) => !backendLevels.includes(l));
+      const intersection = explicitLevels.filter((l) => availableLevels.includes(l));
+      const removed = explicitLevels.filter((l) => !availableLevels.includes(l));
       if (removed.length > 0) {
         console.warn(
           `[route-forge] levels not in backend summary and dropped: ${removed.join(", ")}`
@@ -496,7 +613,7 @@ function createRouteForge(options) {
       }
       effectiveLevels = intersection;
     } else {
-      effectiveLevels = backendLevels;
+      effectiveLevels = availableLevels;
     }
     const backendEager = backendLevels.filter((lvl) => summary.levels[lvl]?.load === "eager");
     if (!explicitEager) {
@@ -580,7 +697,10 @@ function createRouteForge(options) {
     };
     const resp = await adp.request(config);
     if (!resp || resp.status < 200 || resp.status >= 300) {
-      throw new Error(`Failed to load level ${level}: HTTP ${resp?.status}`);
+      throw new HTTPError(
+        `Failed to load level "${level}": HTTP ${resp?.status}`,
+        { level, status: resp?.status, url: buildUrl(level), method: "GET" }
+      );
     }
     const data = resp.data;
     return data;
@@ -592,6 +712,14 @@ function createRouteForge(options) {
     if (existing) return existing;
     const p = (async () => {
       try {
+        if (level === UNASSIGNED_LEVEL && !backendHasUnassignedLevel && summaryUnassigned) {
+          const routes = {};
+          for (const r of summaryUnassigned) {
+            routes[r.name] = { ...r, level: UNASSIGNED_LEVEL };
+          }
+          cache.set({ level: UNASSIGNED_LEVEL, routes, cache: null });
+          return;
+        }
         const resp = await fetchLevel(level);
         cache.set(resp);
       } finally {
@@ -614,27 +742,33 @@ function createRouteForge(options) {
     return buildRequestUrl(meta, params ?? {});
   }
   function buildRequestUrl(meta, params) {
-    let uri = meta.uri;
     const defaults = meta.parameter_defaults ?? {};
     const missingRequired = [];
+    const values = {};
     for (const p of meta.parameters) {
       let v = params[p];
       if ((v === void 0 || v === null) && p in defaults) {
         v = defaults[p];
       }
       if (v === void 0 || v === null) {
-        if (uri.includes(`{${p}?}`)) {
-          uri = uri.replace(`{${p}?}`, "");
-          continue;
+        if (!meta.uri.includes(`{${p}?}`)) {
+          missingRequired.push(p);
         }
-        missingRequired.push(p);
       } else {
-        uri = uri.replace(`{${p}?}`, encodeURIComponent(String(v))).replace(`{${p}}`, encodeURIComponent(String(v)));
+        values[p] = v;
       }
     }
     if (missingRequired.length > 0) {
       throw new MissingRouteParamError(meta.name, missingRequired);
     }
+    let uri = meta.uri.replace(/\{([^{}]+)\}/g, (match, raw) => {
+      const optional = raw.endsWith("?");
+      const name = optional ? raw.slice(0, -1) : raw;
+      if (values[name] !== void 0) {
+        return encodeURIComponent(String(values[name]));
+      }
+      return optional ? "" : match;
+    });
     uri = uri.replace(/\/+/g, "/").replace(/\/$/, "");
     if (effectiveUrlPrefix.includes("://")) {
       const prefix2 = effectiveUrlPrefix.endsWith("/") ? effectiveUrlPrefix.slice(0, -1) : effectiveUrlPrefix;
@@ -662,7 +796,17 @@ function createRouteForge(options) {
     return doApiCall(meta, params);
   }
   async function doApiCall(meta, params) {
-    const { pathParams, query, body, headers } = resolveApiParams(params);
+    const {
+      pathParams,
+      query,
+      body,
+      headers,
+      timeout: perCallTimeout,
+      signal
+    } = resolveApiParams(params);
+    if (signal?.aborted) {
+      throw new RequestAbortedError(meta.name, meta.level, signal.reason);
+    }
     const method = pickMethod(meta);
     const urlWithQuery = appendQuery(buildRequestUrl(meta, pathParams), query);
     const config = {
@@ -673,11 +817,15 @@ function createRouteForge(options) {
       headers: { Accept: "application/json", ...headers ?? {} },
       body,
       params: pathParams,
-      timeout,
+      timeout: perCallTimeout ?? timeout,
+      signal,
       meta
     };
     const adp = await ensureAdapter();
     const finalConfig = adp.runsInterceptors ? config : await runRequestInterceptors(requestInterceptors, config);
+    if (finalConfig.signal?.aborted) {
+      throw new RequestAbortedError(meta.name, meta.level, finalConfig.signal.reason);
+    }
     loadingTracker.start();
     try {
       const source = adp.request(finalConfig).then(
@@ -698,6 +846,9 @@ function createRouteForge(options) {
         },
         (err) => {
           if (err instanceof ForgeError) throw err;
+          if (isAbortError2(err, finalConfig.signal)) {
+            throw new RequestAbortedError(meta.name, meta.level, err);
+          }
           throw new NetworkError(
             err instanceof Error ? err.message : String(err),
             meta.name,
@@ -713,12 +864,17 @@ function createRouteForge(options) {
     }
   }
   function invalidate(level) {
-    if (level) cache.del(level);
-    else cache.clear();
+    if (level === void 0) {
+      cache.clear();
+    } else if (Array.isArray(level)) {
+      for (const lvl of level) cache.del(lvl);
+    } else {
+      cache.del(level);
+    }
   }
   function isLoaded(level) {
     if (level) return cache.get(level) !== void 0;
-    return effectiveLevels.every((lvl) => cache.get(lvl) !== void 0);
+    return effectiveLevels.length > 0 && effectiveLevels.every((lvl) => cache.get(lvl) !== void 0);
   }
   function hasRoute(level, name) {
     return findRouteMeta(level, name) !== void 0;
@@ -792,6 +948,8 @@ function resolveApiParams(input) {
     query: rawQuery,
     body: rawBody,
     headers: rawHeaders,
+    timeout: perCallTimeout,
+    signal,
     ...flatRest
   } = input;
   const pathParams = explicitParams ? { ...explicitParams } : {};
@@ -824,7 +982,15 @@ function resolveApiParams(input) {
       pathParams.headers = rawHeaders;
     }
   }
-  return { pathParams, query, body, headers };
+  return { pathParams, query, body, headers, timeout: perCallTimeout, signal };
+}
+function isAbortError2(err, signal) {
+  if (signal?.aborted) return true;
+  const e = err;
+  if (!e) return false;
+  if (e.name === "AbortError") return true;
+  if (e.code === "ERR_CANCELED") return true;
+  return false;
 }
 
 exports.AdapterNotFoundError = AdapterNotFoundError;
@@ -835,6 +1001,7 @@ exports.InvalidInterceptorReturnError = InvalidInterceptorReturnError;
 exports.LoadingTracker = LoadingTracker;
 exports.MissingRouteParamError = MissingRouteParamError;
 exports.NetworkError = NetworkError;
+exports.RequestAbortedError = RequestAbortedError;
 exports.RouteCache = RouteCache;
 exports.UnknownLevelError = UnknownLevelError;
 exports.UnknownRouteError = UnknownRouteError;