collect-your-stuff 2.1.2 → 2.2.0

package/dist/collections/queue/Queueable.js

@@ -1,148 +1,142 @@
-'use strict'
-
-Object.defineProperty(exports, '__esModule', {
-  value: true
-})
-exports.Queueable = void 0
-const _Linker = require('../linked-list/Linker')
-/**
- * Queueable represents a runnable entry in a queue.
- * @extends Linker
- */
-class Queueable {
-  /**
-   * Create a queueable item that can be used in a queue.
-   * @param {Object} [queueableData={}] The settings for the new queueable.
-   * @param {*} [queueableData.task=null] The data to be stored in this queueable
-   * @param {Queueable|null} [queueableData.next=null] The reference to the next queueable if any
-   * @param {boolean|Function} [queueableData.ready=false] Indicate if the queueable is ready to run
-   */
-  constructor ({
-    task = null,
-    next = null,
-    ready = false
-  } = {}) {
-    /** The task (or data) this queueable holds. */
-    this.data = null
-    /** The queueable after this one, or null when this is the last. */
-    this.next = null
-    /** Whether this queueable has been run to completion. */
-    this.complete = false
-    /** Whether this queueable may run, or a function which answers that when asked. */
-    this.ready = false
-    /** Whether this queueable is running right now. */
-    this.running = false
-    this.classType = Queueable
-    this.data = task
-    this.next = next
-    this.complete = false
-    this.ready = ready
-    this.running = false
-  }
-
-  /**
-   * Check ready state.
-   * @return {boolean}
-   */
-  get isReady () {
-    return typeof this.ready === 'function' ? this.ready() : this.ready
-  }
-
-  /**
-   * Retrieve the data which should be formed as a task.
-   * @return {*}
-   */
-  get task () {
-    if (typeof this.data === 'function') {
-      return this.data
-    }
-    return complete => typeof complete === 'function'
-      ? complete({
-        context: this.data
-      }).context
-      : this.data
-  }
-
-  /**
-   * Set this queueable as completed.
-   * @param {Object} [completeResponse={}] The result to report for the task.
-   * @param {*} [completeResponse.success=true] Indicate when the task failed (use false) or give a success message
-   * @param {*} [completeResponse.error=false] Indicate a task was error-free (use false) or give an error message
-   * @param {*} [completeResponse.context=null] Provide additional data in the response
-   * @return {completeResponse}
-   */
-  markCompleted ({
-    success = true,
-    error = false,
-    context = null
-  } = {}) {
-    this.complete = true
-    this.running = false
-    return {
-      success,
-      error,
-      context
-    }
-  }
-
-  /**
-   * Intend to run the queued task when it is ready. If ready, mark this task as running and run the task.
-   * @return {completeResponse}
-   */
-  run () {
-    if (!this.isReady) {
-      // Not yet ready, return with errors
-      return {
-        success: false,
-        error: 'Task is not ready',
-        context: this.data
-      }
-    }
-    if (this.running) {
-      // Already running, return error since we cannot run again
-      return {
-        success: false,
-        error: 'Queued task is already running, possible missing \'complete\' callback',
-        context: this.data
-      }
-    }
-    this.running = true
-    // Wrap the task in the markCompleted function, so we can set flags and format the response
-    return this.task(this.markCompleted.bind(this))
-  }
-}
-/**
- * Make a new Queueable from the data given if it is not already a valid Queueable.
- * @param {Queueable|*} queueable Return a valid Queueable instance from given data, or even an already valid one.
- * @param {IsLinker} [classType=Queueable] Provide the type of IsLinker to use.
- * @return {Queueable}
- */
-exports.Queueable = Queueable
-Queueable.make = (queueable, classType = Queueable) => {
-  if (queueable === null || typeof queueable !== 'object') {
-    // It is not an object (or it is null), so instantiate the Queueable with an element as the data
-    return new classType({
-      task: queueable,
-      ready: true
-    })
-  }
-  if (queueable.classType) {
-    // Already valid Queueable, return as-is
-    return queueable
-  }
-  if (!('task' in queueable)) {
-    queueable = {
-      task: queueable,
-      ready: true
-    }
-  }
-  // Create the new node as the configured #classType
-  return new classType(queueable)
-}
-/**
- * Convert an array into Queueable instances, return the head and tail Queueables.
- * @param {Array} values Provide an array of data that will be converted to a chain of queueable linkers.
- * @param {IsLinker} [classType=Queueable] Provide the type of IsLinker to use.
- * @returns {{head: Queueable, tail: Queueable}}
- */
-Queueable.fromArray = (values = [], classType = Queueable) => _Linker.Linker.fromArray(values, classType)
+'use strict'
+
+Object.defineProperty(exports, '__esModule', {
+  value: true
+})
+exports.Queueable = void 0
+const _Linker = require('../linked-list/Linker')
+/**
+ * Queueable represents a runnable entry in a queue.
+ * @extends Linker
+ */
+class Queueable {
+  /**
+   * Create a queueable item that can be used in a queue.
+   * @param queueableData The settings for the new queueable.
+   * @param queueableData.task The data to be stored in this queueable
+   * @param queueableData.next The reference to the next queueable if any
+   * @param queueableData.ready Indicate if the queueable is ready to run
+   */
+  constructor ({
+    task = null,
+    next = null,
+    ready = false
+  } = {}) {
+    /** The task (or data) this queueable holds. */
+    this.data = null
+    /** The queueable after this one, or null when this is the last. */
+    this.next = null
+    /** Whether this queueable has been run to completion. */
+    this.complete = false
+    /** Whether this queueable may run, or a function which answers that when asked. */
+    this.ready = false
+    /** Whether this queueable is running right now. */
+    this.running = false
+    this.classType = Queueable
+    this.data = task
+    this.next = next
+    this.complete = false
+    this.ready = ready
+    this.running = false
+  }
+
+  /**
+   * Check ready state.
+   */
+  get isReady () {
+    return typeof this.ready === 'function' ? this.ready() : this.ready
+  }
+
+  /**
+   * Retrieve the data which should be formed as a task.
+   */
+  get task () {
+    if (typeof this.data === 'function') {
+      return this.data
+    }
+    return complete => typeof complete === 'function'
+      ? complete({
+        context: this.data
+      }).context
+      : this.data
+  }
+
+  /**
+   * Set this queueable as completed.
+   * @param completeResponse The result to report for the task.
+   * @param completeResponse.success Indicate when the task failed (use false) or give a success message
+   * @param completeResponse.error Indicate a task was error-free (use false) or give an error message
+   * @param completeResponse.context Provide additional data in the response
+   */
+  markCompleted ({
+    success = true,
+    error = false,
+    context = null
+  } = {}) {
+    this.complete = true
+    this.running = false
+    return {
+      success,
+      error,
+      context
+    }
+  }
+
+  /**
+   * Intend to run the queued task when it is ready. If ready, mark this task as running and run the task.
+   */
+  run () {
+    if (!this.isReady) {
+      // Not yet ready, return with errors
+      return {
+        success: false,
+        error: 'Task is not ready',
+        context: this.data
+      }
+    }
+    if (this.running) {
+      // Already running, return error since we cannot run again
+      return {
+        success: false,
+        error: 'Queued task is already running, possible missing \'complete\' callback',
+        context: this.data
+      }
+    }
+    this.running = true
+    // Wrap the task in the markCompleted function, so we can set flags and format the response
+    return this.task(this.markCompleted.bind(this))
+  }
+}
+/**
+ * Make a new Queueable from the data given if it is not already a valid Queueable.
+ * @param queueable Return a valid Queueable instance from given data, or even an already valid one.
+ * @param classType Provide the type of IsLinker to use.
+ */
+exports.Queueable = Queueable
+Queueable.make = (queueable, classType = Queueable) => {
+  if (queueable === null || typeof queueable !== 'object') {
+    // It is not an object (or it is null), so instantiate the Queueable with an element as the data
+    return new classType({
+      task: queueable,
+      ready: true
+    })
+  }
+  if (queueable.classType) {
+    // Already valid Queueable, return as-is
+    return queueable
+  }
+  if (!('task' in queueable)) {
+    queueable = {
+      task: queueable,
+      ready: true
+    }
+  }
+  // Create the new node as the configured #classType
+  return new classType(queueable)
+}
+/**
+ * Convert an array into Queueable instances, return the head and tail Queueables.
+ * @param values Provide an array of data that will be converted to a chain of queueable linkers.
+ * @param classType Provide the type of IsLinker to use.
+ */
+Queueable.fromArray = (values = [], classType = Queueable) => _Linker.Linker.fromArray(values, classType)

