@mark1russell7/collections 0.6.0 → 0.7.1

package/build/layers.d.ts

@@ -24,7 +24,9 @@ type InnerOf<L> = L extends ((next: infer I) => any) ? I : never;
 type OuterOf<L> = L extends ((next: any) => infer O) ? O : never;
 /**
  * This type checks each neighbor pair of a list of layers. The result of the inner neighbor must
- * fit the input of the outer neighbor. At the first bad pair, the compiler marks that argument.
+ * fit the input of the outer neighbor. A bad pair makes the compiler refuse the call. The compiler
+ * marks the first argument, not the bad pair. Its message shows the type that the first bad pair
+ * needs. At the place of the inner neighbor, it needs a layer that gives the input of the outer one.
  *
  * The type is tail recursive, so the compiler accepts a chain of 100 layers.
  */

package/build/layers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layers.d.ts","names":[],"sources":["../src/core/layers.ts"],"mappings":";;;;;;;;;;;;;;;;;;;KAoBY,MAAM,aAAa,QAAQ,UAAU,MAAM,UAAU;;KAGrD,QAAQ,KAAK,YAAW,YAAY,aAAY;;KAGhD,QAAQ,KAAK,YAAW,oBAAoB,KAAI;;;;;;;KAQhD,MAAM,8BAA8B,iDAC9C,0BAA0B,SAAS,YAAY,MAC1C,QAAQ,aAAa,QAAQ,MAC5B,gBAAgB,MAAM,iBAAiB,MAAM,mBAChC,MAAM,GAAG,WAAW,QAAQ,QAAQ,kBACtC,SAAS;;;;;;KAOhB,SAAS,gCACnB,yBACK,GAAG,MAAM,MAAM,IAChB,0BAA0B,uBACxB,wCAAwC,SACrC,MAAM,QAAQ,UAAU,QAAQ,iBAEnC,0BAA0B,QACvB,MAAM,QAAQ,OAAO,QAAQ;;KAI5B,OAAO,8BAA8B,iBAC/C,0BAA0B,gBAAgB,QAAQ,OAAO,MAAM,MAAM,QAAQ,UAAU;;;;;KAM7E,QAAQ,gCAClB,wCAAwC,SACnC,MAAM,QAAQ,UAAU,OAAO,KAAK,QAAQ,QAC7C,SAAS;;;;;;;;;;;;;iBAcC,cAAc,mBAAmB,YAAY,QAAQ,IAAI,MAAM,KAAK,SAAS"}
+{"version":3,"file":"layers.d.ts","names":[],"sources":["../src/core/layers.ts"],"mappings":";;;;;;;;;;;;;;;;;;;KAoBY,MAAM,aAAa,QAAQ,UAAU,MAAM,UAAU;;KAGrD,QAAQ,KAAK,YAAW,YAAY,aAAY;;KAGhD,QAAQ,KAAK,YAAW,oBAAoB,KAAI;;;;;;;;;KAUhD,MAAM,8BAA8B,iDAC9C,0BAA0B,SAAS,YAAY,MAC1C,QAAQ,aAAa,QAAQ,MAC5B,gBAAgB,MAAM,iBAAiB,MAAM,mBAChC,MAAM,GAAG,WAAW,QAAQ,QAAQ,kBACtC,SAAS;;;;;;KAOhB,SAAS,gCACnB,yBACK,GAAG,MAAM,MAAM,IAChB,0BAA0B,uBACxB,wCAAwC,SACrC,MAAM,QAAQ,UAAU,QAAQ,iBAEnC,0BAA0B,QACvB,MAAM,QAAQ,OAAO,QAAQ;;KAI5B,OAAO,8BAA8B,iBAC/C,0BAA0B,gBAAgB,QAAQ,OAAO,MAAM,MAAM,QAAQ,UAAU;;;;;KAM7E,QAAQ,gCAClB,wCAAwC,SACnC,MAAM,QAAQ,UAAU,OAAO,KAAK,QAAQ,QAC7C,SAAS;;;;;;;;;;;;;iBAcC,cAAc,mBAAmB,YAAY,QAAQ,IAAI,MAAM,KAAK,SAAS"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/collections",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Collections with no dependencies: lists, maps, queues, a summary tree, channels, lazy operations and dependency graphs.",
   "keywords": [
     "collections",
@@ -71,6 +71,7 @@
     "@mark1russell7/rigor-bench": "^0.2.5",
     "@mark1russell7/rigor-generators": "^0.1.5",
     "@mark1russell7/rigor-statistics": "^0.1.8",
+    "@mark1russell7/rigor-testkit": "^0.1.0",
     "@types/node": "^26.6.5",
     "esbuild": "^0.28.2",
     "fast-check": "^4.10.2",
@@ -78,6 +79,9 @@
     "typescript": "^7.0.2",
     "vitest": "^5.0.3"
   },
+  "dependencies": {
+    "@mark1russell7/optional": "^1.2.0"
+  },
   "scripts": {
     "build": "tsdown",
     "test": "vitest run",

package/src/behaviors/readonly.ts

@@ -84,6 +84,30 @@ const MUTATING_METHODS = new Set([
   "compute",
   "merge",
   "putAll",
+
+  // Queue changes that give undefined on an empty queue (C27: a readonly view removed an element)
+  "pollOrUndefined",
+
+  // The internal changes of the structures of this package. TypeScript marks them private, but a call at run
+  // time reaches them. `readonly.test.ts` puts each method of each structure in the reads or in this list.
+  "ensureCapacity",
+  "trimToSize",
+  "grow",
+  "resize",
+  "removeAtOffset",
+  "unlinkNode",
+  "heapify",
+  "bubbleUp",
+  "bubbleDown",
+  "addToEnd",
+  "moveToEnd",
+  "removeFromBucket",
+  "removeFromList",
+  "deleteNode",
+  "fixAfterInsertion",
+  "fixAfterDeletion",
+  "rotateLeft",
+  "rotateRight",
 ]);
 
 /** Methods that return a view of the collection: the view is readonly too. */

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/core/layers.ts

@@ -28,7 +28,9 @@ export type OuterOf<L> = L extends (next: any) => infer O ? O : never;
 
 /**
  * This type checks each neighbor pair of a list of layers. The result of the inner neighbor must
- * fit the input of the outer neighbor. At the first bad pair, the compiler marks that argument.
+ * fit the input of the outer neighbor. A bad pair makes the compiler refuse the call. The compiler
+ * marks the first argument, not the bad pair. Its message shows the type that the first bad pair
+ * needs. At the place of the inner neighbor, it needs a layer that gives the input of the outer one.
  *
  * The type is tail recursive, so the compiler accepts a chain of 100 layers.
  */

package/src/dag/executor.ts

@@ -71,9 +71,11 @@ function notify<T>(name: string, listener: ((arg: T) => void) | undefined, arg:
  * 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.)
+ * `failFast` operates on levels. When a node of a level fails, each node of that level continues to its end.
+ * This includes the nodes that did not start before the failure, when `concurrency` is less than the
+ * size of the level. No later level starts. The run does not cancel a node.
+ *
+ * A node that did not start (`skipped: true`) calls neither `onNodeStart` nor `onNodeComplete`.
  */
 export async function executeDAG<TNode extends DAGNode>(
   dag: DependencyDAG<TNode>,

package/src/dag/types.ts

@@ -39,7 +39,10 @@ export interface DependencyDAG<TNode extends DAGNode = DAGNode> {
 export interface DAGExecutionOptions<TNode extends DAGNode = DAGNode> {
   /** Max parallel operations per level (default: 4) */
   concurrency?: number;
-  /** When this value is true, the run stops on the first error. The default is true. */
+  /**
+   * When this value is true, no level starts after a level with a failure. The default is true.
+   * Each node of the level with the failure runs, also a node that did not start before the failure.
+   */
   failFast?: boolean;
   /**
    * When this value is true, a node whose dependency failed or was skipped does not start. Its result has `skipped: true`.

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

package/src/interfaces/list.ts

@@ -43,10 +43,9 @@ export interface ReadonlyList<T> extends ReadonlyCollection<T> {
   lastIndexOf(element: T, fromIndex?: number): number;
 
   /**
-   * This method gives a view of the portion of this list between fromIndex (inclusive)
-   * and toIndex (exclusive).
+   * This method gives a new list with the elements from fromIndex (inclusive) to toIndex (exclusive).
    *
-   * Changes to the sublist are reflected in the original list.
+   * The new list is a copy, not a view. A change to one list does not change the other list.
    *
    * @param fromIndex Start index (inclusive)
    * @param toIndex End index (exclusive)
@@ -135,7 +134,8 @@ export interface List<T> extends ReadonlyList<T>, Collection<T> {
   reverse(): void;
 
   /**
-   * This method gives a mutable sublist view.
+   * This method gives a new mutable list with the elements from fromIndex (inclusive) to toIndex (exclusive).
+   * The new list is a copy, not a view.
    *
    * @param fromIndex Start index (inclusive)
    * @param toIndex End index (exclusive)