ts-async-queue
A simple async-await task queue written in TypeScript
npm i -S ts-async-queue
What is it?
This is just a simple library for fail-safe async task execution, written in TypeScript. It utilizes OOP principles and TypeScript for painless management of complex task queues and easy extendability.
Unlike many similar libraries for working with async queues, this one behaves more like a "task-player" with start
, pause
, resume
and stop
functions. If you need execution concurrency or complex priority management - look elsewhere. Here you can simply enqueue, dequeue, start, stop, pause and resume in just 2KB of minified code. So if you need simplicity and small package - this is your choice.
Installation options
ts-async-queue
comes with a couple of installation options:
format-name | exports | description |
---|---|---|
es5 | named | Contains an es5-compatible version of ts-async-queue |
es | named | ES6+-compatible version |
esnext | named | ES7+ version with non-transpiled async-awaits |
iife | tsQueue object |
Creates a global variable tsQueue containing the exports. window-only. |
umd | tsQueue object |
Same as iife , but also works for node. |
The dist
folder contains multiple files with names in a following format:
/dist/ts-async-queue.{format-name}.js
, where {format-name}
is a format name from the table.
Named imports
// ES5/CommonJSconst TaskQueue QueueError = ; // If the first one does not work in your environment:const TaskQueue QueueError = ; // ES6+/TypeScript;; // ES6-only; // ES7+ only
Script imports
<!-- IIFE --> <!-- For specific versions of the library -->
Library exports
ts-async-queue
has 2 named exports: TaskQueue
and QueueError
:
const TaskQueue QueueError = ;
;
TaskQueue
Manages a queue of async tasks
See type declaration for more details
Initilize queue and manage tasks:
// Task is a simple function that recieves 0 arguments and returns a promise:const task1 = Promise;const task2 = Promise;const task3 = Promise; // Initialize an empty task queue:const queue = ; // and enqueue tasks of your choice (one or more):queue; // -> queue contains [task1, task2, task3] // or dequeue them // by indexqueue; // -> returns task2; queue contains [task1, task3] // by task referencequeue; // -> returns task1; queue contains [task3] // or simply pop the last onequeue; // dequeues the last task in; queue is empty now.queue; // same as previous // Or initialize a task queue with default tasks:const queueWithElements = task1 task2 task3; // Clear all tasks at oncequeueWithElementsclear; // -> queue is empty now ([]).
queue.start()
Starts task queue execution. Returns currenlty executed queue if execution already started.
const queue = task1 task2 task3; /** Start the queue with * TaskQueue.start(): */ // You can start a queue by calling the `start` function that returns a promise:const endOfQueueExecution = queuestart; // endOfQueueExecution is resolved as soon as the queue has finished executing all tasks,// it always resolves to the array of task results in order of their execution:endOfQueueExecution; // If you don't care about results, you can also simply await the `start()`:await queuestart; // does the exact same procedure as the previous time// .. do here whatever you want to do after the tasks stop executing // If one execution is not enough, you can always restart:queuestart;
queue.stop()
Stops queue execution and clears results.
/** Stop the queue with * TaskQueue.stop(): */ // You can stop the queue execution at any task:const stopped = queue; // The `stopped` promise resolves as soon as the queue stops executing:stopped;
queue.pause()
Pauses the queue's execution flow after a nearest task is completed. Returns a promise that resolves as soon as the queue is paused
queuestart; /** Pause the queue with * TaskQueue.pause(): */ // Pause resolves to results of tasks executed before the execution has been pausedconst results = await queueconst amountOfTasksExecuted = resultslength;
queue.resume()
Resumes a previously paused queue. Returns a promise that resolves as soon as the queue is completed
/** Resume the queue with * TaskQueue.resume(): */ const results = await queue; console; // -> ['task1', 'task2', 'task3']
Instance properties
name | type | description |
---|---|---|
isRunning |
boolean |
true if the queue is currently executing |
length |
number |
Amount of tasks in the queue |
last |
Task |
The last task added to the queue |
peek() |
Task |
A method alias for last |
lastResults |
Array |
An array of results captured from the last queue execution |
currentTaskIndex |
number |
A task index at which the queue is currently running |
currentRunningTask |
Task |
A task which is currently running in the queue |
QueueError
A simple error class that is raised if the queue encountered an error in a currently running task
Properties:
name | type | description |
---|---|---|
message |
string |
An error message text |
queue |
TaskQueue |
The queue instance error is raised from |
data |
any |
Internal error data |
stack |
string |
Error stack trace |
failedTask |
Task |
The task at which the queue has failed |
failedTaskIndex |
number |
An index of the task at which the queue has failed |
Usage example
const queue1 = Promise Promise; const queue2 = Promise // This one rejects the promise, causing an exception to be thrown, Promise; try await queue1start; await queue2start; catch e console; // -> true console; // -> Queue paused at task #1 due to error in handler () => Promise.reject('task1')