@w3lib/evm-batch-call 0.2.0 → 0.4.0

package/src/call.ts

@@ -32,9 +32,10 @@ export interface Call<T = any> {
   /**
    * 内部标记：
    * - ethBalance：原生币余额查询（见 Provider.getEthBalance）
+   * - blockNumber：当前区块号（Multicall3.getBlockNumber；deployless 合约里直接返回 block.number）
    * - stringOrBytes32：string 返回值，解码失败时按 bytes32 解析（MKR 等老代币的 symbol / name）
    */
-  kind?: 'ethBalance' | 'stringOrBytes32'
+  kind?: 'ethBalance' | 'blockNumber' | 'stringOrBytes32'
   /** 仅用于类型推断 */
   readonly __result?: T
 }
@@ -52,13 +53,51 @@ export interface RawResult {
   returnData: string
 }
 
+/**
+ * 单条调用的失败原因：
+ * - invalid-address：合约地址或参数里的地址非法
+ * - invalid-argument：其他参数编码失败（个数不对、数值超出范围等）
+ * - no-contract：调用成功但返回空数据，多半是目标地址上没有合约
+ * - reverted：执行 revert
+ * - decode-failed：有返回数据但无法按 ABI 解码（如合约不是预期的标准）
+ * - not-configured：没有发请求的信息缺失，如主币不在内置链信息表里、也没有配置 nativeName / nativeSymbol
+ */
+export type FailureReason = 'invalid-address' | 'invalid-argument' | 'no-contract' | 'reverted' | 'decode-failed' | 'not-configured'
+
+/** 单条调用的结果：成功的值，或失败原因 */
+export type Settled<T = any> = { ok: true; value: T } | { ok: false; reason: FailureReason }
+
+/** 按 multicall 的原始结果判断成功 / 失败原因 */
+export function settleResult<T>(call: Call, result: RawResult): Settled<T> {
+  if (!result.success) {
+    return { ok: false, reason: 'reverted' }
+  }
+  // 没有返回值的函数成功时本来就返回空数据，照常解码；有返回值却拿到空数据，多半是地址上没有合约
+  if ((!result.returnData || result.returnData === '0x') && call.outputs.length > 0) {
+    return { ok: false, reason: 'no-contract' }
+  }
+  try {
+    return { ok: true, value: decodeCall<T>(call, result.returnData) }
+  } catch {
+    return { ok: false, reason: 'decode-failed' }
+  }
+}
+
+/** 参数编码失败的原因：地址非法，还是其他参数问题 */
+export function encodeFailureReason(err: unknown): FailureReason {
+  const e = err as { code?: unknown; argument?: unknown; message?: unknown } | null
+  return /address/i.test(String(e?.argument ?? '')) || /address/i.test(String(e?.message ?? '')) ? 'invalid-address' : 'invalid-argument'
+}
+
 /** 发给 aggregate3 前的单条请求 */
 export interface CallRequest {
   target: string
   allowFailure: boolean
   callData: string
-  /** 原生币余额查询：有 multicall 合约时走 getEthBalance，deployless 时改走 eth_getBalance */
+  /** 原生币余额查询：默认有 multicall 合约时走 getEthBalance、deployless 时用 BALANCE；其他读取方式见 NativeBalanceMode */
   ethBalanceOf?: string
+  /** 区块号查询：目标换成实际的 multicall 地址（deployless 时由合约内部处理） */
+  blockNumber?: boolean
 }
 
 // inputs → name → outputs → Interface。同一份 ABI 生成的 Call 共享 inputs/outputs 数组（见 contract.ts 的 ABI 缓存），
@@ -100,6 +139,7 @@ export function encodeCall(call: Call, allowFailure: boolean): CallRequest {
     allowFailure,
     callData: iface.encodeFunctionData(fragment, params),
     ethBalanceOf: call.kind === 'ethBalance' ? toEvmAddress(params[0] as string) : undefined,
+    blockNumber: call.kind === 'blockNumber' ? true : undefined,
   }
 }
 

package/src/chains.ts

