list-toolkit 2.2.5 → 2.3.0

package/src/list/core.js

@@ -1,61 +1,105 @@
-'use strict';
-
 import {ExtListBase, HeadNode} from './nodes.js';
 import {pop, splice, append} from './basics.js';
 import Ptr from './ptr.js';
 import {addAliases, mapIterator, normalizeIterator} from '../meta-utils.js';
 
+/** Hosted node-based doubly linked list with a sentinel head. */
 export class List extends HeadNode {
+  /** Pointer to the first node. */
   get frontPtr() {
     return new Ptr(this, this.front);
   }
 
+  /** Pointer to the last node. */
   get backPtr() {
     return new Ptr(this, this.back);
   }
 
+  /**
+   * Create a pointer to a node in this list.
+   * @param {object} [node] - Target node, or `undefined` for the front.
+   * @returns {Ptr} A new Ptr.
+   */
   makePtr(node) {
     if (node && !this.isNodeLike(node)) throw new Error('"node" is not a compatible node');
     return new Ptr(this, node || this.front);
   }
 
+  /**
+   * Create a pointer to the node after `prev`.
+   * @param {object} [prev] - Preceding node, or `undefined` for the front.
+   * @returns {Ptr} A new Ptr.
+   */
   makePtrFromPrev(prev) {
     if (prev && !this.isNodeLike(prev)) throw new Error('"prev" is not a compatible node');
     return new Ptr(this, prev ? prev[this.nextName] : this.front);
   }
 
+  /**
+   * Insert a value at the front.
+   * @param {*} value - Node or value to insert.
+   * @returns {Ptr} A Ptr to the front.
+   */
   pushFront(value) {
     const node = this.adoptValue(value);
     splice(this, this, node);
     return this.makePtr(node);
   }
 
+  /**
+   * Insert a value at the back.
+   * @param {*} value - Node or value to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   pushBack(value) {
     const node = this.adoptValue(value);
     splice(this, this[this.prevName], node);
     return this.makePtr(node);
   }
 
+  /**
+   * Remove and return the front node.
+   * @returns {object|undefined} The removed node, or `undefined` if empty.
+   */
   popFrontNode() {
     if (!this.isEmpty) return pop(this, this[this.nextName]).extracted;
   }
 
+  /**
+   * Remove and return the back node.
+   * @returns {object|undefined} The removed node, or `undefined` if empty.
+   */
   popBackNode() {
     if (!this.isEmpty) return pop(this, this[this.prevName]).extracted;
   }
 
+  /**
+   * Insert an existing node at the front.
+   * @param {object} nodeOrPtr - Node or pointer to insert.
+   * @returns {Ptr} A Ptr to the front.
+   */
   pushFrontNode(nodeOrPtr) {
     const node = this.adoptNode(nodeOrPtr);
     splice(this, this, node);
     return this.makePtr(node);
   }
 
+  /**
+   * Insert an existing node at the back.
+   * @param {object} nodeOrPtr - Node or pointer to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   pushBackNode(nodeOrPtr) {
     const node = this.adoptNode(nodeOrPtr);
     splice(this, this[this.prevName], node);
     return this.makePtr(node);
   }
 
+  /**
+   * Move all nodes from another list to the front.
+   * @param {HeadNode} list - Compatible list to consume.
+   * @returns {Ptr} A Ptr to the new front.
+   */
   appendFront(list) {
     if (!this.isCompatible(list)) throw new Error('Incompatible lists');
     if (list.isEmpty) return this;
@@ -66,6 +110,11 @@ export class List extends HeadNode {
     return this.makePtr();
   }
 
+  /**
+   * Move all nodes from another list to the back.
+   * @param {HeadNode} list - Compatible list to consume.
+   * @returns {Ptr} A Ptr to the first appended node.
+   */
   appendBack(list) {
     if (!this.isCompatible(list)) throw new Error('Incompatible lists');
     if (list.isEmpty) return this;
@@ -76,6 +125,11 @@ export class List extends HeadNode {
     return this.makePtr(head);
   }
 
+  /**
+   * Move a node to the front.
+   * @param {object} nodeOrPtr - Node or pointer to move.
+   * @returns {Ptr} A Ptr to the front.
+   */
   moveToFront(nodeOrPtr) {
     const node = this.normalizeNode(nodeOrPtr);
     if (this[this.nextName] !== node) {
@@ -84,6 +138,11 @@ export class List extends HeadNode {
     return this.frontPtr;
   }
 
+  /**
+   * Move a node to the back.
+   * @param {object} nodeOrPtr - Node or pointer to move.
+   * @returns {Ptr} A Ptr to the back.
+   */
   moveToBack(nodeOrPtr) {
     const node = this.normalizeNode(nodeOrPtr);
     if (this[this.prevName] !== node) {
@@ -92,6 +151,11 @@ export class List extends HeadNode {
     return this.backPtr;
   }
 
+  /**
+   * Remove all nodes.
+   * @param {boolean} [drop] - If `true`, make each removed node stand-alone.
+   * @returns {List} `this` for chaining.
+   */
   clear(drop) {
     if (drop) {
       while (!this.isEmpty) this.popFrontNode();
@@ -101,14 +165,30 @@ export class List extends HeadNode {
     return this;
   }
 
+  /**
+   * Remove a node from the list.
+   * @param {object} nodeOrPtr - Node or pointer to remove.
+   * @returns {object} The removed node.
+   */
   removeNode(nodeOrPtr) {
     return pop(this, this.normalizeNode(nodeOrPtr)).extracted;
   }
 
+  /**
+   * Remove a range and optionally drop nodes.
+   * @param {object} [range] - Range to remove.
+   * @param {boolean} [drop] - If `true`, make each removed node stand-alone.
+   * @returns {List} A new List containing the removed nodes.
+   */
   removeRange(range, drop) {
     return this.extractRange(range).clear(drop);
   }
 
+  /**
+   * Extract a range into a new list.
+   * @param {object} [range={}] - Range to extract (defaults to the whole list).
+   * @returns {List} A new List containing the extracted nodes.
+   */
   extractRange(range = {}) {
     range = this.normalizeRange(range);
     range.from ||= this.front;
@@ -116,11 +196,16 @@ export class List extends HeadNode {
     return append(this, this.make(), range);
   }
 
+  /**
+   * Extract nodes that satisfy a condition into a new list.
+   * @param {Function} condition - Predicate receiving each node.
+   * @returns {List} A new List containing the extracted nodes.
+   */
   extractBy(condition) {
     const extracted = this.make();
     if (this.isEmpty) return extracted;
 
-    while (this.isEmpty && condition(this.front)) extracted.pushBack(this.popFront());
+    while (!this.isEmpty && condition(this.front)) extracted.pushBack(this.popFrontNode());
     if (this.isOneOrEmpty) return extracted;
 
     for (const ptr of this.getPtrIterator({from: this.front[this.nextName]})) {
@@ -130,6 +215,10 @@ export class List extends HeadNode {
     return extracted;
   }
 
+  /**
+   * Reverse the order of all nodes in place.
+   * @returns {List} `this` for chaining.
+   */
   reverse() {
     let current = this;
     do {
@@ -141,6 +230,11 @@ export class List extends HeadNode {
     return this;
   }
 
+  /**
+   * Sort nodes in place using merge sort.
+   * @param {Function} lessFn - Returns `true` if `a` should precede `b`.
+   * @returns {List} `this` for chaining.
+   */
   sort(lessFn) {
     if (this.isOneOrEmpty) return this;
 
@@ -167,10 +261,18 @@ export class List extends HeadNode {
     return this;
   }
 
+  /**
+   * Detach all nodes as a raw circular list.
+   * @returns {object|null} Head of the raw circular list, or `null` if empty.
+   */
   releaseRawList() {
     return this.isEmpty ? null : pop(this, this).rest;
   }
 
+  /**
+   * Detach all nodes as a null-terminated list.
+   * @returns {{head: object, tail: object}|null} Object with `head` and `tail`, or `null` if empty.
+   */
   releaseNTList() {
     if (this.isEmpty) return null;
     const head = this[this.nextName],
@@ -180,6 +282,11 @@ export class List extends HeadNode {
     return {head, tail};
   }
 
+  /**
+   * Validate that a range is reachable within this list.
+   * @param {object} [range={}] - Range to validate.
+   * @returns {boolean} `true` if the range is valid.
+   */
   validateRange(range = {}) {
     range = this.normalizeRange(range);
     let current = range.from;
@@ -190,8 +297,7 @@ export class List extends HeadNode {
     return true;
   }
 
-  // iterators
-
+  /** Iterate over nodes from front to back. */
   [Symbol.iterator]() {
     let current = this[this.nextName],
       readyToStop = this.isEmpty;
@@ -206,6 +312,11 @@ export class List extends HeadNode {
     });
   }
 
+  /**
+   * Get an iterable over nodes in a range.
+   * @param {object} [range={}] - Sub-range to iterate.
+   * @returns {Iterable} An iterable iterator of nodes.
+   */
   getNodeIterator(range = {}) {
     range = this.normalizeRange(range);
     const {from, to} = range;
@@ -227,10 +338,20 @@ export class List extends HeadNode {
     };
   }
 
+  /**
+   * Get an iterable of Ptr objects over a range.
+   * @param {object} [range] - Sub-range to iterate.
+   * @returns {Iterable} An iterable iterator of Ptrs.
+   */
   getPtrIterator(range) {
     return mapIterator(this.getNodeIterator(range), node => new Ptr(this, node));
   }
 
+  /**
+   * Get an iterable over nodes in reverse order.
+   * @param {object} [range={}] - Sub-range to iterate.
+   * @returns {Iterable} An iterable iterator of nodes.
+   */
   getReverseNodeIterator(range = {}) {
     range = this.normalizeRange(range);
     const {from, to} = range;
@@ -252,30 +373,59 @@ export class List extends HeadNode {
     };
   }
 
+  /**
+   * Get an iterable of Ptr objects in reverse order.
+   * @param {object} [range] - Sub-range to iterate.
+   * @returns {Iterable} An iterable iterator of Ptrs.
+   */
   getReversePtrIterator(range) {
     return mapIterator(this.getReverseNodeIterator(range), node => new Ptr(this, node));
   }
 
-  // meta helpers
-
+  /**
+   * Create an empty list with the same options.
+   * @returns {List} A new empty List.
+   */
   make() {
     return new List(this);
   }
 
+  /**
+   * Create a list from values with the same options.
+   * @param {Iterable} values - Iterable of node objects.
+   * @returns {List} A new List.
+   */
   makeFrom(values) {
     return List.from(values, this);
   }
 
+  /**
+   * Create a list from a range with the same options.
+   * @param {object} range - Range to copy.
+   * @returns {List} A new List.
+   */
   makeFromRange(range) {
     return List.fromRange(range, this);
   }
 
+  /**
+   * Build a List from an iterable of node objects.
+   * @param {Iterable} values - Iterable of nodes.
+   * @param {object} [options] - Link property names.
+   * @returns {List} A new List.
+   */
   static from(values, options) {
     const list = new List(options);
     for (const value of values) list.pushBack(value);
     return list;
   }
 
+  /**
+   * Build a List from a range.
+   * @param {object} range - Range to copy.
+   * @param {object} [options] - Link property names.
+   * @returns {List} A new List.
+   */
   static fromRange(range, options) {
     const list = new List(options);
     if (!range) return list;
@@ -286,6 +436,11 @@ export class List extends HeadNode {
     return append(list, list, range);
   }
 
+  /**
+   * Build a List from an external list, consuming it.
+   * @param {ExtListBase} extList - External list to consume.
+   * @returns {List} A new List.
+   */
   static fromExtList(extList) {
     if (!(extList instanceof ExtListBase)) throw new Error('Not a circular list');
 

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

@@ -0,0 +1,253 @@
+import {ExtListBase, ValueNode, PtrBase, DllOptions, DllRange} from './nodes.js';
+import {Ptr} from './ext.js';
+
+/**
+ * External (headless) value-based doubly linked list. Wraps values in {@link ValueNode}.
+ *
+ * Extends `ExtList` at runtime. Internally nodes are `ValueNode<V>`.
+ * The default iterator and `getIterator`/`getReverseIterator` yield
+ * unwrapped `V` values; use `getNodeIterator`/`getReverseNodeIterator`
+ * for `ValueNode<V>` nodes.
+ */
+export class ExtValueList<V = unknown> extends ExtListBase<ValueNode<V>> {
+  /**
+   * Create a pointer to a node in this list.
+   * @param node - Target node, or `undefined` for the head.
+   * @returns A new Ptr, or `null` if the list is empty and no node given.
+   */
+  makePtr(node?: ValueNode<V>): Ptr<ValueNode<V>> | null;
+
+  /**
+   * 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 the current head node and advance to the next.
+   * @returns The removed node, or `null` if empty.
+   */
+  removeCurrent(): ValueNode<V> | null;
+
+  /**
+   * Remove the node before the head.
+   * @returns The removed node, or `null` if empty.
+   */
+  removeNodeBefore(): ValueNode<V> | null;
+
+  /** Alias for {@link removeNodeBefore}. */
+  removeBefore(): ValueNode<V> | null;
+
+  /**
+   * Remove the node after the head.
+   * @returns The removed node, or `null` if empty.
+   */
+  removeNodeAfter(): ValueNode<V> | null;
+
+  /** Alias for {@link removeNodeAfter}. */
+  removeAfter(): ValueNode<V> | null;
+
+  /**
+   * 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>;
+
+  /**
+   * Insert a value after the head.
+   * @param value - Raw value, ValueNode, or Ptr.
+   * @returns A Ptr to the inserted node.
+   */
+  addAfter(value: V | ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /** Alias for {@link addAfter}. */
+  add(value: V | ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * Insert a value before the head.
+   * @param value - Raw value, ValueNode, or Ptr.
+   * @returns A Ptr to the inserted node.
+   */
+  addBefore(value: V | ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * Insert an existing node before the head.
+   * @param nodeOrPtr - ValueNode or pointer to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  addNodeBefore(nodeOrPtr: ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * Insert an existing node after the head.
+   * @param nodeOrPtr - ValueNode or pointer to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  addNodeAfter(nodeOrPtr: ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * Splice another list's nodes before the head.
+   * @param extList - Compatible external list to consume.
+   * @returns A Ptr to the first inserted node, or `null` if empty.
+   */
+  insertBefore(extList: ExtValueList<V>): Ptr<ValueNode<V>> | null;
+
+  /**
+   * Splice another list's nodes after the head.
+   * @param extList - Compatible external list to consume.
+   * @returns A Ptr to the first inserted node, or `null` if empty.
+   */
+  insertAfter(extList: ExtValueList<V>): Ptr<ValueNode<V>> | null;
+
+  /**
+   * Move a node to just before the head.
+   * @param nodeOrPtr - Node or pointer to move.
+   * @returns A Ptr to the moved node, or `this` if already at head.
+   */
+  moveBefore(nodeOrPtr: ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>> | this;
+
+  /**
+   * Move a node to just after the head.
+   * @param nodeOrPtr - Node or pointer to move.
+   * @returns A Ptr to the moved node, or `this` if already at head.
+   */
+  moveAfter(nodeOrPtr: ValueNode<V> | 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 single node from the list.
+   * @param nodeOrPtr - Node or pointer to remove.
+   * @returns The removed node, or `null` if empty.
+   */
+  removeNode(nodeOrPtr: ValueNode<V> | PtrBase<ValueNode<V>>): ValueNode<V> | null;
+
+  /**
+   * 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 ExtValueList containing the removed values.
+   */
+  removeRange(range?: DllRange<ValueNode<V>>, drop?: boolean): ExtValueList<V>;
+
+  /**
+   * Extract a range of nodes into a new list.
+   * @param range - Range to extract (defaults to the whole list).
+   * @returns A new ExtValueList containing the extracted values.
+   */
+  extractRange(range?: DllRange<ValueNode<V>>): ExtValueList<V>;
+
+  /**
+   * Extract nodes that satisfy a condition into a new list.
+   * @param condition - Predicate receiving each ValueNode.
+   * @returns A new ExtValueList containing the extracted values.
+   */
+  extractBy(condition: (node: ValueNode<V>) => boolean): ExtValueList<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;
+
+  /** Iterate over unwrapped values starting from the head. */
+  [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?: DllRange<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?: DllRange<ValueNode<V>>): IterableIterator<V>;
+
+  /** Alias for {@link getValueIterator}. */
+  getIterator(range?: DllRange<ValueNode<V>>): IterableIterator<V>;
+
+  /**
+   * Get an iterable over ValueNodes in reverse order.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of ValueNodes.
+   */
+  getReverseNodeIterator(range?: DllRange<ValueNode<V>>): IterableIterator<ValueNode<V>>;
+
+  /**
+   * Get an iterable over unwrapped values in reverse order.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of values.
+   */
+  getReverseValueIterator(range?: DllRange<ValueNode<V>>): IterableIterator<V>;
+
+  /** Alias for {@link getReverseValueIterator}. */
+  getReverseIterator(range?: DllRange<ValueNode<V>>): IterableIterator<V>;
+
+  /**
+   * Get an iterable of Ptr objects over a range.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of Ptrs.
+   */
+  getPtrIterator(range?: DllRange<ValueNode<V>>): IterableIterator<Ptr<ValueNode<V>>>;
+
+  /**
+   * Get an iterable of Ptr objects in reverse order.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of Ptrs.
+   */
+  getReversePtrIterator(range?: DllRange<ValueNode<V>>): IterableIterator<Ptr<ValueNode<V>>>;
+
+  /**
+   * Create a shallow clone of this list.
+   * @returns A new ExtValueList pointing to the same head.
+   */
+  clone(): ExtValueList<V>;
+
+  /**
+   * Create an empty list with the same options.
+   * @param head - Optional initial head node.
+   * @returns A new ExtValueList.
+   */
+  make(head?: ValueNode<V> | null): ExtValueList<V>;
+
+  /**
+   * Create a list from values with the same options.
+   * @param values - Iterable of values.
+   * @returns A new ExtValueList.
+   */
+  makeFrom(values: Iterable<V>): ExtValueList<V>;
+
+  /**
+   * Build an ExtValueList from an iterable.
+   * @param values - Iterable of values.
+   * @param options - Link property names.
+   * @returns A new ExtValueList.
+   */
+  static from<V = unknown>(values: Iterable<V>, options?: DllOptions): ExtValueList<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};
+export default ExtValueList;

package/src/list/ext-value.js

@@ -1,10 +1,17 @@
-'use strict';
-
 import ExtList, {Ptr} from './ext.js';
 import {ValueNode} from './nodes.js';
 import {addAliases, mapIterator, normalizeIterator} from '../meta-utils.js';
 
+/**
+ * External (headless) value-based doubly linked list. Wraps values in {@link ValueNode}.
+ * Iterators yield unwrapped values; use `getNodeIterator` for ValueNode access.
+ */
 export class ExtValueList extends ExtList {
+  /**
+   * 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');
@@ -21,8 +28,7 @@ export class ExtValueList extends ExtList {
     return new ValueNode(value, this);
   }
 
-  // iterators
-
+  /** Iterate over unwrapped values starting from the head. */
   [Symbol.iterator]() {
     let current = this.head,
       readyToStop = this.isEmpty;
@@ -37,28 +43,56 @@ export class ExtValueList extends ExtList {
     });
   }
 
+  /**
+   * 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);
   }
 
+  /**
+   * Get an iterable over unwrapped values in reverse order.
+   * @param {object} [range] - Sub-range to iterate.
+   * @returns {Iterable} An iterable iterator of values.
+   */
   getReverseValueIterator(range) {
     return mapIterator(this.getReverseNodeIterator(range), node => node.value);
   }
 
-  // meta helpers
-
+  /**
+   * Create a shallow clone of this list.
+   * @returns {ExtValueList} A new ExtValueList pointing to the same head.
+   */
   clone() {
     return new ExtValueList(this);
   }
 
+  /**
+   * Create an empty list with the same options.
+   * @param {object|null} [head=null] - Optional initial head node.
+   * @returns {ExtValueList} A new ExtValueList.
+   */
   make(head = null) {
     return new ExtValueList(head, this);
   }
 
+  /**
+   * Create a list from values with the same options.
+   * @param {Iterable} values - Iterable of values.
+   * @returns {ExtValueList} A new ExtValueList.
+   */
   makeFrom(values) {
     return ExtValueList.from(values, this);
   }
 
+  /**
+   * Build an ExtValueList from an iterable.
+   * @param {Iterable} values - Iterable of values.
+   * @param {object} [options] - Link property names.
+   * @returns {ExtValueList} A new ExtValueList.
+   */
   static from(values, options) {
     const list = new ExtValueList(null, options);
     for (const value of values) {