qask

Queue tasks to run in intervals sequentially with fixed concurrency. Useful for ratelimiting API requests and the such.

Usage no npm install needed!

<script type="module">
  import qask from 'https://cdn.skypack.dev/qask';
</script>

README

qask

Queue tasks to run in intervals sequentially with fixed concurrency. Useful for ratelimiting API requests and the such.

Small and has no dependencies, for node and the browser.

Usage

import { Queue } from "qask";

async function main () {

    const queue = Queue({ interval: 1000, concurrency: 1, autoStart: true });

    // elsewhere
    const companies = await queue.add(
        () => fetch(`https://example.com/api/v1/companies`));
    
    // elsewhere
    const users = await queue.add(
        () => fetch(`https://example.com/api/v1/users`));
    
    // elsewhere
    const clicks = await queue.add(
        () => fetch(`https://example.com/api/v1/clicks`));
    
    // elsewhere
    const reads = await queue.add(
        () => fetch(`https://example.com/api/v1/reads`));

    // All these functions are queued to run at a maximum of 1 per second
}

main();

API

Queue ({ interval, concurrency, autoStart })

Queue factory. Creates a new queue instance.

Params

  • interval (number, default: 0) milliseconds to wait after each cycle
  • concurrency (number, default: 1) number of items to process each cycle
  • autoStart (boolean, default: false) whether to start queue immediately on first push

queue.add (fn)

Add a function to the queue and returns a Promise of return type of fn. Call without params to create a wait function that will resolve when picked from queue if you simply want to lock and take control.

Note: if your function throws an error, .add() will reject, but queue will continue to process. Remember to handle your errors with try await / catch or .catch().

queue.addAll ([...fns])

Adds all functions to queue. If any of the functions throw or reject, .addAll() will reject. However, if all functions resolve, the returned Promise will resolve to an array of values. All other semantics are identical to .add().

queue.start ()

Starts the queue. No-op if queue is already running.

queue.pause ()

Pauses queue execution. Any processes already started will continue, new tasks will not be picked until .start() is called. No-op if queue is already paused.

queue.clear ()

Clears the queue. Queue is not paused, and will continue to try and pick tasks.

queue.cancel ()

Clears the queue and stops taking tasks. Any processes already started will continue.

queue.on (event, listener)

Adds an eventlistener to specified event.

Params

  • event (string) One of "start", "next", "drain", "pause", "clear", "cancel"
  • listener (function) Takes a context object, refer to TS types.

queue.off (event, listener)

Removes an eventlistener to specified event.

Params

  • event (string) One of "start", "next", "drain", "pause", "clear", "cancel"
  • listener (function) Takes a context object, refer to TS types.

queue.interval

(number)

Interval passed via Queue factory. Assign to this prop to modify.

queue.concurrency

(number)

Concurrency passed via Queue factory. Assign to this prop to modify.

queue.size (getter)

(number)

Gets the remaining size of the queue at any point. Cannot be assigned to.

queue.pending (getter)

(number)

Gets the tasks that were started from the queue but pending completion. Cannot be assigned to.

queue.hasStarted (getter)

(boolean)

Returns true if queue has started. Cannot be assigned to.

queue.isEmpty (getter)

(boolean)

Returns true if queue is empty. Cannot be assigned to.

queue.isPaused (getter)

(boolean)

Returns true if queue is paused. Cannot be assigned to.

Credits

Originally started as a gist based on a question by @darvesh with inputs from @TRGWII.