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

// 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

// 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

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

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

Option	Type	Default	Description
concurrency	number	1	Max concurrent requests
autoStart	boolean	true	Auto-start after adding a request
continueOnError	boolean	false	Continue 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 / Method	Description
tasks	All task list
pendingTasks	Tasks waiting to run
runningTasks	Currently executing tasks
completedTasks	Successfully completed tasks
failedTasks	Failed tasks
isRunning	Whether the queue is running
isEmpty	Whether the queue is empty
isAllComplete	Whether all tasks are done
completedCount	Number of completed tasks
totalCount	Total 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

Feature	useQueue	useRequestQueue
Use case	General tasks	HTTP requests
Add task	add(task, options)	addRequest(requestFn, options)
Keyed cancel	Manual	cancelByKey(key) built-in
Metadata	Manual	Auto-tagged type: 'request'