grouped-queue/lib/queue.js

In memory queue system prioritizing tasks

"use strict";
var util = require("util");
var events = require("events");
var SubQueue = require("./subqueue");

module.exports = Queue;

/**
 * Queue constructor
 * @param {String[]} [subQueue] The order of the sub-queues. First one will be runned first.
 */

function Queue(subQueues, runOnAdd = true) {
  subQueues = subQueues || [];
  if (!subQueues.includes("default")) {
    subQueues = subQueues.concat(["default"]);
  }
  subQueues = Array.from(new Set(subQueues));

  this.queueNames = subQueues;
  this.__queues__ = {};
  this.runOnAdd = runOnAdd;

  subQueues.forEach(
    function (name) {
      this.__queues__[name] = new SubQueue();
    }.bind(this),
  );
}

util.inherits(Queue, events.EventEmitter);

/**
 * Create a new sub-queue.
 * @param {String}   name  The sub-queue to create
 * @param {String}   [before]  Add the new sub-queue before the this sub-queue.
 *                             Otherwise the new sub-queue will be added last.
 */

Queue.prototype.addSubQueue = function (name, before) {
  if (this.__queues__[name]) {
    // Sub-queue already exists
    return;
  }

  if (!before) {
    // Add at last place.
    this.queueNames.push(name);
    this.__queues__[name] = new SubQueue();
    return;
  }

  if (!this.__queues__[before] || this.queueNames.indexOf(before) === -1) {
    throw new Error("sub-queue " + before + " not found");
  }

  // Add new sub-queue into the array.
  this.queueNames.splice(this.queueNames.indexOf(before), 0, name);
  this.__queues__[name] = new SubQueue();
};

/**
 * Add a task to a queue.
 * @param {String}   [name='default']  The sub-queue to append the task
 * @param {Function} task
 * @param {Object}   [opt]             Options hash
 * @param {String}   [opt.once]        If a task with the same `once` value is inside the
 *                                     queue, don't add this task.
 * @param {Boolean}  [opt.run]         If `run` is false, don't run the task.
 */

Queue.prototype.add = function (name, task, opt) {
  if (typeof name !== "string") {
    opt = task;
    task = name;
    name = "default";
  }

  this.__queues__[name].push(task, opt);

  // don't run the tasks if `opt.run` is false
  var run = (opt || {}).run;
  run = run === undefined ? this.runOnAdd : run;
  if (!run) return;
  this.start();
};

/**
 * Schedule run() to be executed.
 */

Queue.prototype.start = function () {
  if (this.running) return;

  setImmediate(this.run.bind(this));
};

/**
 * Start emptying the queues
 * Tasks are always run from the higher priority queue down to the lowest. After each
 * task complete, the process is re-runned from the first queue until a task is found.
 *
 * Tasks are passed a `callback` method which should be called once the task is over.
 */

Queue.prototype.run = function () {
  if (this.running) return;

  this.running = true;
  this._exec(
    function () {
      this.running = false;
      if (
        Object.values(this.__queues__).find(
          (queue) => queue.__queue__.length > 0,
        ) === undefined
      ) {
        this.emit("end");
      } else {
        this.emit("paused");
      }
    }.bind(this),
    function (error) {
      this.running = false;
      if (error) {
        this.emit("error", error);
      } else {
        this.running = false;
        this.emit("paused");
      }
    }.bind(this),
  );
};

/**
 * Pause the queue
 */

Queue.prototype.pause = function () {
  this.running = false;
};

Queue.prototype._exec = function (done, stop) {
  var pointer = -1;
  var names = this.queueNames;

  var next = function next() {
    if (!this.running) return done();

    pointer++;
    if (pointer >= names.length) return done();
    this.__queues__[names[pointer]].run(
      next.bind(this),
      this._exec.bind(this, done, stop),
      stop,
    );
  }.bind(this);

  next();
};