Home

Awesome

The Queue Utility

Priority based task scheduling for splitting up heavy work :muscle:

Build Coverage Status JavaScript Style Guide Package size Version dependencies Status License

<details> <summary><strong>Table of Contents</strong></summary> <!-- Do not edit the Table of Contents, instead regenerate with `npm run build-toc` --> <!-- toc --> <!-- tocstop --> </details>

Motivation

Deciding what code to execute next is not an easy decision. Users expect a lot to happen simultaneously - like networking, view updates and smooth animations. The Queue Utility automatically schedules your tasks by priorities, but also lets you control them manually - when the need arises.

Installation

$ npm install @nx-js/queue-util

Usage

Functions can added to queues, which execute them in an order based on their priority. Queues are created by passing a priority level to the Queue constructor.

import { Queue, priorities } from '@nx-js/queue-util'

const queue = new Queue(priorities.LOW)
const criticalQueue = new Queue(priorities.CRITICAL)

// 'Hello World' will be logged when the process has some free time
queue.add(() => console.log('Hello World'))
// 'EMERGENCY!' will be logged ASAP (before 'Hello World')
criticalQueue.add(() => console.log('EMERGENCY!'))

API

queue = new Queue(priority)

Queue instances can be created with the Queue constructor. The constructor requires a single priority as argument.

priorities

The following priorities are exported on the priorities object.

queue.add(fn)

Adds the passed function as a pending task to the queue. Adding the same task multiple times to a queue will only add it once.

queue.delete(fn)

Deletes the passed function from the queue.

boolean = queue.has(fn)

Returns a boolean, which indicates if the passed function is in the queue or not.

queue.clear()

Clears every task from the queue without executing them.

queue.process()

Executes every task in the queue, then clears the queue.

queue.stop()

Stops the automatic task execution of the queue.

queue.start()

Starts the - priority based - automatic task execution of the queue. The queue is automatically started after creation.

promise = queue.processing()

Returns a promise, which resolves after all of the current tasks in the queue are executed. If the queue is empty, it resolves immediately.

Alternative builds

This library detects if you use ES6 or commonJS modules and serve the right format to you. The exposed bundles are transpiled to ES5 to support common tools - like UglifyJS minifying. If you would like a finer control over the provided build, you can specify them in your imports.

If you use a bundler, set up an alias for @nx-js/queue-util to point to your desired build. You can learn how to do it with webpack here and with rollup here.

Contributing

Contributions are always welcomed! Just send a PR for fixes and doc updates and open issues for new features beforehand. Make sure that the tests and the linter pass and that the coverage remains high. Thanks!