vue-reactive-queue

Reactive async task queue for Vue 3 with concurrency control.

Features

- 🚀 Concurrency Control - Limit parallel task execution
- 📊 Reactive State - Track task status in real-time with Vue reactivity
- ⏸️ Pause/Resume - Control queue execution flow
- 🔄 Retry - Retry failed tasks with one call
- 📝 Task History - Keep track of completed tasks
- 🎯 Manual Execution - Start specific tasks on demand
- 💪 TypeScript - Full type support with generics

Install

``bash
npm install vue-reactive-queue
`

Usage

$3

`ts
import { useQueue } from 'vue-reactive-queue'

const queue = useQueue()

// Add tasks to the queue
queue.add(async () => {
await processFile('document.pdf')
})

queue.add(async () => {
await processFile('image.png')
})
`

$3

`ts
const queue = useQueue({ concurrency: 3 })

// Only 3 tasks will run in parallel
queue.add(() => fetchUser(1))
queue.add(() => fetchUser(2))
queue.add(() => fetchUser(3))
queue.add(() => fetchUser(4)) // waits for a slot
`

$3

`vue



`

$3

`ts
const queue = useQueue()

queue.add(() => task1())
queue.add(() => task2())

queue.pause() // Stop executing new tasks
queue.resume() // Continue execution
`

$3

`ts
const queue = useQueue({ immediate: false })

queue.add(() => task1())
queue.add(() => task2())

// Tasks are pending, not running
console.log(queue.stats.value.isPaused) // true

// Start when ready
queue.resume()
`

$3

Start a specific task immediately, ignoring the pause state:

`ts
const queue = useQueue({ immediate: false })

const { id: idA } = queue.add(() => taskA())
const { id: idB } = queue.add(() => taskB())
const { id: idC } = queue.add(() => taskC())

// Only execute taskB, leave others pending
await queue.start(idB)
`

$3

`ts
const queue = useQueue()

const { id } = queue.add(async () => {
await uploadFile(file) // might fail due to network issues
})

// Later, if the task failed
const result = queue.retry(id)
if (result.success) {
await result.promise
}
`

$3

Attach custom data to tasks for UI rendering:

`ts
interface TaskMeta {
filename: string
size: number
}

const queue = useQueue()

queue.add(
() => uploadFile(file),
{ filename: file.name, size: file.size }
)
`

`vue

`

$3

`ts
const queue = useQueue({
onSuccess(task) {
console.log('Task completed:', task.result)
},
onError(task, error) {
console.error('Task failed:', error)
},
onFinished() {
console.log('All tasks done!')
},
})
`

$3

`ts
// Only keep the last 10 completed tasks
const queue = useQueue({ maxHistory: 10 })

// Keep no history (only pending/running tasks visible)
const queue = useQueue({ maxHistory: 0 })
`

$3

`ts
const queue = useQueue()

queue.add(() => task1())
queue.add(() => task2())
queue.add(() => task3())

await queue.waitForIdle()
console.log('All tasks completed!')
`

$3

`ts
import { ref } from 'vue'

const limit = ref(2)
const queue = useQueue({ concurrency: limit })

// Reactively update concurrency
limit.value = 5

// Or use setConcurrency
queue.setConcurrency(10)
`

Type Declarations

`ts
export interface QueueTask {
readonly id: number
status: 'pending' | 'running' | 'fulfilled' | 'rejected'
readonly createdAt: number
startedAt?: number
finishedAt?: number
result?: T
error?: unknown
readonly meta?: M
}

export interface QueueStats {
readonly pending: number
readonly running: number
readonly completed: number
readonly failed: number
readonly total: number
readonly isIdle: boolean
readonly isPaused: boolean
}

export interface UseQueueOptions {
concurrency?: MaybeRefOrGetter // default: 1
immediate?: boolean // default: true
maxHistory?: number // default: undefined (keep all)
onSuccess?: (task: QueueTask) => void
onError?: (task: QueueTask, error: unknown) => void
onFinished?: () => void
}

export interface UseQueueReturn {
tasks: Readonly[]>>
stats: ComputedRef
concurrency: Readonly>
add: (fn: () => T | Promise, meta?: M) => { id: number; task: QueueTask; promise: Promise }
start: (id: number) => Promise | undefined
retry: (id: number) => RetryResult
remove: (id: number) => boolean
clear: () => void
pause: () => void
resume: () => void
setConcurrency: (value: number) => void
waitForIdle: () => Promise
}
``

License

MIT