@mark1russell7/collections 0.9.6 → 0.9.8

package/package.json

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

package/src/behaviors/evented.ts

@@ -19,10 +19,11 @@
 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 { Entry, MapLike } from "../interfaces/map.js";
 import type { Collection } from "../interfaces/collection.js";
 import { Emitter, type Unsubscribe } from "../core/events.js";
 import { removalsOf, type ElementRemoval, type MapRemoval, type RemovalReason } from "../core/removals.js";
+import { compositeMapMethod } from "./composite.js";
 
 /** The number of removals that a layer heard from the layers below it, and the number from the first end. */
 interface Heard {
@@ -48,6 +49,62 @@ function hear<R extends ElementRemoval<unknown> | MapRemoval<unknown, unknown>>(
 const added = (size: number, sizeBefore: number, heard: Heard, heardBefore: number): boolean =>
   size - sizeBefore + heard.all - heardBefore > 0;
 
+/**
+ * This function gives the removals that change `before` to `after`, in the order of a replay.
+ * Each index is the place of the value at the time of its removal. It gives undefined when `after` is not in the order of `before`.
+ */
+function removalsInOrder<T>(before: readonly T[], after: readonly T[]): { value: T; index: number }[] | undefined {
+  const removed: { value: T; index: number }[] = [];
+  let kept = 0;
+  for (const value of before) {
+    if (kept < after.length && Object.is(value, after[kept])) kept++;
+    else removed.push({ value, index: kept });
+  }
+  return kept === after.length ? removed : undefined;
+}
+
+/** This function gives the values of `before` that are not in `after`, with each copy counted. The order does not matter. */
+function removedValues<T>(before: readonly T[], after: readonly T[]): T[] {
+  const left = new Map<T, number>();
+  for (const value of after) left.set(value, (left.get(value) ?? 0) + 1);
+  const removed: T[] = [];
+  for (const value of before) {
+    const count = left.get(value) ?? 0;
+    if (count > 0) left.set(value, count - 1);
+    else removed.push(value);
+  }
+  return removed;
+}
+
+/**
+ * This function wraps a bulk removal (removeAll, retainAll, removeRange) of the collection below.
+ * The base does the removal with its own equality, and `report` gets the contents before and after it.
+ */
+function bulkRemoval<T>(
+  target: { readonly size: number; toArray(): T[] },
+  method: Function,
+  report: (before: T[], after: T[]) => void,
+): (...args: unknown[]) => unknown {
+  return function (...args: unknown[]): unknown {
+    const before = target.toArray();
+    const result = method.apply(target, args);
+    if (target.size !== before.length) report(before, target.toArray());
+    return result;
+  };
+}
+
+/**
+ * This function adds each element with `add` of the layer, one after the other.
+ * Thus each element gives its own event, with the rules of a single add. It gives true when one element goes in.
+ */
+function addEach<T>(elements: Iterable<T>, add: (element: T) => boolean): boolean {
+  let changed = false;
+  for (const element of Array.from(elements)) {
+    if (add(element)) changed = true;
+  }
+  return changed;
+}
+
 // ============================================================================
 // Event type definitions
 // ============================================================================
@@ -78,6 +135,8 @@ export interface QueueEvents<T> {
   enqueue: { value: T };
   /** Element was removed from queue. A removal by a layer below (a drop) has a `reason`. */
   dequeue: { value: T; reason?: RemovalReason };
+  /** An element left from a place that is not the head: `remove`, `removeAll` or `retainAll`. */
+  remove: { value: T };
   /** Collection was cleared */
   clear: {};
 }
@@ -94,6 +153,8 @@ export interface DequeEvents<T> {
   removeFirst: { value: T; reason?: RemovalReason };
   /** Element was removed from back. A removal by a layer below (a drop) has a `reason`. */
   removeLast: { value: T; reason?: RemovalReason };
+  /** An element left from `index`, not with a method of an end: `remove`, `removeAll` or `retainAll`. */
+  remove: { value: T; index: number };
   /** Collection was cleared */
   clear: {};
 }
@@ -232,6 +293,46 @@ export function eventedList<T>(): Middleware<
                 emitter.emit("clear", {});
               };
 
+            // The base writes a bulk change into its storage, and does not call its own add or remove (C24)
+            case "addAll":
+              return function (elements: Iterable<T>): boolean {
+                return addEach(elements, (element) => {
+                  const size = target.size;
+                  const all = heard.all;
+                  (receiver as List<T>).add(element);
+                  return added(target.size, size, heard, all);
+                });
+              };
+
+            case "insertAll":
+              return function (index: number, elements: Iterable<T>): boolean {
+                let at = index;
+                return addEach(elements, (element) => {
+                  const size = target.size;
+                  const all = heard.all;
+                  const first = heard.first;
+                  (receiver as List<T>).insert(at, element);
+                  const wentIn = added(target.size, size, heard, all);
+                  // A drop of the first element below moved the place one lower. The next element goes after a new one.
+                  at = Math.min(target.size, Math.max(0, at - (heard.first - first)) + (wentIn ? 1 : 0));
+                  return wentIn;
+                });
+              };
+
+            case "removeAll":
+            case "retainAll":
+            case "removeRange":
+              return bulkRemoval<T>(target, value as Function, (before, after) => {
+                const removed = removalsInOrder(before, after);
+                if (removed) {
+                  for (const removal of removed) emitter.emit("remove", removal);
+                  return;
+                }
+                // A base that changed the order of the rest: a clear and the adds give the same contents
+                emitter.emit("clear", {});
+                after.forEach((element, at) => emitter.emit("add", { value: element, index: at }));
+              });
+
             case "sort":
               return function (...args: any[]): void {
                 (value as Function).apply(target, args);
@@ -297,11 +398,32 @@ export function eventedQueue<T>(): Middleware<
                 return removed;
               };
 
+            case "pollOrUndefined":
+              return function (): T | undefined {
+                const size = target.size;
+                const removed = (value as Function).call(target);
+                if (target.size < size) emitter.emit("dequeue", { value: removed });
+                return removed;
+              };
+
             case "clear":
               return function (): void {
                 (value as Function).call(target);
                 emitter.emit("clear", {});
               };
+
+            // The base writes a bulk change into its storage, and does not call its own add or remove (C24)
+            case "addAll":
+              return function (elements: Iterable<T>): boolean {
+                return addEach(elements, (element) => (receiver as Queue<T>).add(element) !== false);
+              };
+
+            case "remove":
+            case "removeAll":
+            case "retainAll":
+              return bulkRemoval<T>(target, value as Function, (before, after) => {
+                for (const removed of removedValues(before, after)) emitter.emit("remove", { value: removed });
+              });
           }
         }
 
