list-toolkit 2.2.5 → 2.3.0

package/src/cache/decorator.js

@@ -1,5 +1,9 @@
-'use strict';
-
+/**
+ * Wrap a function with caching. The first argument is used as the cache key.
+ * @param {Function} fn - Function to wrap.
+ * @param {object} cache - Cache instance with `has`, `get`, and `set` methods.
+ * @returns {Function} The wrapped function with `.fn` and `.cache` properties.
+ */
 export const decorateFn = (fn, cache) => {
   if (typeof fn !== 'function') throw new TypeError('Not a function');
   const wrapped = function (...args) {
@@ -15,6 +19,13 @@ export const decorateFn = (fn, cache) => {
   return wrapped;
 };
 
+/**
+ * Replace a property descriptor's value with a cached version.
+ * @param {object} object - Object owning the property.
+ * @param {string} key - Property name.
+ * @param {object} cache - Cache instance.
+ * @returns {Function} The wrapped function.
+ */
 export const decorate = (object, key, cache) => {
   const descriptor = Object.getOwnPropertyDescriptor(object, key);
   if (!descriptor) throw new Error('Missing property: ' + key);
@@ -29,6 +40,13 @@ export const decorate = (object, key, cache) => {
   return wrapped;
 };
 
+/**
+ * Replace a method on an object with a cached version.
+ * @param {object} object - Object owning the method.
+ * @param {string} key - Method name.
+ * @param {object} cache - Cache instance.
+ * @returns {Function} The wrapped function.
+ */
 export const decorateMethod = (object, key, cache) => {
   const fn = object[key],
     wrapped = decorateFn(fn, cache);
@@ -36,6 +54,12 @@ export const decorateMethod = (object, key, cache) => {
   return wrapped;
 };
 
+/**
+ * Retrieve the cache instance from a decorated property.
+ * @param {object} object - Object owning the property.
+ * @param {string} key - Property name.
+ * @returns {object} The cache instance.
+ */
 export const getCache = (object, key) => {
   const descriptor = Object.getOwnPropertyDescriptor(object, key);
   if (!descriptor) throw new Error('Missing property: ' + key);

package/src/cache.d.ts

@@ -0,0 +1,13 @@
+export * from './cache/cache-lru.js';
+import Cache from './cache/cache-lru.js';
+
+/**
+ * Convenience wrapper around the cache decorator.
+ * @param object - Object owning the method.
+ * @param key - Method name.
+ * @param cache - Cache instance (default: new CacheLRU).
+ * @returns The wrapped function.
+ */
+export function cacheDecorator(object: object, key: PropertyKey, cache?: Cache): object;
+
+export default Cache;

package/src/cache.js

@@ -1,9 +1,14 @@
-'use strict';
-
 export * from './cache/cache-lru.js';
 import Cache from './cache/cache-lru.js';
 import decorator from './cache/decorator.js';
 
+/**
+ * Convenience decorator that wraps a property with LRU caching.
+ * @param {object} object - Object owning the property.
+ * @param {string} key - Property name.
+ * @param {object} [cache] - Cache instance (default: new CacheLRU).
+ * @returns {Function} The wrapped function.
+ */
 export const cacheDecorator = (object, key, cache = new Cache()) => decorator(object, key, cache);
 
 export default Cache;

package/src/ext-list.d.ts

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

package/src/ext-list.js

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

package/src/ext-slist.d.ts

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

package/src/ext-slist.js

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

package/src/ext-value-list.d.ts

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

package/src/ext-value-list.js

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

package/src/ext-value-slist.d.ts

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

package/src/ext-value-slist.js

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

package/src/heap/basics.d.ts

@@ -0,0 +1,89 @@
+/** Options for configuring heap ordering. */
+export interface HeapOptions<T = unknown> {
+  /** Returns `true` if `a` should be ordered before `b`. */
+  less?: (a: T, b: T) => boolean;
+  /** Returns `true` if `a` and `b` are considered equal. */
+  equal?: (a: T, b: T) => boolean;
+  /** Comparison function returning negative, zero, or positive. Overrides `less`/`equal` when set. */
+  compare?: ((a: T, b: T) => number) | null;
+}
+
+/** Abstract base class for heap implementations. */
+export class HeapBase<T = unknown> {
+  /** Returns `true` if `a` should be ordered before `b`. */
+  less: (a: T, b: T) => boolean;
+  /** Returns `true` if `a` and `b` are considered equal. */
+  equal: (a: T, b: T) => boolean;
+  /** Comparison function, or `null` if using `less`/`equal`. */
+  compare: ((a: T, b: T) => number) | null;
+
+  /** @param options - Ordering functions. */
+  constructor(options?: HeapOptions<T>);
+
+  /** Whether the heap has no elements. */
+  get isEmpty(): boolean;
+
+  /** The minimum element without removing it. */
+  get top(): T | undefined;
+
+  /** Alias for {@link top}. */
+  peek(): T | undefined;
+
+  /**
+   * Remove and return the minimum element.
+   * @returns The minimum element, or `undefined` if empty.
+   */
+  pop(): T | undefined;
+
+  /**
+   * Insert a value into the heap.
+   * @param value - Value to insert.
+   * @returns `this` for chaining.
+   */
+  push(value: T): this;
+
+  /**
+   * Remove all elements.
+   * @returns `this` for chaining.
+   */
+  clear(): this;
+
+  /**
+   * Push a value then immediately pop the minimum.
+   * @param value - Value to push.
+   * @returns The minimum element after the push.
+   */
+  pushPop(value: T): T;
+
+  /**
+   * Pop the minimum then push a new value.
+   * @param value - Value to push after popping.
+   * @returns The old minimum element.
+   */
+  replaceTop(value: T): T | undefined;
+
+  /**
+   * Merge other heaps or iterables into this heap.
+   * @param args - Heaps or iterables to merge.
+   * @returns `this` for chaining.
+   */
+  merge(...args: Array<HeapBase<T> | Iterable<T>>): this;
+
+  /**
+   * Create a deep copy of this heap.
+   * @returns A new heap with the same elements.
+   */
+  clone(): HeapBase<T>;
+
+  /**
+   * Create a new empty heap with the same options.
+   * @param args - Additional constructor arguments.
+   * @returns A new heap.
+   */
+  make(...args: any[]): HeapBase<T>;
+
+  /** Default ordering functions. */
+  static defaults: HeapOptions;
+}
+
+export default HeapBase;

package/src/heap/basics.js

@@ -1,53 +1,90 @@
-'use strict';
-
 import {copyOptions} from '../meta-utils.js';
 
 const defaultLess = (a, b) => a < b;
 const defaultEqual = (a, b) => a === b;
 
+/** Abstract base class for heap implementations. */
 export class HeapBase {
+  /** @param {object} [options] - Ordering options (`less`, `equal`, `compare`). */
   constructor(options) {
     copyOptions(this, HeapBase.defaults, options);
   }
 
-  // main methods
+  /** Whether the heap has no elements. */
   get isEmpty() {
     throw new Error('Not implemented');
   }
+  /** The minimum element without removing it. */
   get top() {
     throw new Error('Not implemented');
   }
+  /** Alias for {@link HeapBase#top|top}. */
   peek() {
     return this.top;
   }
+  /**
+   * Remove and return the minimum element.
+   * @returns {*} The removed element.
+   */
   pop() {
     throw new Error('Not implemented');
   }
+  /**
+   * Add an element to the heap.
+   * @param {*} value - Element to add.
+   * @returns {HeapBase} `this` for chaining.
+   */
   push() {
     throw new Error('Not implemented');
   }
+  /**
+   * Remove all elements.
+   * @returns {HeapBase} `this` for chaining.
+   */
   clear() {
     throw new Error('Not implemented');
   }
 
-  // performance methods
+  /**
+   * Push then pop in one operation (more efficient than separate calls).
+   * @param {*} value - Element to push.
+   * @returns {*} The popped element.
+   */
   pushPop(value) {
     this.push(value);
     return this.pop();
   }
+  /**
+   * Pop then push in one operation (more efficient than separate calls).
+   * @param {*} value - Element to push.
+   * @returns {*} The popped element.
+   */
   replaceTop(value) {
     const z = this.pop();
     this.push(value);
     return z;
   }
 
-  // helper methods
+  /**
+   * Merge one or more iterables or heaps into this heap.
+   * @param {...Iterable} args - Arrays or heaps to merge.
+   * @returns {HeapBase} `this` for chaining.
+   */
   merge(...args) {
     throw new Error('Not implemented');
   }
+  /**
+   * Create a shallow copy of this heap.
+   * @returns {HeapBase} A new heap with the same elements.
+   */
   clone() {
     throw new Error('Not implemented');
   }
+  /**
+   * Create an empty heap with the same options.
+   * @param {...*} args - Additional arguments for the constructor.
+   * @returns {HeapBase} A new heap.
+   */
   make(...args) {
     return new this.constructor(this, ...args);
   }

package/src/heap/leftist-heap.d.ts

@@ -0,0 +1,107 @@
+import HeapBase, {HeapOptions} from './basics.js';
+
+/** Node used internally by {@link LeftistHeap}. */
+export class LeftistHeapNode<T = unknown> {
+  /** The stored value. */
+  value: T;
+  /** Left child, or `null`. */
+  left: LeftistHeapNode<T> | null;
+  /** Right child, or `null`. */
+  right: LeftistHeapNode<T> | null;
+  /** S-value (rank) of this node. */
+  s: number;
+
+  /** @param value - Value to store. */
+  constructor(value: T);
+
+  /** Reset children to `null` and s-value to 1. */
+  clear(): void;
+
+  /**
+   * Create a deep copy of this subtree.
+   * @returns A new LeftistHeapNode tree.
+   */
+  clone(): LeftistHeapNode<T>;
+}
+
+/** Merge-based leftist heap. */
+export class LeftistHeap<T = unknown> extends HeapBase<T> {
+  /** Root node, or `null` if empty. */
+  root: LeftistHeapNode<T> | null;
+  /** Number of elements. */
+  size: number;
+
+  /**
+   * @param options - Ordering functions.
+   * @param args - Initial heaps to merge.
+   */
+  constructor(options?: HeapOptions<T>, ...args: LeftistHeap<T>[]);
+
+  /** Whether the heap has no elements. */
+  get isEmpty(): boolean;
+
+  /** Number of elements. */
+  get length(): number;
+
+  /** The minimum element without removing it. */
+  get top(): T | undefined;
+
+  /** Alias for {@link top}. */
+  peek(): T | undefined;
+
+  /**
+   * Insert a value into the heap.
+   * @param value - Value to insert.
+   * @returns `this` for chaining.
+   */
+  push(value: T): this;
+
+  /**
+   * Remove and return the minimum element.
+   * @returns The minimum element, or `undefined` if empty.
+   */
+  pop(): T | undefined;
+
+  /**
+   * Push a value then immediately pop the minimum.
+   * @param value - Value to push.
+   * @returns The minimum element after the push.
+   */
+  pushPop(value: T): T;
+
+  /**
+   * Pop the minimum then push a new value.
+   * @param value - Value to push after popping.
+   * @returns The old minimum element, or `undefined` if was empty.
+   */
+  replaceTop(value: T): T | undefined;
+
+  /**
+   * Remove all elements.
+   * @returns `this` for chaining.
+   */
+  clear(): this;
+
+  /**
+   * Merge other leftist heaps into this one, consuming them.
+   * @param args - Heaps to merge (they are cleared).
+   * @returns `this` for chaining.
+   */
+  merge(...args: LeftistHeap<T>[]): this;
+
+  /**
+   * Create a deep copy of this heap.
+   * @returns A new LeftistHeap with the same elements.
+   */
+  clone(): LeftistHeap<T>;
+
+  /**
+   * Build a LeftistHeap from an iterable.
+   * @param array - Iterable of values.
+   * @param options - Ordering functions.
+   * @returns A new LeftistHeap.
+   */
+  static from<T = unknown>(array: Iterable<T>, options?: HeapOptions<T>): LeftistHeap<T>;
+}
+
+export default LeftistHeap;

package/src/heap/leftist-heap.js

@@ -1,5 +1,3 @@
-'use strict';
-
 import HeapBase from './basics.js';
 
 const defaultLess = (a, b) => a < b;
@@ -24,16 +22,23 @@ const merge = (a, b, less) => {
   return a;
 };
 
+/** Node for a leftist heap. */
 export class LeftistHeapNode {
+  /** @param {*} value - Value to store. */
   constructor(value) {
     this.value = value;
     this.right = this.left = null;
     this.s = 1;
   }
+  /** Reset child links and rank. */
   clear() {
     this.left = this.right = null;
     this.s = 1;
   }
+  /**
+   * Deep-clone this node and its subtree.
+   * @returns {LeftistHeapNode} A new node tree.
+   */
   clone() {
     const node = new LeftistHeapNode(this.value);
     node.left = this.left && this.left.clone();
@@ -42,7 +47,12 @@ export class LeftistHeapNode {
   }
 }
 
+/** Leftist heap — a merge-based min-heap using node ranks. */
 export class LeftistHeap extends HeapBase {
+  /**
+   * @param {object} [options] - Ordering options (`less`, `compare`).
+   * @param {...LeftistHeap} args - Initial heaps to merge.
+   */
   constructor(options, ...args) {
     super(options);
     if (typeof this.compare == 'function') {
@@ -52,23 +62,36 @@ export class LeftistHeap extends HeapBase {
     this.size = 0;
     if (args.length) this.merge(...args);
   }
+  /** Whether the heap has no elements. */
   get isEmpty() {
     return !this.root;
   }
+  /** The number of elements. */
   get length() {
     return this.size;
   }
+  /** The minimum element without removing it. */
   get top() {
     return this.root ? this.root.value : undefined;
   }
+  /** Alias for {@link LeftistHeap#top|top}. */
   peek() {
     return this.root ? this.root.value : undefined;
   }
+  /**
+   * Add an element.
+   * @param {*} value - Element to add.
+   * @returns {LeftistHeap} `this` for chaining.
+   */
   push(value) {
     this.root = merge(this.root, new LeftistHeapNode(value), this.less);
     ++this.size;
     return this;
   }
+  /**
+   * Remove and return the minimum element.
+   * @returns {*} The removed element, or `undefined` if empty.
+   */
   pop() {
     if (!this.root) return;
     const z = this.root;
@@ -76,6 +99,11 @@ export class LeftistHeap extends HeapBase {
     --this.size;
     return z.value;
   }
+  /**
+   * Push then pop in one operation.
+   * @param {*} value - Element to push.
+   * @returns {*} The popped element.
+   */
   pushPop(value) {
     if (!this.root || this.less(value, this.root.value)) return value;
     const z = this.root;
@@ -83,6 +111,11 @@ export class LeftistHeap extends HeapBase {
     this.root = merge(this.root, z.right, this.less);
     return z.value;
   }
+  /**
+   * Pop then push in one operation.
+   * @param {*} value - Element to push.
+   * @returns {*} The previously minimum element, or `undefined` if was empty.
+   */
   replaceTop(value) {
     if (!this.root) {
       this.root = new LeftistHeapNode(value);
@@ -94,11 +127,20 @@ export class LeftistHeap extends HeapBase {
     this.root = merge(this.root, z.right, this.less);
     return z.value;
   }
+  /**
+   * Remove all elements.
+   * @returns {LeftistHeap} `this` for chaining.
+   */
   clear() {
     this.root = null;
     this.size = 0;
     return this;
   }
+  /**
+   * Merge one or more heaps into this heap, consuming them.
+   * @param {...LeftistHeap} args - Heaps to merge.
+   * @returns {LeftistHeap} `this` for chaining.
+   */
   merge(...args) {
     for (const other of args) {
       this.root = merge(this.root, other.root, this.less);
@@ -108,6 +150,10 @@ export class LeftistHeap extends HeapBase {
     }
     return this;
   }
+  /**
+   * Create a deep copy of this heap.
+   * @returns {LeftistHeap} A new LeftistHeap with cloned nodes.
+   */
   clone() {
     const heap = new LeftistHeap(this);
     heap.root = this.root && this.root.clone();
@@ -115,6 +161,12 @@ export class LeftistHeap extends HeapBase {
     return heap;
   }
 
+  /**
+   * Build a LeftistHeap from an iterable.
+   * @param {Iterable} array - Elements to insert.
+   * @param {object} [options] - Ordering options.
+   * @returns {LeftistHeap} A new LeftistHeap.
+   */
   static from(array, options = HeapBase.defaults) {
     const heap = new LeftistHeap(options);
     for (const value of array) heap.push(value);