list-toolkit 2.2.5 → 2.3.0

package/src/tree/splay-tree.js

@@ -1,5 +1,3 @@
-'use strict';
-
 import {copyOptions} from '../meta-utils.js';
 
 const defaultLess = (a, b) => a < b;
@@ -55,16 +53,26 @@ const splay = node => {
 
 const count = tree => (tree ? count(tree.left) + count(tree.right) + 1 : 0);
 
+/** Node for a splay tree. */
 export class SplayTreeNode {
+  /** @param {*} value - Value to store. */
   constructor(value) {
     this.left = this.right = this.parent = null;
     this.value = value;
   }
+  /**
+   * Find the minimum node in this subtree.
+   * @returns {SplayTreeNode} The leftmost node.
+   */
   getMin() {
     let z = this;
     while (z.left) z = z.left;
     return z;
   }
+  /**
+   * Find the maximum node in this subtree.
+   * @returns {SplayTreeNode} The rightmost node.
+   */
   getMax() {
     let z = this;
     while (z.right) z = z.right;
@@ -72,7 +80,9 @@ export class SplayTreeNode {
   }
 }
 
+/** Self-adjusting binary search tree. */
 export class SplayTree {
+  /** @param {object} [options] - Ordering options (`less`, `compare`). */
   constructor(options) {
     copyOptions(this, SplayTree.defaults, options);
     if (typeof this.compare == 'function') {
@@ -84,18 +94,33 @@ export class SplayTree {
     this.root = null;
     this.size = 0;
   }
+  /** Whether the tree has no nodes. */
   get isEmpty() {
     return !this.root;
   }
+  /** The number of nodes. */
   get length() {
     return this.size;
   }
+  /**
+   * Get the node with the minimum value.
+   * @returns {SplayTreeNode} The minimum node.
+   */
   getMin() {
     return this.root.getMin();
   }
+  /**
+   * Get the node with the maximum value.
+   * @returns {SplayTreeNode} The maximum node.
+   */
   getMax() {
     return this.root.getMax();
   }
+  /**
+   * Find a node by value.
+   * @param {*} value - Value to search for.
+   * @returns {SplayTreeNode|null} The found node, or `null`.
+   */
   find(value) {
     for (let z = this.root; z; ) {
       if (this.less(z.value, value)) z = z.right;
@@ -104,6 +129,11 @@ export class SplayTree {
     }
     return null;
   }
+  /**
+   * Find a node by value using `compare`.
+   * @param {*} value - Value to search for.
+   * @returns {SplayTreeNode|null} The found node, or `null`.
+   */
   findWithCompare(value) {
     for (let z = this.root; z; ) {
       const cmp = this.compare(value, z.value);
@@ -113,6 +143,11 @@ export class SplayTree {
     }
     return null;
   }
+  /**
+   * Find a value and splay it to the root.
+   * @param {*} value - Value to promote.
+   * @returns {SplayTreeNode|null} The found node, or `null`.
+   */
   promote(value) {
     const z = this.find(value);
     if (z) {
@@ -120,10 +155,20 @@ export class SplayTree {
     }
     return z;
   }
+  /**
+   * Splay a node to the root.
+   * @param {SplayTreeNode} node - Node to splay.
+   * @returns {SplayTree} `this` for chaining.
+   */
   splay(node) {
     this.root = splay(node);
     return this;
   }
+  /**
+   * Insert a value. If it already exists, splay the existing node.
+   * @param {*} value - Value to insert.
+   * @returns {SplayTree} `this` for chaining.
+   */
   insert(value) {
     let z = this.root,
       parent = null;
@@ -145,6 +190,11 @@ export class SplayTree {
     this.root = splay(z);
     return this;
   }
+  /**
+   * Insert a value using `compare`. If it already exists, splay the existing node.
+   * @param {*} value - Value to insert.
+   * @returns {SplayTree} `this` for chaining.
+   */
   insertWithCompare(value) {
     let z = this.root,
       parent = null;
@@ -167,6 +217,11 @@ export class SplayTree {
     this.root = splay(z);
     return this;
   }
+  /**
+   * Remove a value from the tree.
+   * @param {*} value - Value to remove.
+   * @returns {SplayTree} `this` for chaining.
+   */
   remove(value) {
     const z = this.find(value);
     if (!z) return this;
@@ -190,11 +245,20 @@ export class SplayTree {
 
     return this;
   }
+  /**
+   * Remove all nodes.
+   * @returns {SplayTree} `this` for chaining.
+   */
   clear() {
     this.root = null;
     this.size = 0;
     return this;
   }
+  /**
+   * Split the tree: keep nodes ≤ value, return a new tree with nodes > value.
+   * @param {*} value - Split point.
+   * @returns {SplayTree} A new SplayTree with the greater nodes.
+   */
   splitMaxTree(value) {
     if (!this.root) return new SplayTree(this);
     let z = this.root,
@@ -234,6 +298,11 @@ export class SplayTree {
     }
     return newTree;
   }
+  /**
+   * Split the tree using `compare`: keep nodes ≤ value, return a new tree with nodes > value.
+   * @param {*} value - Split point.
+   * @returns {SplayTree} A new SplayTree with the greater nodes.
+   */
   splitMaxTreeWithCompare(value) {
     if (!this.root) return new SplayTree(this);
     let z = this.root,
@@ -274,6 +343,11 @@ export class SplayTree {
     }
     return newTree;
   }
+  /**
+   * Join a tree whose values are all greater than this tree's maximum (unsafe: no validation).
+   * @param {SplayTree} tree - Tree to join (consumed).
+   * @returns {SplayTree} `this` for chaining.
+   */
   joinMaxTreeUnsafe(tree) {
     if (this.root.right) {
       this.splay(this.getMax());
@@ -287,6 +361,11 @@ export class SplayTree {
 
     return this;
   }
+  /**
+   * Join another tree into this one. Uses fast path if ranges don't overlap.
+   * @param {SplayTree} tree - Tree to join (consumed).
+   * @returns {SplayTree} `this` for chaining.
+   */
   join(tree) {
     if (!tree.root) return this;
     if (!this.root) {
@@ -296,7 +375,8 @@ export class SplayTree {
       return this;
     }
 
-    const leftMax = this.getMax(), rightMin = tree.getMin();
+    const leftMax = this.getMax(),
+      rightMin = tree.getMin();
     if (this.less(leftMax.value, rightMin.value)) {
       return this.splay(leftMax).joinMaxTreeUnsafe(tree);
     }
@@ -308,6 +388,7 @@ export class SplayTree {
     tree.clear();
     return this;
   }
+  /** Iterate over values in ascending order. */
   [Symbol.iterator]() {
     let current = this.root ? this.root.getMin() : null;
     return {
@@ -334,6 +415,10 @@ export class SplayTree {
       }
     };
   }
+  /**
+   * Get an iterable over values in descending order.
+   * @returns {Iterable} An iterable iterator of values.
+   */
   getReverseIterator() {
     return {
       [Symbol.iterator]: () => {
@@ -364,6 +449,12 @@ export class SplayTree {
       }
     };
   }
+  /**
+   * Build a SplayTree from an iterable.
+   * @param {Iterable} values - Values to insert.
+   * @param {object} [options] - Ordering options.
+   * @returns {SplayTree} A new SplayTree.
+   */
   static from(values, options) {
     const tree = new SplayTree(options);
     for (const value of values) {

package/src/value-list.d.ts

@@ -0,0 +1,3 @@
+export * from './list/value.js';
+import ValueList from './list/value.js';
+export default ValueList;

package/src/value-list.js

@@ -1,5 +1,3 @@
-'use strict';
-
 export * from './list/value.js';
 import ValueList from './list/value.js';
 

package/src/value-slist.d.ts

@@ -0,0 +1,3 @@
+export * from './slist/value.js';
+import ValueSList from './slist/value.js';
+export default ValueSList;

package/src/value-slist.js

@@ -1,5 +1,3 @@
-'use strict';
-
 export * from './slist/value.js';
 import ValueSList from './slist/value.js';
 

package/cjs/cache/cache-fifo.js

@@ -1,37 +0,0 @@
-'use strict';
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = exports.CacheFIFO = void 0;
-var _cacheLru = _interopRequireDefault(require("./cache-lru.js"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-// Evicts on the first-in-first-out basis.
-
-class CacheFIFO extends _cacheLru.default {
-  use(key) {
-    return this.dict.get(key);
-  }
-  addNew(key, value) {
-    this.list.pushBack({
-      key,
-      value
-    });
-    const node = this.list.back;
-    this.dict.set(key, node);
-    return node;
-  }
-  evictAndReplace(key, value) {
-    const node = this.list.front;
-    this.list.moveToBack(node);
-    this.dict.delete(node.value.key);
-    this.dict.set(key, node);
-    node.value = {
-      key,
-      value
-    };
-    return node;
-  }
-}
-exports.CacheFIFO = CacheFIFO;
-var _default = exports.default = CacheFIFO;

package/cjs/cache/cache-lfu.js

@@ -1,76 +0,0 @@
-'use strict';
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = exports.CacheLFU = void 0;
-var _metaUtils = require("../meta-utils.js");
-var _minHeap = _interopRequireDefault(require("../heap/min-heap.js"));
-var _cacheLru = _interopRequireDefault(require("./cache-lru.js"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-// Evicts the least frequently used items.
-
-class CacheLFU extends _cacheLru.default {
-  constructor(capacity = 10) {
-    super(capacity);
-    this.heap = new _minHeap.default({
-      less: (a, b) => a.value.counter < b.value.counter
-    });
-  }
-  use(key) {
-    const node = this.dict.get(key);
-    if (node) ++node.value.counter;
-    return node;
-  }
-  update(node, value) {
-    node.value.counter = 1;
-    node.value.value = value;
-    return this;
-  }
-  addNew(key, value) {
-    this.list.pushFront({
-      key,
-      value,
-      counter: 1
-    });
-    const node = this.list.front;
-    this.dict.set(key, node);
-    this.heap.push(node);
-    return node;
-  }
-  evictAndReplace(key, value) {
-    const node = this.heap.top;
-    this.dict.delete(node.value.key);
-    node.value = {
-      key,
-      value,
-      counter: 1
-    };
-    this.dict.set(key, node);
-    this.heap.updateTop();
-    return node;
-  }
-  remove(key) {
-    const node = this.dict.get(key);
-    if (node) {
-      this.dict.delete(key);
-      this.list.removeNode(node);
-      this.heap.remove(node);
-    }
-    return this;
-  }
-  clear() {
-    super.clear();
-    this.heap.clear();
-    return this;
-  }
-  resetCounters(initialValue = 1) {
-    for (const item of this.heap) {
-      item.counter = initialValue;
-    }
-    return this;
-  }
-}
-exports.CacheLFU = CacheLFU;
-(0, _metaUtils.addAlias)(CacheLFU.prototype, 'remove', 'delete');
-var _default = exports.default = CacheLFU;

package/cjs/cache/cache-lru.js

@@ -1,100 +0,0 @@
-'use strict';
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = exports.CacheLRU = void 0;
-var _valueList = _interopRequireDefault(require("../value-list.js"));
-var _metaUtils = require("../meta-utils.js");
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-// The base cache class. Evicts the least recently used items.
-// Based on doubly linked value lists.
-
-class CacheLRU {
-  constructor(capacity = 10) {
-    this.capacity = capacity;
-    this.list = new _valueList.default();
-    this.dict = new Map();
-  }
-  get isEmpty() {
-    return !this.dict.size;
-  }
-  get size() {
-    return this.dict.size;
-  }
-  has(key) {
-    return this.dict.has(key);
-  }
-  find(key) {
-    const node = this.use(key);
-    return node ? node.value.value : undefined;
-  }
-  remove(key) {
-    const node = this.dict.get(key);
-    if (node) {
-      this.dict.delete(key);
-      this.list.removeNode(node);
-    }
-    return this;
-  }
-  register(key, value) {
-    const node = this.use(key);
-    if (node) {
-      this.update(node, value);
-      return this;
-    }
-    if (this.dict.size >= this.capacity) {
-      this.evictAndReplace(key, value);
-      return this;
-    }
-    this.addNew(key, value);
-    return this;
-  }
-  use(key) {
-    const node = this.dict.get(key);
-    if (node) this.list.moveToFront(node);
-    return node;
-  }
-  update(node, value) {
-    node.value.value = value;
-    return this;
-  }
-  addNew(key, value) {
-    this.list.pushFront({
-      key,
-      value
-    });
-    const node = this.list.front;
-    this.dict.set(key, node);
-    return node;
-  }
-  evictAndReplace(key, value) {
-    const node = this.list.back;
-    this.list.moveToFront(node);
-    this.dict.delete(node.value.key);
-    this.dict.set(key, node);
-    node.value = {
-      key,
-      value
-    };
-    return node;
-  }
-  clear() {
-    this.dict.clear();
-    this.list.clear();
-    return this;
-  }
-  [Symbol.iterator]() {
-    return this.list[Symbol.iterator]();
-  }
-  getReverseIterator() {
-    return this.list.getReverseIterator();
-  }
-}
-exports.CacheLRU = CacheLRU;
-(0, _metaUtils.addAliases)(CacheLRU.prototype, {
-  register: 'add, set',
-  remove: 'delete',
-  find: 'get'
-});
-var _default = exports.default = CacheLRU;

package/cjs/cache/cache-random.js

@@ -1,77 +0,0 @@
-'use strict';
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = exports.CacheRandom = void 0;
-var _metaUtils = require("../meta-utils.js");
-var _minHeap = _interopRequireDefault(require("../heap/min-heap.js"));
-var _cacheLru = _interopRequireDefault(require("./cache-lru.js"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-// Evicts items randomly.
-
-class CacheRandom extends _cacheLru.default {
-  constructor(capacity = 10) {
-    super(capacity);
-    this.heap = new _minHeap.default({
-      less: (a, b) => a.value.id > b.value.id
-    });
-    this.nextId = 0;
-  }
-  use(key) {
-    return this.dict.get(key);
-  }
-  update(node, value) {
-    node.value.value = value;
-    return this;
-  }
-  addNew(key, value) {
-    this.list.pushFront({
-      key,
-      value,
-      id: this.nextId++
-    });
-    const node = this.list.front;
-    this.dict.set(key, node);
-    this.heap.push(node);
-    return node;
-  }
-  evictAndReplace(key, value) {
-    const index = Math.floor(this.heap.length * Math.random());
-    const node = this.heap.array[index],
-      isDecreased = value > node.value.value;
-    this.dict.delete(node.value.key);
-    this.dict.set(key, node);
-    node.value.key = key;
-    node.value.value = value;
-    this.heap.updateByIndex(index, isDecreased);
-    return node;
-  }
-  remove(key) {
-    const node = this.dict.get(key);
-    if (node) {
-      this.dict.delete(key);
-      this.list.removeNode(node);
-      this.heap.remove(node);
-    }
-    return this;
-  }
-  clear() {
-    super.clear();
-    this.heap.clear();
-    this.nextId = 0;
-    return this;
-  }
-  resetIds() {
-    this.nextId = 0;
-    for (const item of this.heap) {
-      item.id = this.nextId++;
-    }
-    const array = this.heap.array;
-    this.heap.clear().merge(array);
-    return this;
-  }
-}
-exports.CacheRandom = CacheRandom;
-(0, _metaUtils.addAlias)(CacheRandom.prototype, 'remove', 'delete');
-var _default = exports.default = CacheRandom;

package/cjs/cache/decorator.js

@@ -1,47 +0,0 @@
-'use strict';
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.getCache = exports.default = exports.decorateMethod = exports.decorateFn = exports.decorate = void 0;
-const decorateFn = (fn, cache) => {
-  if (typeof fn !== 'function') throw new TypeError('Not a function');
-  const wrapped = function (...args) {
-    const key = args[0],
-      cache = wrapped.cache;
-    if (cache.has(key)) return cache.get(key);
-    const result = wrapped.fn.apply(this, args);
-    cache.set(key, result);
-    return result;
-  };
-  wrapped.fn = fn;
-  wrapped.cache = cache;
-  return wrapped;
-};
-exports.decorateFn = decorateFn;
-const decorate = (object, key, cache) => {
-  const descriptor = Object.getOwnPropertyDescriptor(object, key);
-  if (!descriptor) throw new Error('Missing property: ' + key);
-  const newDescriptor = {
-      ...descriptor
-    },
-    wrapped = decorateFn(descriptor.value, cache);
-  newDescriptor.value = wrapped;
-  Object.defineProperty(object, key, newDescriptor);
-  return wrapped;
-};
-exports.decorate = decorate;
-const decorateMethod = (object, key, cache) => {
-  const fn = object[key],
-    wrapped = decorateFn(fn, cache);
-  object[key] = wrapped;
-  return wrapped;
-};
-exports.decorateMethod = decorateMethod;
-const getCache = (object, key) => {
-  const descriptor = Object.getOwnPropertyDescriptor(object, key);
-  if (!descriptor) throw new Error('Missing property: ' + key);
-  return descriptor.value.cache;
-};
-exports.getCache = getCache;
-var _default = exports.default = decorate;

package/cjs/cache.js

@@ -1,27 +0,0 @@
-'use strict';
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-var _exportNames = {
-  cacheDecorator: true
-};
-exports.default = exports.cacheDecorator = void 0;
-var _cacheLru = _interopRequireWildcard(require("./cache/cache-lru.js"));
-Object.keys(_cacheLru).forEach(function (key) {
-  if (key === "default" || key === "__esModule") return;
-  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
-  if (key in exports && exports[key] === _cacheLru[key]) return;
-  Object.defineProperty(exports, key, {
-    enumerable: true,
-    get: function () {
-      return _cacheLru[key];
-    }
-  });
-});
-var _decorator = _interopRequireDefault(require("./cache/decorator.js"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
-const cacheDecorator = (object, key, cache = new _cacheLru.default()) => (0, _decorator.default)(object, key, cache);
-exports.cacheDecorator = cacheDecorator;
-var _default = exports.default = _cacheLru.default;

package/cjs/ext-list.js

@@ -1,21 +0,0 @@
-'use strict';
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-var _exportNames = {};
-exports.default = void 0;
-var _ext = _interopRequireWildcard(require("./list/ext.js"));
-Object.keys(_ext).forEach(function (key) {
-  if (key === "default" || key === "__esModule") return;
-  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
-  if (key in exports && exports[key] === _ext[key]) return;
-  Object.defineProperty(exports, key, {
-    enumerable: true,
-    get: function () {
-      return _ext[key];
-    }
-  });
-});
-function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
-var _default = exports.default = _ext.default;

package/cjs/ext-slist.js

@@ -1,21 +0,0 @@
-'use strict';
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-var _exportNames = {};
-exports.default = void 0;
-var _ext = _interopRequireWildcard(require("./slist/ext.js"));
-Object.keys(_ext).forEach(function (key) {
-  if (key === "default" || key === "__esModule") return;
-  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
-  if (key in exports && exports[key] === _ext[key]) return;
-  Object.defineProperty(exports, key, {
-    enumerable: true,
-    get: function () {
-      return _ext[key];
-    }
-  });
-});
-function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
-var _default = exports.default = _ext.default;

package/cjs/ext-value-list.js

@@ -1,21 +0,0 @@
-'use strict';
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-var _exportNames = {};
-exports.default = void 0;
-var _extValue = _interopRequireWildcard(require("./list/ext-value.js"));
-Object.keys(_extValue).forEach(function (key) {
-  if (key === "default" || key === "__esModule") return;
-  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
-  if (key in exports && exports[key] === _extValue[key]) return;
-  Object.defineProperty(exports, key, {
-    enumerable: true,
-    get: function () {
-      return _extValue[key];
-    }
-  });
-});
-function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
-var _default = exports.default = _extValue.default;