@xtia/async-queue NPM

async-queue

A lightweight but powerful asynchronous task queuing system, with smart task priority and configurable concurrency limit.

Basic Use:

npm i @xtia/async-queue

import { AsyncQueue } from "@xtia/async-queue";

// create a queue with default options
// (maxConcurrent = 1)
const queue = new AsyncQueue();

// enqueue a task with a Promise-like interface:
// (enqueuing methods return a promise that forwards the task's resolution)
const text = await queue.promise<Response>(resolve => {
    fetch(someUrl).then(resolve);
}).then(r => r.text());

// enqueue a task with a specific priority:
queue.promise(resolve => {
    someAsyncOperation().then(resolve);
}, 1);

As well as resolution, promise rejection is forwarded by enqueuing methods:

queue.promise((resolve, reject) => {
    fetch("doesntexist.lol").then(resolve, reject);
}).catch((err) => console.warn("fetch failed:", err));

`queue.createFunc()`

createFunc(fn, priority?) lets us easily convert asynchronous functions to identically-signed functions that place their behaviour in the queue.

const queue = new AsyncQueue({
    maxConcurrent: 3, // allow 3 notifications to be shown at a time
});

// we have a normal function to show a notification
function showNotification(level: "info" | "warning", message: string) {
    return new Promise(resolve => {
        // ... code to show notification
        // resolve when removed by click or timeout
    });
}

// wrap it so that its behaviour is queued when called
export const enqueueNotification = queue.createFunc(showNotification);

// function's signature is maintained, but calls are automatically enqueued:
enqueueNotification("info", "Download complete");

When wrapping the function, we can provide a priority for that function, or a function to determine a call's priority from its arguments:

// prioritise warnings
export const enqueueNotification = queue.createFunc(
    showNotification,
    (level, message) => level == "warning" ? 1 : 2
);

// wrap builtins, fixed priority
const enqueueFetch = queue.createFunc(fetch, 2);
const urgentFetch = queue.createFunc(fetch, 1);
// all type information is inherited from from fetch

`queue.enqueueFunc()`

enqueueFunc(fn, priority?) adds an asynchronous function to the queue without wrapping it with createFunc.

async function getData(url: string) {
    const response = await fetch(url);
    return await response.json();
}

const data = await queue.enqueueFunc(() => getData("data.json"));