@mark1russell7/collections 0.5.0 → 0.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/collections",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Collections with no dependencies: lists, maps, queues, a summary tree, channels, lazy operations and dependency graphs.",
   "keywords": [
     "collections",
@@ -78,6 +78,9 @@
     "typescript": "^7.0.2",
     "vitest": "^5.0.3"
   },
+  "dependencies": {
+    "@mark1russell7/optional": "^1.2.0"
+  },
   "scripts": {
     "build": "tsdown",
     "test": "vitest run",

package/src/behaviors/safe.ts

@@ -1,35 +1,29 @@
 /**
- * Safe behavior - Gives Option/Result-based error handling.
- *
- * This module wraps collection operations that throw errors to instead return
- * Option<T> or Result<T, E>, enabling functional error handling.
+ * The safe middleware. Each operation that throws on a missing element has a safe form in the property `safe`. The safe
+ * form gives an `Optional` or a `Result` of `@mark1russell7/optional`, and does not throw.
  *
  * @example
- * const list = compose(
- *   safeList<number>()
- * )(arrayList<number>())
+ * import { isSome } from "@mark1russell7/optional";
  *
- * const value = list.safe.get(10) // Option<number> instead of throwing
- * if (isSome(value)) {
- *   console.log(value.value)
- * }
+ * const list = compose(safeList<number>())(arrayList<number>());
+ * const value = list.safe.get(10); // an Optional<number>, not an exception
+ * if (isSome(value)) console.log(value.value);
  */
 
 import type { Middleware } from "../core/middleware.js";
 import type { List } from "../interfaces/list.js";
 import type { Queue, Deque } from "../interfaces/queue.js";
 import type { MapLike } from "../interfaces/map.js";
-import { type Option, type Result } from "../core/effects.js";
-import { None, Some, tryCatch } from "../core/effects.js";
+import { none, some, toOptional, tryCatch, type Optional, type Result } from "@mark1russell7/optional";
 
 /**
  * Safe operations for List.
  */
 export interface SafeListOperations<T> {
   /**
-   * Get element at index, giving Option.
+   * Get element at index, as an optional.
    */
-  get(index: number): Option<T>;
+  get(index: number): Optional<T>;
 
   /**
    * Set element at index, giving Result with old value or error.
@@ -42,24 +36,24 @@ export interface SafeListOperations<T> {
   removeAt(index: number): Result<T, string>;
 
   /**
-   * Get first element as Option.
+   * Get first element as an optional.
    */
-  first(): Option<T>;
+  first(): Optional<T>;
 
   /**
-   * Get last element as Option.
+   * Get last element as an optional.
    */
-  last(): Option<T>;
+  last(): Optional<T>;
 
   /**
-   * Pop element, giving Option.
+   * Pop element, as an optional.
    */
-  pop(): Option<T>;
+  pop(): Optional<T>;
 
   /**
-   * Shift element, giving Option.
+   * Shift element, as an optional.
    */
-  shift(): Option<T>;
+  shift(): Optional<T>;
 }
 
 /**
@@ -67,19 +61,19 @@ export interface SafeListOperations<T> {
  */
 export interface SafeQueueOperations<T> {
   /**
-   * Peek at head element as Option.
+   * Peek at head element as an optional.
    */
-  peek(): Option<T>;
+  peek(): Optional<T>;
 
   /**
-   * Poll element as Option.
+   * Poll element as an optional.
    */
-  poll(): Option<T>;
+  poll(): Optional<T>;
 
   /**
-   * Dequeue element as Option.
+   * Dequeue element as an optional.
    */
-  dequeue(): Option<T>;
+  dequeue(): Optional<T>;
 }
 
 /**
@@ -87,29 +81,29 @@ export interface SafeQueueOperations<T> {
  */
 export interface SafeDequeOperations<T> extends SafeQueueOperations<T> {
   /**
-   * Peek at first element as Option.
+   * Peek at first element as an optional.
    */
-  peekFirst(): Option<T>;
+  peekFirst(): Optional<T>;
 
   /**
-   * Peek at last element as Option.
+   * Peek at last element as an optional.
    */
-  peekLast(): Option<T>;
+  peekLast(): Optional<T>;
 
   /**
-   * Poll first element as Option.
+   * Poll first element as an optional.
    */
-  pollFirst(): Option<T>;
+  pollFirst(): Optional<T>;
 
   /**
-   * Poll last element as Option.
+   * Poll last element as an optional.
    */
-  pollLast(): Option<T>;
+  pollLast(): Optional<T>;
 
   /**
-   * Pop element as Option.
+   * Pop element as an optional.
    */
-  pop(): Option<T>;
+  pop(): Optional<T>;
 }
 
 /**
@@ -117,9 +111,9 @@ export interface SafeDequeOperations<T> extends SafeQueueOperations<T> {
  */
 export interface SafeMapOperations<K, V> {
   /**
-   * Get value for key as Option.
+   * Get value for key as an optional.
    */
-  get(key: K): Option<V>;
+  get(key: K): Optional<V>;
 
   /**
    * Set value for key, giving Result with old value or success.
@@ -135,7 +129,7 @@ export interface SafeMapOperations<K, V> {
 /**
  * This function makes a safe List middleware.
  *
- * This function exposes a `safe` property with Option/Result-based operations.
+ * This function exposes a `safe` property with Optional/Result-based operations.
  */
 export function safeList<T>(): Middleware<
   List<T>,
@@ -143,14 +137,8 @@ export function safeList<T>(): Middleware<
 > {
   return (next: List<T>): List<T> & { safe: SafeListOperations<T> } => {
     const safe: SafeListOperations<T> = {
-      get(index: number): Option<T> {
-        return tryCatch(
-          () => next.get(index),
-          () => "Index out of bounds"
-        ).match<Option<T>>({
-          Ok: (value) => Some(value),
-          Err: () => None,
-        }) as Option<T>;
+      get(index: number): Optional<T> {
+        return toOptional(tryCatch(() => next.get(index)));
       },
 
       set(index: number, element: T): Result<T, string> {
@@ -167,34 +155,22 @@ export function safeList<T>(): Middleware<
         );
       },
 
-      first(): Option<T> {
-        return next.isEmpty ? None : Some(next.first());
+      first(): Optional<T> {
+        return next.isEmpty ? none : some(next.first());
       },
 
-      last(): Option<T> {
-        return next.isEmpty ? None : Some(next.last());
+      last(): Optional<T> {
+        return next.isEmpty ? none : some(next.last());
       },
 
-      pop(): Option<T> {
-        if (next.isEmpty) return None;
-        return tryCatch(
-          () => next.pop(),
-          () => "List is empty"
-        ).match<Option<T>>({
-          Ok: (value) => Some(value),
-          Err: () => None,
-        }) as Option<T>;
+      pop(): Optional<T> {
+        if (next.isEmpty) return none;
+        return toOptional(tryCatch(() => next.pop()));
       },
 
-      shift(): Option<T> {
-        if (next.isEmpty) return None;
-        return tryCatch(
-          () => next.shift(),
-          () => "List is empty"
-        ).match<Option<T>>({
-          Ok: (value) => Some(value),
-          Err: () => None,
-        }) as Option<T>;
+      shift(): Optional<T> {
+        if (next.isEmpty) return none;
+        return toOptional(tryCatch(() => next.shift()));
       },
     };
 
@@ -212,37 +188,19 @@ export function safeQueue<T>(): Middleware<
 > {
   return (next: Queue<T>): Queue<T> & { safe: SafeQueueOperations<T> } => {
     const safe: SafeQueueOperations<T> = {
-      peek(): Option<T> {
-        if (next.isEmpty) return None;
-        return tryCatch(
-          () => next.peek(),
-          () => "Queue is empty"
-        ).match<Option<T>>({
-          Ok: (value) => Some(value),
-          Err: () => None,
-        }) as Option<T>;
+      peek(): Optional<T> {
+        if (next.isEmpty) return none;
+        return toOptional(tryCatch(() => next.peek()));
       },
 
-      poll(): Option<T> {
-        if (next.isEmpty) return None;
-        return tryCatch(
-          () => next.poll(),
-          () => "Queue is empty"
-        ).match<Option<T>>({
-          Ok: (value) => Some(value),
-          Err: () => None,
-        }) as Option<T>;
+      poll(): Optional<T> {
+        if (next.isEmpty) return none;
+        return toOptional(tryCatch(() => next.poll()));
       },
 
-      dequeue(): Option<T> {
-        if (next.isEmpty) return None;
-        return tryCatch(
-          () => next.dequeue(),
-          () => "Queue is empty"
-        ).match<Option<T>>({
-          Ok: (value) => Some(value),
-          Err: () => None,
-        }) as Option<T>;
+      dequeue(): Optional<T> {
+        if (next.isEmpty) return none;
+        return toOptional(tryCatch(() => next.dequeue()));
       },
     };
 
@@ -259,55 +217,43 @@ export function safeDeque<T>(): Middleware<
 > {
   return (next: Deque<T>): Deque<T> & { safe: SafeDequeOperations<T> } => {
     const safe: SafeDequeOperations<T> = {
-      peek(): Option<T> {
-        return next.isEmpty ? None : Some(next.peekFirst());
+      peek(): Optional<T> {
+        return next.isEmpty ? none : some(next.peekFirst());
       },
 
-      poll(): Option<T> {
+      poll(): Optional<T> {
         // One poll: before, the test and the result each called pollFirst(), so poll() removed
         // two elements and returned the second (BUGS-2026-07 L12)
-        if (next.isEmpty) return None;
-        return Some(next.pollFirst() as T);
+        if (next.isEmpty) return none;
+        return some(next.pollFirst() as T);
       },
 
-      dequeue(): Option<T> {
-        if (next.isEmpty) return None;
-        return tryCatch(
-          () => next.dequeue(),
-          () => "Deque is empty"
-        ).match<Option<T>>({
-          Ok: (value) => Some(value),
-          Err: () => None,
-        }) as Option<T>;
+      dequeue(): Optional<T> {
+        if (next.isEmpty) return none;
+        return toOptional(tryCatch(() => next.dequeue()));
       },
 
-      peekFirst(): Option<T> {
-        return next.isEmpty ? None : Some(next.peekFirst());
+      peekFirst(): Optional<T> {
+        return next.isEmpty ? none : some(next.peekFirst());
       },
 
-      peekLast(): Option<T> {
-        return next.isEmpty ? None : Some(next.peekLast());
+      peekLast(): Optional<T> {
+        return next.isEmpty ? none : some(next.peekLast());
       },
 
-      pollFirst(): Option<T> {
+      pollFirst(): Optional<T> {
         const result = next.pollFirst();
-        return result !== undefined ? Some(result) : None;
+        return result !== undefined ? some(result) : none;
       },
 
-      pollLast(): Option<T> {
+      pollLast(): Optional<T> {
         const result = next.pollLast();
-        return result !== undefined ? Some(result) : None;
+        return result !== undefined ? some(result) : none;
       },
 
-      pop(): Option<T> {
-        if (next.isEmpty) return None;
-        return tryCatch(
-          () => next.pop(),
-          () => "Deque is empty"
-        ).match<Option<T>>({
-          Ok: (value) => Some(value),
-          Err: () => None,
-        }) as Option<T>;
+      pop(): Optional<T> {
+        if (next.isEmpty) return none;
+        return toOptional(tryCatch(() => next.pop()));
       },
     };
 
@@ -326,8 +272,8 @@ export function safeMap<K, V>(): Middleware<
     next: MapLike<K, V>
   ): MapLike<K, V> & { safe: SafeMapOperations<K, V> } => {
     const safe: SafeMapOperations<K, V> = {
-      get(key: K): Option<V> {
-        return next.has(key) ? Some(next.get(key)) : None;
+      get(key: K): Optional<V> {
+        return next.has(key) ? some(next.get(key)) : none;
       },
 
       set(key: K, value: V): Result<V | undefined, string> {

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;
 }

package/src/impl/hash-map.ts

@@ -136,46 +136,36 @@ export class HashMap<K, V> implements MapLike<K, V> {
   // ========================================================================
 
   has(key: K): boolean {
-    const hash = this._keyHash(key);
-    const index = this.bucketIndex(hash);
-    let node = this._buckets[index] ?? null;
-
-    while (node !== null) {
-      if (node.hash === hash && this._keyEq(node.key, key)) {
-        return true;
-      }
-      node = node.next;
-    }
-
-    return false;
+    return this.findNode(key) !== null;
   }
 
   get(key: K): V {
-    const value = this.getOrUndefined(key);
-    if (value === undefined) {
+    // The node, not the value, tells if the key is present: a key can have the value undefined (C8)
+    const node = this.findNode(key);
+    if (node === null) {
       throw new Error(`Key not found: ${key}`);
     }
-    return value;
+    return node.value;
   }
 
   getOrUndefined(key: K): V | undefined {
-    const hash = this._keyHash(key);
-    const index = this.bucketIndex(hash);
-    let node = this._buckets[index] ?? null;
+    return this.findNode(key)?.value;
+  }
 
+  getOrDefault(key: K, defaultValue: V): V {
+    const node = this.findNode(key);
+    return node !== null ? node.value : defaultValue;
+  }
+
+  /** This method finds the node of a key, or gives `null`. */
+  private findNode(key: K): Node<K, V> | null {
+    const hash = this._keyHash(key);
+    let node = this._buckets[this.bucketIndex(hash)] ?? null;
     while (node !== null) {
-      if (node.hash === hash && this._keyEq(node.key, key)) {
-        return node.value;
-      }
+      if (node.hash === hash && this._keyEq(node.key, key)) return node;
       node = node.next;
     }
-
-    return undefined;
-  }
-
-  getOrDefault(key: K, defaultValue: V): V {
-    const value = this.getOrUndefined(key);
-    return value !== undefined ? value : defaultValue;
+    return null;
   }
 
   containsValue(value: V): boolean {

package/src/index.ts

@@ -10,7 +10,6 @@
 // ============================================================================
 
 export * from "./core/traits.js";
-export * from "./core/effects.js";
 export * from "./core/policies.js";
 export * from "./core/middleware.js";
 export * from "./core/events.js";
@@ -220,18 +219,3 @@ export {
   groupBy,
 } from "./utils/factories.js";
 
-// Effects
-export {
-  None,
-  Some,
-  type Option,
-  Ok,
-  Err,
-  type Result,
-  isSome,
-  isNone,
-  isOk,
-  isErr,
-  getOrElse,
-  unwrap,
-} from "./core/effects.js";