collect-your-stuff 1.4.0 → 2.1.0

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

@@ -0,0 +1,68 @@
+/**
+ * @file task queue
+ * @author Joshua Heagle <joshuaheagle@gmail.com>
+ * @version 1.1.0
+ * @memberOf module:collect-your-stuff
+ */
+import { Queueable } from './Queueable';
+import { IsArrayable } from '../../recipes/IsArrayable';
+import { IsLinker } from '../../recipes/IsLinker';
+import { completeResponse } from '../../recipes/Runnable';
+/**
+ * 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.
+ */
+export declare class TaskQueue {
+    /** The list which stores the queueables, the first is next to be dequeued. */
+    queuedList: IsArrayable<any>;
+    private listClass;
+    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.
+     */
+    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
+     */
+    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}
+     */
+    static fromArray: (values?: Array<any>, queueableClass?: typeof Queueable, listClass?: any) => TaskQueue;
+}

package/dist/collections/queue/TaskQueue.js

@@ -0,0 +1,137 @@
+'use strict'
+
+Object.defineProperty(exports, '__esModule', {
+  value: true
+})
+exports.TaskQueue = void 0
+var _Queueable = require('./Queueable')
+var _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)
+}

package/dist/collections/queue/TaskQueue.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.TaskQueue=void 0;var _Queueable=require("./Queueable"),_LinkedList=require("../linked-list/LinkedList");class TaskQueue{constructor(e=null,u=_LinkedList.LinkedList,s=_Queueable.Queueable){this.listClass=u,this.queueableClass=s,null===e&&(e=new u(s)),this.queuedList=e}dequeue(){let e=this.remove();for(;e&&e.complete;)e=this.remove();return e?e.running?{success:!1,error:"The queue has been blocked by an unfinished task.",context:e}:e.isReady?(this.empty()||this.enqueue(e),e.run.call(e)):(this.enqueue(e),{success:!1,error:"Unable to find ready task.",context:e}):{success:"No more queueable tasks in the queue",error:!1,context:this.queuedList}}empty(){return this.size()<=0}enqueue(e){this.queuedList.append(e)}peek(){return this.queuedList.first}remove(){return this.empty()?null:this.queuedList.remove(this.queuedList.first)}size(){return this.queuedList.length}}exports.TaskQueue=TaskQueue,TaskQueue.fromArray=(e=[],u=_Queueable.Queueable,s=_LinkedList.LinkedList)=>{const t=new s(u);return t.initialize(u.fromArray(e,u).head),new TaskQueue(t,s,u)};

package/dist/collections/stack/Stack.d.ts

@@ -1,64 +1,64 @@
-/**
- * @file stack.
- * @author Joshua Heagle <joshuaheagle@gmail.com>
- * @version 1.0.0
- * @memberOf module:collect-your-stuff
- */
-import { Stackable } from './Stackable';
+import { Linker } from '../linked-list/Linker';
 import { IsArrayable } from '../../recipes/IsArrayable';
-import { IsLinker } from '../../recipes/IsLinker';
-import { completeResponse } from '../../recipes/Runnable';
+import { IsStack } from '../../recipes/IsStack';
 /**
- * Store a collection of items which can only be inserted and removed from the top.
+ * A last-in-first-out collection: items are added to the top with push and taken from the top with pop. Any value can
+ * be stacked (it is stored as it is, whether it is a function, an object or null), and adding and taking are constant
+ * time. To stack tasks which are run as they are taken use TaskStack.
  */
