list-toolkit 2.1.1 → 2.2.0

package/README.md

@@ -15,7 +15,7 @@ The toolkit provides the following data structures with a full set of efficientl
   * Value-based lists, where a list serves as a container for external objects, and node-based lists, where a list uses custom properties on external objects to link them around.
   * Hosted lists, which use a special head node to manage nodes, and headless lists, which point to an external list without including any headers.
 * Heaps:
-  * Min-heap to support priority queues.
+  * Priority queues: min heap, leftist heap, skew heap.
 * Various list-based data structures:
   * Caches with various eviction algorithms: least recently used (LRU), least frequently used (LFU), first in first out (FIFO), and random.
     * A decorator is provided to decorate functions, methods, and getters with a cache of your choice.
@@ -146,6 +146,7 @@ BSD 3-Clause "New" or "Revised" License. See the LICENSE file for details.
 
 ## Release History
 
+* 2.2.0 *Added leftist and skew heaps.*
 * 2.1.1 *Allowed functions to be used as nodes. Updated deps.*
 * 2.1.0 *Added splay tree. Updated deps.*
 * 2.0.0 *New major release.*

package/cjs/heap/basics.js

@@ -0,0 +1,63 @@
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.HeapBase = void 0;
+var _metaUtils = require("../meta-utils.js");
+const defaultLess = (a, b) => a < b;
+const defaultEqual = (a, b) => a === b;
+class HeapBase {
+  constructor(options) {
+    (0, _metaUtils.copyOptions)(this, HeapBase.defaults, options);
+  }
+
+  // main methods
+  get isEmpty() {
+    throw new Error('Not implemented');
+  }
+  get top() {
+    throw new Error('Not implemented');
+  }
+  peek() {
+    return this.top;
+  }
+  pop() {
+    throw new Error('Not implemented');
+  }
+  push() {
+    throw new Error('Not implemented');
+  }
+  clear() {
+    throw new Error('Not implemented');
+  }
+
+  // performance methods
+  pushPop(value) {
+    this.push(value);
+    return this.pop();
+  }
+  replaceTop(value) {
+    const z = this.pop();
+    this.push(value);
+    return z;
+  }
+
+  // helper methods
+  merge(...args) {
+    throw new Error('Not implemented');
+  }
+  clone() {
+    throw new Error('Not implemented');
+  }
+  make(...args) {
+    return new this.constructor(this, ...args);
+  }
+}
+exports.HeapBase = HeapBase;
+HeapBase.defaults = {
+  less: defaultLess,
+  equal: defaultEqual,
+  compare: null
+};
+var _default = exports.default = HeapBase;

package/cjs/heap/leftist-heap.js

