list-toolkit 2.2.6 → 2.3.0

package/src/list/nodes.d.ts

@@ -0,0 +1,336 @@
+/** Options for configuring link property names. */
+export interface DllOptions {
+  /** Name of the "next" link property. */
+  nextName?: string;
+  /** Name of the "prev" link property. */
+  prevName?: string;
+}
+
+/** A range defined by two nodes. */
+export interface DllRange<T extends object = object> {
+  /** Start node of the range. */
+  from?: T;
+  /** End node of the range. */
+  to?: T;
+  /** List that owns the range. */
+  list?: HeadNode | ExtListBase<T>;
+}
+
+/** A range defined by a pointer and a node. */
+export interface DllPtrRange<T extends object = object> {
+  /** Start pointer of the range. */
+  from?: PtrBase<T>;
+  /** End node of the range. */
+  to?: T;
+  /** List that owns the range. */
+  list?: HeadNode | ExtListBase<T>;
+}
+
+/**
+ * Check whether a node has both link properties set.
+ * @param options - Link property names.
+ * @param node - Object to test.
+ * @returns `true` if the node has both next and prev links.
+ */
+export function isNodeLike<T extends object>(options: DllOptions, node: T | null | undefined): boolean;
+
+/**
+ * Check whether a node links to itself on both sides.
+ * @param options - Link property names.
+ * @param node - Object to test.
+ * @returns `true` if the node is stand-alone (self-linked).
+ */
+export function isStandAlone<T extends object>(options: DllOptions, node: T | null | undefined): boolean;
+
+/**
+ * Check whether two option sets share the same link property names.
+ * @param options1 - First set of options.
+ * @param options2 - Second set of options.
+ * @returns `true` if nextName and prevName match.
+ */
+export function isCompatible(options1: DllOptions, options2: DllOptions): boolean;
+
+/** A self-linked circular DLL node. */
+export class Node {
+  /** Name of the "next" link property. */
+  readonly nextName: string;
+  /** Name of the "prev" link property. */
+  readonly prevName: string;
+
+  /** @param options - Link property names. */
+  constructor(options?: DllOptions);
+
+  /** Whether this node links to itself. */
+  get isStandAlone(): boolean;
+}
+
+/** Sentinel node used as the head of a hosted DLL. */
+export class HeadNode extends Node {
+  /**
+   * Test whether a value looks like a compatible node.
+   * @param node - Object to test.
+   * @returns `true` if the object has valid next and prev links.
+   */
+  isNodeLike<T extends object>(node: T | null | undefined): boolean;
+
+  /**
+   * Test whether an options object shares the same link names.
+   * @param options - Options to compare.
+   * @returns `true` if names match.
+   */
+  isCompatibleNames(options: DllOptions): boolean;
+
+  /**
+   * Test whether another list is compatible.
+   * @param list - List or head node to compare.
+   * @returns `true` if compatible.
+   */
+  isCompatible(list: HeadNode | ExtListBase): boolean;
+
+  /**
+   * Test whether a pointer belongs to a compatible list.
+   * @param ptr - Pointer to test.
+   * @returns `true` if compatible.
+   */
+  isCompatiblePtr(ptr: PtrBase): boolean;
+
+  /**
+   * Test whether a range is compatible with this list.
+   * @param range - Range to test.
+   * @returns `true` if compatible.
+   */
+  isCompatibleRange(range: DllRange | null): boolean;
+
+  /** Whether the list is empty (head links to itself). */
+  get isEmpty(): boolean;
+
+  /** Whether the list contains exactly one node. */
+  get isOne(): boolean;
+
+  /** Whether the list contains zero or one nodes. */
+  get isOneOrEmpty(): boolean;
+
+  /** The sentinel head node. */
+  get head(): this;
+
+  /** The first node after the head. */
+  get front(): object;
+
+  /** The last node before the head. */
+  get back(): object;
+
+  /** A range spanning all nodes, or `null` if empty. */
+  get range(): DllRange | null;
+
+  /**
+   * Count the number of nodes in the list.
+   * @returns Node count.
+   */
+  getLength(): number;
+
+  /**
+   * Adopt a node or pointer into this list, making it stand-alone if needed.
+   * @param nodeOrPtr - Node or pointer to adopt.
+   * @returns The adopted node.
+   * @throws If the node is already part of another list.
+   */
+  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 Normalized range with plain node references.
+   */
+  normalizeRange<T extends object>(range: DllRange<T>): DllRange<T>;
+}
+
+/** A node that wraps an arbitrary value. */
+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?: DllOptions);
+}
+
+/** Base class for DLL pointers. */
+export class PtrBase<T extends object = object> {
+  /** The list this pointer belongs to. */
+  list: HeadNode | ExtListBase<T>;
+  /** The node this pointer references. */
+  node: T;
+
+  /**
+   * @param list - Owning list, or another pointer to copy.
+   * @param node - Target node or pointer.
+   * @param ListClass - Expected list constructor for validation.
+   */
+  constructor(list: HeadNode | ExtListBase<T> | PtrBase<T>, node?: T | PtrBase<T>, ListClass?: Function);
+
+  /** The node after the current node. */
+  get nextNode(): T;
+
+  /** The node before the current node. */
+  get prevNode(): T;
+
+  /**
+   * Whether the previous node is valid for iteration.
+   * @returns Always `true` for DLL pointers.
+   */
+  isPrevNodeValid(): boolean;
+
+  /**
+   * Advance the pointer to the next node.
+   * @returns `this` for chaining.
+   */
+  next(): this;
+
+  /**
+   * Move the pointer to the previous node.
+   * @returns `this` for chaining.
+   */
+  prev(): this;
+}
+
+/** Base class for external (headless) DLL wrappers. */
+export class ExtListBase<T extends object = object> {
+  /** Name of the "next" link property. */
+  readonly nextName: string;
+  /** Name of the "prev" link property. */
+  readonly prevName: string;
+  /** Current head node, or `null` if empty. */
+  head: T | null;
+
+  /**
+   * @param head - Initial head node, pointer, or another ExtListBase to copy.
+   * @param options - Link property names.
+   */
+  constructor(head?: T | PtrBase<T> | ExtListBase<T> | null, options?: DllOptions);
+
+  /**
+   * Test whether another list is compatible.
+   * @param list - List to compare.
+   * @returns `true` if compatible.
+   */
+  isCompatible(list: HeadNode | ExtListBase): boolean;
+
+  /**
+   * Test whether a pointer belongs to a compatible list.
+   * @param ptr - Pointer to test.
+   * @returns `true` if compatible.
+   */
+  isCompatiblePtr(ptr: PtrBase): boolean;
+
+  // Copied from HeadNode via copyDescriptors:
+
+  /**
+   * Test whether a value looks like a compatible node.
+   * @param node - Object to test.
+   * @returns `true` if the object has valid next and prev links.
+   */
+  isNodeLike(node: object | null | undefined): boolean;
+
+  /**
+   * Test whether an options object shares the same link names.
+   * @param options - Options to compare.
+   * @returns `true` if names match.
+   */
+  isCompatibleNames(options: DllOptions): boolean;
+
+  /**
+   * Test whether a range is compatible with this list.
+   * @param range - Range to test.
+   * @returns `true` if compatible.
+   */
+  isCompatibleRange(range: DllRange<T> | null): boolean;
+
+  /**
+   * Normalize a node or pointer to a plain node.
+   * @param nodeOrPtr - Node or pointer.
+   * @returns The underlying node, or `null`.
+   */
+  normalizeNode(nodeOrPtr: T | PtrBase<T> | null): T | null;
+
+  /**
+   * Normalize a range, resolving any pointers to nodes.
+   * @param range - Range to normalize.
+   * @returns Normalized range with plain node references.
+   */
+  normalizeRange(range: DllRange<T>): DllRange<T>;
+
+  /**
+   * Adopt a node or pointer into this list.
+   * @param nodeOrPtr - Node or pointer to adopt.
+   * @returns The adopted node.
+   */
+  adoptNode(nodeOrPtr: T | PtrBase<T>): T;
+
+  /** Alias for {@link adoptNode}. */
+  adoptValue(nodeOrPtr: T | PtrBase<T>): T;
+
+  /** Whether the list is empty. */
+  get isEmpty(): boolean;
+
+  /** Whether the list contains exactly one node. */
+  get isOne(): boolean;
+
+  /** Whether the list contains zero or one nodes. */
+  get isOneOrEmpty(): boolean;
+
+  /** The head node, or `undefined` if empty. */
+  get front(): T | undefined;
+
+  /** The node before the head, or `undefined` if empty. */
+  get back(): T | undefined;
+
+  /** A range spanning all nodes, or `null` if empty. */
+  get range(): DllRange<T> | null;
+
+  /**
+   * Count the number of nodes.
+   * @returns Node count.
+   */
+  getLength(): number;
+
+  /**
+   * Set a new head node.
+   * @param head - New head node or pointer, or `null` to detach.
+   * @returns The previous head node, or `null`.
+   */
+  attach(head?: T | PtrBase<T> | null): T | null;
+
+  /**
+   * Detach the head, leaving the list empty.
+   * @returns The previous head node, or `null`.
+   */
+  detach(): T | null;
+
+  /**
+   * Advance the head to the next node.
+   * @returns `this` for chaining.
+   */
+  next(): this;
+
+  /**
+   * Move the head to the previous node.
+   * @returns `this` for chaining.
+   */
+  prev(): this;
+}