package/dist/collections/queue/TaskQueue.d.ts

@@ -1,8 +1,5 @@
 /**
- * @file task queue
- * @author Joshua Heagle <joshuaheagle@gmail.com>
- * @version 1.1.0
- * @memberOf module:collect-your-stuff
+ * task queue
  */
 import { Queueable } from './Queueable';
 import { IsArrayable } from '../../recipes/IsArrayable';
@@ -20,49 +17,43 @@ export declare class TaskQueue {
     private queueableClass;
     /**
      * Instantiate the queue with the given queue list.
-     * @param {Iterable|LinkedList} queuedList Give the list of queueables to start in this queue.
-     * @param {IsArrayable} [listClass=LinkedList] The type of list to create when no queued list is given.
-     * @param {Queueable} [queueableClass=Queueable] The class used to wrap queued items.
+     * @param queuedList Give the list of queueables to start in this queue.
+     * @param listClass The type of list to create when no queued list is given.
+     * @param queueableClass The class used to wrap queued items.
      */
     constructor(queuedList?: IsArrayable<any>, listClass?: any, queueableClass?: typeof Queueable);
     /**
      * Take a queued task from the front of the queue and run it if ready. A task which is not ready yet is kept in the
      * queue (never dropped), a task which is still running is reported as blocking and left to finish on its own, and
      * completed tasks are discarded.
-     * @return {completeResponse|*}
      */
     dequeue(): completeResponse | any;
     /**
      * Return true if the queue is empty (there are no tasks in the queue list)
-     * @return {boolean}
      */
     empty(): boolean;
     /**
      * Add a queued task to the end of the queue
-     * @param {Queueable} queueable Add a new queueable to the end of the queue
+     * @param queueable Add a new queueable to the end of the queue
      */
     enqueue(queueable: Queueable): void;
     /**
      * Take a look at the next queued task
-     * @return {Queueable}
      */
     peek(): IsLinker;
     /**
      * Remove the next queued item and return it.
-     * @return {Queueable|null}
      */
     remove(): Queueable | null;
     /**
      * Get the length of the current queue.
-     * @return {number}
      */
     size(): number;
     /**
      * Convert an array to a TaskQueue.
-     * @param {Array} values An array of values which will be converted to queueables in this queue
-     * @param {Queueable} queueableClass The class to use for each queueable
-     * @param {TaskQueue|Iterable} listClass The class to use to manage the queueables
-     * @returns {TaskQueue}
+     * @param values An array of values which will be converted to queueables in this queue
+     * @param queueableClass The class to use for each queueable
+     * @param listClass The class to use to manage the queueables
      */
     static fromArray: (values?: Array<any>, queueableClass?: typeof Queueable, listClass?: any) => TaskQueue;
 }

