list-toolkit 2.2.5 → 2.3.0

package/src/list/ext.d.ts

@@ -0,0 +1,242 @@
+import {ExtListBase, PtrBase, DllOptions, DllRange} from './nodes.js';
+
+/** Pointer for navigating and mutating an external (headless) DLL. */
+export class Ptr<T extends object = object> extends PtrBase<T> {
+  /** The external list this pointer belongs to. */
+  list: ExtList<T>;
+
+  /**
+   * @param list - Owning list or another Ptr to copy.
+   * @param node - Target node.
+   */
+  constructor(list: ExtList<T> | Ptr<T>, node?: T);
+
+  /**
+   * Create a copy of this pointer.
+   * @returns A new Ptr referencing the same list and node.
+   */
+  clone(): Ptr<T>;
+}
+
+/** External (headless) node-based doubly linked list. */
+export class ExtList<T extends object = object> extends ExtListBase<T> {
+  /**
+   * 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?: T): Ptr<T> | null;
+
+  /**
+   * 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>;
+
+  // Ptr-style API
+
+  /**
+   * Remove the current head node and advance to the next.
+   * @returns The removed node, or `null` if empty.
+   */
+  removeCurrent(): T | null;
+
+  /**
+   * Remove the node before the head.
+   * @returns The removed node, or `null` if empty.
+   */
+  removeNodeBefore(): T | null;
+
+  /** Alias for {@link removeNodeBefore}. */
+  removeBefore(): T | null;
+
+  /**
+   * Remove the node after the head.
+   * @returns The removed node, or `null` if empty.
+   */
+  removeNodeAfter(): T | null;
+
+  /** Alias for {@link removeNodeAfter}. */
+  removeAfter(): T | null;
+
+  /**
+   * Insert a value before the head.
+   * @param value - Value or node to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  addBefore(value: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Insert a value after the head.
+   * @param value - Value or node to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  addAfter(value: T | PtrBase<T>): Ptr<T>;
+
+  /** Alias for {@link addAfter}. */
+  add(value: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Insert an existing node before the head.
+   * @param nodeOrPtr - Node or pointer to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  addNodeBefore(nodeOrPtr: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Insert an existing node after the head.
+   * @param nodeOrPtr - Node or pointer to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  addNodeAfter(nodeOrPtr: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Splice another external 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: ExtList<T>): Ptr<T> | null;
+
+  /**
+   * Splice another external 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: ExtList<T>): Ptr<T> | 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: T | PtrBase<T>): Ptr<T> | 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: T | PtrBase<T>): Ptr<T> | this;
+
+  // List-style API
+
+  /**
+   * 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: T | PtrBase<T>): T | 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 ExtList containing the removed nodes.
+   */
+  removeRange(range?: DllRange<T>, drop?: boolean): ExtList<T>;
+
+  /**
+   * Extract a range of nodes into a new list.
+   * @param range - Range to extract (defaults to the whole list).
+   * @returns A new ExtList containing the extracted nodes.
+   */
+  extractRange(range?: DllRange<T>): ExtList<T>;
+
+  /**
+   * Extract nodes that satisfy a condition into a new list.
+   * @param condition - Predicate receiving each node.
+   * @returns A new ExtList containing the extracted nodes.
+   */
+  extractBy(condition: (node: T) => boolean): ExtList<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;
+
+  /** Iterate over nodes starting from the head. */
+  [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 a shallow clone of this list (shares nodes).
+   * @returns A new ExtList pointing to the same head.
+   */
+  clone(): ExtList<T>;
+
+  /**
+   * Create an empty list with the same options.
+   * @param head - Optional initial head node.
+   * @returns A new ExtList.
+   */
+  make(head?: T | null): ExtList<T>;
+
+  /**
+   * Create a list from values with the same options.
+   * @param values - Iterable of node objects.
+   * @returns A new ExtList.
+   */
+  makeFrom(values: Iterable<T>): ExtList<T>;
+
+  /**
+   * Build an ExtList from an iterable of node objects.
+   * @param values - Iterable of nodes.
+   * @param options - Link property names.
+   * @returns A new ExtList.
+   */
+  static from<T extends object = object>(values: Iterable<T>, options?: DllOptions): ExtList<T>;
+
+  /** The Ptr class associated with this list type. */
+  static Ptr: typeof Ptr;
+}
+
+export default ExtList;

package/src/list/ext.js

@@ -1,33 +1,53 @@
-'use strict';
-
 import {ExtListBase, PtrBase} from './nodes.js';
 import {pop, extract, splice, append} from './basics.js';
 import {addAliases, normalizeIterator} from '../meta-utils.js';
 
+/** Pointer for navigating and mutating an external doubly linked list. */
 export class Ptr extends PtrBase {
+  /**
+   * @param {ExtList|Ptr} list - Owning list or another Ptr to copy.
+   * @param {object} [node] - Target node.
+   */
   constructor(list, node) {
     super(list, node, ExtList);
     this.node ||= this.list.head;
   }
+  /**
+   * Create a copy of this pointer.
+   * @returns {Ptr} A new Ptr referencing the same list and node.
+   */
   clone() {
     return new Ptr(this);
   }
 }
 
+/** External (headless) node-based doubly linked list. */
 export class ExtList extends ExtListBase {
+  /**
+   * Create a pointer to a node in this list.
+   * @param {object} [node] - Target node, or `undefined` for the head.
+   * @returns {Ptr|null} A new Ptr, or `null` if the list is empty and no node given.
+   */
   makePtr(node) {
     if (node && !this.isNodeLike(node)) throw new Error('"node" is not a compatible node');
     node ||= this.head;
     return node ? new Ptr(this, node) : null;
   }
 
+  /**
+   * 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);
   }
 
-  // Ptr API
-
+  /**
+   * Remove the current head node and advance to the next.
+   * @returns {object|null} The removed node, or `null` if empty.
+   */
   removeCurrent() {
     if (!this.head) return null;
     if (this.head[this.nextName] === this.head) {
@@ -40,14 +60,27 @@ export class ExtList extends ExtListBase {
     return result.extracted;
   }
 
+  /**
+   * Remove the node before the head.
+   * @returns {object|null} The removed node, or `null` if empty.
+   */
   removeNodeBefore() {
     return this.head ? this.removeNode(this.head[this.prevName]) : null;
   }
 
+  /**
+   * Remove the node after the head.
+   * @returns {object|null} The removed node, or `null` if empty.
+   */
   removeNodeAfter() {
     return this.head ? this.removeNode(this.head[this.nextName]) : null;
   }
 
+  /**
+   * Insert a value before the head.
+   * @param {*} value - Value or node to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   addBefore(value) {
     const node = this.adoptValue(value);
     if (this.head) {
@@ -58,6 +91,11 @@ export class ExtList extends ExtListBase {
     return this.makePtr(node);
   }
 
+  /**
+   * Insert a value after the head.
+   * @param {*} value - Value or node to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   addAfter(value) {
     const node = this.adoptValue(value);
     if (this.head) {
@@ -68,6 +106,11 @@ export class ExtList extends ExtListBase {
     return this.makePtr(node);
   }
 
+  /**
+   * Insert an existing node before the head.
+   * @param {object} nodeOrPtr - Node or pointer to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   addNodeBefore(nodeOrPtr) {
     const node = this.adoptNode(nodeOrPtr);
     if (this.head) {
@@ -78,6 +121,11 @@ export class ExtList extends ExtListBase {
     return this.makePtr(node);
   }
 
+  /**
+   * Insert an existing node after the head.
+   * @param {object} nodeOrPtr - Node or pointer to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   addNodeAfter(nodeOrPtr) {
     const node = this.adoptNode(nodeOrPtr);
     if (this.head) {
@@ -88,6 +136,11 @@ export class ExtList extends ExtListBase {
     return this.makePtr(node);
   }
 
+  /**
+   * Splice another external list's nodes before the head.
+   * @param {ExtListBase} extList - Compatible external list to consume.
+   * @returns {Ptr|null} A Ptr to the first inserted node, or `null` if empty.
+   */
   insertBefore(extList) {
     if (!this.isCompatible(extList)) throw new Error('Incompatible lists');
 
@@ -100,6 +153,11 @@ export class ExtList extends ExtListBase {
     return this.makePtr(head);
   }
 
+  /**
+   * Splice another external list's nodes after the head.
+   * @param {ExtListBase} extList - Compatible external list to consume.
+   * @returns {Ptr|null} A Ptr to the first inserted node, or `null` if empty.
+   */
   insertAfter(extList) {
     if (!this.isCompatible(extList)) throw new Error('Incompatible lists');
 
@@ -112,6 +170,11 @@ export class ExtList extends ExtListBase {
     return this.makePtr(head);
   }
 
+  /**
+   * Move a node to just before the head.
+   * @param {object} nodeOrPtr - Node or pointer to move.
+   * @returns {Ptr|ExtList} A Ptr to the moved node, or `this` if already at head.
+   */
   moveBefore(nodeOrPtr) {
     const node = this.normalizeNode(nodeOrPtr);
 
@@ -130,6 +193,11 @@ export class ExtList extends ExtListBase {
     return this.makePtr(node);
   }
 
+  /**
+   * Move a node to just after the head.
+   * @param {object} nodeOrPtr - Node or pointer to move.
+   * @returns {Ptr|ExtList} A Ptr to the moved node, or `this` if already at head.
+   */
   moveAfter(nodeOrPtr) {
     const node = this.normalizeNode(nodeOrPtr);
 
@@ -148,8 +216,11 @@ export class ExtList extends ExtListBase {
     return this.makePtr(node);
   }
 
-  // List API
-
+  /**
+   * Remove all nodes.
+   * @param {boolean} [drop] - If `true`, make each removed node stand-alone.
+   * @returns {ExtList} `this` for chaining.
+   */
   clear(drop) {
     if (drop) {
       for (const current of this.getNodeIterator()) {
@@ -160,6 +231,11 @@ export class ExtList extends ExtListBase {
     return this;
   }
 
+  /**
+   * Remove a node from the list.
+   * @param {object} nodeOrPtr - Node or pointer to remove.
+   * @returns {object|null} The removed node, or `null` if empty.
+   */
   removeNode(nodeOrPtr) {
     if (!this.head) return null;
 
@@ -178,10 +254,21 @@ export class ExtList extends ExtListBase {
     return pop(this, node).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 {ExtList} A new ExtList 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 {ExtList} A new ExtList containing the extracted nodes.
+   */
   extractRange(range = {}) {
     range = this.normalizeRange(range);
     const {from = this.head, to = from} = range;
@@ -195,6 +282,11 @@ export class ExtList extends ExtListBase {
     return extracted;
   }
 
+  /**
+   * Extract nodes that satisfy a condition into a new list.
+   * @param {Function} condition - Predicate receiving each node.
+   * @returns {ExtList} A new ExtList containing the extracted nodes.
+   */
   extractBy(condition) {
     const extracted = this.make();
     if (this.isEmpty) return extracted;
@@ -209,6 +301,10 @@ export class ExtList extends ExtListBase {
     return extracted;
   }
 
+  /**
+   * Reverse the order of all nodes in place.
+   * @returns {ExtList} `this` for chaining.
+   */
   reverse() {
     if (this.isOneOrEmpty) return this;
     let current = this.head;
@@ -222,6 +318,11 @@ export class ExtList extends ExtListBase {
     return this;
   }
 
+  /**
+   * Sort nodes in place using merge sort.
+   * @param {Function} lessFn - Returns `true` if `a` should precede `b`.
+   * @returns {ExtList} `this` for chaining.
+   */
   sort(lessFn) {
     if (this.isOneOrEmpty) return this;
 
@@ -267,8 +368,7 @@ export class ExtList extends ExtListBase {
     return this.next();
   }
 
-  // iterators
-
+  /** Iterate over nodes starting from the head. */
   [Symbol.iterator]() {
     let current = this.head,
       readyToStop = this.isEmpty;
@@ -283,6 +383,11 @@ export class ExtList extends ExtListBase {
     });
   }
 
+  /**
+   * 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;
@@ -304,10 +409,20 @@ export class ExtList extends ExtListBase {
     };
   }
 
+  /**
+   * 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;
@@ -329,24 +444,47 @@ export class ExtList extends ExtListBase {
     };
   }
 
+  /**
+   * 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 a shallow clone of this list.
+   * @returns {ExtList} A new ExtList pointing to the same head.
+   */
   clone() {
     return new ExtList(this);
   }
 
+  /**
+   * Create an empty list with the same options.
+   * @param {object|null} [head=null] - Optional initial head node.
+   * @returns {ExtList} A new ExtList.
+   */
   make(head = null) {
     return new ExtList(head, this);
   }
 
+  /**
+   * Create a list from values with the same options.
+   * @param {Iterable} values - Iterable of node objects.
+   * @returns {ExtList} A new ExtList.
+   */
   makeFrom(values) {
     return ExtList.from(values, this);
   }
 
+  /**
+   * Build an ExtList from an iterable of node objects.
+   * @param {Iterable} values - Iterable of nodes.
+   * @param {object} [options] - Link property names.
+   * @returns {ExtList} A new ExtList.
+   */
   static from(values, options) {
     const list = new ExtList(null, options);
     for (const value of values) {