@@ -1,3 +1,5 @@
+import type { NativeBalanceMode } from './aggregate.js'
+
 /**
  * 内置链的主币信息（balances() / tokens() 里主币的 name / symbol / 精度）。
  * 来源：https://chainid.network/chains.json 的 nativeCurrency；999 在该表里与 Wanchain 测试网撞号，
@@ -44,3 +46,16 @@ export const NATIVE_CURRENCIES: Readonly<Record<number, NativeCurrency>> = {
 export function getNativeCurrency(chainId: number): NativeCurrency | undefined {
   return NATIVE_CURRENCIES[chainId]
 }
+
+/**
+ * 合约里读主币余额不可靠的链，以及应改用的读取方式（ProviderConfig.nativeBalance 的默认值）。
+ * 新链可用 `pnpm check:rpc` 比对“合约里读到的主币余额”和 eth_getBalance 来发现。
+ */
+export const NATIVE_BALANCE_MODES: Readonly<Record<number, NativeBalanceMode>> = {
+  // Anubis：Multicall3.getEthBalance 和 deployless 里的 BALANCE 对任何地址都返回 0，eth_getBalance 正常
+  6714: 'rpc',
+}
+
+export function getNativeBalanceMode(chainId: number): NativeBalanceMode {
+  return NATIVE_BALANCE_MODES[chainId] ?? 'contract'
+}

package/src/deployless.ts

@@ -2,4 +2,4 @@
 
 /** constructor((address target, bool allowFailure, bytes callData)[] calls) — 以 aggregate3 的返回格式带回结果 */
 export const DEPLOYLESS_MULTICALL3_BYTECODE =
