@mark1russell7/collections 0.4.0 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/collections",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Collections with no dependencies: lists, maps, queues, a summary tree, channels, lazy operations and dependency graphs.",
   "keywords": [
     "collections",

package/src/behaviors/bounded.ts

@@ -15,6 +15,7 @@
  * }
  */
 
+import { checkCapacity } from "../core/capacity.js";
 import type { Middleware } from "../core/middleware.js";
 import type { List } from "../interfaces/list.js";
 import type { Queue, Deque } from "../interfaces/queue.js";
@@ -66,7 +67,8 @@ export interface BoundedCollection {
 export function boundedList<T>(
   options: BoundedOptions<T>
 ): Middleware<List<T>, List<T> & BoundedCollection> {
-  const { capacity, policy = "throw", onOverflow } = options;
+  const { policy = "throw", onOverflow } = options;
+  const capacity = checkCapacity(options.capacity, "boundedList");
 
   return (next: List<T>): List<T> & BoundedCollection => {
     // An unshift puts the element at the front, so drop-oldest drops the last element for it
@@ -235,7 +237,8 @@ export function boundedList<T>(
 export function boundedQueue<T>(
   options: BoundedOptions<T>
 ): Middleware<Queue<T>, Queue<T> & BoundedCollection> {
-  const { capacity, policy = "throw", onOverflow } = options;
+  const { policy = "throw", onOverflow } = options;
+  const capacity = checkCapacity(options.capacity, "boundedQueue");
 
   return (next: Queue<T>): Queue<T> & BoundedCollection => {
     const handleOverflow = (element: T): void => {
@@ -306,7 +309,8 @@ export function boundedQueue<T>(
 export function boundedDeque<T>(
   options: BoundedOptions<T>
 ): Middleware<Deque<T>, Deque<T> & BoundedCollection> {
-  const { capacity, policy = "throw", onOverflow } = options;
+  const { policy = "throw", onOverflow } = options;
+  const capacity = checkCapacity(options.capacity, "boundedDeque");
 
   return (next: Deque<T>): Deque<T> & BoundedCollection => {
     const handleOverflow = (element: T): void => {
@@ -383,7 +387,8 @@ export function boundedMap<K, V>(
     onOverflow?: (context: Omit<OverflowContext<V>, "newElement"> & { key: K; value: V }) => void;
   }
 ): Middleware<MapLike<K, V>, MapLike<K, V> & BoundedCollection> {
-  const { capacity, policy = "throw", onOverflow } = options;
+  const { policy = "throw", onOverflow } = options;
+  const capacity = checkCapacity(options.capacity, "boundedMap");
 
   return (next: MapLike<K, V>): MapLike<K, V> & BoundedCollection => {
     let insertionOrder: K[] = []; // Track insertion order for drop-oldest

package/src/behaviors/lru.ts

@@ -14,6 +14,7 @@
  * // When full, least recently accessed keys are evicted
  */
 
+import { checkCapacity } from "../core/capacity.js";
 import type { Middleware } from "../core/middleware.js";
 import type { MapLike } from "../interfaces/map.js";
 import { compositeMapMethod } from "./composite.js";
@@ -23,7 +24,8 @@ import { compositeMapMethod } from "./composite.js";
  */
 export interface LRUOptions {
   /**
-   * Maximum capacity. When exceeded, least recently used items are evicted.
+   * The maximum number of entries, a positive whole number. When the map is full, a new key
+   * evicts the least recently used entry.
    */
   capacity: number;
 
@@ -50,11 +52,14 @@ interface LRUNode<K, V> {
  * This function maintains a doubly-linked list to track access order.
  * Most recently accessed items are at the head.
  * When capacity is exceeded, items at the tail are evicted.
+ *
+ * @throws RangeError when `options.capacity` is not a positive whole number.
  */
 export function lruMap<K, V>(
   options: LRUOptions
 ): Middleware<MapLike<K, V>, MapLike<K, V> & { readonly isFull: boolean }> {
-  const { capacity, onEvict } = options;
+  const { onEvict } = options;
+  const capacity = checkCapacity(options.capacity, "lruMap");
 
   return (next: MapLike<K, V>): MapLike<K, V> & { readonly isFull: boolean } => {
     // Doubly-linked list for LRU tracking
@@ -290,8 +295,13 @@ export class LRUCache<K, V> {
   private head: LRUNode<K, V> | null = null;
   private tail: LRUNode<K, V> | null = null;
 
+  /**
+   * @param capacity - The maximum number of entries, a positive whole number.
+   * @param onEvict - The function that this cache starts for each entry that it evicts.
+   * @throws RangeError when `capacity` is not a positive whole number.
+   */
   constructor(capacity: number, onEvict?: ((key: K, value: V) => void) | undefined) {
-    this.capacity = capacity;
+    this.capacity = checkCapacity(capacity, "LRUCache");
     this.onEvict = onEvict;
   }
 
@@ -359,6 +369,32 @@ export class LRUCache<K, V> {
     return true;
   }
 
+  /**
+   * This method deletes each entry for which `matches` gives true, and it gives the number of
+   * deleted entries. It is not a use: the order of the other entries does not change, and it
+   * does not start `onEvict`. It starts `matches` once for each entry, the most recent first. If
+   * `matches` throws, the entries that it matched before stay deleted.
+   *
+   * @param matches - The test of an entry.
+   * @returns The number of deleted entries.
+   */
+  deleteWhere(matches: (value: V, key: K) => boolean): number {
+    const nodes: LRUNode<K, V>[] = [];
+    for (let node = this.head; node; node = node.next) nodes.push(node);
+    let deleted = 0;
+    for (const node of nodes) {
+      // The function `matches` can change the cache. Skip each node that is not in it now.
+      if (this.map.get(node.key)?.node !== node) continue;
+      if (!matches(node.value, node.key)) continue;
+      // The function `matches` can delete this node itself, so check again.
+      if (this.map.get(node.key)?.node !== node) continue;
+      this.removeNode(node);
+      this.map.delete(node.key);
+      deleted++;
+    }
+    return deleted;
+  }
+
   clear(): void {
     this.map.clear();
     this.head = null;
@@ -439,7 +475,9 @@ export class LRUCache<K, V> {
 }
 
 /**
- * Factory function to make an LRU cache.
+ * This function makes an LRU cache.
+ *
+ * @throws RangeError when `capacity` is not a positive whole number.
  */
 export function lruCache<K, V>(
   capacity: number,

package/src/core/capacity.ts

@@ -0,0 +1,21 @@
+/**
+ * The check of a capacity, for each layer and class that has a maximum size.
+ */
+
+/**
+ * This function gives the capacity when it is a positive whole number. Otherwise it throws a
+ * `RangeError`. A capacity of `NaN` makes a comparison `size >= capacity` always false, so a
+ * structure with that capacity grows without a limit. A capacity of 0 or less, or a fraction,
+ * has no clear meaning.
+ *
+ * @param capacity - The capacity to check.
+ * @param owner - The name of the layer or class, for the message of the error.
+ * @returns The same capacity.
+ * @throws RangeError when the capacity is not a positive whole number.
+ */
+export function checkCapacity(capacity: number, owner: string): number {
+  if (!Number.isSafeInteger(capacity) || capacity < 1) {
+    throw new RangeError(`${owner}: the capacity must be a positive whole number, not ${String(capacity)}`);
+  }
+  return capacity;
+}