list-toolkit 2.3.0 → 2.3.2

package/README.md

@@ -3,52 +3,31 @@
 [npm-img]: https://img.shields.io/npm/v/list-toolkit.svg
 [npm-url]: https://npmjs.org/package/list-toolkit
 
-List-based **efficient** data structures to organize your objects.
-This is a pure JavaScript module with no dependencies
-suitable to use in all environments including browsers.
-
-The toolkit provides the following data structures with a full set of efficiently implemented operations:
-
-- Converters for `null`-terminated (NT) lists, both singly and doubly linked. They convert in place from NT lists to circular lists and back.
-- Various lists:
-  - Doubly linked circular lists (DLL) and singly linked circular lists (SLL).
-  - Value-based lists, where a list serves as a container for external objects, and node-based lists, where a list uses custom properties on external objects to link them around.
-  - Hosted lists, which use a special head node to manage nodes, and headless lists, which point to an external list without including any headers.
-- Heaps:
-  - Priority queues: min heap, leftist heap, skew heap.
-- Various list-based data structures:
-  - Caches with various eviction algorithms: least recently used (LRU), least frequently used (LFU), first in first out (FIFO), and random.
-    - A decorator is provided to decorate functions, methods, and getters with a cache of your choice.
-  - Queue and Stack: adapters for lists.
-- Trees:
-  - Splay tree: a self-adjusting binary search tree.
-- Numerous list utilities.
-
-All lists can be used without the toolkit. Your existing lists, either doubly or singly linked,
-can be used. The toolkit provides a few utilities that you would write yourself if you wanted to use them.
-
-The implementation philosophy was very simple:
-
-- Flexibility, efficiency, and simplicity.
-- No dependencies. No unexpected surprises.
-- You never pay for what you don't use.
-- Suitable for all environments.
-- Should be usable with already existing lists.
-- Could be used as a foundation for other list-based data structures.
+Efficient list-based data structures for JavaScript.
+Pure ESM, zero dependencies, works in Node.js, Bun, Deno, and browsers.
 
