Skip to content
Latestv1.0.63

useRequestQueue ​

useRequestQueue is an HTTP-request-focused queue Hook built on top of useQueue. It provides concurrency control, keyed cancellation, priority execution, and failure retry — all tailored for real API request scenarios.

Basic Usage ​

Batch Request Queue (Concurrency Control & Retry)

cancelByKey: Auto-Cancel Duplicate Requests ​

Type in the search box — old requests are automatically cancelled as you type.

cancelByKey Search Deduplication Demo

Adding Requests ​

typescript
// Add a GET request
const taskId = addRequest(() => request.get('/api/user/1'), {
  key: 'user-1', // Used for cancellation and deduplication
  priority: 10, // Higher = runs first
  delay: 1000, // Delay 1s before execution
  metadata: { type: 'fetch' }
})

// Add a POST request
addRequest(() => request.post('/api/order', { id: 123 }), { key: 'order-123' })

Keyed Cancellation ​

typescript
// Cancel a specific request by key
cancelByKey('user-1')

// Use case: cancel the previous user request when the user switches tabs
const loadUser = (userId: string) => {
  cancelByKey('current-user') // cancel the previous in-flight request
  addRequest(() => request.get(`/api/user/${userId}`), { key: 'current-user' })
}

Concurrency Control ​

typescript
const { addRequest, pause, resume } = useRequestQueue({
  concurrency: 2, // At most 2 concurrent requests
  autoStart: true
})

for (let i = 1; i <= 10; i++) {
  addRequest(() => request.get(`/api/item/${i}`))
}

Error Handling & Retry ​

typescript
const { failedTasks, retry, retryAll } = useRequestQueue({
  concurrency: 2,
  continueOnError: true,
  onTaskError: (task, error) => {
    console.error('Request failed:', task.key, error)
    YhMessage.error(`Failed: ${task.key}`)
  },
  onAllComplete: (tasks) => {
    console.log(`All done: ${tasks.length} requests`)
  }
})

retry(taskId) // Retry a single task
retryAll() // Retry all failed tasks

Full API ​

Options ​

OptionTypeDefaultDescription
concurrencynumber1Max concurrent requests
autoStartbooleantrueAuto-start after adding a request
continueOnErrorbooleanfalseContinue queue when a single request fails
onTaskComplete(task) => void-Callback on single task completion
onTaskError(task, error) => void-Callback on single task failure
onAllComplete(tasks) => void-Callback when all tasks in queue are done

Return Values ​

Property / MethodDescription
tasksAll task list
pendingTasksTasks waiting to run
runningTasksCurrently executing tasks
completedTasksSuccessfully completed tasks
failedTasksFailed tasks
isRunningWhether the queue is running
isEmptyWhether the queue is empty
isAllCompleteWhether all tasks are done
completedCountNumber of completed tasks
totalCountTotal tasks added
addRequest(requestFn, options)Add an HTTP request, returns task ID
cancelByKey(key)Cancel a request by key
remove(taskId)Remove a task
clear()Clear the entire queue
start()Start processing
pause()Pause the queue
resume()Resume the queue
cancel(taskId)Cancel a specific task
cancelAll()Cancel all tasks
retry(taskId)Retry a specific failed task
retryAll()Retry all failed tasks
getTask(taskId)Get task info by ID

useRequestQueue vs useQueue ​

FeatureuseQueueuseRequestQueue
Use caseGeneral tasksHTTP requests
Add taskadd(task, options)addRequest(requestFn, options)
Keyed cancelManualcancelByKey(key) built-in
MetadataManualAuto-tagged type: 'request'

Released under the MIT License.