list-toolkit 2.2.5 → 2.3.0

package/llms.txt

@@ -0,0 +1,100 @@
+# list-toolkit
+
+> Zero-dependency JavaScript library providing efficient list-based data structures: linked lists, caches, heaps, queues, stacks, and splay trees.
+
+- NPM: https://npmjs.org/package/list-toolkit
+- GitHub: https://github.com/uhop/list-toolkit
+- Wiki: https://github.com/uhop/list-toolkit/wiki
+- License: BSD-3-Clause
+
+## Install
+
+```bash
+npm install list-toolkit
+```
+
+## Quick start
+
+```js
+import ValueList from 'list-toolkit/value-list.js';
+
+const list = ValueList.from([1, 2, 3]);
+for (const value of list) console.log(value); // 1, 2, 3
+
+list.pushBack(4);
+list.pushFront(0);
+console.log(list.popFront()); // 0
+```
+
+```js
+import List from 'list-toolkit/list.js';
+
+// Node-based list: link properties are added directly to your objects
+const a = {name: 'Alice'}, b = {name: 'Bob'};
+const people = List.from([a, b]);
+for (const node of people) console.log(node.name); // Alice, Bob
+```
+
+## Modules
+
+### Linked lists (doubly linked, circular)
+
+- **List** (`list-toolkit/list.js`) — hosted node-based DLL. Link properties (`next`/`prev`) are added to user objects. Customizable link names.
+- **ValueList** (`list-toolkit/value-list.js`) — hosted value-based DLL. Wraps values in `ValueNode` containers.
+- **ExtList** (`list-toolkit/ext-list.js`) — external (headless) node-based DLL. Points into an existing circular list.
+- **ExtValueList** (`list-toolkit/ext-value-list.js`) — external (headless) value-based DLL.
+
+### Linked lists (singly linked, circular)
+
+- **SList** (`list-toolkit/slist.js`) — hosted node-based SLL.
+- **ValueSList** (`list-toolkit/value-slist.js`) — hosted value-based SLL.
+- **ExtSList** (`list-toolkit/ext-slist.js`) — external (headless) node-based SLL.
+- **ExtValueSList** (`list-toolkit/ext-value-slist.js`) — external (headless) value-based SLL.
+
+### Caches
+
+- **CacheLRU** (`list-toolkit/cache.js`) — least recently used eviction. Default export.
+- **CacheFIFO** (`list-toolkit/cache/cache-fifo.js`) — first in first out eviction.
+- **CacheLFU** (`list-toolkit/cache/cache-lfu.js`) — least frequently used eviction.
+- **CacheRandom** (`list-toolkit/cache/cache-random.js`) — random eviction.
+- **cacheDecorator** (`list-toolkit/cache.js`) — decorator to cache function/method results.
+
+All caches share the same API: `has(key)`, `find(key)`/`get(key)`, `register(key, value)`/`set(key, value)`, `remove(key)`/`delete(key)`, `clear()`.
+
+### Heaps (priority queues)
+
+- **MinHeap** (`list-toolkit/heap.js`) — array-based binary min-heap. Default export.
+- **LeftistHeap** (`list-toolkit/heap/leftist-heap.js`) — merge-based leftist heap.
+- **SkewHeap** (`list-toolkit/heap/skew-heap.js`) — merge-based skew heap.
+
+All heaps support `less` or `compare` for ordering. Common API: `push(value)`, `pop()`, `top`/`peek()`, `merge()`, `has(value)`, `remove(value)`.
+
+### Adapters
+
+- **Queue** (`list-toolkit/queue.js`) — FIFO queue adapter. Methods: `add`/`push`/`enqueue`, `remove`/`pop`/`dequeue`, `peek`, `top`, `clear`.
+- **Stack** (`list-toolkit/stack.js`) — LIFO stack adapter. Methods: `push`, `pop`, `peek`, `top`, `clear`.
+
+### Trees
+
+- **SplayTree** (`list-toolkit/tree/splay-tree.js`) — self-adjusting BST. Methods: `insert`, `find`, `remove`, `promote`, `split` (via `splitMaxTree`), `join`.
+
+### Utilities
+
+- **list-utils** (`list-toolkit/list-utils.js`) — push/append values, find/remove nodes by condition, validation.
+- **nt-utils** (`list-toolkit/nt-utils.js`) — convert between null-terminated and circular lists.
+- **meta-utils** (`list-toolkit/meta-utils.js`) — `addAlias`, `addAliases`, iterator helpers, `copyOptions`.
+
+## Key concepts
+
+- All lists are **circular** — the last node links back to the head.
+- **Hosted lists** use a `HeadNode` sentinel. **External lists** are headless.
+- **Value lists** wrap values in `ValueNode`. **Node lists** use link properties directly on user objects.
+- Link names (`nextName`/`prevName`) are customizable, allowing objects to be in multiple lists.
+- **Pointers** (`Ptr`) provide safe iteration with insert/remove during traversal.
+- **TypeScript** declarations (`.d.ts`) are included for all modules.
+
+## Links
+
+- Docs: https://github.com/uhop/list-toolkit/wiki
+- npm: https://www.npmjs.com/package/list-toolkit
+- Full LLM reference: https://github.com/uhop/list-toolkit/blob/master/llms-full.txt