-  '0x608060405260405161060f38038061060f8339810160408190526100229161036c565b80516000816001600160401b0381111561003e5761003e6102da565b60405190808252806020026020018201604052801561008457816020015b60408051808201909152600081526060602082015281526020019060019003908161005c5790505b50905060005b828110156102875760008482815181106100a6576100a6610507565b602090810291909101015160408101518151919250906001600160a01b031673ca11bde05977b3631167028862be2a173976ca111480156100e8575080516024145b801561010c5750631348c07360e21b6101008261051d565b6001600160e01b031916145b1561017e5760248101516040805180820182526001815290516001600160a01b039290921691602080830191610149918531910190815260200190565b60405160208183030381529060405281525085858151811061016d5761016d610507565b60200260200101819052505061027d565b60008083600001516001600160a01b03168360405161019d919061055b565b6000604051808303816000865af19150503d80600081146101da576040519150601f19603f3d011682016040523d82523d6000602084013e6101df565b606091505b5091509150811580156101f457508360200151155b156102465760405162461bcd60e51b815260206004820152601760248201527f4d756c746963616c6c333a2063616c6c206661696c656400000000000000000060448201526064015b60405180910390fd5b604051806040016040528083151581526020018281525086868151811061026f5761026f610507565b602002602001018190525050505b505060010161008a565b5060008160405160200161029b9190610577565b6040516020818303038152906040529050616000815111156102d25781604051633649f05160e01b815260040161023d9190610577565b805160208201f35b634e487b7160e01b600052604160045260246000fd5b604051606081016001600160401b0381118282101715610312576103126102da565b60405290565b604051601f8201601f191681016001600160401b0381118282101715610340576103406102da565b604052919050565b60005b8381101561036357818101518382015260200161034b565b50506000910152565b60006020828403121561037e57600080fd5b81516001600160401b0381111561039457600080fd5b8201601f810184136103a557600080fd5b80516001600160401b038111156103be576103be6102da565b8060051b6103ce60208201610318565b918252602081840181019290810190878411156103ea57600080fd5b6020850192505b838310156104fc5782516001600160401b0381111561040f57600080fd5b85016060818a03601f1901121561042557600080fd5b61042d6102f0565b60208201516001600160a01b038116811461044757600080fd5b81526040820151801515811461045c57600080fd5b602082015260608201516001600160401b0381111561047a57600080fd5b60208184010192505089601f83011261049257600080fd5b81516001600160401b038111156104ab576104ab6102da565b6104be601f8201601f1916602001610318565b8181528b60208386010111156104d357600080fd5b6104e4826020830160208701610348565b604083015250835250602092830192909101906103f1565b979650505050505050565b634e487b7160e01b600052603260045260246000fd5b805160208201516001600160e01b0319811691906004821015610554576001600160e01b0319600483900360031b81901b82161692505b5050919050565b6000825161056d818460208701610348565b9190910192915050565b6000602082016020835280845180835260408501915060408160051b86010192506020860160005b8281101561060257603f198786030184528151805115158652602081015190506040602087015280518060408801526105df816060890160208501610348565b601f01601f1916959095016060019450602093840193919091019060010161059f565b5092969550505050505056fe'
+  '0x60806040526040516106c13803806106c18339810160408190526100229161041e565b80516000816001600160401b0381111561003e5761003e61038c565b60405190808252806020026020018201604052801561008457816020015b60408051808201909152600081526060602082015281526020019060019003908161005c5790505b50905060005b828110156103395760008482815181106100a6576100a66105b9565b602090810291909101015160408101518151919250906001600160a01b031673ca11bde05977b3631167028862be2a173976ca111480156100e8575080516024145b801561010c5750631348c07360e21b610100826105cf565b6001600160e01b031916145b1561017e5760248101516040805180820182526001815290516001600160a01b039290921691602080830191610149918531910190815260200190565b60405160208183030381529060405281525085858151811061016d5761016d6105b9565b60200260200101819052505061032f565b81516001600160a01b031673ca11bde05977b3631167028862be2a173976ca111480156101ac575080516004145b80156101d057506310b2ec5760e21b6101c4826105cf565b6001600160e01b031916145b15610230576040518060400160405280600115158152602001436040516020016101fc91815260200190565b604051602081830303815290604052815250848481518110610220576102206105b9565b602002602001018190525061032f565b60008083600001516001600160a01b03168360405161024f919061060d565b6000604051808303816000865af19150503d806000811461028c576040519150601f19603f3d011682016040523d82523d6000602084013e610291565b606091505b5091509150811580156102a657508360200151155b156102f85760405162461bcd60e51b815260206004820152601760248201527f4d756c746963616c6c333a2063616c6c206661696c656400000000000000000060448201526064015b60405180910390fd5b6040518060400160405280831515815260200182815250868681518110610321576103216105b9565b602002602001018190525050505b505060010161008a565b5060008160405160200161034d9190610629565b6040516020818303038152906040529050616000815111156103845781604051633649f05160e01b81526004016102ef9190610629565b805160208201f35b634e487b7160e01b600052604160045260246000fd5b604051606081016001600160401b03811182821017156103c4576103c461038c565b60405290565b604051601f8201601f191681016001600160401b03811182821017156103f2576103f261038c565b604052919050565b60005b838110156104155781810151838201526020016103fd565b50506000910152565b60006020828403121561043057600080fd5b81516001600160401b0381111561044657600080fd5b8201601f8101841361045757600080fd5b80516001600160401b038111156104705761047061038c565b8060051b610480602082016103ca565b9182526020818401810192908101908784111561049c57600080fd5b6020850192505b838310156105ae5782516001600160401b038111156104c157600080fd5b85016060818a03601f190112156104d757600080fd5b6104df6103a2565b60208201516001600160a01b03811681146104f957600080fd5b81526040820151801515811461050e57600080fd5b602082015260608201516001600160401b0381111561052c57600080fd5b60208184010192505089601f83011261054457600080fd5b81516001600160401b0381111561055d5761055d61038c565b610570601f8201601f19166020016103ca565b8181528b602083860101111561058557600080fd5b6105968260208301602087016103fa565b604083015250835250602092830192909101906104a3565b979650505050505050565b634e487b7160e01b600052603260045260246000fd5b805160208201516001600160e01b0319811691906004821015610606576001600160e01b0319600483900360031b81901b82161692505b5050919050565b6000825161061f8184602087016103fa565b9190910192915050565b6000602082016020835280845180835260408501915060408160051b86010192506020860160005b828110156106b457603f198786030184528151805115158652602081015190506040602087015280518060408801526106918160608901602085016103fa565b601f01601f19169590950160600194506020938401939190910190600101610651565b5092969550505050505056fe'

package/src/erc20.ts