-**Read all about the implemented ideas in the [Backgrounder](https://github.com/uhop/list-toolkit/wiki/Backgrounder).**
+Data structures included:
+
+- **Linked lists** — doubly and singly linked, circular. Node-based (link properties on your objects) or value-based (wraps values in nodes). Hosted (sentinel head) or headless (external pointer).
+- **NT list converters** — convert null-terminated lists to/from circular lists in place.
+- **Heaps** — min heap, leftist heap, skew heap.
+- **Caches** — LRU, LFU, FIFO, random eviction. Includes a decorator for functions, methods, and getters.
+- **Queue and Stack** — list-backed adapters.
+- **Splay tree** — self-adjusting binary search tree.
+- **Utilities** — push/append values, find, remove, validate, and more.
 
-All lists support similar intuitive interfaces:
+Works with your existing linked lists — no wrapper objects required.
 
-- Creating from existing objects.
-- Adding, inserting, extracting and removing nodes.
-- Forward and reverse iterators.
-- General manipulations like reversing and sorting.
-- Link names for the next and previous links (for doubly linked lists) are customizable.
+- Flexible, efficient, simple.
+- Zero dependencies, no surprises.
+- Pay only for what you use.
+- Usable as a foundation for other data structures.
+
+**Read all about the implemented ideas in the [Backgrounder](https://github.com/uhop/list-toolkit/wiki/Backgrounder).**
 
-All facilities are efficient, well-debugged, and battle-tested.
+All lists share a consistent API: create from iterables, push/pop, insert/extract/remove, forward and reverse iterators, sort, reverse, and customizable link names.
 
-**All documentation is in the [wiki](https://github.com/uhop/list-toolkit/wiki).**
+**Full documentation: [wiki](https://github.com/uhop/list-toolkit/wiki).**
 
 ## Installation
 
@@ -58,9 +37,9 @@ npm install list-toolkit
 
 ## Introduction
 
-The full documentation is available in the project's [wiki](https://github.com/uhop/list-toolkit/wiki). Below is a cheat sheet of the API.
+See the [wiki](https://github.com/uhop/list-toolkit/wiki) for full documentation. Quick examples below.
 
-Value lists are containers for arbitrary values:
+Value lists wrap arbitrary values:
 
 ```js
 import ValueList from 'list-toolkit/value-list.js';
@@ -130,12 +109,12 @@ for (const node of people) {
 // let's extract all people from Jill to Jim
 const ji = people.extractRange({from: jill, to: jim});
 for (const node of people) console.log(node.name); // Jane, John
-for (const node of ji) console.log(node.name); // Jim, Jill
+for (const node of ji) console.log(node.name); // Jill, Jim
 
 // add them back:
 people.append(ji);
 for (const node of people.getReverseIterator()) {
-  console.log(node.name); // Jill, Jim, John, Jane
+  console.log(node.name); // Jim, Jill, John, Jane
 }
 ji.isEmpty === true;
 
@@ -148,6 +127,8 @@ BSD 3-Clause "New" or "Revised" License. See the LICENSE file for details.
 
 ## Release History
 
+- 2.3.2 _Updated dev dependencies._
+- 2.3.1 _Bugfixes. Improved TS typing tests. Updated docs. Updated dev dependencies._
 - 2.3.0 _Added TypeScript declarations for all modules. Added JSDoc. Removed CJS build. Bugfixes. Added missing methods._
 - 2.2.6 _Updated dev dependencies._
 - 2.2.5 _Updated dev dependencies._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "list-toolkit",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "Zero-dependency list-based data structures: linked lists (doubly/singly linked, circular), caches (LRU, LFU, FIFO), heaps, queues, stacks, splay trees.",
   "type": "module",
   "exports": {
@@ -10,9 +10,9 @@
     "lint": "prettier --check .",
     "lint:fix": "prettier --write .",
     "ts-check": "tsc --noEmit",
-    "ts-test": "tape6 --flags FO '/ts-tests/test-*.*ts'",
-    "ts-test:bun": "tape6-bun --flags FO '/ts-tests/test-*.*ts'",
-    "ts-test:deno": "tape6-deno --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test": "tape6 --flags FO '/tests/test-*.*ts'",
+    "ts-test:bun": "tape6-bun --flags FO '/tests/test-*.*ts'",
+    "ts-test:deno": "tape6-deno --flags FO '/tests/test-*.*ts'",
     "start": "tape6-server --trace",
     "test": "tape6 --flags FO",
     "test:bun": "tape6-bun --flags FO",
@@ -60,10 +60,10 @@
   "llms": "https://raw.githubusercontent.com/uhop/list-toolkit/master/llms.txt",
   "llmsFull": "https://raw.githubusercontent.com/uhop/list-toolkit/master/llms-full.txt",
   "devDependencies": {
-    "nano-benchmark": "^1.0.10",
+    "nano-benchmark": "^1.0.13",
     "prettier": "^3.8.1",
-    "tape-six": "^1.7.2",
-    "tape-six-proc": "^1.2.3",
+    "tape-six": "^1.7.12",
+    "tape-six-proc": "^1.2.7",
     "typescript": "^5.9.3"
   },
   "files": [
@@ -73,7 +73,11 @@
   ],
   "tape6": {
     "tests": [
-      "/tests/test-*.*js"
+      "/tests/test-*.js",
+      "/tests/test-*.mjs"
+    ],
+    "cli": [
+      "/tests/test-*.cjs"
     ],
     "importmap": {
       "imports": {

package/src/heap/leftist-heap.js

@@ -1,7 +1,5 @@
 import HeapBase from './basics.js';
 
-const defaultLess = (a, b) => a < b;
-
 const merge = (a, b, less) => {
   if (!a) return b;
   if (!b) return a;

package/src/heap/min-heap.d.ts

@@ -232,13 +232,7 @@ export class MinHeap<T = unknown> extends HeapBase<T> {
    * @param equal - Equality function.
    * @returns The array.
    */
-  static replace<T = unknown>(
-    heapArray: T[],
-    item: T,
-    newItem: T,
-    less?: (a: T, b: T) => boolean,
-    equal?: (a: T, b: T) => boolean
-  ): T[];
+  static replace<T = unknown>(heapArray: T[], item: T, newItem: T, less?: (a: T, b: T) => boolean, equal?: (a: T, b: T) => boolean): T[];
 
   /**
    * Re-sift an element at a given index in a heap array.

package/src/list/ext.js

@@ -1,6 +1,6 @@
 import {ExtListBase, PtrBase} from './nodes.js';
 import {pop, extract, splice, append} from './basics.js';
-import {addAliases, normalizeIterator} from '../meta-utils.js';
+import {addAliases, mapIterator, normalizeIterator} from '../meta-utils.js';
 
 /** Pointer for navigating and mutating an external doubly linked list. */
 export class Ptr extends PtrBase {

package/src/nt-utils.d.ts

@@ -40,7 +40,7 @@ export function getNTListTail<T extends object>(head: T | null, options?: NTOpti
  * @param options - Link property names (uses `prevName`).
  * @returns The head node, or `null` if empty or circular.
  */
-export function getNTListHead<T extends object>(node: T | null, options?: { prevName?: string }): T | null;
+export function getNTListHead<T extends object>(node: T | null, options?: {prevName?: string}): T | null;
 
 /**
  * Count the number of nodes in a null-terminated list.

package/src/slist/basics.d.ts

@@ -3,7 +3,7 @@ import {SllOptions} from './nodes.js';
 /** Result of extracting or popping nodes from a circular SLL. */
 export interface SllExtractResult<T extends object> {
   /** The extracted sub-range descriptor. */
-  extracted: { prevFrom: T; to: T };
+  extracted: {prevFrom: T; to: T};
   /** The remaining circular list head, or `null` if nothing remains. */
   rest: T | null;
 }
@@ -44,4 +44,4 @@ export function splice<T extends object>(options: SllOptions, target: T, range:
 /**
  * Alias for {@link splice}.
  */
-export { splice as append };
+export {splice as append};

package/src/slist/core.d.ts

@@ -171,7 +171,7 @@ export class SList<T extends object = object> extends HeadNode {
    * Detach all nodes as a null-terminated list.
    * @returns Object with `head` and `tail`, or `null` if empty.
    */
-  releaseNTList(): { head: T; tail: T } | null;
+  releaseNTList(): {head: T; tail: T} | null;
 
   /**
    * Validate that a range is reachable within this list.
@@ -247,5 +247,5 @@ export class SList<T extends object = object> extends HeadNode {
   static Ptr: typeof Ptr;
 }
 
-export { Ptr };
+export {Ptr};
 export default SList;

package/src/slist/core.js

@@ -469,8 +469,11 @@ export class SList extends HeadNode {
    */
   static fromPtrRange(ptrRange, options) {
     const list = new SList(options);
-    if (!list.isCompatiblePtrRange(ptrRange)) throw new Error('"range" is not a compatible range');
-    if (ptrRange) append(list, list, ptrRange);
+    ptrRange = list.normalizePtrRange(ptrRange);
+    if (ptrRange) {
+      append(list, list, {prevFrom: ptrRange.from.prevNode, to: ptrRange.to});
+      list.last = ptrRange.to;
+    }
     return list;
   }
 
@@ -487,7 +490,8 @@ export class SList extends HeadNode {
 
     const range = extList.range;
     if (range) {
-      append(list, list, range);
+      append(list, list, {prevFrom: range.to, to: range.to});
+      list.last = range.to;
       extList.clear();
     }
 
@@ -499,7 +503,6 @@ SList.Ptr = Ptr;
 
 addAliases(SList.prototype, {
   popFrontNode: 'popFront, pop',
-  popBackNode: 'popBack',
   pushFront: 'push',
   appendBack: 'append',
   getNodeIterator: 'getIterator'

package/src/slist/ext-value.d.ts

@@ -184,5 +184,5 @@ export class ExtValueSList<V = unknown> extends ExtListBase<ValueNode<V>> {
   static ValueNode: typeof ValueNode;
 }
 
-export { ValueNode };
+export {ValueNode};
 export default ExtValueSList;

package/src/slist/ext-value.js

@@ -97,7 +97,7 @@ export class ExtValueSList extends ExtSList {
 ExtValueSList.Ptr = Ptr;
 ExtValueSList.ValueNode = ValueNode;
 
-addAlias(ExtValueSList.prototype, 'getIterator', 'getValueIterator');
+addAlias(ExtValueSList.prototype, 'getValueIterator', 'getIterator');
 
 export {ValueNode};
 export default ExtValueSList;

package/src/slist/ext.js

@@ -359,14 +359,14 @@ export class ExtSList extends ExtListBase {
    * @returns {Iterable} An iterable iterator of Ptrs.
    */
   getPtrIterator(ptrRange = {}) {
-    if (!ptrRange.from) ptrRange = Object.assign({from: this.makePtr()}, 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};

package/src/slist/value.d.ts

@@ -165,7 +165,7 @@ export class ValueSList<V = unknown> extends HeadNode {
    * Detach all nodes as a null-terminated list.
    * @returns Object with `head` and `tail`, or `null` if empty.
    */
-  releaseNTList(): { head: ValueNode<V>; tail: ValueNode<V> } | null;
+  releaseNTList(): {head: ValueNode<V>; tail: ValueNode<V>} | null;
 
   /**
    * Validate that a range is reachable within this list.
@@ -242,5 +242,5 @@ export class ValueSList<V = unknown> extends HeadNode {
   static ValueNode: typeof ValueNode;
 }
 
-export { ValueNode, Ptr };
+export {ValueNode, Ptr};
 export default ValueSList;