@route-forge/core 1.3.1 → 2.0.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { I as InterceptorManager, a as InterceptorHandler, C as CacheStorage, R as RouteMeta, L as LevelRoutesResponse, b as RouteForgeOptions, c as RouteForge } from './types-Cd1c1OdJ.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, r as UseForgeByPrefixReturn } from './types-Cd1c1OdJ.js';
+import { I as InterceptorManager, a as InterceptorHandler, C as CacheStorage, R as RouteMeta, L as LevelRoutesResponse, b as RouteForgeOptions, c as RouteForge } from './types-BvLdl02f.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-BvLdl02f.js';
 
 /**
  * 拦截器管理器实现
@@ -45,6 +45,10 @@ declare function createInterceptorManager<TIn, TOut = TIn>(): InterceptorManager
  * - 每层级独立条目，互不污染（cache key = `route-forge:${level}`）
  * - TTL 优先用后端响应里的 cache 字段，本地 cache.ttl 仅作兜底
  * - storage: 'memory' | 'sessionStorage' | 'localStorage'
+ * - storage 模式下维护内存镜像：首次读盘解析后驻留内存，后续 get 直接命中
+ *   （读盘 + JSON.parse 整层路由表是同步阻塞操作，热路径重复执行代价高）；
+ *   写操作（set/del/clear）同步更新镜像，并通过 storage 事件感知其他
+ *   tab 的写入/失效，保证跨 tab 新鲜度与无镜像时一致
  */
 
 interface CacheEntry {
@@ -58,6 +62,8 @@ declare class RouteCache {
     private readonly fallbackTtl;
     private readonly backend;
     private readonly memory;
+    /** 其他 tab 修改 storage 时失效对应镜像（storage 事件：自己的写不触发，自己的写经 set/del 已同步） */
+    private readonly onStorageEvent;
     constructor(opts: {
         storage: CacheStorage;
         ttl: number;
@@ -78,14 +84,19 @@ declare class RouteCache {
 interface ForgeErrorContext {
     [key: string]: unknown;
 }
+/**
+ * Route Forge 错误码字面量联合。
+ * 用户侧 `switch (e.code)` 可获得穷尽检查（漏分支编译报错）。
+ */
+type ForgeErrorCode = 'RF_FE_001' | 'RF_FE_002' | 'RF_FE_003' | 'RF_FE_005' | 'RF_FE_006' | 'RF_FE_007' | 'RF_FE_008' | 'RF_FE_009' | 'RF_FE_010';
 declare class ForgeError extends Error {
-    readonly code: string;
+    readonly code: ForgeErrorCode;
     readonly route?: string;
     readonly level?: string;
     readonly context?: ForgeErrorContext;
     readonly cause?: unknown;
     constructor(message: string, opts: {
-        code: string;
+        code: ForgeErrorCode;
         route?: string;
         level?: string;
         context?: ForgeErrorContext;
@@ -177,4 +188,4 @@ declare function resolveRouteName(forge: RouteResolver, level: string, prefix: s
  */
 declare function resolveRouteNameSync(forge: RouteResolver, level: string, prefix: string, suffix: string, separator?: string): string;
 
-export { AdapterNotFoundError, CacheStorage, ForgeError, HTTPError, InterceptorHandler, InterceptorManager, InterceptorManagerImpl, InvalidInterceptorReturnError, LevelRoutesResponse, MissingRouteParamError, NetworkError, RequestAbortedError, RouteCache, RouteForge, RouteForgeOptions, RouteMeta, type RouteResolver, UnknownLevelError, UnknownRouteError, createInterceptorManager, createRouteForge, resolveRouteName, resolveRouteNameSync };
+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 };

package/dist/index.js

@@ -14,9 +14,18 @@ function pickStorage(storage) {
 var RouteCache = class {
   constructor(opts) {
     this.memory = /* @__PURE__ */ new Map();
+    /** 其他 tab 修改 storage 时失效对应镜像（storage 事件：自己的写不触发，自己的写经 set/del 已同步） */
+    this.onStorageEvent = (e) => {
+      if (!e.key) return;
+      if (!e.key.startsWith(KEY_PREFIX)) return;
+      this.memory.delete(e.key.slice(KEY_PREFIX.length));
+    };
     this.storage = opts.storage;
     this.fallbackTtl = opts.ttl;
     this.backend = pickStorage(opts.storage);
+    if (this.backend && typeof globalThis.addEventListener === "function") {
+      globalThis.addEventListener("storage", this.onStorageEvent);
+    }
   }
   key(level) {
     return `${KEY_PREFIX}${level}`;
@@ -25,6 +34,8 @@ var RouteCache = class {
     if (this.storage === "memory" || !this.backend) {
       return this.getFromMemory(level);
     }
+    const mirrored = this.getFromMemory(level);
+    if (mirrored) return mirrored;
     const raw = this.backend.getItem(this.key(level));
     if (raw) {
       try {
@@ -33,12 +44,13 @@ var RouteCache = class {
           this.del(level);
           return void 0;
         }
+        this.memory.set(level, entry);
         return entry;
       } catch {
         return void 0;
       }
     }
-    return this.getFromMemory(level);
+    return void 0;
   }
   getFromMemory(level) {
     const entry = this.memory.get(level);
@@ -62,14 +74,13 @@ var RouteCache = class {
       ttl,
       cachedAt: Date.now()
     };
+    this.memory.set(resp.level, entry);
     if (this.storage === "memory" || !this.backend) {
-      this.memory.set(resp.level, entry);
       return;
     }
     try {
       this.backend.setItem(this.key(resp.level), JSON.stringify(entry));
     } catch {
-      this.memory.set(resp.level, entry);
     }
   }
   del(level) {
@@ -249,14 +260,14 @@ function createInterceptorManager() {
   return new InterceptorManagerImpl();
 }
 
-// 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) {
+// src/adapters/fetch-core.ts
+function isAbortError(err, signal) {
+  if (signal?.aborted) return true;
   const e = err;
-  return !!e && e.name === "AbortError";
+  if (!e) return false;
+  if (e.name === "AbortError") return true;
+  if (e.code === "ERR_CANCELED") return true;
+  return false;
 }
 function combineSignals(...signals) {
   const valid = signals.filter((s) => !!s);
@@ -275,81 +286,92 @@ function combineSignals(...signals) {
   }
   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 = 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);
-      if (qs) {
-        url = url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
-      }
+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;
+}
+async function rawFetch(config) {
+  const signal = combineSignals(
+    config.signal,
+    config.timeout && config.timeout > 0 ? AbortSignal.timeout(config.timeout) : void 0
+  );
+  let url = config.url;
+  if (config.paramsSerializer && config.params) {
+    const qs = config.paramsSerializer(config.params);
+    if (qs) {
+      url = url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
     }
-    const headers = new Headers(finalConfig.headers);
-    const fetchInit = {
-      method: finalConfig.method,
-      headers
-    };
-    if (signal) fetchInit.signal = signal;
-    if (finalConfig.body !== void 0 && !["GET", "HEAD"].includes(finalConfig.method.toUpperCase())) {
-      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");
-        }
+  }
+  const headers = new Headers(config.headers);
+  const fetchInit = {
+    method: config.method,
+    headers
+  };
+  if (signal) fetchInit.signal = signal;
+  if (config.body !== void 0 && !["GET", "HEAD"].includes(config.method.toUpperCase())) {
+    if (typeof config.body === "string" || isPassthroughBody(config.body)) {
+      fetchInit.body = config.body;
+    } else {
+      fetchInit.body = JSON.stringify(config.body);
+      if (!headers.has("Content-Type")) {
+        headers.set("Content-Type", "application/json");
       }
     }
-    let res;
+  }
+  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),
+      config.route,
+      config.level,
+      e
+    );
+  }
+  const text = await res.text();
+  let data = text;
+  const contentType = res.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
     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 text = await res.text();
-    let data = text;
-    const contentType = res.headers.get("content-type") ?? "";
-    if (contentType.includes("application/json")) {
-      try {
-        data = JSON.parse(text);
-      } catch {
-      }
+      data = JSON.parse(text);
+    } catch {
     }
-    const responseData = {
-      route: finalConfig.route,
-      level: finalConfig.level,
-      method: finalConfig.method,
-      url,
+  }
+  const responseData = {
+    route: config.route,
+    level: config.level,
+    method: config.method,
+    url,
+    status: res.status,
+    headers: res.headers,
+    data,
+    config
+  };
+  if (res.status >= 200 && res.status < 300) {
+    return responseData;
+  }
+  throw new HTTPError(
+    `HTTP ${res.status} for route "${config.route}" (${config.method} ${url})`,
+    {
+      route: config.route,
+      level: config.level,
       status: res.status,
-      headers: res.headers,
-      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
-        }
-      )
-    );
+      url,
+      method: config.method
+    }
+  );
+}
+
+// src/adapters/builtin-http.ts
+function createBuiltinHttp(forgeInterceptors) {
+  const requestMgr = forgeInterceptors?.request ?? createInterceptorManager();
+  const responseMgr = forgeInterceptors?.response ?? createInterceptorManager();
+  const requestRaw = rawFetch;
+  async function request(config) {
+    const finalConfig = await runRequestInterceptors(requestMgr, config);
+    const source = Promise.resolve(finalConfig).then(requestRaw);
     return runResponseInterceptors(
       responseMgr,
       source
@@ -362,6 +384,7 @@ function createBuiltinHttp(forgeInterceptors) {
   const del = (url, config) => request({ ...config, url, method: "DELETE" });
   return {
     request,
+    requestRaw,
     interceptors: {
       request: requestMgr,
       response: responseMgr
@@ -573,7 +596,6 @@ function createRouteForge(options) {
   const loadingTracker = new LoadingTracker();
   const explicitLevels = options.levels;
   const explicitEager = options.eager;
-  const explicitStrict = options.strict ?? false;
   const explicitEndpoint = options.endpoint;
   let effectiveLevels = explicitLevels ?? [];
   let effectiveEager = explicitEager ?? [];
@@ -581,17 +603,12 @@ function createRouteForge(options) {
   let effectiveUrlPrefix = "";
   let summaryUnassigned;
   let backendHasUnassignedLevel = false;
-  const summaryPromise = (async () => {
+  const fetchSummary = async () => {
     try {
-      const summaryUrl = explicitEndpoint;
-      const resp = await fetch(summaryUrl, { method: "GET" });
-      if (!resp.ok) {
-        console.warn(
-          `[route-forge] summary endpoint ${summaryUrl} unreachable (HTTP ${resp.status}); falling back to explicit options`
-        );
-        return null;
-      }
-      return await resp.json();
+      const base = baseURL.endsWith("/") ? baseURL.slice(0, -1) : baseURL;
+      const ep = explicitEndpoint.startsWith("/") ? explicitEndpoint : `/${explicitEndpoint}`;
+      const data = await fetchMeta("__forge__.summary", `${base}${ep}`);
+      return data;
     } catch (e) {
       if (explicitLevels && explicitLevels.length > 0) {
         console.warn(
@@ -601,8 +618,11 @@ function createRouteForge(options) {
       }
       throw new UnknownLevelError("(auto-discovery)");
     }
-  })();
-  const autoDiscoveryPromise = summaryPromise.then((summary) => {
+  };
+  let summaryPromise;
+  const summaryWaiters = [];
+  const whenSummary = () => summaryPromise ?? new Promise((resolve) => summaryWaiters.push(resolve));
+  const autoDiscoveryPromise = whenSummary().then((summary) => {
     if (summary === null) {
       return;
     }
@@ -621,11 +641,6 @@ function createRouteForge(options) {
     if (summary.config.url_prefix) {
       effectiveUrlPrefix = summary.config.url_prefix.endsWith("/") ? summary.config.url_prefix.slice(0, -1) : summary.config.url_prefix;
     }
-    if (summary.config.strict_mode && !explicitStrict) {
-      console.warn(
-        "[route-forge] backend strict_mode=true overrides frontend strict=false; forcing strict=true"
-      );
-    }
     const backendLevels = Object.keys(summary.levels);
     backendHasUnassignedLevel = backendLevels.includes(UNASSIGNED_LEVEL);
     if (Array.isArray(summary.unassigned) && summary.unassigned.length > 0 && !backendHasUnassignedLevel) {
@@ -661,8 +676,12 @@ function createRouteForge(options) {
   });
   let autoDiscoveryCompleted = false;
   let resolveReady;
-  const readyPromise = new Promise((resolve) => {
+  let rejectReady;
+  const readyPromise = new Promise((resolve, reject) => {
     resolveReady = resolve;
+    rejectReady = reject;
+  });
+  readyPromise.catch(() => {
   });
   const cacheTtl = cacheOpts.ttl ?? DEFAULT_CACHE_TTL;
   const cacheStorage = cacheOpts.storage ?? "memory";
@@ -693,13 +712,20 @@ function createRouteForge(options) {
     adapter,
     forgeInterceptors: { request: requestInterceptors, response: responseInterceptors }
   });
+  Promise.resolve().then(() => {
+    summaryPromise = fetchSummary();
+    for (const resolve of summaryWaiters) resolve(summaryPromise);
+  });
   let adapterResolved = false;
   let adapterObj = null;
   async function ensureAdapter() {
     if (!adapterResolved) {
       adapterObj = await adapterPromise.catch((e) => {
         if (e instanceof AdapterNotFoundError) throw e;
-        return resolveAdapter({ adapter: "builtin" });
+        return resolveAdapter({
+          adapter: "builtin",
+          forgeInterceptors: { request: requestInterceptors, response: responseInterceptors }
+        });
       });
       adapterResolved = true;
     }
@@ -725,33 +751,36 @@ function createRouteForge(options) {
     const ep = effectiveEndpoint.startsWith("/") ? effectiveEndpoint : `/${effectiveEndpoint}`;
     return `${base}${ep}/${encodeURIComponent(level)}`;
   }
-  async function fetchLevel(level) {
+  async function fetchMeta(routeTag, url, level = "") {
     const adp = await ensureAdapter();
     const config = {
-      route: `__forge__.load.${level}`,
+      route: routeTag,
       level,
       method: "GET",
-      url: buildUrl(level),
+      url,
       headers: { Accept: "application/json" },
       params: {},
       timeout,
       meta: {
-        name: `__forge__.load.${level}`,
-        uri: buildUrl(level),
+        name: routeTag,
+        uri: url,
         methods: ["GET"],
         parameters: [],
         level
       }
     };
-    const resp = await adp.request(config);
+    const doRawRequest = adp.requestRaw ?? adp.request;
+    const resp = await doRawRequest(config);
     if (!resp || resp.status < 200 || resp.status >= 300) {
       throw new HTTPError(
-        `Failed to load level "${level}": HTTP ${resp?.status}`,
-        { level, status: resp?.status, url: buildUrl(level), method: "GET" }
+        `Failed to fetch "${routeTag}": HTTP ${resp?.status}`,
+        { level, status: resp?.status, url, method: "GET" }
       );
     }
-    const data = resp.data;
-    return data;
+    return resp.data;
+  }
+  async function fetchLevel(level) {
+    return await fetchMeta(`__forge__.load.${level}`, buildUrl(level), level);
   }
   async function loadOne(level) {
     if (autoDiscoveryError) throw autoDiscoveryError;
@@ -923,7 +952,7 @@ function createRouteForge(options) {
         },
         (err) => {
           if (err instanceof ForgeError) throw err;
-          if (isAbortError2(err, signal)) {
+          if (isAbortError(err, signal)) {
             throw new RequestAbortedError(meta.name, meta.level, err);
           }
           throw new NetworkError(
@@ -992,15 +1021,22 @@ function createRouteForge(options) {
   }
   void autoDiscoveryPromise.then(() => {
     autoDiscoveryCompleted = true;
-    options.onSummaryReady?.();
     if (effectiveEager.length > 0) {
-      return Promise.all(effectiveEager.map((lvl) => load(lvl))).catch((e) => {
-        console.warn(`[route-forge] eager load failed: ${e.message}`);
+      return Promise.allSettled(effectiveEager.map((lvl) => load(lvl))).then((results) => {
+        results.forEach((r, i) => {
+          if (r.status === "rejected") {
+            console.error(
+              `[route-forge] eager load failed for level "${effectiveEager[i]}":`,
+              r.reason
+            );
+          }
+        });
       });
     }
   }).then(() => {
     resolveReady(forgeInstance);
-  }).catch(() => {
+  }).catch((e) => {
+    rejectReady(e);
   });
   function ready(onFulfilled, onRejected) {
     if (onFulfilled) {
@@ -1011,7 +1047,8 @@ function createRouteForge(options) {
   }
   const forgeResolver = { load, hasRoute };
   function createBoundForge(level, prefix) {
-    const levelLoadedPromise = load(level).catch(() => {
+    const levelLoadedPromise = load(level);
+    levelLoadedPromise.catch(() => {
     });
     const apiFn = prefix ? (name, params) => resolveRouteName(forgeResolver, level, prefix, name).then(
       (resolved) => api(level, resolved, params)
@@ -1145,14 +1182,6 @@ function resolveApiParams(input) {
   }
   return { pathParams, query, body, headers, timeout: perCallTimeout };
 }
-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;
-}
 
 export { AdapterNotFoundError, ForgeError, HTTPError, InterceptorManagerImpl, InvalidInterceptorReturnError, LoadingTracker, MissingRouteParamError, NetworkError, RequestAbortedError, RouteCache, UnknownLevelError, UnknownRouteError, createInterceptorManager, createRouteForge, resolveRouteName, resolveRouteNameSync };
 //# sourceMappingURL=index.js.map