package/src/list/nodes.js

@@ -1,24 +1,49 @@
-'use strict';
-
 import {isRangeLike, normalizeNode, normalizeRange} from '../list-helpers.js';
 import {addAlias, copyDescriptors, canHaveProps} from '../meta-utils.js';
 
+/**
+ * Check whether a node has valid next and prev links.
+ * @param {object} options - Link property names.
+ * @param {object} node - Node to check.
+ * @returns {boolean} `true` if the node has truthy next and prev links.
+ */
 export const isNodeLike = ({nextName, prevName}, node) => node && node[prevName] && 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 and prev links point to itself.
+ */
 export const isStandAlone = ({nextName, prevName}, node) => node && node[prevName] === node && node[nextName] === node;
+/**
+ * Check whether two option sets share the same link property names.
+ * @param {object} options1 - First options.
+ * @param {object} options2 - Second options.
+ * @returns {boolean} `true` if `nextName` and `prevName` match.
+ */
 export const isCompatible = (options1, options2) => options1.nextName === options2.nextName && options1.prevName === options2.prevName;
 
+/** Doubly linked list node with circular self-links. */
 export class Node {
+  /** @param {object} [options] - Link property names. */
   constructor({nextName = 'next', prevName = 'prev'} = {}) {
     this.nextName = nextName;
     this.prevName = prevName;
     this[nextName] = this[prevName] = this;
   }
+  /** Whether this node's next link points to itself. */
   get isStandAlone() {
     return this[this.nextName] === this;
   }
 }
 