@@ -1,4 +1,4 @@
-import type { BoundCall } from './call.js'
+import type { BoundCall, FailureReason } from './call.js'
 import type { BoundMethod, Contract } from './contract.js'
 
 export const ERC20_ABI = [
@@ -41,9 +41,18 @@ export interface TokenAllowance {
   formatted: string
   /** 额度 ≥ uint96 最大值时为 true（覆盖 MaxUint256，以及 UNI / COMP 等把额度截断为 uint96 的代币） */
   unlimited: boolean
+  /** 仅在 withBlock / minBlock 时返回：读取时的区块号（读取失败为 null） */
+  blockNumber?: number | null
   success: boolean
+  /** 仅在 success 为 false 时返回：失败原因 */
+  error?: FailureReason
+  /** 仅在 success 为 false 时返回：哪一项没读到 */
+  errorField?: 'allowance' | 'decimals'
 }
 
+/** allowances(..., { decimals: false }) 的单项结果：不查 decimals，不带 decimals / formatted */
+export type RawTokenAllowance = Omit<TokenAllowance, 'decimals' | 'formatted'>
+
 /** unlimited 的判定阈值：uint96 最大值 */
 export const UNLIMITED_ALLOWANCE_THRESHOLD = 2n ** 96n - 1n
 
@@ -75,8 +84,14 @@ export type TokenDetails<F extends TokenField = DefaultTokenField> = {
   address: string
   /** 是否是主币占位地址（信息来自内置链信息表 / nativeSymbol 等配置） */
   native: boolean
+  /** 仅在 withBlock / minBlock 时返回：读取时的区块号（读取失败为 null） */
+  blockNumber?: number | null
   /** 请求的字段都读到时为 true（主币没有 totalSupply，不计入） */
   success: boolean
+  /** 仅在 success 为 false 时返回：第一个没读到的字段的失败原因 */
+  error?: FailureReason
+  /** 仅在 success 为 false 时返回：第一个没读到的字段 */
+  errorField?: TokenField
 } & { [K in F]: TokenFieldTypes[K] } & ('totalSupply' extends F ? { totalSupplyFormatted: string | null } : unknown)
 
 /** 主币占位地址（多数聚合器、钱包的约定），传给 balances() 时按主币处理 */
@@ -100,15 +115,27 @@ export interface TokenBalance {
   formatted: string
   /** 仅在 symbol: true 时返回；读取失败或主币 symbol 未知时为 null */
   symbol?: string | null
+  /** 仅在 withBlock / minBlock 时返回：读取时的区块号（与余额在同一次 eth_call 里读出；读取失败为 null） */
+  blockNumber?: number | null
   /** 余额和 decimals 都查到时为 true；失败时 balance、formatted 都为 "0" */
   success: boolean
+  /**
+   * 仅在 success 为 false 时返回：失败原因（invalid-address 地址非法、no-contract 地址上没有合约、
+   * reverted 执行 revert、decode-failed 返回值无法解码）。symbol 读不到不算失败（symbol 为 null）
+   */
+  error?: FailureReason
+  /** 仅在 success 为 false 时返回：哪一项没读到（两项都失败时为 balance） */
+  errorField?: 'balance' | 'decimals'
 }
 
+/** balances(..., { decimals: false }) 的单项结果：不查 decimals，不带 decimals / formatted */
+export type RawTokenBalance = Omit<TokenBalance, 'decimals' | 'formatted' | 'errorField'> & { errorField?: 'balance' }
+
 /**
- * 按精度格式化：formatAmount(1234500000n, 6) === '1234.5'，formatAmount(10n ** 18n, 18) === '1'。
- * 不做四舍五入，保留全部有效小数位。
+ * 按精度格式化（与 ethers 的 formatUnits 同名同义）：formatUnits(1234500000n, 6) === '1234.5'，formatUnits(10n ** 18n, 18) === '1'。
+ * 不做四舍五入，保留全部有效小数位，整数不带小数点（与 ethers 不同：ethers 会返回 '1.0'）。
  */
-export function formatAmount(value: bigint, decimals: number): string {
+export function formatUnits(value: bigint, decimals: number): string {
   const negative = value < 0n
   const digits = (negative ? -value : value).toString().padStart(decimals + 1, '0')
   const whole = digits.slice(0, digits.length - decimals)
@@ -116,7 +143,11 @@ export function formatAmount(value: bigint, decimals: number): string {
   return `${negative ? '-' : ''}${whole}${fraction ? `.${fraction}` : ''}`
 }
 
-// decimals / symbol / name 不会变，按 chainId + 地址缓存，轮询余额时只需要查 balanceOf
+/** @deprecated 改用 formatUnits（同一个函数；formatAmount 容易与项目里的数字展示函数撞名） */
+export const formatAmount = formatUnits
+
+// 代币信息缓存（按 chainId + 地址）：decimals / NFT 标准不会变，永久缓存；name / symbol 在可升级合约上可能改，缓存 1 小时。
+// 条目数有上限，超出时淘汰最早写入的（与 solana-batch-call 一致）。轮询余额时只需要查 balanceOf
 interface TokenMeta {
   decimals?: number
   symbol?: string
@@ -125,21 +156,153 @@ interface TokenMeta {
   standard?: 'ERC721' | 'ERC1155' | null
 }
 
-const tokenMetaCache = new Map<string, TokenMeta>()
+interface CachedMeta extends TokenMeta {
+  /** name / symbol 各自的写入时间（分开计：只刷新其中一个时，另一个照常过期） */
+  nameAt?: number
+  symbolAt?: number
+}
+
+const NAME_TTL = 60 * 60 * 1000
+const MAX_CACHED_TOKENS = 50_000
+const tokenMetaCache = new Map<string, CachedMeta>()
+const cacheListeners = new Set<() => void>()
 
 export function getCachedTokenMeta(chainId: number, token: string): TokenMeta {
-  return tokenMetaCache.get(`${chainId}:${token.toLowerCase()}`) ?? {}
+  const cached = tokenMetaCache.get(`${chainId}:${token.toLowerCase()}`)
+  if (!cached) {
+    return {}
+  }
+  const { nameAt, symbolAt, ...meta } = cached
+  const now = Date.now()
+  if (nameAt === undefined || now - nameAt > NAME_TTL) {
+    delete meta.name
+  }
+  if (symbolAt === undefined || now - symbolAt > NAME_TTL) {
+    delete meta.symbol
+  }
+  return meta
 }
 
 export function setCachedTokenMeta(chainId: number, token: string, meta: TokenMeta): void {
   if (Object.keys(meta).length === 0) {
     return // 没有新数据（如查询失败）时不写入空条目
   }
+  const defined: CachedMeta = { ...meta }
+  if ('name' in meta) {
+    defined.nameAt = Date.now()
+  }
+  if ('symbol' in meta) {
+    defined.symbolAt = Date.now()
+  }
   const key = `${chainId}:${token.toLowerCase()}`
-  tokenMetaCache.set(key, { ...tokenMetaCache.get(key), ...meta })
+  const merged = { ...tokenMetaCache.get(key), ...defined }
+  tokenMetaCache.delete(key) // 重新插入，保持“最近写入在后”的顺序
+  tokenMetaCache.set(key, merged)
+  if (tokenMetaCache.size > MAX_CACHED_TOKENS) {
+    tokenMetaCache.delete(tokenMetaCache.keys().next().value as string)
+  }
+  cacheListeners.forEach((listener) => listener())
 }
 
 /** 测试用：清空 decimals / symbol 缓存 */
 export function resetDecimalsCache(): void {
   tokenMetaCache.clear()
 }
+
+/** exportTokenMetaCache() 的结果，可以 JSON.stringify */
+export interface TokenMetaSnapshot {
+  version: 1
+  /** [chainId:小写地址, 信息]，按写入时间先后 */
+  entries: Array<[string, CachedMeta]>
+}
+
+/**
+ * 导出代币信息缓存（decimals / symbol / name / NFT 标准），可存到任意地方，下次用 importTokenMetaCache 导入，
+ * 页面刷新后不必重查精度。name / symbol 带写入时间，导入后仍按 1 小时过期。
+ *
+ * @param maxEntries 最多导出多少条（最近写入的优先），默认全部
+ */
+export function exportTokenMetaCache(maxEntries = Number.POSITIVE_INFINITY): TokenMetaSnapshot {
+  const entries = [...tokenMetaCache]
+  return { version: 1, entries: entries.slice(Math.max(0, entries.length - maxEntries)) }
+}
+
+/** 导入 exportTokenMetaCache 的结果；格式不对的数据忽略。已有的条目以缓存里的为准（更新） */
+export function importTokenMetaCache(snapshot: unknown): void {
+  const entries = (snapshot as Partial<TokenMetaSnapshot> | null)?.entries
+  if ((snapshot as Partial<TokenMetaSnapshot> | null)?.version !== 1 || !Array.isArray(entries)) {
+    return
+  }
+  for (const entry of entries) {
+    if (!Array.isArray(entry) || typeof entry[0] !== 'string' || !/^\d+:\S+$/.test(entry[0]) || !entry[1] || typeof entry[1] !== 'object') {
+      continue
+    }
+    const [rawKey, value] = entry as [string, CachedMeta]
+    // 与 getCachedTokenMeta 的 key 一致：地址部分小写
+    const separator = rawKey.indexOf(':')
+    const key = `${rawKey.slice(0, separator)}:${rawKey.slice(separator + 1).toLowerCase()}`
+    const meta: CachedMeta = {}
+    if (Number.isInteger(value.decimals) && (value.decimals as number) >= 0 && (value.decimals as number) <= 255) meta.decimals = value.decimals
+    if (typeof value.name === 'string' && typeof value.nameAt === 'number') {
+      meta.name = value.name
+      meta.nameAt = value.nameAt
+    }
+    if (typeof value.symbol === 'string' && typeof value.symbolAt === 'number') {
+      meta.symbol = value.symbol
+      meta.symbolAt = value.symbolAt
+    }
+    if (value.standard === 'ERC721' || value.standard === 'ERC1155' || value.standard === null) meta.standard = value.standard
+    if (Object.keys(meta).length && !tokenMetaCache.has(key)) {
+      tokenMetaCache.set(key, meta)
+    }
+  }
+  while (tokenMetaCache.size > MAX_CACHED_TOKENS) {
+    tokenMetaCache.delete(tokenMetaCache.keys().next().value as string)
+  }
+}
+
+/** persistTokenMetaCache 的存储：localStorage / sessionStorage 可以直接传，也可以自己实现 */
+export interface TokenMetaStore {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+}
+
+/**
+ * 把代币信息缓存持久化到同步的键值存储（如 localStorage）：调用时先读入，之后缓存有更新就防抖（1 秒）整体写回。
+ * 返回停止持久化的函数。存储读写出错（如超出配额）时忽略。
+ *
+ * ```ts
+ * persistTokenMetaCache(localStorage) // 刷新页面后不必重查 decimals
+ * ```
+ */
+export function persistTokenMetaCache(store: TokenMetaStore, options: { key?: string; maxEntries?: number } = {}): () => void {
+  const { key = 'w3lib:evm-token-meta', maxEntries = 5000 } = options
+  try {
+    const raw = store.getItem(key)
+    if (raw) {
+      importTokenMetaCache(JSON.parse(raw))
+    }
+  } catch {
+    // 数据损坏：忽略，之后会被覆盖
+  }
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const save = () => {
+    timer = undefined
+    try {
+      store.setItem(key, JSON.stringify(exportTokenMetaCache(maxEntries)))
+    } catch {
+      // 超出配额等：忽略
+    }
+  }
+  const listener = () => {
+    timer ??= setTimeout(save, 1000)
+  }
+  cacheListeners.add(listener)
+  return () => {
+    cacheListeners.delete(listener)
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      save()
+    }
+  }
+}

package/src/events.ts

@@ -0,0 +1,42 @@
+/** 一次对某个节点的请求（onRequest 的事件） */
+export interface RequestEvent {
+  /** 节点标识：URL 节点只取 host（不含 path / query，避免泄露 API Key）；钱包为 'wallet'，tronWeb 为 'tronWeb'，其他对象为 'provider' */
+  node: string
+  /** 'call' | 'getBalance' | 'getChainId' | 'getBlockNumber' | 'getLogs' */
+  method: string
+  /** 耗时（毫秒） */
+  ms: number
+  ok: boolean
+  /** 失败时的错误 */
+  error?: unknown
+  /** 本次请求按故障切换顺序的第几个节点（0 起）；大于 0 表示换过节点 */
+  attempt: number
+}
+
+export type RequestListener = (event: RequestEvent) => void
+
+const listeners = new Set<RequestListener>()
+
+/**
+ * 订阅所有节点请求（全局，对所有 Provider 生效），用于观察哪个节点返回、换过几次节点、每次耗时。返回取消订阅的函数。
+ *
+ * ```ts
+ * const off = onRequest((e) => console.log(e.node, e.method, e.ms, e.ok, e.attempt))
+ * ```
+ */
+export function onRequest(listener: RequestListener): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+export function emitRequest(event: RequestEvent): void {
+  for (const listener of listeners) {
+    try {
+      listener(event)
+    } catch {
+      // 监听函数出错不影响请求
+    }
+  }
+}