@@ -0,0 +1,124 @@
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.LeftistHeapNode = exports.LeftistHeap = void 0;
+var _basics = _interopRequireDefault(require("./basics.js"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const defaultLess = (a, b) => a < b;
+const merge = (a, b, less) => {
+  if (!a) return b;
+  if (!b) return a;
+  if (less(b.value, a.value)) [a, b] = [b, a]; // swap
+
+  a.right = merge(a.right, b, less);
+  if (!a.left) {
+    [a.left, a.right] = [a.right, a.left]; // swap
+    a.s = 1;
+    return a;
+  }
+  if (a.left.s < a.right.s) {
+    [a.left, a.right] = [a.right, a.left]; // swap
+  }
+  a.s = a.right.s + 1;
+  return a;
+};
+class LeftistHeapNode {
+  constructor(value) {
+    this.value = value;
+    this.right = this.left = null;
+    this.s = 1;
+  }
+  clear() {
+    this.left = this.right = null;
+    this.s = 1;
+  }
+  clone() {
+    const node = new LeftistHeapNode(this.value);
+    node.left = this.left && this.left.clone();
+    node.right = this.right && this.right.clone();
+    return node;
+  }
+}
+exports.LeftistHeapNode = LeftistHeapNode;
+class LeftistHeap extends _basics.default {
+  constructor(options, ...args) {
+    super(options);
+    if (typeof this.compare == 'function') {
+      this.less = (a, b) => this.compare(a, b) < 0;
+    }
+    this.root = null;
+    this.size = 0;
+    if (args.length) this.merge(...args);
+  }
+  get isEmpty() {
+    return !this.root;
+  }
+  get length() {
+    return this.size;
+  }
+  get top() {
+    return this.root ? this.root.value : undefined;
+  }
+  peek() {
+    return this.root ? this.root.value : undefined;
+  }
+  push(value) {
+    this.root = merge(this.root, new LeftistHeapNode(value), this.less);
+    ++this.size;
+    return this;
+  }
+  pop() {
+    if (!this.root) return;
+    const z = this.root;
+    this.root = merge(this.root.left, this.root.right, this.less);
+    --this.size;
+    return z.value;
+  }
+  pushPop(value) {
+    if (!this.root || this.less(value, this.root.value)) return value;
+    const z = this.root;
+    this.root = merge(z.left, new LeftistHeapNode(value), this.less);
+    this.root = merge(this.root, z.right, this.less);
+    return z.value;
+  }
+  replaceTop(value) {
+    if (!this.root) {
+      this.root = new LeftistHeapNode(value);
+      this.size = 1;
+      return; // undefined
+    }
+    const z = this.root;
+    this.root = merge(z.left, new LeftistHeapNode(value), this.less);
+    this.root = merge(this.root, z.right, this.less);
+    return z.value;
+  }
+  clear() {
+    this.root = null;
+    this.size = 0;
+    return this;
+  }
+  merge(...args) {
+    for (const other of args) {
+      this.root = merge(this.root, other.root, this.less);
+      this.size += other.size;
+      other.root = null;
+      other.size = 0;
+    }
+    return this;
+  }
+  clone() {
+    const heap = new LeftistHeap(this);
+    heap.root = this.root && this.root.clone();
+    heap.size = this.size;
+    return heap;
+  }
+  static from(array, options = _basics.default.defaults) {
+    const heap = new LeftistHeap(options);
+    for (const value of array) heap.push(value);
+    return heap;
+  }
+}
+exports.LeftistHeap = LeftistHeap;
+var _default = exports.default = LeftistHeap;

package/cjs/heap/min-heap.js

@@ -4,15 +4,14 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = exports.MinHeap = void 0;
-var _metaUtils = require("../meta-utils.js");
+var _basics = _interopRequireDefault(require("./basics.js"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 // the following functions are inlined:
 
 // const left = i => (i << 1) + 1;
 // const right = i => (i + 1) << 1;
 // const parent = i => (i - 1) >> 1;
 
-const defaultLess = (a, b) => a < b;
-const defaultEqual = (a, b) => a === b;
 const up = (array, i, less = defaultLess) => {
   for (let p = i - 1 >> 1; i > 0; i = p, p = i - 1 >> 1) {
     const iValue = array[i],
@@ -38,15 +37,15 @@ const down = (array, i, less = defaultLess, n = array.length) => {
   }
   return array;
 };
-class MinHeap {
+class MinHeap extends _basics.default {
   constructor(options, ...args) {
-    (0, _metaUtils.copyOptions)(this, MinHeap.defaults, options);
+    super(options);
     if (typeof this.compare == 'function') {
       this.less = (a, b) => this.compare(a, b) < 0;
       this.equal = (a, b) => !this.compare(a, b);
     }
     this.array = [];
-    this.merge(...args);
+    if (args.length) this.merge(...args);
   }
   get length() {
     return this.array.length;
@@ -191,9 +190,6 @@ class MinHeap {
     })), this.less);
     return this;
   }
-  make(...args) {
-    return new MinHeap(this, ...args);
-  }
   clone() {
     const heap = new MinHeap(this);
     heap.array = this.array.slice(0);
@@ -288,11 +284,11 @@ class MinHeap {
     }
     return heapArray;
   }
+  static from(array, options = MinHeap.defaults) {
+    const heap = new MinHeap(options);
+    heap.array = MinHeap.build(array, heap.less);
+    return heap;
+  }
 }
 exports.MinHeap = MinHeap;
-MinHeap.defaults = {
-  less: defaultLess,
-  equal: defaultEqual,
-  compare: null
-};
 var _default = exports.default = MinHeap;

package/cjs/heap/skew-heap.js

@@ -0,0 +1,114 @@
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.SkewHeapNode = exports.SkewHeap = void 0;
+var _basics = _interopRequireDefault(require("./basics.js"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const merge = (a, b, less) => {
+  if (!a) return b;
+  if (!b) return a;
+  if (less(b.value, a.value)) [a, b] = [b, a]; // swap
+
+  const temp = a.right;
+  a.right = a.left;
+  a.left = merge(b, temp, less);
+  return a;
+};
+class SkewHeapNode {
+  constructor(value) {
+    this.value = value;
+    this.right = this.left = null;
+  }
+  clear() {
+    this.left = this.right = null;
+  }
+  clone() {
+    const node = new SkewHeapNode(this.value);
+    node.left = this.left && this.left.clone();
+    node.right = this.right && this.right.clone();
+    return node;
+  }
+}
+exports.SkewHeapNode = SkewHeapNode;
+class SkewHeap extends _basics.default {
+  constructor(options, ...args) {
+    super(options);
+    if (typeof this.compare == 'function') {
+      this.less = (a, b) => this.compare(a, b) < 0;
+    }
+    this.root = null;
+    this.size = 0;
+    if (args.length) this.merge(...args);
+  }
+  get isEmpty() {
+    return !this.root;
+  }
+  get length() {
+    return this.size;
+  }
+  get top() {
+    return this.root ? this.root.value : undefined;
+  }
+  peek() {
+    return this.root ? this.root.value : undefined;
+  }
+  push(value) {
+    this.root = merge(this.root, new SkewHeapNode(value), this.less);
+    ++this.size;
+    return this;
+  }
+  pop() {
+    if (!this.root) return;
+    const z = this.root;
+    this.root = merge(this.root.left, this.root.right, this.less);
+    --this.size;
+    return z.value;
+  }
+  pushPop(value) {
+    if (!this.root || this.less(value, this.root.value)) return value;
+    const z = this.root;
+    this.root = merge(z.left, new SkewHeapNode(value), this.less);
+    this.root = merge(this.root, z.right, this.less);
+    return z.value;
+  }
+  replaceTop(value) {
+    if (!this.root) {
+      this.root = new SkewHeapNode(value);
+      this.size = 1;
+      return; // undefined
+    }
+    const z = this.root;
+    this.root = merge(z.left, new SkewHeapNode(value), this.less);
+    this.root = merge(this.root, z.right, this.less);
+    return z.value;
+  }
+  clear() {
+    this.root = null;
+    this.size = 0;
+    return this;
+  }
+  merge(...args) {
+    for (const other of args) {
+      this.root = merge(this.root, other.root, this.less);
+      this.size += other.size;
+      other.root = null;
+      other.size = 0;
+    }
+    return this;
+  }
+  clone() {
+    const heap = new SkewHeap(this);
+    heap.root = this.root && this.root.clone();
+    heap.size = this.size;
+    return heap;
+  }
+  static from(array, options = _basics.default.defaults) {
+    const heap = new SkewHeap(options);
+    for (const value of array) heap.push(value);
+    return heap;
+  }
+}
+exports.SkewHeap = SkewHeap;
+var _default = exports.default = SkewHeap;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "list-toolkit",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "List-based data structures to organize your objects.",
   "type": "module",
   "exports": {
@@ -31,6 +31,7 @@
     "data structures"
   ],
   "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (http://www.lazutkin.com/)",
+  "funding": "https://github.com/sponsors/uhop",
   "license": "BSD-3-Clause",
   "bugs": {
     "url": "https://github.com/uhop/list-toolkit/issues"
@@ -40,6 +41,7 @@
     "@babel/cli": "^7.25.6",
     "@babel/core": "^7.25.2",
     "@babel/preset-env": "^7.25.4",
+    "nano-benchmark": "^1.0.3",
     "tape-six": "^0.12.2"
   },
   "files": [

package/src/heap/basics.js

@@ -0,0 +1,58 @@
+'use strict';
+
+import {copyOptions} from '../meta-utils.js';
+
+const defaultLess = (a, b) => a < b;
+const defaultEqual = (a, b) => a === b;
+
+export class HeapBase {
+  constructor(options) {
+    copyOptions(this, HeapBase.defaults, options);
+  }
+
+  // main methods
+  get isEmpty() {
+    throw new Error('Not implemented');
+  }
+  get top() {
+    throw new Error('Not implemented');
+  }
+  peek() {
+    return this.top;
+  }
+  pop() {
+    throw new Error('Not implemented');
+  }
+  push() {
+    throw new Error('Not implemented');
+  }
+  clear() {
+    throw new Error('Not implemented');
+  }
+
+  // performance methods
+  pushPop(value) {
+    this.push(value);
+    return this.pop();
+  }
+  replaceTop(value) {
+    const z = this.pop();
+    this.push(value);
+    return z;
+  }
+
+  // helper methods
+  merge(...args) {
+    throw new Error('Not implemented');
+  }
+  clone() {
+    throw new Error('Not implemented');
+  }
+  make(...args) {
+    return new this.constructor(this, ...args);
+  }
+}
+
+HeapBase.defaults = {less: defaultLess, equal: defaultEqual, compare: null};
+
+export default HeapBase;

package/src/heap/leftist-heap.js

@@ -0,0 +1,125 @@
+'use strict';
+
+import HeapBase from './basics.js';
+
+const defaultLess = (a, b) => a < b;
+
+const merge = (a, b, less) => {
+  if (!a) return b;
+  if (!b) return a;
+  if (less(b.value, a.value)) [a, b] = [b, a]; // swap
+
+  a.right = merge(a.right, b, less);
+
+  if (!a.left) {
+    [a.left, a.right] = [a.right, a.left]; // swap
+    a.s = 1;
+    return a;
+  }
+
+  if (a.left.s < a.right.s) {
+    [a.left, a.right] = [a.right, a.left]; // swap
+  }
+  a.s = a.right.s + 1;
+  return a;
+};
+
+export class LeftistHeapNode {
+  constructor(value) {
+    this.value = value;
+    this.right = this.left = null;
+    this.s = 1;
+  }
+  clear() {
+    this.left = this.right = null;
+    this.s = 1;
+  }
+  clone() {
+    const node = new LeftistHeapNode(this.value);
+    node.left = this.left && this.left.clone();
+    node.right = this.right && this.right.clone();
+    return node;
+  }
+}
+
+export class LeftistHeap extends HeapBase {
+  constructor(options, ...args) {
+    super(options);
+    if (typeof this.compare == 'function') {
+      this.less = (a, b) => this.compare(a, b) < 0;
+    }
+    this.root = null;
+    this.size = 0;
+    if (args.length) this.merge(...args);
+  }
+  get isEmpty() {
+    return !this.root;
+  }
+  get length() {
+    return this.size;
+  }
+  get top() {
+    return this.root ? this.root.value : undefined;
+  }
+  peek() {
+    return this.root ? this.root.value : undefined;
+  }
+  push(value) {
+    this.root = merge(this.root, new LeftistHeapNode(value), this.less);
+    ++this.size;
+    return this;
+  }
+  pop() {
+    if (!this.root) return;
+    const z = this.root;
+    this.root = merge(this.root.left, this.root.right, this.less);
+    --this.size;
+    return z.value;
+  }
+  pushPop(value) {
+    if (!this.root || this.less(value, this.root.value)) return value;
+    const z = this.root;
+    this.root = merge(z.left, new LeftistHeapNode(value), this.less);
+    this.root = merge(this.root, z.right, this.less);
+    return z.value;
+  }
+  replaceTop(value) {
+    if (!this.root) {
+      this.root = new LeftistHeapNode(value);
+      this.size = 1;
+      return; // undefined
+    }
+    const z = this.root;
+    this.root = merge(z.left, new LeftistHeapNode(value), this.less);
+    this.root = merge(this.root, z.right, this.less);
+    return z.value;
+  }
+  clear() {
+    this.root = null;
+    this.size = 0;
+    return this;
+  }
+  merge(...args) {
+    for (const other of args) {
+      this.root = merge(this.root, other.root, this.less);
+      this.size += other.size;
+      other.root = null;
+      other.size = 0;
+    }
+    return this;
+  }
+  clone() {
+    const heap = new LeftistHeap(this);
+    heap.root = this.root && this.root.clone();
+    heap.size = this.size;
+    return heap;
+  }
+
+  static from(array, options = HeapBase.defaults) {
+    const heap = new LeftistHeap(options);
+    for (const value of array) heap.push(value);
+    return heap;
+  }
+}
+
+export default LeftistHeap;

package/src/heap/min-heap.js

@@ -1,6 +1,6 @@
 'use strict';
 
-import {copyOptions} from '../meta-utils.js';
+import HeapBase from './basics.js';
 
 // the following functions are inlined:
 
@@ -8,9 +8,6 @@ import {copyOptions} from '../meta-utils.js';
 // const right = i => (i + 1) << 1;
 // const parent = i => (i - 1) >> 1;
 
-const defaultLess = (a, b) => a < b;
-const defaultEqual = (a, b) => a === b;
-
 const up = (array, i, less = defaultLess) => {
   for (let p = (i - 1) >> 1; i > 0; i = p, p = (i - 1) >> 1) {
     const iValue = array[i],
@@ -38,15 +35,15 @@ const down = (array, i, less = defaultLess, n = array.length) => {
   return array;
 };
 
-export class MinHeap {
+export class MinHeap extends HeapBase {
   constructor(options, ...args) {
-    copyOptions(this, MinHeap.defaults, options);
+    super(options);
     if (typeof this.compare == 'function') {
       this.less = (a, b) => this.compare(a, b) < 0;
       this.equal = (a, b) => !this.compare(a, b);
     }
     this.array = [];
-    this.merge(...args);
+    if (args.length) this.merge(...args);
   }
 
   get length() {
@@ -216,10 +213,6 @@ export class MinHeap {
     return this;
   }
 
-  make(...args) {
-    return new MinHeap(this, ...args);
-  }
-
   clone() {
     const heap = new MinHeap(this);
     heap.array = this.array.slice(0);
@@ -327,8 +320,12 @@ export class MinHeap {
     }
     return heapArray;
   }
-}
 
-MinHeap.defaults = {less: defaultLess, equal: defaultEqual, compare: null};
+  static from(array, options = MinHeap.defaults) {
+    const heap = new MinHeap(options);
+    heap.array = MinHeap.build(array, heap.less);
+    return heap;
+  }
+}
 
 export default MinHeap;

package/src/heap/skew-heap.js

@@ -0,0 +1,113 @@
+'use strict';
+
+import HeapBase from './basics.js';
+
+const merge = (a, b, less) => {
+  if (!a) return b;
+  if (!b) return a;
+  if (less(b.value, a.value)) [a, b] = [b, a]; // swap
+
+  const temp = a.right;
+  a.right = a.left;
+  a.left = merge(b, temp, less);
+
+  return a;
+};
+
+export class SkewHeapNode {
+  constructor(value) {
+    this.value = value;
+    this.right = this.left = null;
+  }
+  clear() {
+    this.left = this.right = null;
+  }
+  clone() {
+    const node = new SkewHeapNode(this.value);
+    node.left = this.left && this.left.clone();
+    node.right = this.right && this.right.clone();
+    return node;
+  }
+}
+
+export class SkewHeap extends HeapBase {
+  constructor(options, ...args) {
+    super(options);
+    if (typeof this.compare == 'function') {
+      this.less = (a, b) => this.compare(a, b) < 0;
+    }
+    this.root = null;
+    this.size = 0;
+    if (args.length) this.merge(...args);
+  }
+  get isEmpty() {
+    return !this.root;
+  }
+  get length() {
+    return this.size;
+  }
+  get top() {
+    return this.root ? this.root.value : undefined;
+  }
+  peek() {
+    return this.root ? this.root.value : undefined;
+  }
+  push(value) {
+    this.root = merge(this.root, new SkewHeapNode(value), this.less);
+    ++this.size;
+    return this;
+  }
+  pop() {
+    if (!this.root) return;
+    const z = this.root;
+    this.root = merge(this.root.left, this.root.right, this.less);
+    --this.size;
+    return z.value;
+  }
+  pushPop(value) {
+    if (!this.root || this.less(value, this.root.value)) return value;
+    const z = this.root;
+    this.root = merge(z.left, new SkewHeapNode(value), this.less);
+    this.root = merge(this.root, z.right, this.less);
+    return z.value;
+  }
+  replaceTop(value) {
+    if (!this.root) {
+      this.root = new SkewHeapNode(value);
+      this.size = 1;
+      return; // undefined
+    }
+    const z = this.root;
+    this.root = merge(z.left, new SkewHeapNode(value), this.less);
+    this.root = merge(this.root, z.right, this.less);
+    return z.value;
+  }
+  clear() {
+    this.root = null;
+    this.size = 0;
+    return this;
+  }
+  merge(...args) {
+    for (const other of args) {
+      this.root = merge(this.root, other.root, this.less);
+      this.size += other.size;
+      other.root = null;
+      other.size = 0;
+    }
+    return this;
+  }
+  clone() {
+    const heap = new SkewHeap(this);
+    heap.root = this.root && this.root.clone();
+    heap.size = this.size;
+    return heap;
+  }
+
+  static from(array, options = HeapBase.defaults) {
+    const heap = new SkewHeap(options);
+    for (const value of array) heap.push(value);
+    return heap;
+  }
+}
+
+export default SkewHeap;