list-toolkit 2.2.6 → 2.3.0

package/src/slist/value.d.ts

@@ -0,0 +1,246 @@
+import {HeadNode, ValueNode, PtrBase, SllOptions, SllRange, SllPtrRange} from './nodes.js';
+import {Ptr} from './ptr.js';
+
+/**
+ * Hosted value-based singly linked list. Wraps values in {@link ValueNode}.
+ *
+ * Extends `SList` at runtime. Internally nodes are `ValueNode<V>`.
+ * The default iterator and `getIterator` yield unwrapped `V` values;
+ * use `getNodeIterator` for `ValueNode<V>` nodes.
+ */
+export class ValueSList<V = unknown> extends HeadNode {
+  /** Pointer to the first node. */
+  get frontPtr(): Ptr<ValueNode<V>>;
+
+  /** A pointer-based range spanning all nodes, or `null` if empty. */
+  get ptrRange(): SllPtrRange<ValueNode<V>> | null;
+
+  /**
+   * Create a pointer to a node in this list.
+   * @param node - Target node, or `undefined` for the front.
+   * @returns A new Ptr.
+   */
+  makePtr(node?: ValueNode<V>): Ptr<ValueNode<V>>;
+
+  /**
+   * Create a pointer to the node after `prev`.
+   * @param prev - Preceding node, or `undefined` for the front.
+   * @returns A new Ptr.
+   */
+  makePtrFromPrev(prev?: ValueNode<V>): Ptr<ValueNode<V>>;
+
+  /**
+   * Remove and return the front value.
+   * @returns The unwrapped value, or `undefined` if empty.
+   */
+  popFront(): V | undefined;
+
+  /** Alias for {@link popFront}. */
+  pop(): V | undefined;
+
+  /**
+   * Remove and return the front ValueNode.
+   * @returns The removed node, or `undefined` if empty.
+   */
+  popFrontNode(): ValueNode<V> | undefined;
+
+  /**
+   * Insert a value at the front.
+   * @param value - Raw value, ValueNode, or Ptr.
+   * @returns A Ptr to the front.
+   */
+  pushFront(value: V | ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /** Alias for {@link pushFront}. */
+  push(value: V | ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * Insert a value at the back.
+   * @param value - Raw value, ValueNode, or Ptr.
+   * @returns A Ptr to the inserted node.
+   */
+  pushBack(value: V | ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * Insert an existing ValueNode at the front.
+   * @param nodeOrPtr - ValueNode or pointer to insert.
+   * @returns A Ptr to the front.
+   */
+  pushFrontNode(nodeOrPtr: ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * Insert an existing ValueNode at the back.
+   * @param nodeOrPtr - ValueNode or pointer to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  pushBackNode(nodeOrPtr: ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * 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<ValueNode<V>>;
+
+  /**
+   * 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<ValueNode<V>>;
+
+  /** Alias for {@link appendBack}. */
+  append(list: HeadNode): Ptr<ValueNode<V>>;
+
+  /**
+   * Move a pointed-to node to the front.
+   * @param ptr - Pointer to the node to move.
+   * @returns A Ptr to the front, or `this` if at head.
+   */
+  moveToFront(ptr: PtrBase<ValueNode<V>>): Ptr<ValueNode<V>> | this;
+
+  /**
+   * Move a pointed-to node to the back.
+   * @param ptr - Pointer to the node to move.
+   * @returns A Ptr to the back, or `this` if at head.
+   */
+  moveToBack(ptr: PtrBase<ValueNode<V>>): Ptr<ValueNode<V>> | this;
+
+  /**
+   * Remove all nodes.
+   * @param drop - If `true`, make each removed node stand-alone.
+   * @returns `this` for chaining.
+   */
+  clear(drop?: boolean): this;
+
+  /**
+   * Remove a node via its pointer.
+   * @param ptr - Pointer to the node to remove.
+   * @returns The removed node, or `null` if at head.
+   */
+  removeNode(ptr: PtrBase<ValueNode<V>>): ValueNode<V> | null;
+
+  /**
+   * Remove a pointer-based range and optionally drop nodes.
+   * @param ptrRange - Range to remove.
+   * @param drop - If `true`, make each removed node stand-alone.
+   * @returns A new ValueSList containing the removed values.
+   */
+  removeRange(ptrRange?: SllPtrRange<ValueNode<V>>, drop?: boolean): ValueSList<V>;
+
+  /**
+   * Extract a pointer-based range into a new list.
+   * @param ptrRange - Range to extract (defaults to the whole list).
+   * @returns A new ValueSList containing the extracted values.
+   */
+  extractRange(ptrRange?: SllPtrRange<ValueNode<V>>): ValueSList<V>;
+
+  /**
+   * Extract nodes that satisfy a condition into a new list.
+   * @param condition - Predicate receiving each ValueNode.
+   * @returns A new ValueSList containing the extracted values.
+   */
+  extractBy(condition: (node: ValueNode<V>) => boolean): ValueSList<V>;
+
+  /**
+   * Reverse the order of all nodes in place.
+   * @returns `this` for chaining.
+   */
+  reverse(): this;
+
+  /**
+   * Sort nodes in place using merge sort.
+   * @param lessFn - Comparison receiving ValueNodes, returns `true` if `a` should precede `b`.
+   * @returns `this` for chaining.
+   */
+  sort(lessFn: (a: ValueNode<V>, b: ValueNode<V>) => boolean): this;
+
+  /**
+   * Detach all nodes as a raw circular list.
+   * @returns Head of the raw circular list, or `null` if empty.
+   */
+  releaseRawList(): ValueNode<V> | null;
+
+  /**
+   * Detach all nodes as a null-terminated list.
+   * @returns Object with `head` and `tail`, or `null` if empty.
+   */
+  releaseNTList(): { head: ValueNode<V>; tail: ValueNode<V> } | null;
+
+  /**
+   * Validate that a range is reachable within this list.
+   * @param range - Range to validate.
+   * @returns `true` if the range is valid.
+   */
+  validateRange(range?: SllRange<ValueNode<V>>): boolean;
+
+  /**
+   * Adopt a value, pointer, or ValueNode into this list.
+   * @param value - Raw value, Ptr, or ValueNode.
+   * @returns A ValueNode ready for insertion.
+   */
+  adoptValue(value: V | ValueNode<V> | PtrBase<ValueNode<V>>): ValueNode<V>;
+
+  /** Iterate over unwrapped values from front to back. */
+  [Symbol.iterator](): IterableIterator<V>;
+
+  /**
+   * Get an iterable over ValueNodes in a range.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of ValueNodes.
+   */
+  getNodeIterator(range?: SllRange<ValueNode<V>>): IterableIterator<ValueNode<V>>;
+
+  /**
+   * Get an iterable over unwrapped values in a range.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of values.
+   */
+  getValueIterator(range?: SllRange<ValueNode<V>>): IterableIterator<V>;
+
+  /** Alias for {@link getValueIterator}. */
+  getIterator(range?: SllRange<ValueNode<V>>): IterableIterator<V>;
+
+  /**
+   * Get an iterable of Ptr objects over a pointer range.
+   * @param ptrRange - Sub-range to iterate.
+   * @returns An iterable iterator of Ptrs.
+   */
+  getPtrIterator(ptrRange?: SllPtrRange<ValueNode<V>>): IterableIterator<Ptr<ValueNode<V>>>;
+
+  /**
+   * Create a shallow clone of this list.
+   * @returns A new ValueSList with the same values.
+   */
+  clone(): ValueSList<V>;
+
+  /**
+   * Create an empty list with the same options.
+   * @returns A new empty ValueSList.
+   */
+  make(): ValueSList<V>;
+
+  /**
+   * Create a list from values with the same options.
+   * @param values - Iterable of values.
+   * @returns A new ValueSList.
+   */
+  makeFrom(values: Iterable<V>): ValueSList<V>;
+
+  /**
+   * Build a ValueSList from an iterable.
+   * @param values - Iterable of values.
+   * @param options - Link property names.
+   * @returns A new ValueSList.
+   */
+  static from<V = unknown>(values: Iterable<V>, options?: SllOptions): ValueSList<V>;
+
+  /** The Ptr class associated with this list type. */
+  static Ptr: typeof Ptr;
+
+  /** The ValueNode class used by this list type. */
+  static ValueNode: typeof ValueNode;
+}
+
+export { ValueNode, Ptr };
+export default ValueSList;

package/src/slist/value.js

@@ -1,14 +1,25 @@
-'use strict';
-
 import List, {Ptr} from './core.js';
 import {ValueNode} from './nodes.js';
 import {addAliases, mapIterator, normalizeIterator} from '../meta-utils.js';
 
+/**
+ * Hosted value-based singly linked list. Wraps values in {@link ValueNode}.
+ * Iterators yield unwrapped values; use `getNodeIterator` for ValueNode access.
+ */
 export class ValueSList extends List {
+  /**
+   * Remove and return the front value.
+   * @returns {*} The unwrapped value, or `undefined` if empty.
+   */
   popFront() {
     return this.popFrontNode()?.value;
   }
 
+  /**
+   * Adopt a value, pointer, or ValueNode into this list.
+   * @param {*} value - Raw value, Ptr, or ValueNode.
+   * @returns {ValueNode} A ValueNode ready for insertion.
+   */
   adoptValue(value) {
     if (value instanceof Ptr) {
       if (!this.isCompatiblePtr(value)) throw new Error('Incompatible pointer');
@@ -25,8 +36,7 @@ export class ValueSList extends List {
     return new ValueNode(value, this);
   }
 
-  // iterators
-
+  /** Iterate over unwrapped values from front to back. */
   [Symbol.iterator]() {
     let current = this[this.nextName],
       readyToStop = this.isEmpty;
@@ -41,24 +51,46 @@ export class ValueSList extends List {
     });
   }
 
+  /**
+   * Get an iterable over unwrapped values in a range.
+   * @param {object} [range] - Sub-range to iterate.
+   * @returns {Iterable} An iterable iterator of values.
+   */
   getValueIterator(range) {
     return mapIterator(this.getNodeIterator(range), node => node.value);
   }
 
-  // meta helpers
-
+  /**
+   * Create a shallow clone of this list.
+   * @returns {ValueSList} A new ValueSList with the same values.
+   */
   clone() {
     return ValueSList.from(this, this);
   }
 
+  /**
+   * Create an empty list with the same options.
+   * @returns {ValueSList} A new empty ValueSList.
+   */
   make() {
     return new ValueSList(this);
   }
 
+  /**
+   * Create a list from values with the same options.
+   * @param {Iterable} values - Iterable of values.
+   * @returns {ValueSList} A new ValueSList.
+   */
   makeFrom(values) {
     return ValueSList.from(values, this);
   }
 
+  /**
+   * Build a ValueSList from an iterable.
+   * @param {Iterable} values - Iterable of values.
+   * @param {object} [options] - Link property names.
+   * @returns {ValueSList} A new ValueSList.
+   */
   static from(values, options) {
     const list = new ValueSList(options);
     for (const value of values) list.pushBack(value);

package/src/slist.d.ts

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

package/src/slist.js

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

package/src/stack.d.ts

@@ -0,0 +1,59 @@
+/** LIFO stack backed by a value list. */
+export class Stack<V = unknown> {
+  /** Number of elements in the stack. */
+  size: number;
+
+  /**
+   * @param UnderlyingList - Optional value list constructor to use (default: ValueList).
+   */
+  constructor(UnderlyingList?: new () => object);
+
+  /** Whether the stack has no elements. */
+  get isEmpty(): boolean;
+
+  /** The top element without removing it, or `undefined` if empty. */
+  get top(): V | undefined;
+
+  /** Alias for {@link top}. */
+  peek(): V | undefined;
+
+  /**
+   * Push a value onto the top of the stack.
+   * @param value - Value to push.
+   * @returns `this` for chaining.
+   */
+  push(value: V): this;
+
+  /** Alias for {@link push}. */
+  pushFront(value: V): this;
+
+  /**
+   * Remove and return the top value.
+   * @returns The top value, or `undefined` if empty.
+   */
+  pop(): V | undefined;
+
+  /**
+   * Push multiple values onto the stack.
+   * @param values - Iterable of values.
+   * @returns `this` for chaining.
+   */
+  pushValues(values: Iterable<V>): this;
+
+  /**
+   * Remove all elements.
+   * @returns `this` for chaining.
+   */
+  clear(): this;
+
+  /** Iterate over values from top to bottom. */
+  [Symbol.iterator](): IterableIterator<V>;
+
+  /**
+   * Iterate over values from bottom to top.
+   * @returns An iterable iterator.
+   */
+  getReverseIterator(): IterableIterator<V>;
+}
+
+export default Stack;

package/src/stack.js

@@ -1,47 +1,73 @@
-'use strict';
-
 import ValueList from './value-list.js';
 import {addAlias} from './meta-utils.js';
 import {pushValuesFront} from './list-utils.js';
 
+/** LIFO stack backed by a value list. */
 export class Stack {
+  /** @param {Function} [UnderlyingList=ValueList] - Constructor for the backing list. */
   constructor(UnderlyingList = ValueList) {
     this.size = 0;
     this.list = new UnderlyingList();
   }
+  /** Whether the stack has no elements. */
   get isEmpty() {
     return this.list.isEmpty;
   }
+  /** The top element without removing it, or `undefined` if empty. */
   get top() {
     return this.list.isEmpty ? undefined : this.list.front.value;
   }
+  /** Alias for {@link Stack#top|top}. */
   peek() {
     return this.list.isEmpty ? undefined : this.list.front.value;
   }
+  /**
+   * Push a value onto the stack.
+   * @param {*} value - Value to push.
+   * @returns {Stack} `this` for chaining.
+   */
   push(value) {
     this.list.pushFront(value);
     ++this.size;
     return this;
   }
+  /**
+   * Remove and return the top value.
+   * @returns {*} The popped value, or `undefined` if empty.
+   */
   pop() {
     if (!this.list.isEmpty) {
       --this.size;
-      return this.list.popFront().value;
+      return this.list.popFront();
     }
     // return undefined;
   }
+  /**
+   * Push multiple values onto the stack.
+   * @param {Iterable} values - Values to push.
+   * @returns {Stack} `this` for chaining.
+   */
   pushValues(values) {
     pushValuesFront(this, values);
     return this;
   }
+  /**
+   * Remove all elements.
+   * @returns {Stack} `this` for chaining.
+   */
   clear() {
     this.list.clear();
     this.size = 0;
     return this;
   }
+  /** Iterate over values from top to bottom. */
   [Symbol.iterator]() {
     return this.list[Symbol.iterator]();
   }
+  /**
+   * Get an iterable over values in reverse (bottom-to-top) order.
+   * @returns {Iterable} An iterable iterator of values.
+   */
   getReverseIterator() {
     return this.list.getReverseIterator?.();
   }

package/src/tree/splay-tree.d.ts

@@ -0,0 +1,151 @@
+/** Options for configuring splay tree ordering. */
+export interface SplayTreeOptions<T = unknown> {
+  /** Returns `true` if `a` should be ordered before `b`. */
+  less?: (a: T, b: T) => boolean;
+  /** Comparison function returning negative, zero, or positive. Overrides `less` when set. */
+  compare?: ((a: T, b: T) => number) | null;
+}
+
+/** Node used internally by {@link SplayTree}. */
+export class SplayTreeNode<T = unknown> {
+  /** The stored value. */
+  value: T;
+  /** Left child, or `null`. */
+  left: SplayTreeNode<T> | null;
+  /** Right child, or `null`. */
+  right: SplayTreeNode<T> | null;
+  /** Parent node, or `null` for the root. */
+  parent: SplayTreeNode<T> | null;
+
+  /** @param value - Value to store. */
+  constructor(value: T);
+
+  /**
+   * Find the minimum node in this subtree.
+   * @returns The leftmost descendant.
+   */
+  getMin(): SplayTreeNode<T>;
+
+  /**
+   * Find the maximum node in this subtree.
+   * @returns The rightmost descendant.
+   */
+  getMax(): SplayTreeNode<T>;
+}
+
+/** Self-adjusting binary search tree. */
+export class SplayTree<T = unknown> {
+  /** Returns `true` if `a` should be ordered before `b`. */
+  less: (a: T, b: T) => boolean;
+  /** Comparison function, or `null` if using `less`. */
+  compare: ((a: T, b: T) => number) | null;
+  /** Root node, or `null` if empty. */
+  root: SplayTreeNode<T> | null;
+  /** Number of elements. */
+  size: number;
+
+  /** @param options - Ordering functions. */
+  constructor(options?: SplayTreeOptions<T>);
+
+  /** Whether the tree has no elements. */
+  get isEmpty(): boolean;
+
+  /** Number of elements. */
+  get length(): number;
+
+  /**
+   * Find the node with the minimum value.
+   * @returns The minimum node.
+   */
+  getMin(): SplayTreeNode<T>;
+
+  /**
+   * Find the node with the maximum value.
+   * @returns The maximum node.
+   */
+  getMax(): SplayTreeNode<T>;
+
+  /**
+   * Find a node by value.
+   * @param value - Value to search for.
+   * @returns The matching node, or `null` if not found.
+   */
+  find(value: T): SplayTreeNode<T> | null;
+
+  /**
+   * Find and splay a node to the root.
+   * @param value - Value to search for and promote.
+   * @returns The matching node, or `null` if not found.
+   */
+  promote(value: T): SplayTreeNode<T> | null;
+
+  /**
+   * Splay a given node to the root.
+   * @param node - Node to splay.
+   * @returns `this` for chaining.
+   */
+  splay(node: SplayTreeNode<T>): this;
+
+  /**
+   * Insert a value. If the value already exists, it is splayed to the root.
+   * @param value - Value to insert.
+   * @returns `this` for chaining.
+   */
+  insert(value: T): this;
+
+  /**
+   * Remove a value from the tree.
+   * @param value - Value to remove.
+   * @returns `this` for chaining.
+   */
+  remove(value: T): this;
+
+  /**
+   * Remove all elements.
+   * @returns `this` for chaining.
+   */
+  clear(): this;
+
+  /**
+   * Split the tree: values ≤ `value` stay, values > `value` go to the returned tree.
+   * @param value - Split point.
+   * @returns A new SplayTree containing values greater than `value`.
+   */
+  splitMaxTree(value: T): SplayTree<T>;
+
+  /**
+   * Join another tree into this one (unsafe: assumes all values in `tree` are greater).
+   * @param tree - Tree to join (cleared after joining).
+   * @returns `this` for chaining.
+   */
+  joinMaxTreeUnsafe(tree: SplayTree<T>): this;
+
+  /**
+   * Join another tree into this one. Falls back to individual inserts if ranges overlap.
+   * @param tree - Tree to join (cleared after joining).
+   * @returns `this` for chaining.
+   */
+  join(tree: SplayTree<T>): this;
+
+  /** Iterate over values in ascending order. */
+  [Symbol.iterator](): IterableIterator<T>;
+
+  /**
+   * Iterate over values in descending order.
+   * @returns An iterable iterator.
+   */
+  getReverseIterator(): IterableIterator<T>;
+
+  /**
+   * Build a SplayTree from an iterable.
+   * @param values - Iterable of values to insert.
+   * @param options - Ordering functions.
+   * @returns A new SplayTree.
+   */
+  static from<T = unknown>(values: Iterable<T>, options?: SplayTreeOptions<T>): SplayTree<T>;
+
+  /** Default ordering functions. */
+  static defaults: SplayTreeOptions;
+}
+
+export default SplayTree;