@w3lib/solana-batch-call 0.1.0 → 0.2.0

package/src/shortcuts.ts

@@ -1,4 +1,13 @@
-import { SolanaClient, type BalancesOptions, type ClientConfig, type OwnerTokensOptions, type TokensOptions } from './client.js'
+import {
+  SolanaClient,
+  type BalanceQuery,
+  type BalancesOptions,
+  type ClientConfig,
+  type OwnerTokensOptions,
+  type RequestOptions,
+  type SolBalancesOptions,
+  type TokensOptions,
+} from './client.js'
 import type { RpcSource } from './source.js'
 import type { DefaultTokenField, NftDetails, NftOwner, OwnedToken, SolBalance, TokenBalance, TokenDetails, TokenField } from './types.js'
 
@@ -55,7 +64,10 @@ function sourceKey(source: ShortcutOptions['provider']): string | object | null
   return source as object
 }
 
-/** 拆出节点参数和函数自己的参数（ownKeys），其余作为客户端配置；值为 undefined 的参数忽略 */
+/**
+ * 拆出节点参数和函数自己的参数（ownKeys），其余作为客户端配置；值为 undefined 的参数忽略。
+ * signal 总是作为函数自己的参数（放进客户端配置会让每次调用都新建客户端）
+ */
 function resolve<T extends ShortcutOptions, K extends keyof T & string = never>(
   options: T,
   ownKeys: readonly K[] = [],
@@ -65,7 +77,7 @@ function resolve<T extends ShortcutOptions, K extends keyof T & string = never>(
   const config: Record<string, unknown> = {}
   for (const [key, value] of Object.entries(others)) {
     if (value !== undefined) {
-      ;((ownKeys as readonly string[]).includes(key) ? own : config)[key] = value
+      ;((ownKeys as readonly string[]).includes(key) ? own : key === 'signal' ? {} : config)[key] = value
     }
   }
   return { client: getClient(provider, config as ClientConfig), own: own as Pick<T, K> }
@@ -104,17 +116,36 @@ export interface GetBalancesOptions extends BalancesOptions, ShortcutOptions {}
  *
  * await getBalances(owner, [NATIVE_MINT, USDC])                        // 指定代币：免费公共节点也能用
  * await getBalances(owner, [NATIVE_MINT, USDC], { symbol: true })
+ * await getBalances(owner, undefined, { tokenPrograms: ['spl'] })            // 不含 Token-2022 代币
+ * await getBalances(owner, [USDC], { accounts: 'all' })                      // 算上非 ATA 账户：需要支持 getTokenAccountsByOwner 的节点
  * await getBalances(owner, undefined, { provider: 'https://my-rpc…' })  // 全部持仓：需要支持 getTokenAccountsByOwner 的节点
  * ```
  */
 export function getBalances(owner: string, mints?: readonly string[], options: GetBalancesOptions = {}): Promise<TokenBalance[]> {
-  const { client, own } = resolve(options, ['symbol', 'scan'])
+  const { client, own } = resolve(options, BALANCE_KEYS)
   return client.balances(owner, mints, own)
 }
 
+const BALANCE_KEYS = ['symbol', 'scan', 'accounts', 'tokenPrograms', 'signal', 'minContextSlot', 'withSlot'] as const
+
+/**
+ * 多个钱包一次查，结果与 queries 一一对应；ATA 模式下所有钱包合并成一次 getMultipleAccounts。参数同 getBalances。
+ *
+ * ```ts
+ * await getMultiBalances([{ owner: a, mints: [NATIVE_MINT, USDC] }, { owner: b, mints: [USDC] }])
+ * ```
+ */
+export function getMultiBalances(queries: readonly BalanceQuery[], options: GetBalancesOptions = {}): Promise<TokenBalance[][]> {
+  const { client, own } = resolve(options, BALANCE_KEYS)
+  return client.multiBalances(queries, own)
+}
+
+export interface GetSolBalancesOptions extends SolBalancesOptions, ShortcutOptions {}
+
 /** 批量查多个地址的 SOL 余额（一次 getMultipleAccounts） */
-export function getSolBalances(addresses: readonly string[], options: ShortcutOptions = {}): Promise<SolBalance[]> {
-  return resolve(options).client.solBalances(addresses)
+export function getSolBalances(addresses: readonly string[], options: GetSolBalancesOptions = {}): Promise<SolBalance[]> {
+  const { client, own } = resolve(options, ['signal', 'minContextSlot', 'withSlot'])
+  return client.solBalances(addresses, own)
 }
 
 export interface GetTokensOptions<F extends TokenField = DefaultTokenField> extends TokensOptions<F>, ShortcutOptions {}
@@ -127,23 +158,28 @@ export interface GetTokensOptions<F extends TokenField = DefaultTokenField> exte
  * ```
  */
 export function getTokens<const F extends TokenField = DefaultTokenField>(mints: readonly string[], options: GetTokensOptions<F> = {}): Promise<TokenDetails<F>[]> {
-  const { client, own } = resolve(options, ['fields'])
-  return client.tokens<F>(mints, { fields: own.fields })
+  const { client, own } = resolve(options, ['fields', 'signal'])
+  return client.tokens<F>(mints, own)
 }
 
+export interface GetNftsOptions extends RequestOptions, ShortcutOptions {}
+
 /** 批量查 NFT 元数据（名称、uri、所属集合、版税、创作者等） */
-export function getNfts(mints: readonly string[], options: ShortcutOptions = {}): Promise<NftDetails[]> {
-  return resolve(options).client.nfts(mints)
+export function getNfts(mints: readonly string[], options: GetNftsOptions = {}): Promise<NftDetails[]> {
+  const { client, own } = resolve(options, ['signal'])
+  return client.nfts(mints, own)
 }
 
 /** 批量查 NFT 持有人 */
-export function getNftOwners(mints: readonly string[], options: ShortcutOptions = {}): Promise<NftOwner[]> {
-  return resolve(options).client.nftOwners(mints)
+export function getNftOwners(mints: readonly string[], options: GetNftsOptions = {}): Promise<NftOwner[]> {
+  const { client, own } = resolve(options, ['signal'])
+  return client.nftOwners(mints, own)
 }
 
 /** 查某地址持有的全部 NFT（需要支持 getTokenAccountsByOwner 的节点） */
-export function getOwnerNfts(owner: string, options: ShortcutOptions = {}): Promise<NftDetails[]> {
-  return resolve(options).client.ownerNfts(owner)
+export function getOwnerNfts(owner: string, options: GetNftsOptions = {}): Promise<NftDetails[]> {
+  const { client, own } = resolve(options, ['signal'])
+  return client.ownerNfts(owner, own)
 }
 
 export interface GetOwnerTokensOptions extends OwnerTokensOptions, ShortcutOptions {}
@@ -158,10 +194,168 @@ export interface GetOwnerTokensOptions extends OwnerTokensOptions, ShortcutOptio
  * ```
  */
 export function getOwnerTokens(owner: string, options: GetOwnerTokensOptions = {}): Promise<OwnedToken[]> {
-  const { client, own } = resolve(options, ['metadata', 'includeNative', 'includeZero', 'includeNfts'])
+  const { client, own } = resolve(options, ['metadata', 'includeNative', 'includeZero', 'includeNfts', 'tokenPrograms', 'signal', 'minContextSlot', 'withSlot'])
   return client.ownerTokens(owner, own)
 }
 
+export interface WatchBalancesOptions extends Omit<GetBalancesOptions, 'signal' | 'minContextSlot'> {
+  /** 轮询间隔（毫秒），默认 15000；多处订阅同一份时取最小的 */
+  interval?: number
+  /** 第一次拿到结果、以及之后余额（balance）变化时调用；previous 是上一次通知的结果（第一次为 null） */
+  onChange: (balances: TokenBalance[], previous: TokenBalance[] | null) => void
+  /** 某次轮询失败时调用（之后照常继续轮询） */
+  onError?: (err: unknown) => void
+}
+
+interface Watcher {
+  interval: number
+  onChange: WatchBalancesOptions['onChange']
+  onError?: WatchBalancesOptions['onError']
+}
+
+interface Watch {
+  client: SolanaClient
+  owner: string
+  mints: readonly string[] | undefined
+  options: BalancesOptions
+  watchers: Set<Watcher>
+  timer: ReturnType<typeof setTimeout> | null
+  running: boolean
+  stopped: boolean
+  last: TokenBalance[] | null
+  lastKey: string | null
+}
+
+// 共享轮询：按客户端（同样的节点配置会复用同一个客户端）+ owner + mints（顺序无关）+ 影响结果的选项
+const watches = new WeakMap<SolanaClient, Map<string, Watch>>()
+
+/**
+ * 轮询余额，多处订阅同一个钱包时合并成一份轮询，只在余额变化时通知。返回取消订阅的函数；最后一个订阅者取消时停止轮询。
+ * 参数同 getBalances（不支持 signal / minContextSlot）；上一次请求没完成时不会发起下一次。
+ * 结果顺序按第一个订阅者传的 mints；新订阅者加入时如果已有结果，立即收到一次（previous 为 null）
+ *
+ * ```ts
+ * const stop = watchBalances(owner, [NATIVE_MINT, USDC], { interval: 10_000, onChange: (list) => render(list) })
+ * stop()
+ * ```
+ */
+export function watchBalances(owner: string, mints: readonly string[] | undefined, options: WatchBalancesOptions): () => void {
+  const { onChange, onError, interval = 15_000, ...rest } = options
+  if (!(interval > 0)) {
+    throw new Error(`Invalid interval: ${interval}`)
+  }
+  const { client, own } = resolve(rest, ['symbol', 'scan', 'accounts', 'tokenPrograms', 'withSlot'])
+  const key = JSON.stringify([
+    owner,
+    mints === undefined ? null : [...new Set(mints)].sort(),
+    own.symbol ?? false,
+    own.scan ?? false,
+    own.accounts ?? 'ata',
+    own.tokenPrograms === undefined ? null : [...own.tokenPrograms].sort(),
+    own.withSlot ?? false,
+  ])
+  let group = watches.get(client)
+  if (!group) {
+    group = new Map()
+    watches.set(client, group)
+  }
+  let watch = group.get(key)
+  const watcher: Watcher = { interval, onChange, onError }
+  if (!watch) {
+    watch = { client, owner, mints, options: own, watchers: new Set([watcher]), timer: null, running: false, stopped: false, last: null, lastKey: null }
+    group.set(key, watch)
+    poll(watch)
+  } else {
+    watch.watchers.add(watcher)
+    const current = watch
+    if (current.last) {
+      const last = current.last
+      queueMicrotask(() => current.watchers.has(watcher) && safely(() => watcher.onChange(last, null)))
+    }
+    // 间隔变小：按新的间隔重新安排下一次
+    if (current.timer && interval < nextInterval(current, watcher)) {
+      clearTimeout(current.timer)
+      current.timer = null
+      schedule(current)
+    }
+  }
+  const owned = watch
+  const ownedGroup = group
+  return () => {
+    if (!owned.watchers.delete(watcher) || owned.watchers.size) {
+      return
+    }
+    owned.stopped = true
+    if (owned.timer) {
+      clearTimeout(owned.timer)
+      owned.timer = null
+    }
+    if (ownedGroup.get(key) === owned) {
+      ownedGroup.delete(key)
+    }
+  }
+}
+
+/** 除了 except 以外订阅者的最小间隔（用于判断新订阅者是否让间隔变小） */
+function nextInterval(watch: Watch, except?: Watcher): number {
+  let min = Number.POSITIVE_INFINITY
+  for (const w of watch.watchers) {
+    if (w !== except) min = Math.min(min, w.interval)
+  }
+  return min
+}
+
+function schedule(watch: Watch): void {
+  if (watch.stopped || watch.timer || watch.running) {
+    return
+  }
+  watch.timer = setTimeout(() => poll(watch), nextInterval(watch))
+}
+
+function poll(watch: Watch): void {
+  watch.timer = null
+  if (watch.running || watch.stopped) {
+    return
+  }
+  watch.running = true
+  watch.client
+    .balances(watch.owner, watch.mints, watch.options)
+    .then(
+      (balances) => {
+        // 只比较余额（slot 每次都会变）
+        const key = JSON.stringify(balances.map((b) => [b.token, b.balance, b.success]))
+        if (watch.stopped || key === watch.lastKey) {
+          return
+        }
+        const previous = watch.last
+        watch.last = balances
+        watch.lastKey = key
+        for (const w of [...watch.watchers]) {
+          safely(() => w.onChange(balances, previous))
+        }
+      },
+      (err: unknown) => {
+        if (!watch.stopped) {
+          for (const w of [...watch.watchers]) {
+            safely(() => w.onError?.(err))
+          }
+        }
+      },
+    )
+    .finally(() => {
+      watch.running = false
+      schedule(watch)
+    })
+}
+
+function safely(fn: () => void): void {
+  try {
+    fn()
+  } catch {
+    // 订阅者的回调出错不影响轮询
+  }
+}
+
 /** 测试用：按参数取（或创建）客户端，用于验证缓存复用（不在包的公开导出里） */
 export function resolveClientForTest(options: ShortcutOptions): SolanaClient {
   return resolve(options).client

package/src/source.ts

@@ -144,8 +144,6 @@ export function resolveSource(
   // 内置节点本来就是按 cluster 选的，不校验；单个节点且没指定 cluster 时，期望值就是它自己，也不需要校验
   const check = !isDefault && (multiple || cluster !== undefined)
   const nodes = check ? raw.map((node) => new NetworkCheckedRpc(node, genesis)) : raw
-  return {
-    transport: multiple ? new FallbackRpc(nodes, options) : (nodes[0] as RpcTransport),
-    genesis,
-  }
+  // 单个节点也包一层 FallbackRpc：统一 onRequest 事件和健康状态（单节点失败时抛原始错误）
+  return { transport: new FallbackRpc(nodes, options), genesis }
 }

package/src/types.ts

@@ -1,5 +1,24 @@
 export type Commitment = 'processed' | 'confirmed' | 'finalized'
 
+/**
+ * tokenPrograms 参数的取值：简写 'spl'（SPL Token）/ 'token-2022'，也可以直接传程序地址
+ * （TOKEN_PROGRAM_ID / TOKEN_2022_PROGRAM_ID）
+ */
+export type TokenProgramName = 'spl' | 'token-2022'
+// (string & {})：保留 'spl' / 'token-2022' 的自动补全
+export type TokenProgramOption = TokenProgramName | (string & {})
+
+/**
+ * 单项失败（success: false）的原因：
+ * - invalid-address：地址格式非法（不是 base58 的 32 字节）
+ * - not-found：地址合法，但链上没有这个账户（如 mint 不存在）
+ * - not-token：账户存在，但不是代币 mint（或代币账户）
+ * - no-metadata：代币存在，但没有元数据（nfts）
+ * - no-holder：没有持有人（nftOwners：供应量为 0 或已销毁）
+ * - missing-field：代币存在，但请求的字段读不到（tokens），见 errorField
+ */
+export type FailureReason = 'invalid-address' | 'not-found' | 'not-token' | 'no-metadata' | 'no-holder' | 'missing-field'
+
 /** balances() 的单项结果，字段都是字符串 / 数字 / 布尔 / null，可以直接 JSON.stringify */
 export interface TokenBalance {
   /** 代币的 mint（原样） */
@@ -17,10 +36,14 @@ export interface TokenBalance {
   symbol?: string | null
   /** 查询失败（mint 不存在、地址非法等）时为 false，balance / formatted 为 "0" */
   success: boolean
+  /** 失败原因，仅 success 为 false 时返回 */
+  error?: FailureReason
+  /** 传了 withSlot / minContextSlot 时返回：读取时节点的 slot（一次查询发了多个请求时取最小的） */
+  slot?: number
 }
 
-/** ownerTokens() / getOwnerTokens() 的单项结果 */
-export interface OwnedToken extends Omit<TokenBalance, 'symbol'> {
+/** ownerTokens() / getOwnerTokens() 的单项结果（总是 success: true） */
+export interface OwnedToken extends Omit<TokenBalance, 'symbol' | 'error'> {
   /** 该代币的代币账户数量；大于 1 时 balance 为所有账户的合计 */
   accounts: number
   /** metadata 为 true（默认）时返回；没有元数据或读取失败时为 null（见 metadataStatus） */
@@ -37,10 +60,33 @@ export interface SolBalance {
   /** 按 9 位精度换算后的 SOL */
   formatted: string
   success: boolean
+  /** 失败原因（只有 invalid-address），仅 success 为 false 时返回 */
+  error?: FailureReason
+  /** 传了 withSlot / minContextSlot 时返回：读取时节点的 slot（多个请求时取最小的）；没有发请求（地址全部非法）时不返回 */
+  slot?: number
 }
 
 /** tokens() / getTokens() 可选的字段 */
-export type TokenField = 'name' | 'symbol' | 'uri' | 'decimals' | 'supply' | 'tokenProgram' | 'mintAuthority' | 'freezeAuthority'
+export type TokenField = 'name' | 'symbol' | 'uri' | 'decimals' | 'supply' | 'tokenProgram' | 'mintAuthority' | 'freezeAuthority' | 'transferFee'
+
+/** Token-2022 转账手续费的一套配置 */
+export interface TransferFee {
+  /** 费率，万分比（100 = 1%） */
+  basisPoints: number
+  /** 单笔最多收取的手续费（最小单位的十进制字符串） */
+  maximumFee: string
+  /** 从这个 epoch 开始生效 */
+  epoch: string
+}
+
+/**
+ * tokens() 的 transferFee 字段：顶层是**当前 epoch** 生效的配置（按 getEpochInfo 选 newer / older），
+ * older / newer 是扩展里的两套原始配置。收到的数量 = 转账数量 - min(数量 × basisPoints / 10000 向上取整, maximumFee)
+ */
+export interface TransferFeeConfig extends TransferFee {
+  older: TransferFee
+  newer: TransferFee
+}
 
 export const DEFAULT_TOKEN_FIELDS = ['name', 'symbol', 'decimals'] as const satisfies readonly TokenField[]
 
@@ -58,6 +104,8 @@ interface TokenFieldTypes {
   /** 没有 mint 权限（已放弃）时为 null */
   mintAuthority: string | null
   freezeAuthority: string | null
+  /** Token-2022 转账手续费；SPL Token、没有这个扩展、主币时为 null（不算失败） */
+  transferFee: TransferFeeConfig | null
 }
 
 /**
@@ -70,6 +118,10 @@ export type TokenDetails<F extends TokenField = DefaultTokenField> = {
   native: boolean
   /** mint 存在且请求的 name / symbol / uri / decimals / supply 都读到时为 true */
   success: boolean
+  /** 失败原因，仅 success 为 false 时返回 */
+  error?: FailureReason
+  /** error 为 missing-field 时：第一个读不到的字段 */
+  errorField?: F
 } & { [K in F]: TokenFieldTypes[K] } & ('supply' extends F ? { supplyFormatted: string | null } : unknown)
 
 export type TokenStandard =
@@ -96,6 +148,8 @@ export interface NftDetails {
   isMutable: boolean | null
   updateAuthority: string | null
   success: boolean
+  /** 失败原因，仅 success 为 false 时返回 */
+  error?: FailureReason
 }
 
 export interface NftOwner {
@@ -105,4 +159,6 @@ export interface NftOwner {
   /** 持有该 NFT 的代币账户 */
   tokenAccount: string | null
   success: boolean
+  /** 失败原因，仅 success 为 false 时返回 */
+  error?: FailureReason
 }