list-toolkit 2.2.6 → 2.3.0

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

@@ -0,0 +1,105 @@
+import HeapBase, {HeapOptions} from './basics.js';
+
+/** Node used internally by {@link SkewHeap}. */
+export class SkewHeapNode<T = unknown> {
+  /** The stored value. */
+  value: T;
+  /** Left child, or `null`. */
+  left: SkewHeapNode<T> | null;
+  /** Right child, or `null`. */
+  right: SkewHeapNode<T> | null;
+
+  /** @param value - Value to store. */
+  constructor(value: T);
+
+  /** Reset children to `null`. */
+  clear(): void;
+
+  /**
+   * Create a deep copy of this subtree.
+   * @returns A new SkewHeapNode tree.
+   */
+  clone(): SkewHeapNode<T>;
+}
+
+/** Merge-based skew heap. */
+export class SkewHeap<T = unknown> extends HeapBase<T> {
+  /** Root node, or `null` if empty. */
+  root: SkewHeapNode<T> | null;
+  /** Number of elements. */
+  size: number;
+
+  /**
+   * @param options - Ordering functions.
+   * @param args - Initial heaps to merge.
+   */
+  constructor(options?: HeapOptions<T>, ...args: SkewHeap<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 skew heaps into this one, consuming them.
+   * @param args - Heaps to merge (they are cleared).
+   * @returns `this` for chaining.
+   */
+  merge(...args: SkewHeap<T>[]): this;
+
+  /**
+   * Create a deep copy of this heap.
+   * @returns A new SkewHeap with the same elements.
+   */
+  clone(): SkewHeap<T>;
+
+  /**
+   * Build a SkewHeap from an iterable.
+   * @param array - Iterable of values.
+   * @param options - Ordering functions.
+   * @returns A new SkewHeap.
+   */
+  static from<T = unknown>(array: Iterable<T>, options?: HeapOptions<T>): SkewHeap<T>;
+}
+
+export default SkewHeap;

package/src/heap/skew-heap.js

@@ -1,5 +1,3 @@
-'use strict';
-
 import HeapBase from './basics.js';
 
 const merge = (a, b, less) => {
@@ -14,14 +12,21 @@ const merge = (a, b, less) => {
   return a;
 };
 
+/** Node for a skew heap. */
 export class SkewHeapNode {
+  /** @param {*} value - Value to store. */
   constructor(value) {
     this.value = value;
     this.right = this.left = null;
   }
+  /** Reset child links. */
   clear() {
     this.left = this.right = null;
   }
+  /**
+   * Deep-clone this node and its subtree.
+   * @returns {SkewHeapNode} A new node tree.
+   */
   clone() {
     const node = new SkewHeapNode(this.value);
     node.left = this.left && this.left.clone();
@@ -30,7 +35,12 @@ export class SkewHeapNode {
   }
 }
 
+/** Skew heap — a self-adjusting merge-based min-heap. */
 export class SkewHeap extends HeapBase {
+  /**
+   * @param {object} [options] - Ordering options (`less`, `compare`).
+   * @param {...SkewHeap} args - Initial heaps to merge.
+   */
   constructor(options, ...args) {
     super(options);
     if (typeof this.compare == 'function') {
@@ -40,23 +50,36 @@ export class SkewHeap 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 SkewHeap#top|top}. */
   peek() {
     return this.root ? this.root.value : undefined;
   }
+  /**
+   * Add an element.
+   * @param {*} value - Element to add.
+   * @returns {SkewHeap} `this` for chaining.
+   */
   push(value) {
     this.root = merge(this.root, new SkewHeapNode(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;
@@ -64,6 +87,11 @@ export class SkewHeap 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;
@@ -71,6 +99,11 @@ export class SkewHeap 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 SkewHeapNode(value);
@@ -82,11 +115,20 @@ export class SkewHeap extends HeapBase {
     this.root = merge(this.root, z.right, this.less);
     return z.value;
   }
+  /**
+   * Remove all elements.
+   * @returns {SkewHeap} `this` for chaining.
+   */
   clear() {
     this.root = null;
     this.size = 0;
     return this;
   }
+  /**
+   * Merge one or more heaps into this heap, consuming them.
+   * @param {...SkewHeap} args - Heaps to merge.
+   * @returns {SkewHeap} `this` for chaining.
+   */
   merge(...args) {
     for (const other of args) {
       this.root = merge(this.root, other.root, this.less);
@@ -96,6 +138,10 @@ export class SkewHeap extends HeapBase {
     }
     return this;
   }
+  /**
+   * Create a deep copy of this heap.
+   * @returns {SkewHeap} A new SkewHeap with cloned nodes.
+   */
   clone() {
     const heap = new SkewHeap(this);
     heap.root = this.root && this.root.clone();
@@ -103,6 +149,12 @@ export class SkewHeap extends HeapBase {
     return heap;
   }
 
+  /**
+   * Build a SkewHeap from an iterable.
+   * @param {Iterable} array - Elements to insert.
+   * @param {object} [options] - Ordering options.
+   * @returns {SkewHeap} A new SkewHeap.
+   */
   static from(array, options = HeapBase.defaults) {
     const heap = new SkewHeap(options);
     for (const value of array) heap.push(value);

package/src/heap.d.ts

@@ -0,0 +1,3 @@
+export * from './heap/min-heap.js';
+import Heap from './heap/min-heap.js';
+export default Heap;

package/src/heap.js

@@ -1,5 +1,3 @@
-'use strict';
-
 export * from './heap/min-heap.js';
 import Heap from './heap/min-heap.js';
 

package/src/list/basics.d.ts

@@ -0,0 +1,43 @@
+import {DllOptions, DllRange} from './nodes.js';
+
+/** Result of extracting or popping nodes from a circular list. */
+export interface ExtractResult<T extends object> {
+  /** The extracted node (or first node of the extracted range). */
+  extracted: T;
+  /** The remaining circular list head, or `null` if nothing remains. */
+  rest: T | null;
+}
+
+/**
+ * Extract a range of nodes from a circular list.
+ * @param options - Link property names.
+ * @param range - Range to extract (`from` and optionally `to`).
+ * @returns The extracted circular sub-list and the remaining list.
+ */
+export function extract<T extends object>(options: DllOptions, range: DllRange<T>): ExtractResult<T>;
+
+/**
+ * Pop a single node out of its circular list.
+ * @param options - Link property names.
+ * @param node - Node to remove.
+ * @returns The popped node (now stand-alone) and the remaining list.
+ */
+export function pop<T extends object>(options: DllOptions, node: T): ExtractResult<T>;
+
+/**
+ * Splice a circular list into another list after a target node.
+ * @param options - Link property names.
+ * @param target - Node after which to insert.
+ * @param circularList - Head of the circular list to splice in.
+ * @returns The target node.
+ */
+export function splice<T extends object>(options: DllOptions, target: T, circularList: T): T;
+
+/**
+ * Extract a range and splice it after a target node in one operation.
+ * @param options - Link property names.
+ * @param target - Node after which to insert.
+ * @param range - Range to extract and append (`from` and optionally `to`).
+ * @returns The target node.
+ */
+export function append<T extends object>(options: DllOptions, target: T, range: DllRange<T>): T;

package/src/list/basics.js

@@ -1,7 +1,9 @@
-'use strict';
-
-// useful low-level operations on doubly linked lists
-
+/**
+ * Extract a range of nodes from a circular DLL.
+ * @param {object} options - Link property names.
+ * @param {object} range - Range descriptor with `from` and optional `to`.
+ * @returns {{extracted: object, rest: object|null}} The extracted sub-list and the remaining list.
+ */
 export const extract = ({nextName, prevName}, {from, to = from}) => {
   const next = to[nextName],
     prev = from[prevName];
@@ -17,8 +19,12 @@ export const extract = ({nextName, prevName}, {from, to = from}) => {
   return {extracted: from, rest: next === from ? null : next};
 };
 
-// pop(options, head).node === extract(options, {from: node})
-
+/**
+ * Pop a single node out of its circular DLL.
+ * @param {object} options - Link property names.
+ * @param {object} node - The node to pop.
+ * @returns {{extracted: object, rest: object|null}} The popped node (now stand-alone) and the remaining list.
+ */
 export const pop = ({nextName, prevName}, node) => {
   const next = node[nextName],
     prev = node[prevName];
@@ -33,6 +39,13 @@ export const pop = ({nextName, prevName}, node) => {
   return {extracted: node, rest: next === node ? null : next};
 };
 
+/**
+ * Splice a circular DLL into another list after a target node.
+ * @param {object} options - Link property names.
+ * @param {object} target - Node after which to insert.
+ * @param {object} circularList - Head of the circular list to splice in.
+ * @returns {object} The target node.
+ */
 export const splice = ({nextName, prevName}, target, circularList) => {
   const next = target[nextName],
     from = circularList,
@@ -47,8 +60,13 @@ export const splice = ({nextName, prevName}, target, circularList) => {
   return target;
 };
 
-// append(options, target, range) === splice(options, target, extract(options, range))
-
+/**
+ * Extract a range and splice it after a target node in one operation.
+ * @param {object} options - Link property names.
+ * @param {object} target - Node after which to insert.
+ * @param {object} range - Range descriptor with `from` and optional `to`.
+ * @returns {object} The target node.
+ */
 export const append = ({nextName, prevName}, target, {from, to = from}) => {
   // extract
   from[prevName][nextName] = to[nextName];

package/src/list/core.d.ts

@@ -0,0 +1,271 @@
+import {HeadNode, ExtListBase, PtrBase, DllOptions, DllRange} from './nodes.js';
+import {Ptr} from './ptr.js';
+
+/** Hosted node-based doubly linked list with a sentinel head. */
+export class List<T extends object = object> extends HeadNode {
+  /** The first node after the head. */
+  get front(): T;
+
+  /** The last node before the head. */
+  get back(): T;
+
+  /** A range spanning all nodes, or `null` if empty. */
+  get range(): DllRange<T> | null;
+
+  /** Pointer to the first node. */
+  get frontPtr(): Ptr<T>;
+
+  /** Pointer to the last node. */
+  get backPtr(): Ptr<T>;
+
+  /**
+   * Create a pointer to a node in this list.
+   * @param node - Target node, or `undefined` for the front.
+   * @returns A new Ptr.
+   */
+  makePtr(node?: T): Ptr<T>;
+
+  /**
+   * Create a pointer to the node after `prev`.
+   * @param prev - Preceding node, or `undefined` for the front.
+   * @returns A new Ptr.
+   */
+  makePtrFromPrev(prev?: T): Ptr<T>;
+
+  /**
+   * Insert a value at the front.
+   * @param value - Value or node to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  pushFront(value: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Insert a value at the back.
+   * @param value - Value or node to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  pushBack(value: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Remove and return the front node.
+   * @returns The removed node, or `undefined` if empty.
+   */
+  popFrontNode(): T | undefined;
+
+  /**
+   * Remove and return the back node.
+   * @returns The removed node, or `undefined` if empty.
+   */
+  popBackNode(): T | undefined;
+
+  /** Alias for {@link popFrontNode}. */
+  popFront(): T | undefined;
+
+  /** Alias for {@link popFrontNode}. */
+  pop(): T | undefined;
+
+  /** Alias for {@link popBackNode}. */
+  popBack(): T | undefined;
+
+  /**
+   * Insert an existing node at the front.
+   * @param nodeOrPtr - Node or pointer to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  pushFrontNode(nodeOrPtr: T | PtrBase<T>): Ptr<T>;
+
+  /** Alias for {@link pushFront}. */
+  push(value: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Insert an existing node at the back.
+   * @param nodeOrPtr - Node or pointer to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  pushBackNode(nodeOrPtr: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Move all nodes from another list to the front.
+   * @param list - Compatible list to consume.
+   * @returns A Ptr to the new front.
+   */
+  appendFront(list: HeadNode): Ptr<T>;
+
+  /**
+   * Move all nodes from another list to the back.
+   * @param list - Compatible list to consume.
+   * @returns A Ptr to the first appended node.
+   */
+  appendBack(list: HeadNode): Ptr<T>;
+
+  /** Alias for {@link appendBack}. */
+  append(list: HeadNode): Ptr<T>;
+
+  /**
+   * Move a node to the front of the list.
+   * @param nodeOrPtr - Node or pointer to move.
+   * @returns A Ptr to the front.
+   */
+  moveToFront(nodeOrPtr: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Move a node to the back of the list.
+   * @param nodeOrPtr - Node or pointer to move.
+   * @returns A Ptr to the back.
+   */
+  moveToBack(nodeOrPtr: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Remove all nodes.
+   * @param drop - If `true`, pop nodes one by one (making each stand-alone).
+   * @returns `this` for chaining.
+   */
+  clear(drop?: boolean): this;
+
+  /**
+   * Remove a single node from the list.
+   * @param nodeOrPtr - Node or pointer to remove.
+   * @returns The removed node.
+   */
+  removeNode(nodeOrPtr: T | PtrBase<T>): T;
+
+  /**
+   * Remove a range of nodes and optionally drop them.
+   * @param range - Range to remove.
+   * @param drop - If `true`, make each removed node stand-alone.
+   * @returns A new List containing the removed nodes.
+   */
+  removeRange(range?: DllRange<T>, drop?: boolean): List<T>;
+
+  /**
+   * Extract a range of nodes into a new list.
+   * @param range - Range to extract (defaults to the whole list).
+   * @returns A new List containing the extracted nodes.
+   */
+  extractRange(range?: DllRange<T>): List<T>;
+
+  /**
+   * Extract nodes that satisfy a condition into a new list.
+   * @param condition - Predicate receiving each node.
+   * @returns A new List containing the extracted nodes.
+   */
+  extractBy(condition: (node: T) => boolean): List<T>;
+
+  /**
+   * Reverse the order of all nodes in place.
+   * @returns `this` for chaining.
+   */
+  reverse(): this;
+
+  /**
+   * Sort nodes in place using merge sort.
+   * @param lessFn - Comparison function returning `true` if `a` should precede `b`.
+   * @returns `this` for chaining.
+   */
+  sort(lessFn: (a: T, b: T) => boolean): this;
+
+  /**
+   * Detach all nodes as a raw circular list (no sentinel).
+   * @returns Head of the raw circular list, or `null` if empty.
+   */
+  releaseRawList(): T | null;
+
+  /**
+   * Detach all nodes as a null-terminated list.
+   * @returns Object with `head` and `tail`, or `null` if empty.
+   */
+  releaseNTList(): {head: T; tail: T} | null;
+
+  /**
+   * Validate that a range is reachable within this list.
+   * @param range - Range to validate.
+   * @returns `true` if the range is valid.
+   */
+  validateRange(range?: DllRange<T>): boolean;
+
+  /** Iterate over nodes from front to back. */
+  [Symbol.iterator](): IterableIterator<T>;
+
+  /**
+   * Get an iterable over nodes in a range.
+   * @param range - Sub-range to iterate (defaults to the whole list).
+   * @returns An iterable iterator of nodes.
+   */
+  getNodeIterator(range?: DllRange<T>): IterableIterator<T>;
+
+  /** Alias for {@link getNodeIterator}. */
+  getIterator(range?: DllRange<T>): IterableIterator<T>;
+
+  /**
+   * Get an iterable of Ptr objects over a range.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of Ptrs.
+   */
+  getPtrIterator(range?: DllRange<T>): IterableIterator<Ptr<T>>;
+
+  /**
+   * Get an iterable over nodes in reverse order.
+   * @param range - Sub-range to iterate (defaults to the whole list).
+   * @returns An iterable iterator of nodes.
+   */
+  getReverseNodeIterator(range?: DllRange<T>): IterableIterator<T>;
+
+  /** Alias for {@link getReverseNodeIterator}. */
+  getReverseIterator(range?: DllRange<T>): IterableIterator<T>;
+
+  /**
+   * Get an iterable of Ptr objects in reverse order.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of Ptrs.
+   */
+  getReversePtrIterator(range?: DllRange<T>): IterableIterator<Ptr<T>>;
+
+  /**
+   * Create an empty list with the same options.
+   * @returns A new empty List.
+   */
+  make(): List<T>;
+
+  /**
+   * Create a list from values with the same options.
+   * @param values - Iterable of values.
+   * @returns A new List.
+   */
+  makeFrom(values: Iterable<T>): List<T>;
+
+  /**
+   * Create a list by extracting a range with the same options.
+   * @param range - Range to extract.
+   * @returns A new List.
+   */
+  makeFromRange(range: DllRange<T>): List<T>;
+
+  /**
+   * Build a list from an iterable.
+   * @param values - Iterable of values.
+   * @param options - Link property names.
+   * @returns A new List.
+   */
+  static from<T extends object = object>(values: Iterable<T>, options?: DllOptions): List<T>;
+
+  /**
+   * Build a list by extracting a range.
+   * @param range - Fully specified range.
+   * @param options - Link property names.
+   * @returns A new List.
+   */
+  static fromRange<T extends object = object>(range: DllRange<T> | null, options?: DllOptions): List<T>;
+
+  /**
+   * Convert an external list into a hosted list.
+   * @param extList - External list to consume (will be cleared).
+   * @returns A new List.
+   */
+  static fromExtList<T extends object = object>(extList: ExtListBase<T>): List<T>;
+
+  /** The Ptr class associated with this list type. */
+  static Ptr: typeof Ptr;
+}
+
+export {Ptr};
+export default List;