-export declare class Stack {
-    /** The list which stores the stackables, the first is the top of the stack. */
+export declare class Stack<T = any> implements IsStack<T>, Iterable<T> {
+    /** The list which stores the stacked items, the first is the top of the stack. */
     stackedList: IsArrayable<any>;
-    private listClass;
-    private stackableClass;
+    private readonly linkerClass;
     /**
-     * Instantiate the state with the starter stacked list.
-     * @param {Iterable|LinkedList} [stackedList=null] The list of stackables to start in this stack.
-     * @param {IsArrayable} [listClass=LinkedList] The type of list to create when no stacked list is given.
-     * @param {Stackable} [stackableClass=Stackable] The class used to wrap stacked items.
+     * Instantiate the stack, optionally with a list of items to start from.
+     * @param {IsArrayable|null} [stackedList=null] The list of linkers to start in this stack (the first is the top)
+     * @param {IsArrayable} [listClass=LinkedList] The type of list to create when no stacked list is given
+     * @param {Linker} [linkerClass=Linker] The class used to hold each stacked item
      */
-    constructor(stackedList?: IsArrayable<any>, listClass?: any, stackableClass?: typeof Stackable);
+    constructor(stackedList?: IsArrayable<any> | null, listClass?: any, linkerClass?: typeof Linker);
     /**
-     * Return true if the stack is empty (there are no tasks in the stacked list)
+     * Check whether the stack has no items.
      * @return {boolean}
      */
     empty(): boolean;
     /**
-     * Take a look at the next stacked task
-     * @return {Stackable}
-     */
-    top(): IsLinker;
-    /**
-     * Remove the next stacked task and return it.
-     * @return {Stackable|null}
+     * Look at the item on the top of the stack, without removing it.
+     * @return {*|null} The item, or null when the stack is empty
      */
-    pop(): Stackable | completeResponse | null;
+    peek(): T | null;
     /**
-     * Push a stackable task to the top of the stack.
-     * @param {Stackable|*} stackable Add a new stackable to the top of the stack
+     * Take the item from the top of the stack.
+     * @return {*|null} The item, or null when the stack is empty
      */
-    push(stackable: any): void;
+    pop(): T | null;
     /**
-     * Remove the next stacked task and return it.
-     * @return {Stackable|null}
+     * Add an item to the top of the stack.
+     * @param {*} data The item to add
+     * @return {Stack} This stack, so that adding can be chained
      */
-    remove(): Stackable | null;
+    push(data: T): this;
     /**
-     * Get the size of the current stack.
+     * Count the items in the stack.
      * @return {number}
      */
     size(): number;
     /**
-     * Convert an array to a Stack.
-     * @param {Array} values An array of values which will be converted to stackables in this queue
-     * @param {Stackable} stackableClass The class to use for each stackable
-     * @param {Stack|Iterable} listClass The class to use to manage the stackables
+     * The item on the top of the stack (the same as peek).
+     * @return {*|null} The item, or null when the stack is empty
+     */
+    top(): T | null;
+    /**
+     * Iterate over the items from the top of the stack to the bottom, without removing them.
+     * @return {Iterator}
+     */
+    [Symbol.iterator](): Iterator<T>;
+    /**
+     * Convert an array to a Stack by pushing each value in turn, so the last value is on the top.
+     * @param {Array} [values=[]] The items to stack
+     * @param {IsArrayable} [listClass=LinkedList] The type of list used to store the items
+     * @param {Linker} [linkerClass=Linker] The class used to hold each stacked item
      * @returns {Stack}
      */
-    static fromArray: (values?: Array<any>, stackableClass?: typeof Stackable, listClass?: any) => Stack;
+    static fromArray: <T_1 = any>(values?: Array<T_1>, listClass?: any, linkerClass?: typeof Linker) => Stack<T_1>;
 }

package/dist/collections/stack/Stack.js

@@ -4,36 +4,36 @@ Object.defineProperty(exports, '__esModule', {
   value: true
 })
 exports.Stack = void 0
-var _Stackable = require('./Stackable')
+require('core-js/modules/esnext.iterator.constructor.js')
+require('core-js/modules/esnext.iterator.for-each.js')
 var _LinkedList = require('../linked-list/LinkedList')
+var _Linker = require('../linked-list/Linker')
 /**
  * @file stack.
  * @author Joshua Heagle <joshuaheagle@gmail.com>
- * @version 1.0.0
+ * @version 2.0.0
  * @memberOf module:collect-your-stuff
  */
 
 /**
- * Store a collection of items which can only be inserted and removed from the top.
+ * A last-in-first-out collection: items are added to the top with push and taken from the top with pop. Any value can
+ * be stacked (it is stored as it is, whether it is a function, an object or null), and adding and taking are constant
+ * time. To stack tasks which are run as they are taken use TaskStack.
  */
 class Stack {
   /**
-   * Instantiate the state with the starter stacked list.
-   * @param {Iterable|LinkedList} [stackedList=null] The list of stackables to start in this stack.
-   * @param {IsArrayable} [listClass=LinkedList] The type of list to create when no stacked list is given.
-   * @param {Stackable} [stackableClass=Stackable] The class used to wrap stacked items.
+   * Instantiate the stack, optionally with a list of items to start from.
+   * @param {IsArrayable|null} [stackedList=null] The list of linkers to start in this stack (the first is the top)
+   * @param {IsArrayable} [listClass=LinkedList] The type of list to create when no stacked list is given
+   * @param {Linker} [linkerClass=Linker] The class used to hold each stacked item
    */
-  constructor (stackedList = null, listClass = _LinkedList.LinkedList, stackableClass = _Stackable.Stackable) {
-    this.listClass = listClass
-    this.stackableClass = stackableClass
-    if (stackedList === null) {
-      stackedList = new listClass(stackableClass)
-    }
-    this.stackedList = stackedList
+  constructor (stackedList = null, listClass = _LinkedList.LinkedList, linkerClass = _Linker.Linker) {
+    this.linkerClass = linkerClass
+    this.stackedList = stackedList === null ? new listClass(linkerClass) : stackedList
   }
 
   /**
-   * Return true if the stack is empty (there are no tasks in the stacked list)
+   * Check whether the stack has no items.
    * @return {boolean}
    */
   empty () {
@@ -41,66 +41,87 @@ class Stack {
   }
 
   /**
-   * Take a look at the next stacked task
-   * @return {Stackable}
+   * Look at the item on the top of the stack, without removing it.
+   * @return {*|null} The item, or null when the stack is empty
    */
-  top () {
-    return this.stackedList.first
+  peek () {
+    const top = this.stackedList.first
+    return top === null || typeof top === 'undefined' ? null : top.data
   }
 
   /**
-   * Remove the next stacked task and return it.
-   * @return {Stackable|null}
+   * Take the item from the top of the stack.
+   * @return {*|null} The item, or null when the stack is empty
    */
   pop () {
-    const next = this.remove()
-    if (!next) {
-      return {
-        success: 'No more stackable tasks in the stack',
-        error: false,
-        context: this.stackedList
-      }
+    const top = this.stackedList.first
+    if (top === null || typeof top === 'undefined') {
+      return null
     }
-    return next.run()
+    this.stackedList.remove(top)
+    return top.data
   }
 
   /**
-   * Push a stackable task to the top of the stack.
-   * @param {Stackable|*} stackable Add a new stackable to the top of the stack
+   * Add an item to the top of the stack.
+   * @param {*} data The item to add
+   * @return {Stack} This stack, so that adding can be chained
    */
-  push (stackable) {
-    this.stackedList.prepend(stackable)
+  push (data) {
+    // The item is wrapped here rather than left to the list, since the list treats objects that look like a linker's
+    // settings (they have a data property) as such, and a stack must give back exactly what it was given
+    this.stackedList.prepend(new this.linkerClass({
+      data
+    }))
+    return this
   }
 
   /**
-   * Remove the next stacked task and return it.
-   * @return {Stackable|null}
+   * Count the items in the stack.
+   * @return {number}
    */
-  remove () {
-    if (this.empty()) {
-      return null
-    }
-    return this.stackedList.remove(this.stackedList.first)
+  size () {
+    return this.stackedList.length
   }
 
   /**
-   * Get the size of the current stack.
-   * @return {number}
+   * The item on the top of the stack (the same as peek).
+   * @return {*|null} The item, or null when the stack is empty
    */
-  size () {
-    return this.stackedList.length
+  top () {
+    return this.peek()
+  }
+
+  /**
+   * Iterate over the items from the top of the stack to the bottom, without removing them.
+   * @return {Iterator}
+   */
+  [Symbol.iterator] () {
+    const linkers = this.stackedList[Symbol.iterator]()
+    return {
+      next: () => {
+        const result = linkers.next()
+        return result.done ? {
+          done: true,
+          value: undefined
+        } : {
+          done: false,
+          value: result.value.data
+        }
+      }
+    }
   }
 }
 /**
- * Convert an array to a Stack.
- * @param {Array} values An array of values which will be converted to stackables in this queue
- * @param {Stackable} stackableClass The class to use for each stackable
- * @param {Stack|Iterable} listClass The class to use to manage the stackables
+ * Convert an array to a Stack by pushing each value in turn, so the last value is on the top.
+ * @param {Array} [values=[]] The items to stack
+ * @param {IsArrayable} [listClass=LinkedList] The type of list used to store the items
+ * @param {Linker} [linkerClass=Linker] The class used to hold each stacked item
  * @returns {Stack}
  */
 exports.Stack = Stack
-Stack.fromArray = (values = [], stackableClass = _Stackable.Stackable, listClass = _LinkedList.LinkedList) => {
-  const list = new listClass(stackableClass)
-  list.initialize(stackableClass.fromArray(values, stackableClass).head)
-  return new Stack(list, listClass, stackableClass)
+Stack.fromArray = (values = [], listClass = _LinkedList.LinkedList, linkerClass = _Linker.Linker) => {
+  const stack = new Stack(null, listClass, linkerClass)
+  values.forEach(value => stack.push(value))
+  return stack
 }

package/dist/collections/stack/Stack.min.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.Stack=void 0;var _Stackable=require("./Stackable"),_LinkedList=require("../linked-list/LinkedList");class Stack{constructor(t=null,e=_LinkedList.LinkedList,s=_Stackable.Stackable){this.listClass=e,this.stackableClass=s,null===t&&(t=new e(s)),this.stackedList=t}empty(){return this.size()<=0}top(){return this.stackedList.first}pop(){const t=this.remove();return t?t.run():{success:"No more stackable tasks in the stack",error:!1,context:this.stackedList}}push(t){this.stackedList.prepend(t)}remove(){return this.empty()?null:this.stackedList.remove(this.stackedList.first)}size(){return this.stackedList.length}}exports.Stack=Stack,Stack.fromArray=(t=[],e=_Stackable.Stackable,s=_LinkedList.LinkedList)=>{const i=new s(e);return i.initialize(e.fromArray(t,e).head),new Stack(i,s,e)};
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.Stack=void 0,require("core-js/modules/esnext.iterator.constructor.js"),require("core-js/modules/esnext.iterator.for-each.js");var _LinkedList=require("../linked-list/LinkedList"),_Linker=require("../linked-list/Linker");class Stack{constructor(e=null,t=_LinkedList.LinkedList,s=_Linker.Linker){this.linkerClass=s,this.stackedList=null===e?new t(s):e}empty(){return this.size()<=0}peek(){const e=this.stackedList.first;return null==e?null:e.data}pop(){const e=this.stackedList.first;return null==e?null:(this.stackedList.remove(e),e.data)}push(e){return this.stackedList.prepend(new this.linkerClass({data:e})),this}size(){return this.stackedList.length}top(){return this.peek()}[Symbol.iterator](){const e=this.stackedList[Symbol.iterator]();return{next:()=>{const t=e.next();return t.done?{done:!0,value:void 0}:{done:!1,value:t.value.data}}}}}exports.Stack=Stack,Stack.fromArray=(e=[],t=_LinkedList.LinkedList,s=_Linker.Linker)=>{const r=new Stack(null,t,s);return e.forEach((e=>r.push(e))),r};

package/dist/collections/stack/TaskStack.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @file task stack.
+ * @author Joshua Heagle <joshuaheagle@gmail.com>
+ * @version 1.0.0
+ * @memberOf module:collect-your-stuff
+ */
+import { Stackable } from './Stackable';
+import { IsArrayable } from '../../recipes/IsArrayable';
+import { IsLinker } from '../../recipes/IsLinker';
+import { completeResponse } from '../../recipes/Runnable';
+/**
+ * Store a collection of tasks (Stackables) which can only be inserted and removed from the top: pop() takes the task from
+ * the top and RUNS it. For a plain last-in-first-out collection of items use Stack.
+ */
+export declare class TaskStack {
+    /** The list which stores the stackables, the first is the top of the stack. */
+    stackedList: IsArrayable<any>;
+    private listClass;
+    private stackableClass;
+    /**
+     * Instantiate the state with the starter stacked list.
+     * @param {Iterable|LinkedList} [stackedList=null] The list of stackables to start in this stack.
+     * @param {IsArrayable} [listClass=LinkedList] The type of list to create when no stacked list is given.
+     * @param {Stackable} [stackableClass=Stackable] The class used to wrap stacked items.
+     */
+    constructor(stackedList?: IsArrayable<any>, listClass?: any, stackableClass?: typeof Stackable);
+    /**
+     * Return true if the stack is empty (there are no tasks in the stacked list)
+     * @return {boolean}
+     */
+    empty(): boolean;
+    /**
+     * Take a look at the next stacked task
+     * @return {Stackable}
+     */
+    top(): IsLinker;
+    /**
+     * Remove the next stacked task and return it.
+     * @return {Stackable|null}
+     */
+    pop(): Stackable | completeResponse | null;
+    /**
+     * Push a stackable task to the top of the stack.
+     * @param {Stackable|*} stackable Add a new stackable to the top of the stack
+     */
+    push(stackable: any): void;
+    /**
+     * Remove the next stacked task and return it.
+     * @return {Stackable|null}
+     */
+    remove(): Stackable | null;
+    /**
+     * Get the size of the current stack.
+     * @return {number}
+     */
+    size(): number;
+    /**
+     * Convert an array to a TaskStack.
+     * @param {Array} values An array of values which will be converted to stackables in this queue
+     * @param {Stackable} stackableClass The class to use for each stackable
+     * @param {TaskStack|Iterable} listClass The class to use to manage the stackables
+     * @returns {TaskStack}
+     */
+    static fromArray: (values?: Array<any>, stackableClass?: typeof Stackable, listClass?: any) => TaskStack;
+}