package/package.json

@@ -1,25 +1,28 @@
 {
   "name": "list-toolkit",
-  "version": "2.2.5",
-  "description": "List-based data structures to organize your objects.",
+  "version": "2.3.0",
+  "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": {
-    "./*": {
-      "require": "./cjs/*",
-      "default": "./src/*"
-    }
+    "./*": "./src/*"
   },
   "scripts": {
-    "prepare-dist": "node scripts/prepare-dist.js",
-    "build": "babel src --out-dir cjs",
-    "prepublishOnly": "npm run prepare-dist && npm run build",
+    "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'",
+    "start": "tape6-server --trace",
     "test": "tape6 --flags FO",
     "test:bun": "tape6-bun --flags FO",
     "test:deno": "tape6-deno --flags FO",
     "test:proc": "tape6-proc --flags FO",
-    "test:proc:bun": "bun run `npx tape6-proc --self` --flags FO",
-    "test:proc:deno": "deno run -A `npx tape6-proc --self` --flags FO -r -A",
-    "start": "tape6-server --trace"
+    "test:proc:bun": "bun run `tape6-proc --self` --flags FO",
+    "test:proc:deno": "deno run -A `tape6-proc --self` --flags FO -r -A",
+    "test:seq": "tape6-seq --flags FO",
+    "test:seq:bun": "bun run `tape6-seq --self` --flags FO",
+    "test:seq:deno": "deno run -A `tape6-seq --self` --flags FO"
   },
   "repository": {
     "type": "git",
@@ -28,9 +31,23 @@
   "keywords": [
     "list",
     "lists",
+    "linked-list",
+    "doubly-linked-list",
+    "singly-linked-list",
+    "circular-list",
     "cache",
+    "lru-cache",
+    "lfu-cache",
+    "fifo-cache",
     "heap",
-    "data structures"
+    "min-heap",
+    "priority-queue",
+    "queue",
+    "stack",
+    "splay-tree",
+    "data-structures",
+    "esm",
+    "zero-dependency"
   ],
   "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (http://www.lazutkin.com/)",
   "funding": "https://github.com/sponsors/uhop",
@@ -38,31 +55,22 @@
   "bugs": {
     "url": "https://github.com/uhop/list-toolkit/issues"
   },
+  "github": "http://github.com/uhop/list-toolkit",
   "homepage": "https://github.com/uhop/list-toolkit#readme",
+  "llms": "https://raw.githubusercontent.com/uhop/list-toolkit/master/llms.txt",
+  "llmsFull": "https://raw.githubusercontent.com/uhop/list-toolkit/master/llms-full.txt",
   "devDependencies": {
-    "@babel/cli": "^7.28.6",
-    "@babel/core": "^7.28.6",
-    "@babel/preset-env": "^7.28.6",
-    "nano-benchmark": "^1.0.7",
-    "tape-six": "^1.4.5",
-    "tape-six-proc": "^1.1.6"
+    "nano-benchmark": "^1.0.10",
+    "prettier": "^3.8.1",
+    "tape-six": "^1.7.2",
+    "tape-six-proc": "^1.2.3",
+    "typescript": "^5.9.3"
   },
   "files": [
     "/src",
-    "/cjs"
+    "llms.txt",
+    "llms-full.txt"
   ],
-  "babel": {
-    "presets": [
-      [
-        "@babel/preset-env",
-        {
-          "targets": {
-            "node": "current"
-          }
-        }
-      ]
-    ]
-  },
   "tape6": {
     "tests": [
       "/tests/test-*.*js"

package/src/cache/cache-fifo.d.ts

@@ -0,0 +1,6 @@
+import {CacheLRU} from './cache-lru.js';
+
+/** FIFO (First In First Out) cache. Evicts the oldest entry. */
+export class CacheFIFO<K = unknown, V = unknown> extends CacheLRU<K, V> {}
+
+export default CacheFIFO;

package/src/cache/cache-fifo.js

@@ -1,19 +1,22 @@
-'use strict';
-
 import CacheLRU from './cache-lru.js';
 
-// Evicts on the first-in-first-out basis.
-
+/**
+ * FIFO (First In First Out) cache. Evicts the oldest entry.
+ * Extends {@link CacheLRU} with FIFO eviction policy.
+ */
 export class CacheFIFO extends CacheLRU {
+  /** @override */
   use(key) {
     return this.dict.get(key);
   }
+  /** @override */
   addNew(key, value) {
     this.list.pushBack({key, value});
     const node = this.list.back;
     this.dict.set(key, node);
     return node;
   }
+  /** @override */
   evictAndReplace(key, value) {
     const node = this.list.front;
     this.list.moveToBack(node);

package/src/cache/cache-lfu.d.ts

@@ -0,0 +1,18 @@
+import {CacheLRU} from './cache-lru.js';
+
+/** LFU (Least Frequently Used) cache. Evicts the least frequently accessed entry. */
+export class CacheLFU<K = unknown, V = unknown> extends CacheLRU<K, V> {
+  /**
+   * @param capacity - Maximum number of entries (default 10).
+   */
+  constructor(capacity?: number);
+
+  /**
+   * Reset all frequency counters to a given value.
+   * @param initialValue - Counter value to set (default 1).
+   * @returns `this` for chaining.
+   */
+  resetCounters(initialValue?: number): this;
+}
+
+export default CacheLFU;

package/src/cache/cache-lfu.js

@@ -1,26 +1,30 @@
-'use strict';
-
 import {addAlias} from '../meta-utils.js';
 import MinHeap from '../heap/min-heap.js';
 import CacheLRU from './cache-lru.js';
 
-// Evicts the least frequently used items.
-
+/**
+ * LFU (Least Frequently Used) cache. Evicts the least frequently accessed entry.
+ * Extends {@link CacheLRU} with a min-heap for frequency tracking.
+ */
 export class CacheLFU extends CacheLRU {
+  /** @param {number} [capacity=10] - Maximum number of entries. */
   constructor(capacity = 10) {
     super(capacity);
     this.heap = new MinHeap({less: (a, b) => a.value.counter < b.value.counter});
   }
+  /** @override */
   use(key) {
     const node = this.dict.get(key);
     if (node) ++node.value.counter;
     return node;
   }
+  /** @override */
   update(node, value) {
     node.value.counter = 1;
     node.value.value = value;
     return this;
   }
+  /** @override */
   addNew(key, value) {
     this.list.pushFront({key, value, counter: 1});
     const node = this.list.front;
@@ -28,6 +32,7 @@ export class CacheLFU extends CacheLRU {
     this.heap.push(node);
     return node;
   }
+  /** @override */
   evictAndReplace(key, value) {
     const node = this.heap.top;
     this.dict.delete(node.value.key);
@@ -36,6 +41,7 @@ export class CacheLFU extends CacheLRU {
     this.heap.updateTop();
     return node;
   }
+  /** @override */
   remove(key) {
     const node = this.dict.get(key);
     if (node) {
@@ -45,14 +51,20 @@ export class CacheLFU extends CacheLRU {
     }
     return this;
   }
+  /** @override */
   clear() {
     super.clear();
     this.heap.clear();
     return this;
   }
+  /**
+   * Reset all frequency counters.
+   * @param {number} [initialValue=1] - Value to set all counters to.
+   * @returns {CacheLFU} `this` for chaining.
+   */
   resetCounters(initialValue = 1) {
-    for (const item of this.heap) {
-      item.counter = initialValue;
+    for (const item of this.heap.array) {
+      item.value.counter = initialValue;
     }
     return this;
   }

package/src/cache/cache-lru.d.ts

@@ -0,0 +1,74 @@
+/** LRU (Least Recently Used) cache backed by a doubly linked value list and a Map. */
+export class CacheLRU<K = unknown, V = unknown> {
+  /** Maximum number of entries. */
+  capacity: number;
+
+  /**
+   * @param capacity - Maximum number of entries (default 10).
+   */
+  constructor(capacity?: number);
+
+  /** Whether the cache has no entries. */
+  get isEmpty(): boolean;
+
+  /** Number of entries currently stored. */
+  get size(): number;
+
+  /**
+   * Check whether a key exists in the cache.
+   * @param key - Key to look up.
+   * @returns `true` if the key is present.
+   */
+  has(key: K): boolean;
+
+  /**
+   * Look up a value by key, promoting it as most recently used.
+   * @param key - Key to look up.
+   * @returns The value, or `undefined` if not found.
+   */
+  find(key: K): V | undefined;
+
+  /** Alias for {@link find}. */
+  get(key: K): V | undefined;
+
+  /**
+   * Remove an entry by key.
+   * @param key - Key to remove.
+   * @returns `this` for chaining.
+   */
+  remove(key: K): this;
+
+  /** Alias for {@link remove}. */
+  delete(key: K): this;
+
+  /**
+   * Add or update an entry. Evicts the least recently used entry if at capacity.
+   * @param key - Key to register.
+   * @param value - Value to associate.
+   * @returns `this` for chaining.
+   */
+  register(key: K, value: V): this;
+
+  /** Alias for {@link register}. */
+  add(key: K, value: V): this;
+
+  /** Alias for {@link register}. */
+  set(key: K, value: V): this;
+
+  /**
+   * Remove all entries.
+   * @returns `this` for chaining.
+   */
+  clear(): this;
+
+  /** Iterate over `{key, value}` entry objects from most to least recently used. */
+  [Symbol.iterator](): IterableIterator<{key: K; value: V}>;
+
+  /**
+   * Iterate over `{key, value}` entry objects from least to most recently used.
+   * @returns An iterable iterator.
+   */
+  getReverseIterator(): IterableIterator<{key: K; value: V}>;
+}
+
+export default CacheLRU;

package/src/cache/cache-lru.js

@@ -1,30 +1,47 @@
-'use strict';
-
 import ValueList from '../value-list.js';
 import {addAliases} from '../meta-utils.js';
 
-// The base cache class. Evicts the least recently used items.
-// Based on doubly linked value lists.
-
+/**
+ * LRU (Least Recently Used) cache backed by a doubly linked value list.
+ * Evicts the least recently used item when capacity is exceeded.
+ */
 export class CacheLRU {
+  /** @param {number} [capacity=10] - Maximum number of entries. */
   constructor(capacity = 10) {
     this.capacity = capacity;
     this.list = new ValueList();
     this.dict = new Map();
   }
+  /** Whether the cache has no entries. */
   get isEmpty() {
     return !this.dict.size;
   }
+  /** The number of entries in the cache. */
   get size() {
     return this.dict.size;
   }
+  /**
+   * Check whether a key exists.
+   * @param {*} key - Key to look up.
+   * @returns {boolean} `true` if the key exists.
+   */
   has(key) {
     return this.dict.has(key);
   }
+  /**
+   * Retrieve the value for a key, marking it as recently used.
+   * @param {*} key - Key to look up.
+   * @returns {*} The value, or `undefined` if not found.
+   */
   find(key) {
     const node = this.use(key);
     return node ? node.value.value : undefined;
   }
+  /**
+   * Remove an entry by key.
+   * @param {*} key - Key to remove.
+   * @returns {CacheLRU} `this` for chaining.
+   */
   remove(key) {
     const node = this.dict.get(key);
     if (node) {
@@ -33,6 +50,12 @@ export class CacheLRU {
     }
     return this;
   }
+  /**
+   * Add or update an entry. Evicts the LRU item if at capacity.
+   * @param {*} key - Key to register.
+   * @param {*} value - Value to store.
+   * @returns {CacheLRU} `this` for chaining.
+   */
   register(key, value) {
     const node = this.use(key);
     if (node) {
@@ -46,21 +69,44 @@ export class CacheLRU {
     this.addNew(key, value);
     return this;
   }
+  /**
+   * Mark a key as recently used and return its node.
+   * @param {*} key - Key to look up.
+   * @returns {object|undefined} The internal node, or `undefined`.
+   */
   use(key) {
     const node = this.dict.get(key);
     if (node) this.list.moveToFront(node);
     return node;
   }
+  /**
+   * Update the value of an existing node.
+   * @param {object} node - Internal node to update.
+   * @param {*} value - New value.
+   * @returns {CacheLRU} `this` for chaining.
+   */
   update(node, value) {
     node.value.value = value;
     return this;
   }
+  /**
+   * Add a new entry to the cache.
+   * @param {*} key - Key.
+   * @param {*} value - Value.
+   * @returns {object} The newly created node.
+   */
   addNew(key, value) {
     this.list.pushFront({key, value});
     const node = this.list.front;
     this.dict.set(key, node);
     return node;
   }
+  /**
+   * Evict the LRU entry and replace it with a new key/value.
+   * @param {*} key - New key.
+   * @param {*} value - New value.
+   * @returns {object} The reused node.
+   */
   evictAndReplace(key, value) {
     const node = this.list.back;
     this.list.moveToFront(node);
@@ -69,14 +115,23 @@ export class CacheLRU {
     node.value = {key, value};
     return node;
   }
+  /**
+   * Remove all entries.
+   * @returns {CacheLRU} `this` for chaining.
+   */
   clear() {
     this.dict.clear();
     this.list.clear();
     return this;
   }
+  /** Iterate over `{key, value}` entries from most to least recently used. */
   [Symbol.iterator]() {
     return this.list[Symbol.iterator]();
   }
+  /**
+   * Get an iterable over entries in reverse (LRU-first) order.
+   * @returns {Iterable} An iterable iterator of `{key, value}` objects.
+   */
   getReverseIterator() {
     return this.list.getReverseIterator();
   }

package/src/cache/cache-random.d.ts

@@ -0,0 +1,20 @@
+import {CacheLRU} from './cache-lru.js';
+
+/** Random eviction cache. Evicts a randomly selected entry. */
+export class CacheRandom<K = unknown, V = unknown> extends CacheLRU<K, V> {
+  /** Next ID counter for random ordering. */
+  nextId: number;
+
+  /**
+   * @param capacity - Maximum number of entries (default 10).
+   */
+  constructor(capacity?: number);
+
+  /**
+   * Reset all IDs and rebuild the internal heap.
+   * @returns `this` for chaining.
+   */
+  resetIds(): this;
+}
+
+export default CacheRandom;

package/src/cache/cache-random.js

@@ -1,24 +1,28 @@
-'use strict';
-
 import {addAlias} from '../meta-utils.js';
 import MinHeap from '../heap/min-heap.js';
 import CacheLRU from './cache-lru.js';
 
-// Evicts items randomly.
-
+/**
+ * Random eviction cache. Evicts a randomly chosen entry.
+ * Extends {@link CacheLRU} with random eviction via a min-heap.
+ */
 export class CacheRandom extends CacheLRU {
+  /** @param {number} [capacity=10] - Maximum number of entries. */
   constructor(capacity = 10) {
     super(capacity);
     this.heap = new MinHeap({less: (a, b) => a.value.id > b.value.id});
     this.nextId = 0;
   }
+  /** @override */
   use(key) {
     return this.dict.get(key);
   }
+  /** @override */
   update(node, value) {
     node.value.value = value;
     return this;
   }
+  /** @override */
   addNew(key, value) {
     this.list.pushFront({key, value, id: this.nextId++});
     const node = this.list.front;
@@ -26,6 +30,7 @@ export class CacheRandom extends CacheLRU {
     this.heap.push(node);
     return node;
   }
+  /** @override */
   evictAndReplace(key, value) {
     const index = Math.floor(this.heap.length * Math.random());
 
@@ -42,6 +47,7 @@ export class CacheRandom extends CacheLRU {
 
     return node;
   }
+  /** @override */
   remove(key) {
     const node = this.dict.get(key);
     if (node) {
@@ -51,16 +57,21 @@ export class CacheRandom extends CacheLRU {
     }
     return this;
   }
+  /** @override */
   clear() {
     super.clear();
     this.heap.clear();
     this.nextId = 0;
     return this;
   }
+  /**
+   * Reset all internal IDs and rebuild the heap.
+   * @returns {CacheRandom} `this` for chaining.
+   */
   resetIds() {
     this.nextId = 0;
-    for (const item of this.heap) {
-      item.id = this.nextId++;
+    for (const item of this.heap.array) {
+      item.value.id = this.nextId++;
     }
     const array = this.heap.array;
     this.heap.clear().merge(array);

package/src/cache/decorator.d.ts

@@ -0,0 +1,46 @@
+import {CacheLRU} from './cache-lru.js';
+
+/** A wrapped function with attached cache and original function reference. */
+export interface WrappedFn<F extends (...args: any[]) => any, K = unknown, V = unknown> {
+  (...args: Parameters<F>): ReturnType<F>;
+  /** The original unwrapped function. */
+  fn: F;
+  /** The cache backing this wrapper. */
+  cache: CacheLRU<K, V>;
+}
+
+/**
+ * Wrap a function with caching. The first argument is used as the cache key.
+ * @param fn - Function to wrap.
+ * @param cache - Cache instance to use.
+ * @returns A wrapped function with `.fn` and `.cache` properties.
+ */
+export function decorateFn<F extends (...args: any[]) => any>(fn: F, cache: CacheLRU): WrappedFn<F>;
+
+/**
+ * Decorate an own property descriptor's `value` with caching.
+ * @param object - Object owning the property.
+ * @param key - Property name.
+ * @param cache - Cache instance to use.
+ * @returns The wrapped function.
+ */
+export function decorate(object: object, key: PropertyKey, cache: CacheLRU): WrappedFn<any>;
+
+/**
+ * Decorate a method on an object with caching (direct assignment).
+ * @param object - Object owning the method.
+ * @param key - Method name.
+ * @param cache - Cache instance to use.
+ * @returns The wrapped function.
+ */
+export function decorateMethod(object: object, key: PropertyKey, cache: CacheLRU): WrappedFn<any>;
+
+/**
+ * Retrieve the cache from a previously decorated property.
+ * @param object - Object owning the property.
+ * @param key - Property name.
+ * @returns The cache instance.
+ */
+export function getCache(object: object, key: PropertyKey): CacheLRU;
+
+export default decorate;