@1delta/data-sdk 0.0.56 → 0.0.57

package/dist/index.js

@@ -1034,17 +1034,32 @@ var parseFraxlendPairKey = (lender) => {
 var FRESH_TTL_MS = 5 * 60 * 1e3;
 var STALE_WHILE_REVALIDATE_MS = 12 * 60 * 60 * 1e3;
 var REMOTE_CACHE_STORE_TTL_S = 7 * 24 * 60 * 60;
+var STUCK_REVALIDATE_MS = 60 * 1e3;
+var MISSING_TTL_MS = FRESH_TTL_MS;
 var STATE_KEY = "__1delta_remote_cache__";
 function getState() {
   const g = globalThis;
-  if (!g[STATE_KEY]) g[STATE_KEY] = { memo: /* @__PURE__ */ new Map(), inflight: /* @__PURE__ */ new Map(), revalidating: /* @__PURE__ */ new Set() };
+  if (!g[STATE_KEY]) {
+    g[STATE_KEY] = {
+      memo: /* @__PURE__ */ new Map(),
+      inflight: /* @__PURE__ */ new Map(),
+      revalidating: /* @__PURE__ */ new Map(),
+      missing: /* @__PURE__ */ new Map(),
+      loaders: /* @__PURE__ */ new Map()
+    };
+  }
   const state = g[STATE_KEY];
-  if (!state.revalidating) state.revalidating = /* @__PURE__ */ new Set();
+  if (!(state.revalidating instanceof Map)) state.revalidating = /* @__PURE__ */ new Map();
+  if (!state.missing) state.missing = /* @__PURE__ */ new Map();
+  if (!state.loaders) state.loaders = /* @__PURE__ */ new Map();
   return state;
 }
 function setRemoteCacheStore(next) {
   getState().store = next;
 }
+function setRemoteCacheWaitUntil(next) {
+  getState().waitUntil = next;
+}
 function setRemoteCacheGithubToken(token) {
   getState().githubToken = token;
 }
@@ -1052,7 +1067,11 @@ function clearRemoteCache() {
   const state = getState();
   state.memo.clear();
   state.inflight.clear();
+  state.revalidating.clear();
+  state.missing.clear();
+  state.loaders.clear();
 }
+var tokenListCacheKey = (chainId) => `token-list:${chainId}`;
 var RAW_HOST = "https://raw.githubusercontent.com/";
 function githubApiMirror(url) {
   if (!url.startsWith(RAW_HOST)) return void 0;
@@ -1100,11 +1119,21 @@ async function readStore(key, isValid) {
   const { store } = getState();
   if (!store) return void 0;
   try {
-    const raw = await store.get(storeKey(key));
+    let raw;
+    let metaAt;
+    if (store.getWithMetadata) {
+      const got = await store.getWithMetadata(storeKey(key));
+      raw = got.value;
+      if (typeof got.metadata?.at === "number") metaAt = got.metadata.at;
+    } else {
+      raw = await store.get(storeKey(key));
+    }
     if (!raw) return void 0;
     const parsed = JSON.parse(raw);
-    if (typeof parsed?.at !== "number" || !isValid(parsed.value)) return void 0;
-    return parsed;
+    if (!isValid(parsed?.value)) return void 0;
+    const at = metaAt ?? parsed?.at;
+    if (typeof at !== "number") return void 0;
+    return { at, value: parsed.value };
   } catch {
     return void 0;
   }
@@ -1113,50 +1142,106 @@ async function writeStore(key, entry) {
   const { store } = getState();
   if (!store) return;
   try {
-    await store.put(storeKey(key), JSON.stringify(entry), REMOTE_CACHE_STORE_TTL_S);
+    const body = JSON.stringify(entry);
+    if (store.putWithMetadata) {
+      await store.putWithMetadata(storeKey(key), body, REMOTE_CACHE_STORE_TTL_S, { at: entry.at });
+    } else {
+      await store.put(storeKey(key), body, REMOTE_CACHE_STORE_TTL_S);
+    }
   } catch {
   }
 }
+function background(promise) {
+  const { waitUntil } = getState();
+  if (!waitUntil) return;
+  try {
+    waitUntil(promise);
+  } catch {
+  }
+}
+function adopt(key, entry) {
+  const { memo } = getState();
+  const current = memo.get(key);
+  if (!current || current.at <= entry.at) memo.set(key, entry);
+}
+var negativeCacheError = (entry) => new RemoteFetchError(entry.message, entry.status);
+function revalidate(key, loader, preferStore) {
+  const state = getState();
+  const existing = state.revalidating.get(key);
+  if (existing && Date.now() - existing.startedAt < STUCK_REVALIDATE_MS) return existing.promise;
+  const entry = { startedAt: Date.now(), promise: Promise.resolve(false) };
+  entry.promise = (async () => {
+    try {
+      const mine = state.memo.get(key);
+      if (preferStore && state.store) {
+        const stored = await readStore(key, loader.isValid);
+        if (stored && stored.at > (mine?.at ?? 0) && Date.now() - stored.at < FRESH_TTL_MS) {
+          adopt(key, stored);
+          return true;
+        }
+      }
+      const value = await loader.load();
+      const fresh = { at: Date.now(), value };
+      adopt(key, fresh);
+      state.missing.delete(key);
+      await writeStore(key, fresh);
+      return true;
+    } catch {
+      return false;
+    } finally {
+      if (state.revalidating.get(key) === entry) state.revalidating.delete(key);
+    }
+  })();
+  state.revalidating.set(key, entry);
+  return entry.promise;
+}
 async function loadCached(key, load, isValid) {
-  const { memo, inflight, revalidating } = getState();
+  const state = getState();
+  const { memo, inflight } = state;
+  const loader = { load, isValid };
+  state.loaders.set(key, loader);
   const cached = memo.get(key);
-  if (cached && Date.now() - cached.at < FRESH_TTL_MS) return cached.value;
+  if (cached) {
+    const age = Date.now() - cached.at;
+    if (age < FRESH_TTL_MS) return cached.value;
+    if (age < STALE_WHILE_REVALIDATE_MS) {
+      background(revalidate(key, loader, true));
+      return cached.value;
+    }
+  }
+  const missing = state.missing.get(key);
+  if (missing && Date.now() - missing.at < MISSING_TTL_MS) throw negativeCacheError(missing);
   const pending = inflight.get(key);
   if (pending) return pending;
   const task = (async () => {
     const stored = await readStore(key, isValid);
     if (stored && Date.now() - stored.at < FRESH_TTL_MS) {
-      memo.set(key, stored);
+      adopt(key, stored);
       return stored.value;
     }
     if (stored && Date.now() - stored.at < STALE_WHILE_REVALIDATE_MS) {
-      memo.set(key, stored);
-      if (revalidating.has(key)) return stored.value;
-      revalidating.add(key);
-      void (async () => {
-        try {
-          const value = await load();
-          const entry = { at: Date.now(), value };
-          const current = memo.get(key);
-          if (!current || current.at <= entry.at) memo.set(key, entry);
-          await writeStore(key, entry);
-        } catch {
-        } finally {
-          revalidating.delete(key);
-        }
-      })();
+      adopt(key, stored);
+      background(revalidate(key, loader, false));
       return stored.value;
     }
     try {
       const value = await load();
       const entry = { at: Date.now(), value };
-      memo.set(key, entry);
-      await writeStore(key, entry);
+      adopt(key, entry);
+      state.missing.delete(key);
+      const put = writeStore(key, entry);
+      if (state.waitUntil) background(put);
+      else await put;
       return value;
     } catch (error) {
       const stale = memo.get(key) ?? stored;
-      if (!stale) throw error;
-      memo.set(key, stale);
+      if (!stale) {
+        if (error instanceof RemoteFetchError && error.isMissing) {
+          state.missing.set(key, { at: Date.now(), status: error.status, message: error.message });
+        }
+        throw error;
+      }
+      adopt(key, stale);
       return stale.value;
     }
   })().finally(() => {
@@ -1165,6 +1250,14 @@ async function loadCached(key, load, isValid) {
   inflight.set(key, task);
   return task;
 }
+async function refreshRemoteCache(key, opts = {}) {
+  const state = getState();
+  const loader = state.loaders.get(key);
+  if (!loader) return "unknown";
+  const cached = state.memo.get(key);
+  if (cached && opts.maxAgeMs !== void 0 && Date.now() - cached.at < opts.maxAgeMs) return "fresh";
+  return await revalidate(key, loader, false) ? "refreshed" : "failed";
+}
 async function loadCachedJson(key, url, isValid, label = key) {
   return loadCached(key, () => fetchRemoteJson(url, label), isValid);
 }
@@ -1372,6 +1465,7 @@ exports.parseMidnightRef = parseMidnightRef;
 exports.parseSiloV2LenderKey = parseSiloV2LenderKey;
 exports.parseSiloV3LenderKey = parseSiloV3LenderKey;
 exports.parseTermMaxLenderKey = parseTermMaxLenderKey;
+exports.refreshRemoteCache = refreshRemoteCache;
 exports.resolveMidnightApiBase = resolveMidnightApiBase;
 exports.resolveTenorApiUrl = resolveTenorApiUrl;
 exports.resolveTermApiBase = resolveTermApiBase;
@@ -1388,6 +1482,7 @@ exports.riverMarkets = riverMarkets;
 exports.setMidnightApiBase = setMidnightApiBase;
 exports.setRemoteCacheGithubToken = setRemoteCacheGithubToken;
 exports.setRemoteCacheStore = setRemoteCacheStore;
+exports.setRemoteCacheWaitUntil = setRemoteCacheWaitUntil;
 exports.setTenorApiUrl = setTenorApiUrl;
 exports.setTermApiBase = setTermApiBase;
 exports.setTermOrderStoreBase = setTermOrderStoreBase;
@@ -1419,6 +1514,7 @@ exports.termMaxConfig = termMaxConfig;
 exports.termMaxConfigByChain = termMaxConfigByChain;
 exports.termMaxLenderKey = termMaxLenderKey;
 exports.termOrderStoreBaseOverride = termOrderStoreBaseOverride;
+exports.tokenListCacheKey = tokenListCacheKey;
 exports.twyneBaseKey = twyneBaseKey;
 exports.twyneBeaconFor = twyneBeaconFor;
 exports.twyneChainData = twyneChainData;

package/dist/index.mjs

@@ -1032,17 +1032,32 @@ var parseFraxlendPairKey = (lender) => {
 var FRESH_TTL_MS = 5 * 60 * 1e3;
 var STALE_WHILE_REVALIDATE_MS = 12 * 60 * 60 * 1e3;
 var REMOTE_CACHE_STORE_TTL_S = 7 * 24 * 60 * 60;
+var STUCK_REVALIDATE_MS = 60 * 1e3;
+var MISSING_TTL_MS = FRESH_TTL_MS;
 var STATE_KEY = "__1delta_remote_cache__";
 function getState() {
   const g = globalThis;
-  if (!g[STATE_KEY]) g[STATE_KEY] = { memo: /* @__PURE__ */ new Map(), inflight: /* @__PURE__ */ new Map(), revalidating: /* @__PURE__ */ new Set() };
+  if (!g[STATE_KEY]) {
+    g[STATE_KEY] = {
+      memo: /* @__PURE__ */ new Map(),
+      inflight: /* @__PURE__ */ new Map(),
+      revalidating: /* @__PURE__ */ new Map(),
+      missing: /* @__PURE__ */ new Map(),
+      loaders: /* @__PURE__ */ new Map()
+    };
+  }
   const state = g[STATE_KEY];
-  if (!state.revalidating) state.revalidating = /* @__PURE__ */ new Set();
+  if (!(state.revalidating instanceof Map)) state.revalidating = /* @__PURE__ */ new Map();
+  if (!state.missing) state.missing = /* @__PURE__ */ new Map();
+  if (!state.loaders) state.loaders = /* @__PURE__ */ new Map();
   return state;
 }
 function setRemoteCacheStore(next) {
   getState().store = next;
 }
+function setRemoteCacheWaitUntil(next) {
+  getState().waitUntil = next;
+}
 function setRemoteCacheGithubToken(token) {
   getState().githubToken = token;
 }
@@ -1050,7 +1065,11 @@ function clearRemoteCache() {
   const state = getState();
   state.memo.clear();
   state.inflight.clear();
+  state.revalidating.clear();
+  state.missing.clear();
+  state.loaders.clear();
 }
+var tokenListCacheKey = (chainId) => `token-list:${chainId}`;
 var RAW_HOST = "https://raw.githubusercontent.com/";
 function githubApiMirror(url) {
   if (!url.startsWith(RAW_HOST)) return void 0;
@@ -1098,11 +1117,21 @@ async function readStore(key, isValid) {
   const { store } = getState();
   if (!store) return void 0;
   try {
-    const raw = await store.get(storeKey(key));
+    let raw;
+    let metaAt;
+    if (store.getWithMetadata) {
+      const got = await store.getWithMetadata(storeKey(key));
+      raw = got.value;
+      if (typeof got.metadata?.at === "number") metaAt = got.metadata.at;
+    } else {
+      raw = await store.get(storeKey(key));
+    }
     if (!raw) return void 0;
     const parsed = JSON.parse(raw);
-    if (typeof parsed?.at !== "number" || !isValid(parsed.value)) return void 0;
-    return parsed;
+    if (!isValid(parsed?.value)) return void 0;
+    const at = metaAt ?? parsed?.at;
+    if (typeof at !== "number") return void 0;
+    return { at, value: parsed.value };
   } catch {
     return void 0;
   }
@@ -1111,50 +1140,106 @@ async function writeStore(key, entry) {
   const { store } = getState();
   if (!store) return;
   try {
-    await store.put(storeKey(key), JSON.stringify(entry), REMOTE_CACHE_STORE_TTL_S);
+    const body = JSON.stringify(entry);
+    if (store.putWithMetadata) {
+      await store.putWithMetadata(storeKey(key), body, REMOTE_CACHE_STORE_TTL_S, { at: entry.at });
+    } else {
+      await store.put(storeKey(key), body, REMOTE_CACHE_STORE_TTL_S);
+    }
   } catch {
   }
 }
+function background(promise) {
+  const { waitUntil } = getState();
+  if (!waitUntil) return;
+  try {
+    waitUntil(promise);
+  } catch {
+  }
+}
+function adopt(key, entry) {
+  const { memo } = getState();
+  const current = memo.get(key);
+  if (!current || current.at <= entry.at) memo.set(key, entry);
+}
+var negativeCacheError = (entry) => new RemoteFetchError(entry.message, entry.status);
+function revalidate(key, loader, preferStore) {
+  const state = getState();
+  const existing = state.revalidating.get(key);
+  if (existing && Date.now() - existing.startedAt < STUCK_REVALIDATE_MS) return existing.promise;
+  const entry = { startedAt: Date.now(), promise: Promise.resolve(false) };
+  entry.promise = (async () => {
+    try {
+      const mine = state.memo.get(key);
+      if (preferStore && state.store) {
+        const stored = await readStore(key, loader.isValid);
+        if (stored && stored.at > (mine?.at ?? 0) && Date.now() - stored.at < FRESH_TTL_MS) {
+          adopt(key, stored);
+          return true;
+        }
+      }
+      const value = await loader.load();
+      const fresh = { at: Date.now(), value };
+      adopt(key, fresh);
+      state.missing.delete(key);
+      await writeStore(key, fresh);
+      return true;
+    } catch {
+      return false;
+    } finally {
+      if (state.revalidating.get(key) === entry) state.revalidating.delete(key);
+    }
+  })();
+  state.revalidating.set(key, entry);
+  return entry.promise;
+}
 async function loadCached(key, load, isValid) {
-  const { memo, inflight, revalidating } = getState();
+  const state = getState();
+  const { memo, inflight } = state;
+  const loader = { load, isValid };
+  state.loaders.set(key, loader);
   const cached = memo.get(key);
-  if (cached && Date.now() - cached.at < FRESH_TTL_MS) return cached.value;
+  if (cached) {
+    const age = Date.now() - cached.at;
+    if (age < FRESH_TTL_MS) return cached.value;
+    if (age < STALE_WHILE_REVALIDATE_MS) {
+      background(revalidate(key, loader, true));
+      return cached.value;
+    }
+  }
+  const missing = state.missing.get(key);
+  if (missing && Date.now() - missing.at < MISSING_TTL_MS) throw negativeCacheError(missing);
   const pending = inflight.get(key);
   if (pending) return pending;
   const task = (async () => {
     const stored = await readStore(key, isValid);
     if (stored && Date.now() - stored.at < FRESH_TTL_MS) {
-      memo.set(key, stored);
+      adopt(key, stored);
       return stored.value;
     }
     if (stored && Date.now() - stored.at < STALE_WHILE_REVALIDATE_MS) {
-      memo.set(key, stored);
-      if (revalidating.has(key)) return stored.value;
-      revalidating.add(key);
-      void (async () => {
-        try {
-          const value = await load();
-          const entry = { at: Date.now(), value };
-          const current = memo.get(key);
-          if (!current || current.at <= entry.at) memo.set(key, entry);
-          await writeStore(key, entry);
-        } catch {
-        } finally {
-          revalidating.delete(key);
-        }
-      })();
+      adopt(key, stored);
+      background(revalidate(key, loader, false));
       return stored.value;
     }
     try {
       const value = await load();
       const entry = { at: Date.now(), value };
-      memo.set(key, entry);
-      await writeStore(key, entry);
+      adopt(key, entry);
+      state.missing.delete(key);
+      const put = writeStore(key, entry);
+      if (state.waitUntil) background(put);
+      else await put;
       return value;
     } catch (error) {
       const stale = memo.get(key) ?? stored;
-      if (!stale) throw error;
-      memo.set(key, stale);
+      if (!stale) {
+        if (error instanceof RemoteFetchError && error.isMissing) {
+          state.missing.set(key, { at: Date.now(), status: error.status, message: error.message });
+        }
+        throw error;
+      }
+      adopt(key, stale);
       return stale.value;
     }
   })().finally(() => {
@@ -1163,6 +1248,14 @@ async function loadCached(key, load, isValid) {
   inflight.set(key, task);
   return task;
 }
+async function refreshRemoteCache(key, opts = {}) {
+  const state = getState();
+  const loader = state.loaders.get(key);
+  if (!loader) return "unknown";
+  const cached = state.memo.get(key);
+  if (cached && opts.maxAgeMs !== void 0 && Date.now() - cached.at < opts.maxAgeMs) return "fresh";
+  return await revalidate(key, loader, false) ? "refreshed" : "failed";
+}
 async function loadCachedJson(key, url, isValid, label = key) {
   return loadCached(key, () => fetchRemoteJson(url, label), isValid);
 }
@@ -1211,4 +1304,4 @@ async function fetchMainTokensMap() {
   }
 }
 
-export { COOLER_ETHEREUM_CONFIG, CURVANCE_MONAD_CONFIG, FRAXLEND_ETHEREUM_CONFIG, GEARBOX_ACCOUNT_COMPRESSOR_V310, REMOTE_CACHE_STORE_TTL_S, RESUPPLY_ETHEREUM_CONFIG, RemoteFetchError, aaveOracles, aaveOraclesConfig, aavePools, aaveReserves, aaveTokens, aaveV4Oracles, aaveV4Peripherals, aaveV4SpokeLenderKey, aaveV4Spokes, aaveWethGateway, assertTwyneKeysUnique, chainLogoURI, chains, clearRemoteCache, compoundV2Oracles, compoundV2OraclesConfig, compoundV2Pools, compoundV2Reserves, compoundV2TokenArray, compoundV2Tokens, compoundV3BaseData, compoundV3Bulker, compoundV3OraclesData, compoundV3Pools, compoundV3Reserves, coolerConfig, coolerConfigFor, coolerLendersByChain, curvanceConfig, curvanceConfigFor, curvanceLendersByChain, curvancePositionManager, curvancePositionManagersFor, dolomiteChains, dolomiteConfigs, dolomiteEmode, dolomiteMarketIdByToken, dolomiteOdosExecutorShim, dssChainData, dssConfigFor, dssDebtJoin, dssDebtToken, dssMarketByIlk, eulerConfigs, eulerVaults, exactlyConfig, exactlyMarketByAddress, exactlyMarketByAsset, exactlyMarkets, exactlyMarketsByChain, fetchMainTokensMap, fetchRemoteJson, fetchTokenList, fetchTokenListFile, fetchTokenLists, findAaveV4PositionManager, fluidChains, fluidResolvers, fluidVaultEntries, fluidVaults, flyingTulipAssets, flyingTulipAssetsFor, flyingTulipConfig, flyingTulipConfigFor, flyingTulipLendersByChain, frankencoinChainData, frankencoinConfig, frankencoinConfigFor, frankencoinLendersByChain, frankencoinMarketByPosition, frankencoinMarkets, fraxlendConfig, fraxlendConfigFor, fraxlendLendersByChain, fraxlendPairKey, fraxlendPairsFor, gearboxAccountCompressor, gearboxAddressProviderV310, gearboxBotListV3, gearboxChains, gearboxMarketCompressor, gearboxMarketConfigurators, gearboxResolvers, gearboxV3LenderKey, getAaveV4GatewayAddresses, getAaveV4PositionManagers, getAaveV4SpokeAccess, getAaveV4SpokeEntry, getAaveV4SpokePeripherals, getChainEntries, getSiloV2MarketEntry, getSiloV3MarketEntry, initConfig, initializeChainData, initializeLenderData, inverseChainData, inverseConfig, inverseConfigFor, inverseLendersByChain, inverseMarketByAddress, inverseMarkets, isAaveV4OperationRestricted, isListaSmartLpAsset, isMidnightCollateralRef, liquityBranchByIndex, liquityBranchByTroveManager, liquityBranchesByChain, liquityConfig, liquityConfigFor, liquityLendersByChain, liquityMarkets, listaCollateralProvider, listaCollateralProviders, listaNativeProvider, listaSmartLpByCollateral, llamaLendApiBaseUrl, llamaLendChainData, llamaLendConfig, llamaLendConfigFor, llamaLendLenderKey, llamaLendLendersByChain, llamaLendLeverageZap, llamaLendMarketByController, llamaLendMarketByVault, llamaLendMarkets, llamaLendSupportsDelegation, llamaLendSupportsLeverage, loadCached, loadCachedJson, midnightApiBaseOverride, midnightCollateralRef, midnightConfig, midnightLoanRef, midnightMarketById, midnightMarketIsEnterable, midnightMarkets, midnightMarketsByChain, midnightNotEnterableReason, morphoBundler3, morphoOracles, morphoPools, morphoTypeMarkets, morphoTypeOracles, morphoTypeVaults, parseAaveV4SpokeLenderKey, parseFraxlendPairKey, parseGearboxV3LenderKey, parseLlamaLendLenderKey, parseMidnightRef, parseSiloV2LenderKey, parseSiloV3LenderKey, parseTermMaxLenderKey, resolveMidnightApiBase, resolveTenorApiUrl, resolveTermApiBase, resolveTermOrderStoreBase, resupplyConfig, resupplyConfigFor, resupplyLendersByChain, riverChainData, riverConfig, riverConfigFor, riverLendersByChain, riverMarketByIndex, riverMarkets, setMidnightApiBase, setRemoteCacheGithubToken, setRemoteCacheStore, setTenorApiUrl, setTermApiBase, setTermOrderStoreBase, siloMarkets, siloMarketsV3, siloPeripherals, siloPeripheralsV3, siloV2LenderKey, siloV3LenderKey, skyChainData, skyConfig, skyConfigFor, skyLendersByChain, skyMarkets, tellerConfig, tellerConfigByChain, tellerPoolByAddress, tellerPools, tellerPoolsByChain, tenorApiUrlOverride, termApiBaseOverride, termConfig, termMarketById, termMarkets, termMarketsByChain, termMaxApiBaseUrl, termMaxChainIds, termMaxConfig, termMaxConfigByChain, termMaxLenderKey, termOrderStoreBaseOverride, twyneBaseKey, twyneBeaconFor, twyneChainData, twyneConfig, twyneConfigFor, twyneLendersByChain, twyneMarketByKey, twyneMarketFor, twyneMarketKey, twyneMarkets, twyneMarketsForIntermediateVault, twyneOperator, usddChainData, usddConfig, usddConfigFor, usddLendersByChain, usddMarketByIlk, usddMarkets };
+export { COOLER_ETHEREUM_CONFIG, CURVANCE_MONAD_CONFIG, FRAXLEND_ETHEREUM_CONFIG, GEARBOX_ACCOUNT_COMPRESSOR_V310, REMOTE_CACHE_STORE_TTL_S, RESUPPLY_ETHEREUM_CONFIG, RemoteFetchError, aaveOracles, aaveOraclesConfig, aavePools, aaveReserves, aaveTokens, aaveV4Oracles, aaveV4Peripherals, aaveV4SpokeLenderKey, aaveV4Spokes, aaveWethGateway, assertTwyneKeysUnique, chainLogoURI, chains, clearRemoteCache, compoundV2Oracles, compoundV2OraclesConfig, compoundV2Pools, compoundV2Reserves, compoundV2TokenArray, compoundV2Tokens, compoundV3BaseData, compoundV3Bulker, compoundV3OraclesData, compoundV3Pools, compoundV3Reserves, coolerConfig, coolerConfigFor, coolerLendersByChain, curvanceConfig, curvanceConfigFor, curvanceLendersByChain, curvancePositionManager, curvancePositionManagersFor, dolomiteChains, dolomiteConfigs, dolomiteEmode, dolomiteMarketIdByToken, dolomiteOdosExecutorShim, dssChainData, dssConfigFor, dssDebtJoin, dssDebtToken, dssMarketByIlk, eulerConfigs, eulerVaults, exactlyConfig, exactlyMarketByAddress, exactlyMarketByAsset, exactlyMarkets, exactlyMarketsByChain, fetchMainTokensMap, fetchRemoteJson, fetchTokenList, fetchTokenListFile, fetchTokenLists, findAaveV4PositionManager, fluidChains, fluidResolvers, fluidVaultEntries, fluidVaults, flyingTulipAssets, flyingTulipAssetsFor, flyingTulipConfig, flyingTulipConfigFor, flyingTulipLendersByChain, frankencoinChainData, frankencoinConfig, frankencoinConfigFor, frankencoinLendersByChain, frankencoinMarketByPosition, frankencoinMarkets, fraxlendConfig, fraxlendConfigFor, fraxlendLendersByChain, fraxlendPairKey, fraxlendPairsFor, gearboxAccountCompressor, gearboxAddressProviderV310, gearboxBotListV3, gearboxChains, gearboxMarketCompressor, gearboxMarketConfigurators, gearboxResolvers, gearboxV3LenderKey, getAaveV4GatewayAddresses, getAaveV4PositionManagers, getAaveV4SpokeAccess, getAaveV4SpokeEntry, getAaveV4SpokePeripherals, getChainEntries, getSiloV2MarketEntry, getSiloV3MarketEntry, initConfig, initializeChainData, initializeLenderData, inverseChainData, inverseConfig, inverseConfigFor, inverseLendersByChain, inverseMarketByAddress, inverseMarkets, isAaveV4OperationRestricted, isListaSmartLpAsset, isMidnightCollateralRef, liquityBranchByIndex, liquityBranchByTroveManager, liquityBranchesByChain, liquityConfig, liquityConfigFor, liquityLendersByChain, liquityMarkets, listaCollateralProvider, listaCollateralProviders, listaNativeProvider, listaSmartLpByCollateral, llamaLendApiBaseUrl, llamaLendChainData, llamaLendConfig, llamaLendConfigFor, llamaLendLenderKey, llamaLendLendersByChain, llamaLendLeverageZap, llamaLendMarketByController, llamaLendMarketByVault, llamaLendMarkets, llamaLendSupportsDelegation, llamaLendSupportsLeverage, loadCached, loadCachedJson, midnightApiBaseOverride, midnightCollateralRef, midnightConfig, midnightLoanRef, midnightMarketById, midnightMarketIsEnterable, midnightMarkets, midnightMarketsByChain, midnightNotEnterableReason, morphoBundler3, morphoOracles, morphoPools, morphoTypeMarkets, morphoTypeOracles, morphoTypeVaults, parseAaveV4SpokeLenderKey, parseFraxlendPairKey, parseGearboxV3LenderKey, parseLlamaLendLenderKey, parseMidnightRef, parseSiloV2LenderKey, parseSiloV3LenderKey, parseTermMaxLenderKey, refreshRemoteCache, resolveMidnightApiBase, resolveTenorApiUrl, resolveTermApiBase, resolveTermOrderStoreBase, resupplyConfig, resupplyConfigFor, resupplyLendersByChain, riverChainData, riverConfig, riverConfigFor, riverLendersByChain, riverMarketByIndex, riverMarkets, setMidnightApiBase, setRemoteCacheGithubToken, setRemoteCacheStore, setRemoteCacheWaitUntil, setTenorApiUrl, setTermApiBase, setTermOrderStoreBase, siloMarkets, siloMarketsV3, siloPeripherals, siloPeripheralsV3, siloV2LenderKey, siloV3LenderKey, skyChainData, skyConfig, skyConfigFor, skyLendersByChain, skyMarkets, tellerConfig, tellerConfigByChain, tellerPoolByAddress, tellerPools, tellerPoolsByChain, tenorApiUrlOverride, termApiBaseOverride, termConfig, termMarketById, termMarkets, termMarketsByChain, termMaxApiBaseUrl, termMaxChainIds, termMaxConfig, termMaxConfigByChain, termMaxLenderKey, termOrderStoreBaseOverride, tokenListCacheKey, twyneBaseKey, twyneBeaconFor, twyneChainData, twyneConfig, twyneConfigFor, twyneLendersByChain, twyneMarketByKey, twyneMarketFor, twyneMarketKey, twyneMarkets, twyneMarketsForIntermediateVault, twyneOperator, usddChainData, usddConfig, usddConfigFor, usddLendersByChain, usddMarketByIlk, usddMarkets };

package/dist/remoteCache.d.ts

@@ -11,21 +11,70 @@
  * These files change on the order of days, so serving a stale copy is strictly
  * better than failing — hence the stale-on-error fallback, which is the part
  * that actually survives an outage.
+ *
+ * Read order, and what each layer is for:
+ *
+ *   memory  — served IMMEDIATELY whenever a copy exists and is inside the SWR
+ *             window; older than `FRESH_TTL_MS` it also kicks a background
+ *             refresh. The request path never awaits the store or the network
+ *             while memory is warm — a 6.66 MB token list re-read from KV every
+ *             five minutes used to land on whichever user request crossed the
+ *             boundary.
+ *   store   — a KV namespace in the workers. Consulted only when memory has
+ *             nothing usable (a cold isolate), so a fresh isolate never touches
+ *             GitHub at all.
+ *   network — raw.githubusercontent.com, then the api.github.com mirror.
  */
 /** How long a persisted copy is kept around purely as the stale fallback. */
 export declare const REMOTE_CACHE_STORE_TTL_S: number;
+/** What the store carries next to a value, when it can carry anything. */
+export interface RemoteCacheEntryMetadata {
+    /** Epoch ms of the upstream fetch that produced the value. */
+    at: number;
+}
 /**
  * Durable backing store — a Cloudflare KV namespace in the workers, absent
  * everywhere else. Without one the cache is per-process, which still collapses
  * N requests into one upstream fetch but cannot help a cold start; with one, a
  * fresh isolate never touches GitHub at all.
+ *
+ * The two `*WithMetadata` members are optional. When present, the fetch
+ * timestamp is written as store METADATA as well as inside the value, so a
+ * store that can list keys with their metadata (KV's `list()` can) can answer
+ * "how old is this entry?" without transferring a multi-MB value. Note that
+ * KV's `getWithMetadata` still returns the value — only `list` is
+ * metadata-only — so reads through this interface do not get cheaper; what
+ * the metadata buys is an inspectable freshness signal for operators and for
+ * a future probe that stays off the value read.
  */
 export interface RemoteCacheStore {
     get(key: string): Promise<string | null>;
     put(key: string, value: string, ttlSeconds: number): Promise<void>;
+    getWithMetadata?(key: string): Promise<{
+        value: string | null;
+        metadata: RemoteCacheEntryMetadata | null;
+    }>;
+    putWithMetadata?(key: string, value: string, ttlSeconds: number, metadata: RemoteCacheEntryMetadata): Promise<void>;
 }
+/** `ctx.waitUntil`-shaped hook: keeps a background promise alive post-response. */
+export type RemoteCacheWaitUntil = (promise: Promise<unknown>) => void;
 /** Installs (or with `undefined`, removes) the durable store. */
 export declare function setRemoteCacheStore(next: RemoteCacheStore | undefined): void;
+/**
+ * Installs (or with `undefined`, removes) the hook that keeps background work
+ * alive after a response — `ctx.waitUntil` on Cloudflare Workers.
+ *
+ * The LATEST hook wins. Workers hand each request its own context, and a
+ * module-level slot can only hold one, so a refresh kicked by request A may be
+ * registered against request B's context if B arrived in between. That is
+ * harmless in the direction that matters (B's context keeps A's refresh alive
+ * at least as long as B runs) and the stuck guard covers the other direction
+ * (a context that closed before the refresh settled). The hook is called under
+ * try/catch for the same reason: a closed context may throw.
+ *
+ * Without a hook (Node, tests) background work is simply detached.
+ */
+export declare function setRemoteCacheWaitUntil(next: RemoteCacheWaitUntil | undefined): void;
 /**
  * Optional GitHub token for the API mirror below. Unauthenticated it allows 60
  * requests/hour per IP, which is thin for a shared Worker egress; a token
@@ -34,6 +83,12 @@ export declare function setRemoteCacheStore(next: RemoteCacheStore | undefined):
 export declare function setRemoteCacheGithubToken(token: string | undefined): void;
 /** Drops every cached value. Intended for tests. */
 export declare function clearRemoteCache(): void;
+/**
+ * The remote-cache key of a chain's token list. `tokens.ts` builds the same
+ * string inline; this is exported so a pre-warm can name the key without
+ * importing the loader.
+ */
+export declare const tokenListCacheKey: (chainId: string) => string;
 /**
  * A non-2xx from the remote. Carries the ORIGIN status so a caller can tell a
  * settled answer (404/410 — the file is not published) from a transient one
@@ -57,6 +112,10 @@ export declare function fetchRemoteJson<T>(url: string, label: string): Promise<
  * failed `load()` falls back to whatever stale copy either layer holds, only
  * rethrowing when there is nothing to fall back to.
  *
+ * Memory is served WITHOUT awaiting anything for as long as the copy is inside
+ * the SWR window; past `FRESH_TTL_MS` a refresh runs behind it. The store is
+ * consulted only when memory has nothing inside that window.
+ *
  * Concurrent callers for the same key share one in-flight load.
  *
  * `isValid` guards the durable layer: a truncated or shape-changed entry is
@@ -64,5 +123,28 @@ export declare function fetchRemoteJson<T>(url: string, label: string): Promise<
  * mis-decimals every balance built from it.
  */
 export declare function loadCached<T>(key: string, load: () => Promise<T>, isValid: (value: any) => boolean): Promise<T>;
+/** Outcome of {@link refreshRemoteCache}. */
+export type RemoteCacheRefreshResult = 
+/** Upstream was fetched and the store written. */
+'refreshed'
+/** The memory copy was younger than `maxAgeMs`; nothing was done. */
+ | 'fresh'
+/** Upstream failed; the previous copy (if any) is still served. */
+ | 'failed'
+/** Nothing has loaded this key in this process, so there is no loader to run. */
+ | 'unknown';
+/**
+ * Forces a refresh of `key` from UPSTREAM (never the store), and awaits the
+ * store write. For a pre-warm job: the routine path only refreshes once a
+ * copy is `FRESH_TTL_MS` old, so a job that runs more often than that would
+ * otherwise never write anything.
+ *
+ * `maxAgeMs` skips the work when the memory copy is younger than that — so a
+ * job that has just loaded the key cold does not immediately fetch it again.
+ * Joins an in-flight refresh rather than starting a second one.
+ */
+export declare function refreshRemoteCache(key: string, opts?: {
+    maxAgeMs?: number;
+}): Promise<RemoteCacheRefreshResult>;
 /** `loadCached` over a JSON URL, failing on any non-2xx so stale can take over. */
 export declare function loadCachedJson<T>(key: string, url: string, isValid: (value: any) => boolean, label?: string): Promise<T>;

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.0.56",
+  "version": "0.0.57",
   "description": "Hold and initialize lending protocol data across a stack",
   "files": [
     "dist"