list-toolkit 2.2.5 → 2.3.0

package/src/slist/nodes.js

@@ -1,79 +1,143 @@
-'use strict';
-
 import {isRangeLike, normalizeNode, normalizeRange, normalizePtrRange} from '../list-helpers.js';
 import {addAlias, copyDescriptors, canHaveProps} from '../meta-utils.js';
 
+/**
+ * Check whether a node has a valid next link.
+ * @param {object} options - Link property names.
+ * @param {object} node - Node to check.
+ * @returns {boolean} `true` if the node has a truthy next link.
+ */
 export const isNodeLike = ({nextName}, node) => node && node[nextName];
+
+/**
+ * Check whether a node points to itself (stand-alone).
+ * @param {object} options - Link property names.
+ * @param {object} node - Node to check.
+ * @returns {boolean} `true` if the node's next link points to itself.
+ */
 export const isStandAlone = ({nextName}, node) => node && node[nextName] === node;
+
+/**
+ * Check whether two option sets share the same next link property name.
+ * @param {object} options1 - First options.
+ * @param {object} options2 - Second options.
+ * @returns {boolean} `true` if `nextName` matches.
+ */
 export const isCompatible = (options1, options2) => options1.nextName === options2.nextName;
 
+/** Singly linked list node with a circular self-link. */
 export class Node {
+  /** @param {object} [options] - Link property names. */
   constructor({nextName = 'next'} = {}) {
     this.nextName = nextName;
     this[nextName] = this;
   }
+  /** Whether this node's next link points to itself. */
   get isStandAlone() {
     return this[this.nextName] === this;
   }
 }
 
