异步节流指南

异步节流指南

节流指南中的所有核心概念同样适用于异步节流。

何时使用异步节流

通常情况下，你可以直接使用普通的同步节流器，它也能与异步函数一起工作。但是，对于一些高级用例，例如希望使用节流函数的返回值（而不仅仅是调用 setState 副作用），或者将错误处理逻辑放在节流器中，你可以使用异步节流器。

TanStack Pacer 中的异步节流

TanStack Pacer 通过 AsyncThrottler 类和 asyncThrottle 函数提供异步节流功能。

基本用法示例

以下是一个基本示例，展示了如何将异步节流器用于搜索操作：

const throttledSearch = asyncThrottle(
  async (searchTerm: string) => {
    const results = await fetchSearchResults(searchTerm)
    return results
  },
  {
    wait: 500,
    onSuccess: (results, throttler) => {
      console.log('搜索成功：', results)
    },
    onError: (error, throttler) => {
      console.error('搜索失败：', error)
    }
  }
)

// 用法
try {
  const results = await throttledSearch('query')
  // 处理成功的结果
} catch (error) {
  // 如果未提供 onError 处理程序，则处理错误
  console.error('搜索失败：', error)
}

const throttledSearch = asyncThrottle(
  async (searchTerm: string) => {
    const results = await fetchSearchResults(searchTerm)
    return results
  },
  {
    wait: 500,
    onSuccess: (results, throttler) => {
      console.log('搜索成功：', results)
    },
    onError: (error, throttler) => {
      console.error('搜索失败：', error)
    }
  }
)

// 用法
try {
  const results = await throttledSearch('query')
  // 处理成功的结果
} catch (error) {
  // 如果未提供 onError 处理程序，则处理错误
  console.error('搜索失败：', error)
}

与同步节流的主要区别

1. 返回值处理

与返回 void 的同步节流器不同，异步版本允许你捕获和使用节流函数的返回值。maybeExecute 方法返回一个 Promise，该 Promise 会解析为函数的返回值，从而允许你等待结果并适当地处理它。

2. 错误处理

异步节流器提供了强大的错误处理功能：

如果你的节流函数抛出错误并且未提供 onError 处理程序，则该错误将被抛出并向上传播给调用者
如果你提供了 onError 处理程序，错误将被捕获并传递给处理程序，而不是被抛出
throwOnError 选项可用于控制错误抛出行为：
- 当为 true 时（如果未提供 onError 处理程序，则为默认值），将抛出错误
- 当为 false 时（如果提供了 onError 处理程序，则为默认值），错误将被忽略
- 可以显式设置以覆盖这些默认值
你可以使用 getErrorCount() 跟踪错误计数，并使用 getIsExecuting() 检查执行状态
节流器会维护其状态，并且在发生错误后可以继续使用

3. 不同的回调

AsyncThrottler 支持以下回调：

onSuccess：每次成功执行后调用，提供结果和节流器实例
onSettled：每次执行（成功或失败）后调用，提供节流器实例
onError：如果异步函数抛出错误，则调用，同时提供错误和节流器实例

示例：

const asyncThrottler = new AsyncThrottler(async (value) => {
  await saveToAPI(value)
}, {
  wait: 500,
  onSuccess: (result, throttler) => {
    // 每次成功执行后调用
    console.log('异步函数已执行', throttler.getSuccessCount())
  },
  onSettled: (throttler) => {
    // 每次执行尝试后调用
    console.log('异步函数已完成', throttler.getSettledCount())
  },
  onError: (error) => {
    // 如果异步函数抛出错误，则调用
    console.error('异步函数失败：', error)
  }
})

const asyncThrottler = new AsyncThrottler(async (value) => {
  await saveToAPI(value)
}, {
  wait: 500,
  onSuccess: (result, throttler) => {
    // 每次成功执行后调用
    console.log('异步函数已执行', throttler.getSuccessCount())
  },
  onSettled: (throttler) => {
    // 每次执行尝试后调用
    console.log('异步函数已完成', throttler.getSettledCount())
  },
  onError: (error) => {
    // 如果异步函数抛出错误，则调用
    console.error('异步函数失败：', error)
  }
})