The Queue Utility

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

• Motivation
• Installation
• Usage
• API
  • queue = new Queue(priority)
  • priorities
  • queue.add(fn)
  • queue.delete(fn)
  • boolean = queue.has(fn)
  • queue.clear()
  • queue.process()
  • queue.start()
  • queue.stop()
  • promise = queue.processing()
• Alternative builds
• Contributing

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.

• priorities.SYNC: Tasks are executed right away synchronously.
• priorities.CRITICAL: Tasks are executed ASAP (always before the next repaint in the browser).
• priorities.HIGH: Tasks are executed when there is free time and no more pending critical tasks.
• priorities.LOW: Tasks are executed when there is free time and no more pending critical or high prio tasks.

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.

• @nx-js/queue-util/dist/es.es6.js exposes an ES6 build with ES6 modules.
• @nx-js/queue-util/dist/es.es5.js exposes an ES5 build with ES6 modules.
• @nx-js/queue-util/dist/cjs.es6.js exposes an ES6 build with commonJS modules.
• @nx-js/queue-util/dist/cjs.es5.js exposes an ES5 build with commonJS modules.

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!