+/** Sentinel head node for hosted singly linked lists. */
 export class HeadNode extends Node {
+  /** @param {object} [options] - Link property names. */
   constructor(options) {
     super(options);
     this.last = this;
   }
+  /**
+   * Check whether a value looks like a compatible node.
+   * @param {*} node - Value to check.
+   * @returns {boolean} `true` if the value has a valid next link.
+   */
   isNodeLike(node) {
     if (!node) return false;
     const next = node[this.nextName];
     return next && canHaveProps[typeof next] === 1;
   }
+  /**
+   * Check whether another options object shares the same link name.
+   * @param {object} options - Options to compare.
+   * @returns {boolean} `true` if `nextName` matches.
+   */
   isCompatibleNames({nextName}) {
     return this.nextName === nextName;
   }
+  /**
+   * Check whether another list is compatible with this one.
+   * @param {object} list - List to compare.
+   * @returns {boolean} `true` if compatible.
+   */
   isCompatible(list) {
     return list === this || (list instanceof HeadNode && this.nextName === list.nextName);
   }
+  /**
+   * Check whether a pointer belongs to a compatible list.
+   * @param {PtrBase} ptr - Pointer to check.
+   * @returns {boolean} `true` if compatible.
+   */
   isCompatiblePtr(ptr) {
     return ptr instanceof PtrBase && (ptr.list === this || (ptr.list instanceof HeadNode && this.nextName === ptr.list.nextName));
   }
+  /**
+   * Check whether a range is compatible with this list.
+   * @param {object} [range] - Range to validate.
+   * @returns {boolean} `true` if compatible.
+   */
   isCompatibleRange(range) {
-    return isRangeLike(this, range);
+    return isRangeLike(this, range, PtrBase);
   }
 
+  /** Whether the list has no nodes. */
   get isEmpty() {
     return this[this.nextName] === this;
   }
 
+  /** Whether the list has exactly one node. */
   get isOne() {
     return this[this.nextName] !== this && this[this.nextName][this.nextName] === this;
   }
 
+  /** Whether the list has zero or one node. */
   get isOneOrEmpty() {
     return this[this.nextName][this.nextName] === this;
   }
 
+  /** The head sentinel itself. */
   get head() {
     return this;
   }
 
+  /** The first node after the head. */
   get front() {
     return this[this.nextName];
   }
 
+  /** The last node in the list. */
   get back() {
     return this.last;
   }
 
+  /** A range spanning all nodes, or `null` if empty. */
   get range() {
     return this[this.nextName] === this ? null : {from: this[this.nextName], to: this.last, list: this};
   }
 
+  /**
+   * Count the number of nodes.
+   * @returns {number} The node count.
+   */
   getLength() {
     let n = 0;
     for (let p = this[this.nextName]; p !== this; ++n, p = p[this.nextName]);
     return n;
   }
 
+  /**
+   * Adopt a node or pointer, making it stand-alone if needed.
+   * @param {object} nodeOrPtr - Node or pointer to adopt.
+   * @returns {object} The adopted node.
+   */
   adoptNode(nodeOrPtr) {
     const isPtr = nodeOrPtr instanceof PtrBase;
     if (isPtr && !this.isCompatiblePtr(nodeOrPtr)) throw new Error('Incompatible pointer');
@@ -90,20 +154,39 @@ export class HeadNode extends Node {
     return node;
   }
 
+  /**
+   * Normalize a node or pointer to a plain node.
+   * @param {object|null} nodeOrPtr - Node or pointer.
+   * @returns {object|null} The underlying node, or `null`.
+   */
   normalizeNode(nodeOrPtr) {
     const node = normalizeNode(this, nodeOrPtr, PtrBase);
     if (nodeOrPtr instanceof PtrBase) nodeOrPtr.list = this;
     return node;
   }
 
+  /**
+   * Normalize a range, resolving any pointers to nodes.
+   * @param {object} [range] - Range to normalize.
+   * @returns {object|null} The normalized range, or `null`.
+   */
   normalizeRange(range) {
     return normalizeRange(this, range, PtrBase);
   }
 
+  /**
+   * Normalize a pointer-based range.
+   * @param {object} [range] - Pointer range to normalize.
+   * @returns {object|null} The normalized pointer range, or `null`.
+   */
   normalizePtrRange(range) {
     return normalizePtrRange(this, range, PtrBase);
   }
 
+  /**
+   * Recalculate the `last` pointer by traversing the list.
+   * @returns {HeadNode} `this` for chaining.
+   */
   syncLast() {
     this.last = this;
     while (this.last[this.nextName] !== this) this.last = this.last[this.nextName];
@@ -113,14 +196,26 @@ export class HeadNode extends Node {
 
 addAlias(HeadNode.prototype, 'adoptNode', 'adoptValue');
 
+/** Value wrapper node for singly linked lists. */
 export class ValueNode extends Node {
+  /**
+   * @param {*} value - Value to wrap.
+   * @param {object} [options] - Link property names.
+   */
   constructor(value, options) {
     super(options);
     this.value = value;
   }
 }
 
+/** Base class for SLL pointers providing navigation. */
 export class PtrBase {
+  /**
+   * @param {PtrBase|HeadNode|ExtListBase} list - Owning list or another PtrBase to copy.
+   * @param {object} [node] - Target node.
+   * @param {object} [prev] - Node preceding the target.
+   * @param {Function} [ListClass] - Expected list constructor for validation.
+   */
   constructor(list, node, prev, ListClass) {
     if (list instanceof PtrBase) {
       this.list = list.list;
@@ -150,9 +245,14 @@ export class PtrBase {
       if (this.prevNode) this.node = this.prevNode[this.list.nextName];
     }
   }
+  /** The node after the current node. */
   get nextNode() {
     return this.node[this.list.nextName];
   }
+  /**
+   * Check whether the prevNode link is valid.
+   * @returns {boolean} `true` if prevNode's next points to the current node.
+   */
   isPrevNodeValid() {
     if (!this.prevNode) this.prevNode = this.node;
     if (this.prevNode[this.list.nextName] === this.node) return true;
@@ -165,16 +265,28 @@ export class PtrBase {
     this.prevNode = this.node;
     return false;
   }
+  /**
+   * Advance to the next node.
+   * @returns {PtrBase} `this` for chaining.
+   */
   next() {
     this.prevNode = this.node;
     this.node = this.node[this.list.nextName];
     return this;
   }
+  /**
+   * Move to the previous node (requires valid prevNode).
+   * @returns {PtrBase} `this` for chaining.
+   */
   prev() {
     if (!this.isPrevNodeValid()) throw new Error('Cannot get previous node: "prevNode" is invalid');
     this.node = this.prevNode;
     return this;
   }
+  /**
+   * Synchronize prevNode by traversing the list if needed.
+   * @returns {PtrBase} `this` for chaining.
+   */
   syncPrev() {
     if (this.isPrevNodeValid()) return this;
     this.prevNode = this.node;
@@ -187,7 +299,12 @@ export class PtrBase {
   }
 }
 
+/** Base class for external (headless) singly linked lists. */
 export class ExtListBase {
+  /**
+   * @param {object|ExtListBase|PtrBase|null} [head=null] - Initial head node, ExtListBase, or PtrBase.
+   * @param {object} [options] - Link property names.
+   */
   constructor(head = null, {nextName = 'next'} = {}) {
     if (head instanceof ExtListBase) {
       this.nextName = head.nextName;
@@ -203,34 +320,53 @@ export class ExtListBase {
     this.attach(head);
   }
 
+  /**
+   * Check whether another list is compatible.
+   * @param {object} list - List to compare.
+   * @returns {boolean} `true` if compatible.
+   */
   isCompatible(list) {
     return list === this || (list instanceof ExtListBase && this.nextName === list.nextName);
   }
 
+  /**
+   * Check whether a pointer belongs to a compatible list.
+   * @param {PtrBase} ptr - Pointer to check.
+   * @returns {boolean} `true` if compatible.
+   */
   isCompatiblePtr(ptr) {
     return ptr instanceof PtrBase && (ptr.list === this || (ptr.list instanceof ExtListBase && this.nextName === ptr.list.nextName));
   }
 
+  /** Whether the list has no nodes. */
   get isEmpty() {
     return !this.head;
   }
 
+  /** Whether the list has exactly one node. */
   get isOne() {
     return this.head && this.head[this.nextName] === this.head;
   }
 
+  /** Whether the list has zero or one node. */
   get isOneOrEmpty() {
     return !this.head || this.head[this.nextName] === this.head;
   }
 
+  /** The head node, or `null` if empty. */
   get front() {
     return this.head;
   }
 
+  /** A range spanning all nodes, or `null` if empty. */
   get range() {
     return this.head ? {from: this.head[this.nextName], to: this.head, list: this.head} : null;
   }
 
+  /**
+   * Count the number of nodes.
+   * @returns {number} The node count.
+   */
   getLength() {
     if (!this.head) return 0;
 
@@ -244,6 +380,10 @@ export class ExtListBase {
     return n;
   }
 
+  /**
+   * Find the last node by traversing the list.
+   * @returns {object|null} The last node, or `null` if empty.
+   */
   getBack() {
     if (!this.head) return null;
     for (let current = this.head; ; ) {
@@ -254,6 +394,11 @@ export class ExtListBase {
     // unreachable
   }
 
+  /**
+   * Set a new head node.
+   * @param {object|PtrBase|null} [head=null] - New head node, pointer, or `null`.
+   * @returns {object|null} The previous head node.
+   */
   attach(head = null) {
     const oldHead = this.head;
     if (head instanceof PtrBase) {
@@ -266,12 +411,20 @@ export class ExtListBase {
     return oldHead;
   }
 
+  /**
+   * Remove the head reference without modifying nodes.
+   * @returns {object|null} The previous head node.
+   */
   detach() {
     const oldHead = this.head;
     this.head = null;
     return oldHead;
   }
 
+  /**
+   * Advance the head to the next node.
+   * @returns {ExtListBase} `this` for chaining.
+   */
   next() {
     if (this.head) this.head = this.head[this.nextName];
     return this;

package/src/slist/ptr.d.ts

@@ -0,0 +1,73 @@
+import {HeadNode, PtrBase} from './nodes.js';
+
+/** Pointer for navigating and mutating a hosted singly linked list. */
+export class Ptr<T extends object = object> extends PtrBase<T> {
+  /** The hosted list this pointer belongs to. */
+  list: HeadNode;
+
+  /**
+   * @param list - Owning list or another Ptr to copy.
+   * @param node - Target node.
+   * @param prev - Preceding node.
+   */
+  constructor(list: HeadNode | Ptr<T>, node?: T | PtrBase<T>, prev?: T);
+
+  /** Whether the pointer is at the head sentinel. */
+  get isHead(): boolean;
+
+  /**
+   * Create a copy of this pointer.
+   * @returns A new Ptr referencing the same list and node.
+   */
+  clone(): Ptr<T>;
+
+  /**
+   * Remove the current node and advance to the next.
+   * @returns The removed node, or `null` if at head or single node.
+   */
+  removeCurrent(): T | null;
+
+  /**
+   * Insert a value before the current node.
+   * @param value - Value or node to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  addBefore(value: any): Ptr<T>;
+
+  /**
+   * Insert an existing node before the current node.
+   * @param node - Node to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  addNodeBefore(node: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Insert a value after the current node.
+   * @param value - Value or node to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  addAfter(value: any): Ptr<T>;
+
+  /**
+   * Insert an existing node after the current node.
+   * @param node - Node to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  addNodeAfter(node: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Splice another list's nodes before the current node.
+   * @param list - Compatible list to consume.
+   * @returns A Ptr to the first inserted node.
+   */
+  insertBefore(list: HeadNode): Ptr<T>;
+
+  /**
+   * Splice another list's nodes after the current node.
+   * @param list - Compatible list to consume.
+   * @returns A Ptr to the first inserted node.
+   */
+  insertAfter(list: HeadNode): Ptr<T>;
+}
+
+export default Ptr;

package/src/slist/ptr.js

@@ -1,19 +1,32 @@
-'use strict';
-
 import {HeadNode, PtrBase} from './nodes.js';
 import {pop, splice} from './basics.js';
 
+/** Pointer for navigating and mutating a hosted singly linked list. */
 export class Ptr extends PtrBase {
+  /**
+   * @param {HeadNode|Ptr} list - Owning list or another Ptr to copy.
+   * @param {object} [node] - Target node.
+   * @param {object} [prev] - Node preceding the target.
+   */
   constructor(list, node, prev) {
     super(list, node, prev, HeadNode);
   }
 
+  /** Whether the pointer is at the head sentinel. */
   get isHead() {
     return this.node === this.list;
   }
+  /**
+   * Create a copy of this pointer.
+   * @returns {Ptr} A new Ptr referencing the same list and node.
+   */
   clone() {
     return new Ptr(this);
   }
+  /**
+   * Remove the current node and advance to the next.
+   * @returns {object|null} The removed node, or `null` if at head.
+   */
   removeCurrent() {
     if (!this.isPrevNodeValid()) throw new Error('Current node cannot be removed: "prevNode" is invalid');
     if (this.node === this.list || this.node === this.prevNode) return null;
@@ -22,6 +35,11 @@ export class Ptr extends PtrBase {
     this.node = this.prevNode[this.list.nextName];
     return node;
   }
+  /**
+   * Insert a value before the current node.
+   * @param {*} value - Value or node to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   addBefore(value) {
     if (!this.isPrevNodeValid()) throw new Error('Cannot be added before: "prevNode" is invalid');
     const node = this.list.adoptValue(value),
@@ -30,6 +48,11 @@ export class Ptr extends PtrBase {
     if (this.list.last === this.list) this.list.last = node;
     return this.list.makePtr(prev);
   }
+  /**
+   * Insert an existing node before the current node.
+   * @param {object} node - Node to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   addNodeBefore(node) {
     if (!this.isPrevNodeValid()) throw new Error('Cannot be added before: "prevNode" is invalid');
     node = this.list.adoptNode(node);
@@ -38,16 +61,31 @@ export class Ptr extends PtrBase {
     if (this.list.last === this.list) this.list.last = node;
     return this.list.makePtr(prev);
   }
+  /**
+   * Insert a value after the current node.
+   * @param {*} value - Value or node to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   addAfter(value) {
     const node = this.list.adoptValue(value),
       prev = splice(this.list, this.node, {prevFrom: node});
     return this.list.makePtr(prev);
   }
+  /**
+   * Insert an existing node after the current node.
+   * @param {object} node - Node to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   addNodeAfter(node) {
     node = this.list.adoptNode(node);
     const prev = splice(this.list, this.node, {prevFrom: node});
     return this.list.makePtr(prev);
   }
+  /**
+   * Splice another list's nodes before the current node.
+   * @param {HeadNode} list - Compatible list to consume.
+   * @returns {Ptr} A Ptr to the first inserted node, or `this` if empty.
+   */
   insertBefore(list) {
     if (!this.isPrevNodeValid()) throw new Error('Cannot be inserted before: "prevNode" is invalid');
     if (!this.list.isCompatible(list)) throw new Error('Incompatible lists');
@@ -61,6 +99,11 @@ export class Ptr extends PtrBase {
 
     return this.list.makePtr(prev);
   }
+  /**
+   * Splice another list's nodes after the current node.
+   * @param {HeadNode} list - Compatible list to consume.
+   * @returns {Ptr} A Ptr to the first inserted node, or `this` if empty.
+   */
   insertAfter(list) {
     if (!this.list.isCompatible(list)) throw new Error('Incompatible lists');
     if (list.isEmpty) return this;