list-toolkit 2.2.5 → 2.3.0

package/src/slist/basics.js

@@ -1,7 +1,9 @@
-'use strict';
-
-// useful low-level operations on singly linked lists
-
+/**
+ * Extract a range of nodes from a circular SLL.
+ * @param {object} options - Link property names.
+ * @param {object} range - Range descriptor with `prevFrom` and optional `to`.
+ * @returns {{extracted: {prevFrom: object, to: object}, rest: object|null}} The extracted sub-list and the remaining list.
+ */
 export const extract = ({nextName}, {prevFrom, to = prevFrom[nextName]}) => {
   const node = prevFrom[nextName],
     next = to[nextName];
@@ -15,8 +17,12 @@ export const extract = ({nextName}, {prevFrom, to = prevFrom[nextName]}) => {
   return {extracted: {prevFrom: to, to}, rest: next === node ? null : next};
 };
 
-// pop(options, prev).node === extract(options, {prevFrom: prev}).prevFrom[options.nextName]
-
+/**
+ * Pop a single node out of its circular SLL.
+ * @param {object} options - Link property names.
+ * @param {object} prev - The node preceding the one to pop.
+ * @returns {{extracted: {prevFrom: object, to: object}, rest: object|null}} The popped node descriptor and the remaining list.
+ */
 export const pop = ({nextName}, prev) => {
   const node = prev[nextName],
     next = node[nextName];
@@ -30,6 +36,13 @@ export const pop = ({nextName}, prev) => {
   return {extracted: {prevFrom: node, to: node}, rest: next === node ? null : next};
 };
 
+/**
+ * Splice a range of nodes into a circular SLL after a target node.
+ * @param {object} options - Link property names.
+ * @param {object} target - Node after which to insert.
+ * @param {object} range - Range descriptor with `prevFrom` and optional `to`.
+ * @returns {object} The target node.
+ */
 export const splice = ({nextName}, target, {prevFrom, to = prevFrom[nextName]}) => {
   // form the combined head
   const next = target[nextName];
@@ -42,6 +55,8 @@ export const splice = ({nextName}, target, {prevFrom, to = prevFrom[nextName]})
   return target;
 };
 
-// append(options, target, range) === splice(options, target, extract(options, range))
-
+/**
+ * Alias for {@link splice}. Extract a range and splice it after a target node.
+ * @type {typeof splice}
+ */
 export const append = splice;

package/src/slist/core.d.ts

@@ -0,0 +1,251 @@
+import {HeadNode, PtrBase, ExtListBase, SllOptions, SllRange, SllPtrRange} from './nodes.js';
+import {Ptr} from './ptr.js';
+
+/** Hosted node-based singly linked list. */
+export class SList<T extends object = object> extends HeadNode {
+  /** The first node after the head. */
+  get front(): T;
+
+  /** The last node in the list. */
+  get back(): T;
+
+  /** A range spanning all nodes, or `null` if empty. */
+  get range(): SllRange<T> | null;
+
+  /** Pointer to the first node. */
+  get frontPtr(): Ptr<T>;
+
+  /** A pointer-based range spanning all nodes, or `null` if empty. */
+  get ptrRange(): SllPtrRange<T> | null;
+
+  /**
+   * Create a pointer to a node in this list.
+   * @param node - Target node, or `undefined` for the front.
+   * @returns A new Ptr.
+   */
+  makePtr(node?: T): Ptr<T>;
+
+  /**
+   * 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>;
+
+  /**
+   * Remove and return the front node.
+   * @returns The removed node, or `undefined` if empty.
+   */
+  popFrontNode(): T | undefined;
+
+  /** Alias for {@link popFrontNode}. */
+  popFront(): T | undefined;
+
+  /** Alias for {@link popFrontNode}. */
+  pop(): T | undefined;
+
+  /**
+   * Insert a value at the front.
+   * @param value - Node or value to insert.
+   * @returns A Ptr to the front.
+   */
+  pushFront(value: T | PtrBase<T>): Ptr<T>;
+
+  /** Alias for {@link pushFront}. */
+  push(value: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Insert a value at the back.
+   * @param value - Node or value to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  pushBack(value: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Insert an existing node at the front.
+   * @param nodeOrPtr - Node or pointer to insert.
+   * @returns A Ptr to the front.
+   */
+  pushFrontNode(nodeOrPtr: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Insert an existing node at the back.
+   * @param nodeOrPtr - Node or pointer to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  pushBackNode(nodeOrPtr: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Move all nodes from another list to the front.
+   * @param list - Compatible list to consume.
+   * @returns A Ptr to the new front.
+   */
+  appendFront(list: HeadNode): Ptr<T>;
+
+  /**
+   * Move all nodes from another list to the back.
+   * @param list - Compatible list to consume.
+   * @returns A Ptr to the first appended node.
+   */
+  appendBack(list: HeadNode): Ptr<T>;
+
+  /** Alias for {@link appendBack}. */
+  append(list: HeadNode): Ptr<T>;
+
+  /**
+   * Move a pointed-to node to the front.
+   * @param ptr - Pointer to the node to move.
+   * @returns A Ptr to the front, or `this` if at head.
+   */
+  moveToFront(ptr: PtrBase<T>): Ptr<T> | this;
+
+  /**
+   * Move a pointed-to node to the back.
+   * @param ptr - Pointer to the node to move.
+   * @returns A Ptr to the back, or `this` if at head.
+   */
+  moveToBack(ptr: PtrBase<T>): Ptr<T> | this;
+
+  /**
+   * Remove all nodes.
+   * @param drop - If `true`, make each removed node stand-alone.
+   * @returns `this` for chaining.
+   */
+  clear(drop?: boolean): this;
+
+  /**
+   * Remove a node via its pointer.
+   * @param ptr - Pointer to the node to remove.
+   * @returns The removed node, or `null` if at head.
+   */
+  removeNode(ptr: PtrBase<T>): T | null;
+
+  /**
+   * Remove a pointer-based range and optionally drop nodes.
+   * @param ptrRange - Range to remove.
+   * @param drop - If `true`, make each removed node stand-alone.
+   * @returns A new SList containing the removed nodes.
+   */
+  removeRange(ptrRange?: SllPtrRange<T>, drop?: boolean): SList<T>;
+
+  /**
+   * Extract a pointer-based range into a new list.
+   * @param ptrRange - Range to extract (defaults to the whole list).
+   * @returns A new SList containing the extracted nodes.
+   */
+  extractRange(ptrRange?: SllPtrRange<T>): SList<T>;
+
+  /**
+   * Extract nodes that satisfy a condition into a new list.
+   * @param condition - Predicate receiving each node.
+   * @returns A new SList containing the extracted nodes.
+   */
+  extractBy(condition: (node: T) => boolean): SList<T>;
+
+  /**
+   * Reverse the order of all nodes in place.
+   * @returns `this` for chaining.
+   */
+  reverse(): this;
+
+  /**
+   * Sort nodes in place using merge sort.
+   * @param lessFn - Returns `true` if `a` should precede `b`.
+   * @returns `this` for chaining.
+   */
+  sort(lessFn: (a: T, b: T) => boolean): this;
+
+  /**
+   * Detach all nodes as a pointer range.
+   * @returns A pointer range, or `null` if empty.
+   */
+  releaseAsPtrRange(): SllPtrRange<T> | null;
+
+  /**
+   * Detach all nodes as a raw circular list.
+   * @returns Head of the raw circular list, or `null` if empty.
+   */
+  releaseRawList(): T | null;
+
+  /**
+   * Detach all nodes as a null-terminated list.
+   * @returns Object with `head` and `tail`, or `null` if empty.
+   */
+  releaseNTList(): { head: T; tail: T } | null;
+
+  /**
+   * Validate that a range is reachable within this list.
+   * @param range - Range to validate.
+   * @returns `true` if the range is valid.
+   */
+  validateRange(range?: SllRange<T>): boolean;
+
+  /** Iterate over nodes from front to back. */
+  [Symbol.iterator](): IterableIterator<T>;
+
+  /**
+   * Get an iterable over nodes in a range.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of nodes.
+   */
+  getNodeIterator(range?: SllRange<T>): IterableIterator<T>;
+
+  /** Alias for {@link getNodeIterator}. */
+  getIterator(range?: SllRange<T>): IterableIterator<T>;
+
+  /**
+   * Get an iterable of Ptr objects over a pointer range.
+   * @param ptrRange - Sub-range to iterate.
+   * @returns An iterable iterator of Ptrs.
+   */
+  getPtrIterator(ptrRange?: SllPtrRange<T>): IterableIterator<Ptr<T>>;
+
+  /**
+   * Create an empty list with the same options.
+   * @returns A new empty SList.
+   */
+  make(): SList<T>;
+
+  /**
+   * Create a list from values with the same options.
+   * @param values - Iterable of node objects.
+   * @returns A new SList.
+   */
+  makeFrom(values: Iterable<T>): SList<T>;
+
+  /**
+   * Create a list from a range with the same options.
+   * @param range - Range to copy.
+   * @returns A new SList.
+   */
+  makeFromRange(range: SllRange<T>): SList<T>;
+
+  /**
+   * Build an SList from an iterable of node objects.
+   * @param values - Iterable of nodes.
+   * @param options - Link property names.
+   * @returns A new SList.
+   */
+  static from<T extends object = object>(values: Iterable<T>, options?: SllOptions): SList<T>;
+
+  /**
+   * Build an SList from a pointer range.
+   * @param ptrRange - Pointer range to copy.
+   * @param options - Link property names.
+   * @returns A new SList.
+   */
+  static fromPtrRange<T extends object = object>(ptrRange: SllPtrRange<T>, options?: SllOptions): SList<T>;
+
+  /**
+   * Build an SList from an external list, consuming it.
+   * @param extList - External list to consume.
+   * @returns A new SList.
+   */
+  static fromExtList<T extends object = object>(extList: ExtListBase<T>): SList<T>;
+
+  /** The Ptr class associated with this list type. */
+  static Ptr: typeof Ptr;
+}
+
+export { Ptr };
+export default SList;

package/src/slist/core.js

@@ -1,29 +1,44 @@
-'use strict';
-
 import {addAliases, normalizeIterator} from '../meta-utils.js';
 import {ExtListBase, HeadNode} from './nodes.js';
 import {append} from './basics.js';
 import Ptr from './ptr.js';
 
+/** Hosted node-based singly linked list with a sentinel head. */
 export class SList extends HeadNode {
+  /** Pointer to the first node. */
   get frontPtr() {
     return new Ptr(this);
   }
 
+  /** A pointer-based range spanning all nodes, or `null` if empty. */
   get ptrRange() {
     return this.isEmpty ? null : {from: new Ptr(this), to: this.last};
   }
 
+  /**
+   * 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);
   }
 
+  /**
+   * 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);
   }
 
+  /**
+   * Remove and return the front node.
+   * @returns {object|undefined} The removed node, or `undefined` if empty.
+   */
   popFrontNode() {
     if (this[this.nextName] === this) return undefined;
     const node = this[this.nextName];
@@ -32,6 +47,11 @@ export class SList extends HeadNode {
     return (node[this.nextName] = node);
   }
 
+  /**
+   * 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);
     node[this.nextName] = this[this.nextName];
@@ -40,6 +60,11 @@ export class SList extends HeadNode {
     return this.makePtr();
   }
 
+  /**
+   * 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);
     node[this.nextName] = this;
@@ -48,6 +73,11 @@ export class SList extends HeadNode {
     return this.makePtrFromPrev(last);
   }
 
+  /**
+   * 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);
     node[this.nextName] = this[this.nextName];
@@ -56,6 +86,11 @@ export class SList extends HeadNode {
     return this.makePtr();
   }
 
+  /**
+   * 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);
     node[this.nextName] = this;
@@ -64,6 +99,11 @@ export class SList extends HeadNode {
     return this.makePtrFromPrev(last);
   }
 
+  /**
+   * 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;
@@ -76,6 +116,11 @@ export class SList 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;
@@ -90,6 +135,11 @@ export class SList extends HeadNode {
     return this.makePtrFromPrev(last);
   }
 
+  /**
+   * Move a node (identified by pointer) to the front.
+   * @param {Ptr} ptr - Pointer to the node to move.
+   * @returns {Ptr|SList} A Ptr to the front, or `this` if at head.
+   */
   moveToFront(ptr) {
     if (!this.isCompatiblePtr(ptr)) throw new Error('Incompatible pointer');
     ptr.list = this;
@@ -99,6 +149,11 @@ export class SList extends HeadNode {
     return this.pushFrontNode(node);
   }
 
+  /**
+   * Move a node (identified by pointer) to the back.
+   * @param {Ptr} ptr - Pointer to the node to move.
+   * @returns {Ptr|SList} A Ptr to the back, or `this` if at head.
+   */
   moveToBack(ptr) {
     if (!this.isCompatiblePtr(ptr)) throw new Error('Incompatible pointer');
     ptr.list = this;
@@ -108,6 +163,11 @@ export class SList extends HeadNode {
     return this.pushBackNode(node);
   }
 
+  /**
+   * Remove all nodes.
+   * @param {boolean} [drop] - If `true`, make each removed node stand-alone.
+   * @returns {SList} `this` for chaining.
+   */
   clear(drop) {
     if (drop) {
       let current = this;
@@ -123,6 +183,11 @@ export class SList extends HeadNode {
     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 at head.
+   */
   removeNode(ptr) {
     if (!ptr.isPrevNodeValid()) throw new Error('Cannot remove node: "prevNode" is invalid');
     if (!this.isCompatiblePtr(ptr)) throw new Error('Incompatible pointer');
@@ -135,10 +200,21 @@ export class SList extends HeadNode {
     return node;
   }
 
+  /**
+   * 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 {SList} A new SList 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 {SList} A new SList containing the extracted nodes.
+   */
   extractRange(ptrRange = {}) {
     const originalTo = ptrRange.to;
     ptrRange = this.normalizePtrRange(ptrRange.from ? ptrRange : {...ptrRange, from: this.frontPtr});
@@ -156,6 +232,11 @@ export class SList extends HeadNode {
     return extracted;
   }
 
+  /**
+   * Extract nodes that satisfy a condition into a new list.
+   * @param {Function} condition - Predicate receiving each node.
+   * @returns {SList} A new SList containing the extracted nodes.
+   */
   extractBy(condition) {
     const extracted = this.make();
     if (this.isEmpty) return extracted;
@@ -170,6 +251,10 @@ export class SList extends HeadNode {
     return extracted;
   }
 
+  /**
+   * Reverse the order of all nodes in place.
+   * @returns {SList} `this` for chaining.
+   */
   reverse() {
     if (this.isOneOrEmpty) return this;
     this.last = this[this.nextName];
@@ -185,6 +270,11 @@ export class SList extends HeadNode {
     return this;
   }
 
+  /**
+   * Sort nodes in place using merge sort.
+   * @param {Function} lessFn - Returns `true` if `a` should precede `b`.
+   * @returns {SList} `this` for chaining.
+   */
   sort(lessFn) {
     if (this.isOneOrEmpty) return this;
 
@@ -211,6 +301,10 @@ export class SList extends HeadNode {
     return this;
   }
 
+  /**
+   * Detach all nodes as a pointer range.
+   * @returns {object|null} A pointer range, or `null` if empty.
+   */
   releaseAsPtrRange() {
     if (this.isEmpty) return null;
     const head = this[this.nextName],
@@ -220,6 +314,10 @@ export class SList extends HeadNode {
     return {from: new Ptr(this, null, tail), to: tail};
   }
 
+  /**
+   * Detach all nodes as a raw circular list.
+   * @returns {object|null} Head of the raw circular list, or `null` if empty.
+   */
   releaseRawList() {
     if (this.isEmpty) return null;
     const head = this[this.nextName],
@@ -229,6 +327,10 @@ export class SList extends HeadNode {
     return head;
   }
 
+  /**
+   * 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],
@@ -238,6 +340,11 @@ export class SList 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;
@@ -248,8 +355,7 @@ export class SList extends HeadNode {
     return true;
   }
 
-  // iterators
-
+  /** Iterate over nodes from front to back. */
   [Symbol.iterator]() {
     let current = this[this.nextName],
       readyToStop = this.isEmpty;
@@ -264,6 +370,11 @@ export class SList 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;
@@ -285,6 +396,11 @@ export class SList extends HeadNode {
     };
   }
 
+  /**
+   * 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.frontPtr}, ptrRange);
     ptrRange = this.normalizePtrRange(ptrRange);
@@ -307,26 +423,50 @@ export class SList extends HeadNode {
     };
   }
 
-  // meta helpers
-
+  /**
+   * Create an empty list with the same options.
+   * @returns {SList} A new empty SList.
+   */
   make() {
     return new SList(this);
   }
 
+  /**
+   * Create a list from values with the same options.
+   * @param {Iterable} values - Iterable of node objects.
+   * @returns {SList} A new SList.
+   */
   makeFrom(values) {
     return SList.from(values, this);
   }
 
+  /**
+   * Create a list from a range with the same options.
+   * @param {object} range - Range to copy.
+   * @returns {SList} A new SList.
+   */
   makeFromRange(range) {
     return SList.fromRange(range, this);
   }
 
+  /**
+   * Build an SList from an iterable of node objects.
+   * @param {Iterable} values - Iterable of nodes.
+   * @param {object} [options] - Link property names.
+   * @returns {SList} A new SList.
+   */
   static from(values, options) {
     const list = new SList(options);
     for (const value of values) list.pushBack(value);
     return list;
   }
 
+  /**
+   * Build an SList from a pointer range.
+   * @param {object} ptrRange - Pointer range to copy.
+   * @param {object} [options] - Link property names.
+   * @returns {SList} A new SList.
+   */
   static fromPtrRange(ptrRange, options) {
     const list = new SList(options);
     if (!list.isCompatiblePtrRange(ptrRange)) throw new Error('"range" is not a compatible range');
@@ -334,6 +474,11 @@ export class SList extends HeadNode {
     return list;
   }
 
+  /**
+   * Build an SList from an external list, consuming it.
+   * @param {ExtListBase} extList - External list to consume.
+   * @returns {SList} A new SList.
+   */
   static fromExtList(extList) {
     if (!(extList instanceof ExtListBase)) throw new Error('Not a circular list');