GitHub
Open Github

UseQueue

Manage and process async task queues in React.

Installation

pnpm add @hookraft/usequeue

Usage

import { useQueue } from "@hookraft/usequeue"
const queue = useQueue({
  onProcess: async (item) => await sendEmail(item),
  onSuccess: (item) => toast.success(`Done: ${item.email}`),
  onError: (item, error) => toast.error(`Failed: ${item.email}`),
  onDone: () => toast.success("All done!"),
  concurrency: 1,
})

Full Example

function BulkEmailSender() {
  const queue = useQueue({
    onProcess: async (item) => await sendEmail(item.email),
    onSuccess: (item) => console.log(`Sent to ${item.email}`),
    onError: (item, err) => console.error(`Failed: ${item.email}`, err),
    onDone: () => console.log("All emails sent!"),
  })

  return (
    <div>
      <button onClick={() => queue.add({ email: "a@b.com" })}>Add Email</button>
      <button onClick={queue.start} disabled={queue.is("running")}>Start</button>
      <button onClick={queue.pause} disabled={!queue.is("running")}>Pause</button>
      <button onClick={queue.clear}>Clear</button>

      <p>Pending: {queue.pending.length}</p>
      <p>Processing: {queue.processing.length}</p>
      <p>Completed: {queue.completed.length}</p>
      <p>Failed: {queue.failed.length}</p>

      <Queue when={queue.status} onDone={() => console.log("rendered done state")}>
        <p>Queue is active</p>
      </Queue>
    </div>
  )
}

Options

PropTypeDefault
onProcess
(item: T) => Promise<void>
-
onSuccess
(item: T) => void
-
onError
(item: T, error: unknown) => void
-
onDone
() => void
-
concurrency
number
1

Returns

PropTypeDefault
status
QueueStatus
-
is(status)
(s: QueueStatus) => boolean
-
add(item)
(item: T) => string
-
start()
() => void
-
pause()
() => void
-
clear()
() => void
-
reset()
() => void
-
items
QueueItem<T>[]
-
pending
QueueItem<T>[]
-
processing
QueueItem<T>[]
-
completed
QueueItem<T>[]
-
failed
QueueItem<T>[]
-

Queue Component

The declarative JSX wrapper for queue states.

import { Queue } from "@hookraft/usequeue"
<Queue
  when={queue.status}
  onRunning={() => console.log("started")}
  onDone={() => console.log("finished")}
  fallback={<p>Queue is idle</p>}
>
  <p>Queue is active</p>
</Queue>

Props

PropTypeDefault
when
QueueStatus
-
onRunning
() => void
-
onPaused
() => void
-
onDone
() => void
-
onIdle
() => void
-
fallback
ReactNode
null
children
ReactNode
-