@@ -380,11 +502,44 @@ export function eventedDeque<T>(): Middleware<
                 return removed;
               };
 
+            case "pollOrUndefined":
+              return function (): T | undefined {
+                const size = target.size;
+                const removed = (value as Function).call(target);
+                if (target.size < size) emitter.emit("removeFirst", { value: removed });
+                return removed;
+              };
+
             case "clear":
               return function (): void {
                 (value as Function).call(target);
                 emitter.emit("clear", {});
               };
+
+            // The base writes a bulk change into its storage, and does not call its own add or remove (C24)
+            case "addAll":
+              return function (elements: Iterable<T>): boolean {
+                return addEach(elements, (element) => {
+                  const size = target.size;
+                  const all = heard.all;
+                  (receiver as Deque<T>).addLast(element);
+                  return added(target.size, size, heard, all);
+                });
+              };
+
+            case "remove":
+            case "removeAll":
+            case "retainAll":
+              return bulkRemoval<T>(target, value as Function, (before, after) => {
+                const removed = removalsInOrder(before, after);
+                if (removed) {
+                  for (const removal of removed) emitter.emit("remove", removal);
+                  return;
+                }
+                // A base that changed the order of the rest: a clear and the adds give the same contents
+                emitter.emit("clear", {});
+                for (const element of after) emitter.emit("addLast", { value: element });
+              });
           }
         }
 
