DynamicQueue
A dynamic queue accepts new tasks at any moment and never stops running.
The API is for dynamic-queue 0.2.0+, old versions are deprecated.
Install
npm i dynamic-queue --save
Example
const { Queue } = require("dynamic-queue");
var outs = [];
// instantiate with a first task using normal function.
var queue = new Queue((next) => {
outs.push("Hello, World!");
next();
});
// push a new task.
queue.push((next) => {
outs.push("Hi, Ayon!");
next();
});
// push an AsyncFunction.
queue.push(async () => {
outs.push("Nice to meet you!");
});
queue.push(() => {
console.log(outs); // => ['Hello, World!', 'Hi, Ayon!', 'Nice to meet you!']
});
More examples, please visit here.
API
new Queue(task?: TaskFunction)
- type
TaskFunction
=(next?: () => void) => void | Promise<void> | Queue
- type
queue.length
Returns the length of waiting tasks.queue.state
The state of queue is eitherpending
(by default),paused
orstopped
.queue.isRunning
Whether the queue is running (state
is notstopped
).queue.push(task?: TaskFunction): this
Pushes a new task to the queue.queue.stop()
Stops the queue manually.queue.resume()
Continues running the queue after it has been stopped or hanged.queue.catch(handler: (err: any, resume?: () => void) => void)
Adds an error handler to catch any error occurred during running the task.
Notes
A queue is auto-started when it's instantiated, unless calling queue.stop()
,
otherwise the queue will continue running any task that pushed to internal
list.
The queue will be automatically closed when no more procedures are going to
run (generally before existing the program), you don't have to call
queue.stop()
normally.
When pushing a task, you can either pass or don't pass the next
argument. If
it's passed, you must call it manually. If it's omitted, the next task will be
called when the current one finishes running.
If you passed the next
argument and yet not calling it, then the queue will
hang and any left or new task will never run. You must call queue.resume()
if
you want the queue to continue running.
Nested Queues
This package allows you nest queues inside an existing one, similar to Promise
,
you just need to return a new Queue
inside one of the task function, and the
outer-queue will wait until all the remaining tasks in the inner-queue are
executed before continue running its own tasks. Just like this:
var queue = new Queue();
queue.push(() => {
console.log(1);
});
queue.push(() => {
var innerQueue = new Queue();
innerQueue.push(() => {
console.log(2);
});
innerQueue.push(() => {
console.log(3);
});
return innerQueue;
});
queue.push(() => {
console.log(4);
});
// the output sequence would be: 1, 2, 3, 4
Catch Errors
As mentioned above, you can catch any error occurred during the runtime.
var queue = new Queue();
queue.catch((err) => {
console.log(err.stack);
// `queue.state` is `paused`
queue.resume(); // continue running tasks
// `queue.state` will be `pending`
});
queue.push(() => {
throw new Error("this error will be caught");
});
queue.push(() => {
console.log("Hello, World!");
});
// The output sequence would be:
// => this error will be caught
// => Hello, World!
Warning
If an inner-queue throws an error and doesn't have a handler to catch it, the outer-queue's error handler will be copied into the inner one.
The queue will be paused if any error occurred, you can set an error handler via
queue.catch()
method, and call queue.resume()
to continue running tasks, or
call queue.stop()
to stop the queue completely.
Promises
When running asynchronous tasks, you can either pass and call the next
function, or push an async
function, or any function that returns a Promise
.
As a matter of fact, in TypeScript or babel, the async
function will be
converted to an ordinary function that returns a promise if the target ES
version doesn't support AsyncFunction.