@mark1russell7/collections 0.4.0 → 0.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/collections",
-  "version": "0.4.0",
+  "version": "0.6.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;
+}

package/src/dag/executor.ts

@@ -68,6 +68,9 @@ function notify<T>(name: string, listener: ((arg: T) => void) | undefined, arg:
  * A processor that throws does NOT reject the whole run. The run records the throw
  * as a failed NodeResult, so partial results are always given.
  *
+ * With `skipDependents` (the default), a node whose dependency failed or was skipped does not start. Its result has
+ * `skipped: true` and an error that names those dependencies. A dependency outside the DAG does not count.
+ *
  * `failFast` operates at level granularity. When a node in a level fails, each
  * node already in flight in that level continues to completion. No later level
  * starts. (There is no mid-level cancellation.)
@@ -80,20 +83,37 @@ export async function executeDAG<TNode extends DAGNode>(
   const {
     concurrency = 4,
     failFast = true,
+    skipDependents = true,
     onNodeStart,
     onNodeComplete,
   } = options;
 
   const results = new Map<string, NodeResult<TNode>>();
   const failedNodes: string[] = [];
+  const skippedNodes: string[] = [];
+  // The ids of the nodes that failed or were skipped
+  const blocked = new Set<string>();
   const startTime = Date.now();
   let shouldStop = false;
 
   for (const level of dag.levels) {
     if (shouldStop) break;
 
+    const runnable: TNode[] = [];
+    for (const node of level) {
+      const blockers = skipDependents ? node.dependencies.filter((dep) => blocked.has(dep)) : [];
+      if (blockers.length === 0) {
+        runnable.push(node);
+        continue;
+      }
+      const message = "Skipped " + node.id + ": the dependencies " + blockers.join(", ") + " failed or were skipped";
+      results.set(node.id, { node, success: false, skipped: true, error: new Error(message), duration: 0, logs: [message] });
+      skippedNodes.push(node.id);
+      blocked.add(node.id);
+    }
+
     const levelResults = await executeWithConcurrency(
-      level,
+      runnable,
       async (node) => {
         const startError = notify("onNodeStart", onNodeStart, node);
         const nodeStart = Date.now();
@@ -127,6 +147,7 @@ export async function executeDAG<TNode extends DAGNode>(
       results.set(result.node.id, result);
       if (!result.success) {
         failedNodes.push(result.node.id);
+        blocked.add(result.node.id);
         if (failFast) {
           shouldStop = true;
         }
@@ -135,9 +156,10 @@ export async function executeDAG<TNode extends DAGNode>(
   }
 
   return {
-    success: failedNodes.length === 0,
+    success: failedNodes.length === 0 && skippedNodes.length === 0,
     results,
     failedNodes,
+    skippedNodes,
     totalDuration: Date.now() - startTime,
   };
 }

package/src/dag/types.ts

@@ -41,6 +41,11 @@ export interface DAGExecutionOptions<TNode extends DAGNode = DAGNode> {
   concurrency?: number;
   /** When this value is true, the run stops on the first error. The default is true. */
   failFast?: boolean;
+  /**
+   * When this value is true, a node whose dependency failed or was skipped does not start. Its result has `skipped: true`.
+   * The default is true. Give false only when the nodes do not use the work of their dependencies.
+   */
+  skipDependents?: boolean;
   /** Callback for progress reporting */
   onNodeStart?: (node: TNode) => void;
   /** Callback when a node completes */
@@ -63,6 +68,8 @@ export interface NodeResult<TNode extends DAGNode = DAGNode> {
   logs: string[];
   /** Optional output from the processor */
   output?: unknown | undefined;
+  /** This value is true when the node did not start, because a dependency failed or was skipped. */
+  skipped?: boolean | undefined;
 }
 
 /**
@@ -73,8 +80,10 @@ export interface DAGResult<TNode extends DAGNode = DAGNode> {
   success: boolean;
   /** Results for each node */
   results: Map<string, NodeResult<TNode>>;
-  /** Names of failed nodes */
+  /** The ids of the nodes whose processor failed */
   failedNodes: string[];
+  /** The ids of the nodes that did not start, because a dependency failed or was skipped */
+  skippedNodes: string[];
   /** Total duration in milliseconds */
   totalDuration: number;
 }