list-toolkit 2.2.6 → 2.3.1

package/src/slist/ext.js

@@ -1,39 +1,66 @@
-'use strict';
-
 import {ExtListBase, PtrBase} from './nodes.js';
 import {pop, extract, splice} from './basics.js';
 import {addAliases, normalizeIterator} from '../meta-utils.js';
 
+/** Pointer for navigating and mutating an external singly linked list. */
 export class Ptr extends PtrBase {
+  /**
+   * @param {ExtSList|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, ExtSList);
   }
+  /**
+   * 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 singly linked list. */
 export class ExtSList extends ExtListBase {
+  /** A pointer-based range spanning all nodes, or `null` if empty. */
   get ptrRange() {
     return this.head ? {from: this.makePtr(), to: this.head, list: this.head} : null;
   }
 
+  /**
+   * Create a pointer to a node in this list.
+   * @param {object} [node] - Target node, or `undefined` for the head.
+   * @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);
   }
 
+  /**
+   * Create a pointer to the node after `prev`.
+   * @param {object} [prev] - Preceding node, or `undefined` for the head.
+   * @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, null, prev || this.head);
   }
 
-  // Ptr API
-
+  /**
+   * Remove the node after the head.
+   * @returns {object|null} The removed node, or `null` if empty.
+   */
   removeNodeAfter() {
     return this.head ? this.removeNode(this.makePtr()) : null;
   }
 
+  /**
+   * 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) {
@@ -44,6 +71,11 @@ export class ExtSList extends ExtListBase {
     return this.makePtr();
   }
 
+  /**
+   * Insert an existing node after the head.
+   * @param {object} node - Node to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   addNodeAfter(node) {
     node = this.adoptNode(node);
     if (this.head) {
@@ -54,6 +86,11 @@ export class ExtSList extends ExtListBase {
     return this.makePtr();
   }
 
+  /**
+   * Splice another external list's nodes after the head.
+   * @param {ExtListBase} extList - Compatible external list to consume.
+   * @returns {Ptr} A Ptr to the first inserted node.
+   */
   insertAfter(extList) {
     if (!this.isCompatible(extList)) throw new Error('Incompatible lists');
 
@@ -66,6 +103,11 @@ export class ExtSList extends ExtListBase {
     return this.makePtr();
   }
 
+  /**
+   * Move a node to just after the head.
+   * @param {Ptr} ptr - Pointer to the node to move.
+   * @returns {Ptr|ExtSList} A Ptr to the moved node, or `this`.
+   */
   moveAfter(ptr) {
     if (!this.isCompatiblePtr(ptr)) throw new Error('Incompatible pointer');
     ptr.list = this;
@@ -87,8 +129,11 @@ export class ExtSList extends ExtListBase {
     return ptr.clone();
   }
 
-  // List API
-
+  /**
+   * Remove all nodes.
+   * @param {boolean} [drop] - If `true`, make each removed node stand-alone.
+   * @returns {ExtSList} `this` for chaining.
+   */
   clear(drop) {
     if (drop) {
       for (const current of this.getNodeIterator()) {
@@ -99,6 +144,11 @@ export class ExtSList extends ExtListBase {
     return this;
   }
 
+  /**
+   * Remove the node at a pointer position.
+   * @param {Ptr} ptr - Pointer whose current node to remove.
+   * @returns {object|null} The removed node, or `null` if empty.
+   */
   removeNode(ptr) {
     if (!this.head) return null;
     if (!this.isCompatiblePtr(ptr)) throw new Error('Incompatible pointer');
@@ -112,10 +162,21 @@ export class ExtSList extends ExtListBase {
     return pop(this, ptr.prevNode).extracted.to;
   }
 
+  /**
+   * Remove a pointer-based range and optionally drop nodes.
+   * @param {object} [ptrRange] - Range to remove.
+   * @param {boolean} [drop] - If `true`, make each removed node stand-alone.
+   * @returns {ExtSList} A new ExtSList containing the removed nodes.
+   */
   removeRange(ptrRange, drop) {
     return this.extractRange(ptrRange).clear(drop);
   }
 
+  /**
+   * Extract a pointer-based range into a new list.
+   * @param {object} [ptrRange={}] - Range to extract (defaults to the whole list).
+   * @returns {ExtSList} A new ExtSList containing the extracted nodes.
+   */
   extractRange(ptrRange = {}) {
     ptrRange = this.normalizePtrRange(ptrRange.from ? ptrRange : {...ptrRange, from: this.makePtr()});
     ptrRange.to ||= this.head;
@@ -131,6 +192,11 @@ export class ExtSList extends ExtListBase {
     return extracted;
   }
 
+  /**
+   * Extract nodes that satisfy a condition into a new list.
+   * @param {Function} condition - Predicate receiving each node.
+   * @returns {ExtSList} A new ExtSList containing the extracted nodes.
+   */
   extractBy(condition) {
     const extracted = this.make();
     if (this.isEmpty) return extracted;
@@ -154,6 +220,10 @@ export class ExtSList extends ExtListBase {
     return extracted;
   }
 
+  /**
+   * Reverse the order of all nodes in place.
+   * @returns {ExtSList} `this` for chaining.
+   */
   reverse() {
     if (this.isOneOrEmpty) return this;
 
@@ -172,6 +242,11 @@ export class ExtSList extends ExtListBase {
     return this;
   }
 
+  /**
+   * Sort nodes in place using merge sort.
+   * @param {Function} lessFn - Returns `true` if `a` should precede `b`.
+   * @returns {ExtSList} `this` for chaining.
+   */
   sort(lessFn) {
     if (this.isOneOrEmpty) return this;
 
@@ -237,8 +312,7 @@ export class ExtSList extends ExtListBase {
     return this.next();
   }
 
-  // iterators
-
+  /** Iterate over nodes starting from the head. */
   [Symbol.iterator]() {
     let current = this.head,
       readyToStop = this.isEmpty;
@@ -253,6 +327,11 @@ export class ExtSList 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;
@@ -274,15 +353,20 @@ export class ExtSList extends ExtListBase {
     };
   }
 
-  getPtrIterator(range) {
-    if (!ptrRange.from) ptrRange = Object.assign({from: this.frontPtr}, ptrRange);
+  /**
+   * Get an iterable of Ptr objects over a pointer range.
+   * @param {object} [ptrRange={}] - Sub-range to iterate.
+   * @returns {Iterable} An iterable iterator of Ptrs.
+   */
+  getPtrIterator(ptrRange = {}) {
+    if (!ptrRange.from) ptrRange = Object.assign({from: this.makePtr(this.head)}, ptrRange);
     ptrRange = this.normalizePtrRange(ptrRange);
     const {from: fromPtr, to} = ptrRange;
     return {
       [Symbol.iterator]: () => {
         let current = fromPtr.clone(),
           readyToStop = this.isEmpty;
-        const stop = to ? to[this.nextName] : this;
+        const stop = to ? to[this.nextName] : this.head;
         return normalizeIterator({
           next: () => {
             if (readyToStop && current.node === stop) return {done: true};
@@ -296,20 +380,38 @@ export class ExtSList extends ExtListBase {
     };
   }
 
-  // meta helpers
-
+  /**
+   * Create a shallow clone of this list.
+   * @returns {ExtSList} A new ExtSList pointing to the same head.
+   */
   clone() {
     return new ExtSList(this);
   }
 
+  /**
+   * Create an empty list with the same options.
+   * @param {object|null} [head=null] - Optional initial head node.
+   * @returns {ExtSList} A new ExtSList.
+   */
   make(head = null) {
     return new ExtSList(head, this);
   }
 
+  /**
+   * Create a list from values with the same options.
+   * @param {Iterable} values - Iterable of node objects.
+   * @returns {ExtSList} A new ExtSList.
+   */
   makeFrom(values) {
     return ExtSList.from(values, this);
   }
 
+  /**
+   * Build an ExtSList from an iterable of node objects.
+   * @param {Iterable} values - Iterable of nodes.
+   * @param {object} [options] - Link property names.
+   * @returns {ExtSList} A new ExtSList.
+   */
   static from(values, options) {
     const list = new ExtSList(null, options);
     for (const value of values) {

package/src/slist/nodes.d.ts

@@ -0,0 +1,361 @@
+/** Options for configuring SLL link property names. */
+export interface SllOptions {
+  /** Property name used for the next link. */
+  nextName?: string;
+}
+
+/** A range of nodes in a singly linked list. */
+export interface SllRange<T extends object = object> {
+  /** First node of the range (or a Ptr). */
+  from?: T | PtrBase<T>;
+  /** Last node of the range (or a Ptr). */
+  to?: T | PtrBase<T>;
+  /** Owning list for validation. */
+  list?: HeadNode | ExtListBase<T>;
+}
+
+/** A pointer-based range where `from` must be a Ptr. */
+export interface SllPtrRange<T extends object = object> {
+  /** Pointer to the first node. */
+  from: PtrBase<T>;
+  /** Last node of the range (or a Ptr). */
+  to?: T | PtrBase<T>;
+  /** Owning list for validation. */
+  list?: HeadNode | ExtListBase<T>;
+}
+
+/**
+ * Check whether a node has a valid next link.
+ * @param options - Link property names.
+ * @param node - Node to check.
+ * @returns `true` if the node has a truthy next link.
+ */
+export function isNodeLike<T extends object>(options: SllOptions, node: T): boolean;
+
+/**
+ * Check whether a node points to itself (stand-alone).
+ * @param options - Link property names.
+ * @param node - Node to check.
+ * @returns `true` if the node's next link points to itself.
+ */
+export function isStandAlone<T extends object>(options: SllOptions, node: T): boolean;
+
+/**
+ * Check whether two option sets share the same link property name.
+ * @param options1 - First options.
+ * @param options2 - Second options.
+ * @returns `true` if `nextName` matches.
+ */
+export function isCompatible(options1: SllOptions, options2: SllOptions): boolean;
+
+/** Singly linked list node with a circular self-link. */
+export class Node {
+  /** Property name for the next link. */
+  nextName: string;
+
+  /** @param options - Link property names. */
+  constructor(options?: SllOptions);
+
+  /** Whether this node's next link points to itself. */
+  get isStandAlone(): boolean;
+}
+
+/** Sentinel head node for hosted singly linked lists. */
+export class HeadNode extends Node {
+  /** Pointer to the last node in the list. */
+  last: Node | object;
+
+  /** @param options - Link property names. */
+  constructor(options?: SllOptions);
+
+  /**
+   * Check whether a value looks like a compatible node.
+   * @param node - Value to check.
+   * @returns `true` if the value has a valid next link.
+   */
+  isNodeLike(node: unknown): boolean;
+
+  /**
+   * Check whether another options object shares the same link names.
+   * @param options - Options to compare.
+   * @returns `true` if `nextName` matches.
+   */
+  isCompatibleNames(options: SllOptions): boolean;
+
+  /**
+   * Check whether another list is compatible with this one.
+   * @param list - List to compare.
+   * @returns `true` if compatible.
+   */
+  isCompatible(list: HeadNode | ExtListBase): boolean;
+
+  /**
+   * Check whether a pointer belongs to a compatible list.
+   * @param ptr - Pointer to check.
+   * @returns `true` if compatible.
+   */
+  isCompatiblePtr(ptr: PtrBase): boolean;
+
+  /**
+   * Check whether a range is compatible with this list.
+   * @param range - Range to validate.
+   * @returns `true` if compatible.
+   */
+  isCompatibleRange<T extends object>(range: SllRange<T>): boolean;
+
+  /** Whether the list has no nodes. */
+  get isEmpty(): boolean;
+
+  /** Whether the list has exactly one node. */
+  get isOne(): boolean;
+
+  /** Whether the list has zero or one node. */
+  get isOneOrEmpty(): boolean;
+
+  /** The head sentinel itself. */
+  get head(): this;
+
+  /** The first node after the head. */
+  get front(): object;
+
+  /** The last node in the list. */
+  get back(): object;
+
+  /** A range spanning all nodes, or `null` if empty. */
+  get range(): SllRange | null;
+
+  /**
+   * Count the number of nodes.
+   * @returns The node count.
+   */
+  getLength(): number;
+
+  /**
+   * Adopt a node or pointer, making it stand-alone if needed.
+   * @param nodeOrPtr - Node or pointer to adopt.
+   * @returns The adopted node.
+   */
+  adoptNode<T extends object>(nodeOrPtr: T | PtrBase<T>): T;
+
+  /**
+   * Adopt a value into this list. Overridden by value-list subclasses.
+   * @param nodeOrPtr - Node, pointer, or value to adopt.
+   * @returns The adopted node.
+   */
+  adoptValue(nodeOrPtr: any): any;
+
+  /**
+   * Normalize a node or pointer to a plain node.
+   * @param nodeOrPtr - Node or pointer.
+   * @returns The underlying node, or `null`.
+   */
+  normalizeNode<T extends object>(nodeOrPtr: T | PtrBase<T> | null): T | null;
+
+  /**
+   * Normalize a range, resolving any pointers to nodes.
+   * @param range - Range to normalize.
+   * @returns The normalized range, or `null`.
+   */
+  normalizeRange<T extends object>(range?: SllRange<T> | null): SllRange<T> | null;
+
+  /**
+   * Normalize a pointer-based range.
+   * @param range - Pointer range to normalize.
+   * @returns The normalized pointer range, or `null`.
+   */
+  normalizePtrRange<T extends object>(range?: SllPtrRange<T> | null): SllPtrRange<T> | null;
+
+  /**
+   * Recalculate the `last` pointer by traversing the list.
+   * @returns `this` for chaining.
+   */
+  syncLast(): this;
+}
+
+/** Value wrapper node for singly linked lists. */
+export class ValueNode<V = unknown> extends Node {
+  /** The wrapped value. */
+  value: V;
+
+  /**
+   * @param value - Value to wrap.
+   * @param options - Link property names.
+   */
+  constructor(value: V, options?: SllOptions);
+}
+
+/** Base class for SLL pointers providing navigation. */
+export class PtrBase<T extends object = object> {
+  /** The list this pointer belongs to. */
+  list: HeadNode | ExtListBase<T>;
+  /** The current node. */
+  node: T;
+  /** The node preceding the current node. */
+  prevNode: T;
+
+  /**
+   * @param list - Owning list or another PtrBase to copy.
+   * @param node - Target node.
+   * @param prev - Preceding node.
+   * @param ListClass - Expected list constructor for validation.
+   */
+  constructor(list: PtrBase<T> | HeadNode | ExtListBase<T>, node?: T | PtrBase<T>, prev?: T, ListClass?: Function);
+
+  /** The node after the current node. */
+  get nextNode(): T;
+
+  /**
+   * Check and repair the prevNode link.
+   * @returns `true` if prevNode is valid.
+   */
+  isPrevNodeValid(): boolean;
+
+  /**
+   * Advance to the next node.
+   * @returns `this` for chaining.
+   */
+  next(): this;
+
+  /**
+   * Move to the previous node.
+   * @returns `this` for chaining.
+   * @throws If prevNode is invalid.
+   */
+  prev(): this;
+
+  /**
+   * Synchronize prevNode by scanning forward.
+   * @returns `this` for chaining.
+   */
+  syncPrev(): this;
+}
+
+/** Base class for external (headless) singly linked lists. */
+export class ExtListBase<T extends object = object> {
+  /** Current head node, or `null` if empty. */
+  head: T | null;
+  /** Property name for the next link. */
+  nextName: string;
+
+  /**
+   * @param head - Initial head node, ExtListBase, or PtrBase.
+   * @param options - Link property names.
+   */
+  constructor(head?: T | ExtListBase<T> | PtrBase<T> | null, options?: SllOptions);
+
+  /**
+   * Check whether another list is compatible.
+   * @param list - List to compare.
+   * @returns `true` if compatible.
+   */
+  isCompatible(list: ExtListBase | HeadNode): boolean;
+
+  /**
+   * Check whether a pointer belongs to a compatible list.
+   * @param ptr - Pointer to check.
+   * @returns `true` if compatible.
+   */
+  isCompatiblePtr(ptr: PtrBase): boolean;
+
+  /**
+   * Check whether a value looks like a compatible node.
+   * @param node - Value to check.
+   * @returns `true` if the value has a valid next link.
+   */
+  isNodeLike(node: unknown): boolean;
+
+  /**
+   * Check whether another options object shares the same link names.
+   * @param options - Options to compare.
+   * @returns `true` if `nextName` matches.
+   */
+  isCompatibleNames(options: SllOptions): boolean;
+
+  /**
+   * Check whether a range is compatible with this list.
+   * @param range - Range to validate.
+   * @returns `true` if compatible.
+   */
+  isCompatibleRange<T extends object>(range: SllRange<T>): boolean;
+
+  /**
+   * Normalize a node or pointer to a plain node.
+   * @param nodeOrPtr - Node or pointer.
+   * @returns The underlying node, or `null`.
+   */
+  normalizeNode<T extends object>(nodeOrPtr: T | PtrBase<T> | null): T | null;
+
+  /**
+   * Normalize a range, resolving any pointers to nodes.
+   * @param range - Range to normalize.
+   * @returns The normalized range, or `null`.
+   */
+  normalizeRange<T extends object>(range?: SllRange<T> | null): SllRange<T> | null;
+
+  /**
+   * Normalize a pointer-based range.
+   * @param range - Pointer range to normalize.
+   * @returns The normalized pointer range, or `null`.
+   */
+  normalizePtrRange<T extends object>(range?: SllPtrRange<T> | null): SllPtrRange<T> | null;
+
+  /**
+   * Adopt a node or pointer, making it stand-alone if needed.
+   * @param nodeOrPtr - Node or pointer to adopt.
+   * @returns The adopted node.
+   */
+  adoptNode<T extends object>(nodeOrPtr: T | PtrBase<T>): T;
+
+  /**
+   * Adopt a value into this list. Overridden by value-list subclasses.
+   * @param nodeOrPtr - Node, pointer, or value to adopt.
+   * @returns The adopted node.
+   */
+  adoptValue(nodeOrPtr: any): any;
+
+  /** Whether the list has no nodes. */
+  get isEmpty(): boolean;
+
+  /** Whether the list has exactly one node. */
+  get isOne(): boolean;
+
+  /** Whether the list has zero or one node. */
+  get isOneOrEmpty(): boolean;
+
+  /** The head node, or `null` if empty. */
+  get front(): T | null;
+
+  /** A range spanning all nodes, or `null` if empty. */
+  get range(): SllRange<T> | null;
+
+  /**
+   * Count the number of nodes.
+   * @returns The node count.
+   */
+  getLength(): number;
+
+  /**
+   * Get the last node by traversal.
+   * @returns The last node, or `null` if empty.
+   */
+  getBack(): T | null;
+
+  /**
+   * Set a new head node.
+   * @param head - New head node, pointer, or `null`.
+   * @returns The previous head node.
+   */
+  attach(head?: T | PtrBase<T> | null): T | null;
+
+  /**
+   * Remove the head reference without modifying nodes.
+   * @returns The previous head node.
+   */
+  detach(): T | null;
+
+  /**
+   * Advance the head to the next node.
+   * @returns `this` for chaining.
+   */
+  next(): this;
+}