package/dist/collections/queue/TaskQueue.js

@@ -1,137 +1,128 @@
-'use strict'
-
-Object.defineProperty(exports, '__esModule', {
-  value: true
-})
-exports.TaskQueue = void 0
-const _Queueable = require('./Queueable')
-const _LinkedList = require('../linked-list/LinkedList')
-/**
- * @file task queue
- * @author Joshua Heagle <joshuaheagle@gmail.com>
- * @version 1.1.0
- * @memberOf module:collect-your-stuff
- */
-
-/**
- * Maintain a series of queued tasks (Queueables): dequeue() takes the next task from the front and RUNS it, giving each
- * task in turn a chance to run (a task which is not ready, or which has not finished, is placed at the back again).
- * This is a task scheduler, for a plain first-in-first-out collection of items use Queue.
- */
-class TaskQueue {
-  /**
-   * Instantiate the queue with the given queue list.
-   * @param {Iterable|LinkedList} queuedList Give the list of queueables to start in this queue.
-   * @param {IsArrayable} [listClass=LinkedList] The type of list to create when no queued list is given.
-   * @param {Queueable} [queueableClass=Queueable] The class used to wrap queued items.
-   */
-  constructor (queuedList = null, listClass = _LinkedList.LinkedList, queueableClass = _Queueable.Queueable) {
-    this.listClass = listClass
-    this.queueableClass = queueableClass
-    if (queuedList === null) {
-      queuedList = new listClass(queueableClass)
-    }
-    this.queuedList = queuedList
-  }
-
-  /**
-   * Take a queued task from the front of the queue and run it if ready. A task which is not ready yet is kept in the
-   * queue (never dropped), a task which is still running is reported as blocking and left to finish on its own, and
-   * completed tasks are discarded.
-   * @return {completeResponse|*}
-   */
-  dequeue () {
-    let next = this.remove()
-    // Tasks which already completed are discarded when they reach the front of the queue
-    while (next && next.complete) {
-      next = this.remove()
-    }
-    if (!next) {
-      return {
-        success: 'No more queueable tasks in the queue',
-        error: false,
-        context: this.queuedList
-      }
-    }
-    if (next.running) {
-      // The unfinished task reports back through its own complete callback, so it is not kept in the queue
-      return {
-        success: false,
-        error: 'The queue has been blocked by an unfinished task.',
-        context: next
-      }
-    }
-    if (!next.isReady) {
-      // Keep the task (at the back, so the next dequeue can try the other tasks) rather than losing it
-      this.enqueue(next)
-      // We could go check the next in queue here but if we end up in a state where nothing is ready it would infinite loop
-      // Also, we want the loop handled externally
-      return {
-        success: false,
-        error: 'Unable to find ready task.',
-        context: next
-      }
-    }
-    if (!this.empty()) {
-      // Place back in queue to be checked once again next time, only if the queue will not be empty
-      this.enqueue(next)
-    }
-    return next.run.call(next)
-  }
-
-  /**
-   * Return true if the queue is empty (there are no tasks in the queue list)
-   * @return {boolean}
-   */
-  empty () {
-    return this.size() <= 0
-  }
-
-  /**
-   * Add a queued task to the end of the queue
-   * @param {Queueable} queueable Add a new queueable to the end of the queue
-   */
-  enqueue (queueable) {
-    this.queuedList.append(queueable)
-  }
-
-  /**
-   * Take a look at the next queued task
-   * @return {Queueable}
-   */
-  peek () {
-    return this.queuedList.first
-  }
-
-  /**
-   * Remove the next queued item and return it.
-   * @return {Queueable|null}
-   */
-  remove () {
-    if (this.empty()) {
-      return null
-    }
-    return this.queuedList.remove(this.queuedList.first)
-  }
-
-  /**
-   * Get the length of the current queue.
-   * @return {number}
-   */
-  size () {
-    return this.queuedList.length
-  }
-}
-/**
- * Convert an array to a TaskQueue.
- * @param {Array} values An array of values which will be converted to queueables in this queue
- * @param {Queueable} queueableClass The class to use for each queueable
- * @param {TaskQueue|Iterable} listClass The class to use to manage the queueables
- * @returns {TaskQueue}
- */
-exports.TaskQueue = TaskQueue
-TaskQueue.fromArray = (values = [], queueableClass = _Queueable.Queueable, listClass = _LinkedList.LinkedList) => {
-  const list = new listClass(queueableClass)
-  list.initialize(queueableClass.fromArray(values, queueableClass).head)
-  return new TaskQueue(list, listClass, queueableClass)
-}
+'use strict'
+
+Object.defineProperty(exports, '__esModule', {
+  value: true
+})
+exports.TaskQueue = void 0
+const _Queueable = require('./Queueable')
+const _LinkedList = require('../linked-list/LinkedList')
+/**
+ * task queue
+ */
+
+/**
+ * Maintain a series of queued tasks (Queueables): dequeue() takes the next task from the front and RUNS it, giving each
+ * task in turn a chance to run (a task which is not ready, or which has not finished, is placed at the back again).
+ * This is a task scheduler, for a plain first-in-first-out collection of items use Queue.
+ */
+class TaskQueue {
+  /**
+   * Instantiate the queue with the given queue list.
+   * @param queuedList Give the list of queueables to start in this queue.
+   * @param listClass The type of list to create when no queued list is given.
+   * @param queueableClass The class used to wrap queued items.
+   */
+  constructor (queuedList = null, listClass = _LinkedList.LinkedList, queueableClass = _Queueable.Queueable) {
+    this.listClass = listClass
+    this.queueableClass = queueableClass
+    if (queuedList === null) {
+      queuedList = new listClass(queueableClass)
+    }
+    this.queuedList = queuedList
+  }
+
+  /**
+   * Take a queued task from the front of the queue and run it if ready. A task which is not ready yet is kept in the
+   * queue (never dropped), a task which is still running is reported as blocking and left to finish on its own, and
+   * completed tasks are discarded.
+   */
+  dequeue () {
+    let next = this.remove()
+    // Tasks which already completed are discarded when they reach the front of the queue
+    while (next && next.complete) {
+      next = this.remove()
+    }
+    if (!next) {
+      return {
+        success: 'No more queueable tasks in the queue',
+        error: false,
+        context: this.queuedList
+      }
+    }
+    if (next.running) {
+      // The unfinished task reports back through its own complete callback, so it is not kept in the queue
+      return {
+        success: false,
+        error: 'The queue has been blocked by an unfinished task.',
+        context: next
+      }
+    }
+    if (!next.isReady) {
+      // Keep the task (at the back, so the next dequeue can try the other tasks) rather than losing it
+      this.enqueue(next)
+      // We could go check the next in queue here but if we end up in a state where nothing is ready it would infinite loop
+      // Also, we want the loop handled externally
+      return {
+        success: false,
+        error: 'Unable to find ready task.',
+        context: next
+      }
+    }
+    if (!this.empty()) {
+      // Place back in queue to be checked once again next time, only if the queue will not be empty
+      this.enqueue(next)
+    }
+    return next.run.call(next)
+  }
+
+  /**
+   * Return true if the queue is empty (there are no tasks in the queue list)
+   */
+  empty () {
+    return this.size() <= 0
+  }
+
+  /**
+   * Add a queued task to the end of the queue
+   * @param queueable Add a new queueable to the end of the queue
+   */
+  enqueue (queueable) {
+    this.queuedList.append(queueable)
+  }
+
+  /**
+   * Take a look at the next queued task
+   */
+  peek () {
+    return this.queuedList.first
+  }
+
+  /**
+   * Remove the next queued item and return it.
+   */
+  remove () {
+    if (this.empty()) {
+      return null
+    }
+    return this.queuedList.remove(this.queuedList.first)
+  }
+
+  /**
+   * Get the length of the current queue.
+   */
+  size () {
+    return this.queuedList.length
+  }
+}
+/**
+ * Convert an array to a TaskQueue.
+ * @param values An array of values which will be converted to queueables in this queue
+ * @param queueableClass The class to use for each queueable
+ * @param listClass The class to use to manage the queueables
+ */
+exports.TaskQueue = TaskQueue
+TaskQueue.fromArray = (values = [], queueableClass = _Queueable.Queueable, listClass = _LinkedList.LinkedList) => {
+  const list = new listClass(queueableClass)
+  list.initialize(queueableClass.fromArray(values, queueableClass).head)
+  return new TaskQueue(list, listClass, queueableClass)
+}