@@ -416,6 +571,13 @@ export function eventedMap<K, V>(): Middleware<
           return emitter.on.bind(emitter);
         }
 
+        // Composite methods (computeIfAbsent, compute, merge, putAll and others) go through this
+        // proxy's own set and delete, so each change gives its event (C24). The base calls its own set.
+        const composite = compositeMapMethod(receiver as MapLike<K, V>, prop);
+        if (composite) {
+          return composite;
+        }
+
         const value = Reflect.get(target, prop, receiver);
 
         if (typeof value === "function") {
@@ -441,6 +603,15 @@ export function eventedMap<K, V>(): Middleware<
                 return deletedValue;
               };
 
+            // The first or last entry of a navigable map (treeMap)
+            case "pollFirstEntry":
+            case "pollLastEntry":
+              return function (): Entry<K, V> | undefined {
+                const entry: Entry<K, V> | undefined = (value as Function).call(target);
+                if (entry !== undefined) emitter.emit("delete", { key: entry.key, value: entry.value });
+                return entry;
+              };
+
             case "clear":
               return function (): void {
                 (value as Function).call(target);
@@ -504,6 +675,32 @@ export function evented<T>(): Middleware<
                 (value as Function).call(target);
                 emitter.emit("clear", {});
               };
+
+            // The base writes a bulk change into its storage, and does not call its own add or remove (C24)
+            case "addAll":
+              return function (elements: Iterable<T>): boolean {
+                let changed = false;
+                for (const element of Array.from(elements)) {
+                  if ((receiver as Collection<T>).add(element)) changed = true;
+                }
+                return changed;
+              };
+
+            case "removeAll":
+            case "retainAll":
+              return bulkRemoval<T>(target, value as Function, (before, after) => {
+                for (const removed of removedValues(before, after)) emitter.emit("remove", { value: removed });
+              });
+
+            // The first or last element of a sorted set (treeSet)
+            case "pollFirst":
+            case "pollLast":
+              return function (): T | undefined {
+                const size = target.size;
+                const removed = (value as Function).call(target);
+                if (target.size < size) emitter.emit("remove", { value: removed });
+                return removed;
+              };
           }
         }
 

package/src/behaviors/synchronized.ts

@@ -277,8 +277,12 @@ export function readWriteLock<C extends object>(): Middleware<C> {
       "forEach",
       "getOrDefault",
       "getOrUndefined",
+      "descendingIterator",
     ]);
 
+    // The reads that give an iterator. The lock copies the elements before it releases the read (C32).
+    const ITERATOR_READS = new Set(["keys", "values", "entries", "descendingIterator"]);
+
     return new Proxy(next, {
       get(target, prop, receiver) {
         const value = Reflect.get(target, prop, receiver);
@@ -287,15 +291,28 @@ export function readWriteLock<C extends object>(): Middleware<C> {
           return value;
         }
 
-        const isReadMethod = typeof prop === "string" && READ_METHODS.has(prop);
+        // A method with a symbol key, for example Symbol.iterator, stays synchronous, so `for of` works (C32).
+        // The loop reads at once with no lock, as a plain method of synchronized().
+        if (typeof prop === "symbol") {
+          return function (this: unknown, ...args: unknown[]) {
+            return (value as Function).apply(target, args);
+          };
+        }
+
+        const isReadMethod = READ_METHODS.has(prop);
+        const isIteratorRead = ITERATOR_READS.has(prop);
 
         return async function (this: any, ...args: any[]) {
           if (isReadMethod) {
             // Acquire read lock
             await acquireRead();
             try {
-              const result = (value as Function).apply(target, args);
-              return result instanceof Promise ? await result : result;
+              const raw = (value as Function).apply(target, args);
+              const result = raw instanceof Promise ? await raw : raw;
+              // Before C32, the iteration started after the release of the read, so a write could change the elements.
+              return isIteratorRead && result != null && typeof result[Symbol.iterator] === "function"
+                ? Array.from(result as Iterable<unknown>)[Symbol.iterator]()
+                : result;
             } finally {
               releaseRead();
             }