+/** Sentinel head node for hosted doubly linked lists. */
 export class HeadNode extends Node {
+  /**
+   * Check whether a value looks like a compatible node.
+   * @param {*} node - Value to check.
+   * @returns {boolean} `true` if the value has valid next and prev links.
+   */
   isNodeLike(node) {
     if (!node) return false;
     const next = node[this.nextName];
@@ -27,14 +52,29 @@ export class HeadNode extends Node {
     return prev && canHaveProps[typeof prev] === 1;
   }
 
+  /**
+   * Check whether another options object shares the same link names.
+   * @param {object} options - Options to compare.
+   * @returns {boolean} `true` if `nextName` and `prevName` match.
+   */
   isCompatibleNames({nextName, prevName}) {
     return this.nextName === nextName && this.prevName === prevName;
   }
 
+  /**
+   * 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 && this.prevName === list.prevName);
   }
 
+  /**
+   * 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 &&
@@ -42,38 +82,54 @@ export class HeadNode extends Node {
     );
   }
 
+  /**
+   * 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 before the head. */
   get back() {
     return this[this.prevName];
   }
 
+  /** A range spanning all nodes, or `null` if empty. */
   get range() {
     return this[this.nextName] === this ? null : {from: this[this.nextName], to: this[this.prevName], list: this};
   }
 
+  /**
+   * Count the number of nodes.
+   * @returns {number} The node count.
+   */
   getLength() {
     let n = 0;
     const nextName = this.nextName;
@@ -81,6 +137,11 @@ export class HeadNode extends Node {
     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 node = nodeOrPtr instanceof PtrBase ? nodeOrPtr.node : nodeOrPtr;
     if (node[this.nextName] || node[this.prevName]) {
@@ -92,12 +153,22 @@ 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);
   }
@@ -105,14 +176,25 @@ export class HeadNode extends Node {
 
 addAlias(HeadNode.prototype, 'adoptNode', 'adoptValue');
 
+/** Value wrapper node for doubly 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 DLL pointers providing navigation. */
 export class PtrBase {
+  /**
+   * @param {PtrBase|HeadNode|ExtListBase} list - Owning list or another PtrBase to copy.
+   * @param {object} [node] - Target node.
+   * @param {Function} [ListClass] - Expected list constructor for validation.
+   */
   constructor(list, node, ListClass) {
     if (list instanceof PtrBase) {
       this.list = list.list;
@@ -132,30 +214,49 @@ export class PtrBase {
     if (!this.node) this.node = this.list.front;
   }
 
+  /** The node after the current node. */
   get nextNode() {
     return this.node[this.list.nextName];
   }
 
+  /** The node before the current node. */
   get prevNode() {
     return this.node[this.list.prevName];
   }
 
+  /**
+   * Check whether the prevNode link is valid. Always `true` for DLL pointers.
+   * @returns {boolean} `true`.
+   */
   isPrevNodeValid() {
     return true;
   }
 
+  /**
+   * Advance to the next node.
+   * @returns {PtrBase} `this` for chaining.
+   */
   next() {
     this.node = this.node[this.list.nextName];
     return this;
   }
 
+  /**
+   * Move to the previous node.
+   * @returns {PtrBase} `this` for chaining.
+   */
   prev() {
     this.node = this.node[this.list.prevName];
     return this;
   }
 }
 
+/** Base class for external (headless) doubly 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', prevName = 'prev'} = {}) {
     if (head instanceof ExtListBase) {
       this.nextName = head.nextName;
@@ -174,10 +275,20 @@ 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 && this.prevName === list.prevName);
   }
 
+  /**
+   * 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 &&
@@ -185,30 +296,40 @@ export class ExtListBase {
     );
   }
 
+  /** 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;
   }
 
+  /** The last node, or `undefined` if empty. */
   get back() {
     return this.head?.[this.prevName];
   }
 
+  /** A range spanning all nodes, or `null` if empty. */
   get range() {
     return this.head ? {from: this.head, to: this.head[this.prevName], list: this.head} : null;
   }
 
+  /**
+   * Count the number of nodes.
+   * @returns {number} The node count.
+   */
   getLength() {
     if (!this.head) return 0;
 
@@ -222,6 +343,11 @@ export class ExtListBase {
     return n;
   }
 
+  /**
+   * 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) {
@@ -234,17 +360,29 @@ 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;
   }
 
+  /**
+   * Move the head to the previous node.
+   * @returns {ExtListBase} `this` for chaining.
+   */
   prev() {
     if (this.head) this.head = this.head[this.prevName];
     return this;