@mark1russell7/collections 0.7.2 → 0.9.0

package/package.json

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

@@ -20,6 +20,7 @@ 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 { removals, removalSource, type ElementRemoval, type MapRemoval } from "../core/removals.js";
 import type { Collection } from "../interfaces/collection.js";
 import type {
   OverflowPolicy,
@@ -71,6 +72,7 @@ export function boundedList<T>(
   const capacity = checkCapacity(options.capacity, "boundedList");
 
   return (next: List<T>): List<T> & BoundedCollection => {
+    const source = removalSource<ElementRemoval<T>>(next);
     // An unshift puts the element at the front, so drop-oldest drops the last element for it
     const handleOverflow = (element: T, dropFrom: "first" | "last" = "first"): void => {
       // Call overflow handler if provided
@@ -92,8 +94,8 @@ export function boundedList<T>(
         case "drop-oldest":
           // Remove one element: the first, or the last for an unshift
           if (!next.isEmpty) {
-            if (dropFrom === "last") next.pop();
-            else next.shift();
+            const value = dropFrom === "last" ? next.pop() : next.shift();
+            source.emit({ value, end: dropFrom, reason: "drop" });
           }
           break;
 
@@ -123,6 +125,7 @@ export function boundedList<T>(
     return new Proxy(next, {
       get(target, prop, receiver) {
         // Capacity property
+        if (prop === removals) return source.channel;
         if (prop === "capacity") {
           return capacity;
         }
@@ -231,6 +234,19 @@ export function boundedList<T>(
   };
 }
 
+/**
+ * This function adds each element with `add`, one after the other, until `add` refuses one.
+ * It gives true when one element goes in. A throw of `add` stops it, and the earlier elements stay.
+ */
+function addEach<T>(elements: Iterable<T>, add: (element: T) => boolean): boolean {
+  let added = false;
+  for (const element of Array.from(elements)) {
+    if (!add(element)) break;
+    added = true;
+  }
+  return added;
+}
+
 /**
  * This function makes a bounded Queue middleware.
  */
@@ -241,6 +257,7 @@ export function boundedQueue<T>(
   const capacity = checkCapacity(options.capacity, "boundedQueue");
 
   return (next: Queue<T>): Queue<T> & BoundedCollection => {
+    const source = removalSource<ElementRemoval<T>>(next);
     const handleOverflow = (element: T): void => {
       if (onOverflow) {
         const context: OverflowContext<T> = {
@@ -257,7 +274,7 @@ export function boundedQueue<T>(
           throw new Error(`Queue is full (capacity: ${capacity})`);
         case "drop-oldest":
           if (!next.isEmpty) {
-            next.poll();
+            source.emit({ value: next.poll() as T, end: "first", reason: "drop" });
           }
           break;
         case "drop-newest":
@@ -274,6 +291,7 @@ export function boundedQueue<T>(
 
     return new Proxy(next, {
       get(target, prop, receiver) {
+        if (prop === removals) return source.channel;
         if (prop === "capacity") return capacity;
         if (prop === "isFull") return target.size >= capacity;
         if (prop === "remainingCapacity") return Math.max(0, capacity - target.size);
@@ -294,6 +312,12 @@ export function boundedQueue<T>(
                 }
                 return (value as Function).call(target, element);
               };
+
+            // The base addAll goes past the bound, so each element goes through add of this proxy (C10)
+            case "addAll":
+              return function (elements: Iterable<T>): boolean {
+                return addEach(elements, (element) => (receiver as Queue<T>).add(element));
+              };
           }
         }
 
@@ -313,7 +337,9 @@ export function boundedDeque<T>(
   const capacity = checkCapacity(options.capacity, "boundedDeque");
 
   return (next: Deque<T>): Deque<T> & BoundedCollection => {
-    const handleOverflow = (element: T): void => {
+    const source = removalSource<ElementRemoval<T>>(next);
+    // An insert at the front drops the last element, as unshift of boundedList does (C10)
+    const handleOverflow = (element: T, dropFrom: "first" | "last"): void => {
       if (onOverflow) {
         const context: OverflowContext<T> = {
           newElement: element,
@@ -329,7 +355,8 @@ export function boundedDeque<T>(
           throw new Error(`Deque is full (capacity: ${capacity})`);
         case "drop-oldest":
           if (!next.isEmpty) {
-            next.removeFirst();
+            const value = dropFrom === "last" ? next.removeLast() : next.removeFirst();
+            source.emit({ value, end: dropFrom, reason: "drop" });
           }
           break;
         case "drop-newest":
@@ -346,6 +373,7 @@ export function boundedDeque<T>(
 
     return new Proxy(next, {
       get(target, prop, receiver) {
+        if (prop === removals) return source.channel;
         if (prop === "capacity") return capacity;
         if (prop === "isFull") return target.size >= capacity;
         if (prop === "remainingCapacity") return Math.max(0, capacity - target.size);
@@ -363,13 +391,19 @@ export function boundedDeque<T>(
             case "add":
               return function (element: T): any {
                 if (target.size >= capacity && policy !== "grow") {
-                  handleOverflow(element);
+                  handleOverflow(element, prop === "addFirst" || prop === "offerFirst" ? "last" : "first");
                   if (policy === "reject" || policy === "drop-newest") {
                     return prop.startsWith("offer") || prop === "add" ? false : undefined;
                   }
                 }
                 return (value as Function).call(target, element);
               };
+
+            // The base addAll goes past the bound, so each element goes through add of this proxy (C10)
+            case "addAll":
+              return function (elements: Iterable<T>): boolean {
+                return addEach(elements, (element) => (receiver as Deque<T>).add(element));
+              };
           }
         }
 
@@ -392,6 +426,10 @@ export function boundedMap<K, V>(
 
   return (next: MapLike<K, V>): MapLike<K, V> & BoundedCollection => {
     let insertionOrder: K[] = []; // Track insertion order for drop-oldest
+    // A removal below (for example an eviction of lruMap) takes its key out of the order
+    const source = removalSource<MapRemoval<K, V>>(next, ({ key }) => {
+      insertionOrder = insertionOrder.filter((k) => !next.keyEq(k, key));
+    });
 
     const handleOverflow = (key: K, value: V): void => {
       if (onOverflow) {
@@ -409,9 +447,15 @@ export function boundedMap<K, V>(
           throw new Error(`Map is full (capacity: ${capacity})`);
         case "drop-oldest":
           // Remove oldest key
-          if (insertionOrder.length > 0) {
+          // The removal channel below keeps the order exact. A layer below with no channel can remove a key
+          // without this layer seeing it, so a drop skips each key that is gone.
+          while (insertionOrder.length > 0) {
             const oldestKey = insertionOrder.shift()!;
+            if (!next.has(oldestKey)) continue;
+            const value = next.get(oldestKey);
             next.delete(oldestKey);
+            source.emit({ key: oldestKey, value, reason: "drop" });
+            break;
           }
           break;
         case "drop-newest":
@@ -428,6 +472,7 @@ export function boundedMap<K, V>(
 
     return new Proxy(next, {
       get(target, prop, receiver) {
+        if (prop === removals) return source.channel;
         if (prop === "capacity") return capacity;
         if (prop === "isFull") return target.size >= capacity;
         if (prop === "remainingCapacity") return Math.max(0, capacity - target.size);

package/src/behaviors/evented.ts

@@ -22,6 +22,31 @@ import type { Queue, Deque } from "../interfaces/queue.js";
 import type { 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";
+
+/** The number of removals that a layer heard from the layers below it, and the number from the first end. */
+interface Heard {
+  all: number;
+  first: number;
+}
+
+/**
+ * This function gives each removal below `next` to `listener` and counts the removals.
+ * With the counts, a layer tells a refused add (the size did not grow) from an add that caused a drop.
+ */
+function hear<R extends ElementRemoval<unknown> | MapRemoval<unknown, unknown>>(next: object, listener: (removal: R) => void): Heard {
+  const heard: Heard = { all: 0, first: 0 };
+  removalsOf<R>(next)?.on((removal) => {
+    heard.all++;
+    if ("end" in removal && removal.end === "first") heard.first++;
+    listener(removal);
+  });
+  return heard;
+}
+
+/** This function tells if a call added an element: the size grew, after the removals of the layers below. */
+const added = (size: number, sizeBefore: number, heard: Heard, heardBefore: number): boolean =>
+  size - sizeBefore + heard.all - heardBefore > 0;
 
 // ============================================================================
 // Event type definitions
@@ -33,8 +58,8 @@ import { Emitter, type Unsubscribe } from "../core/events.js";
 export interface ListEvents<T> {
   /** Element was added */
   add: { value: T; index?: number };
-  /** Element was removed */
-  remove: { value: T; index?: number };
+  /** Element was removed. A removal by a layer below (a drop) has a `reason`. */
+  remove: { value: T; index?: number; reason?: RemovalReason };
   /** Element was replaced */
   set: { oldValue: T; newValue: T; index: number };
   /** Collection was cleared */
@@ -51,8 +76,8 @@ export interface ListEvents<T> {
 export interface QueueEvents<T> {
   /** Element was added to queue */
   enqueue: { value: T };
-  /** Element was removed from queue */
-  dequeue: { value: T };
+  /** Element was removed from queue. A removal by a layer below (a drop) has a `reason`. */
+  dequeue: { value: T; reason?: RemovalReason };
   /** Collection was cleared */
   clear: {};
 }
@@ -65,10 +90,10 @@ export interface DequeEvents<T> {
   addFirst: { value: T };
   /** Element was added to back */
   addLast: { value: T };
-  /** Element was removed from front */
-  removeFirst: { value: T };
-  /** Element was removed from back */
-  removeLast: { value: T };
+  /** Element was removed from front. A removal by a layer below (a drop) has a `reason`. */
+  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 };
   /** Collection was cleared */
   clear: {};
 }
@@ -79,8 +104,8 @@ export interface DequeEvents<T> {
 export interface MapEvents<K, V> {
   /** Key-value pair was set */
   set: { key: K; value: V; oldValue?: V };
-  /** Key was deleted */
-  delete: { key: K; value: V };
+  /** Key was deleted. A removal by a layer below (a drop, an eviction or an expiry) has a `reason`. */
+  delete: { key: K; value: V; reason?: RemovalReason };
   /** Collection was cleared */
   clear: {};
 }
@@ -91,8 +116,8 @@ export interface MapEvents<K, V> {
 export interface CollectionEvents<T> {
   /** Element was added */
   add: { value: T };
-  /** Element was removed */
-  remove: { value: T };
+  /** Element was removed. A removal by a layer below has a `reason`. */
+  remove: { value: T; reason?: RemovalReason };
   /** Collection was cleared */
   clear: {};
 }
@@ -117,6 +142,10 @@ export function eventedList<T>(): Middleware<
 > {
   return (next: List<T>) => {
     const emitter = new Emitter<ListEvents<T>>();
+    // A removal from the last end left the index that is now the size
+    const heard = hear<ElementRemoval<T>>(next, ({ value, end, reason }) =>
+      emitter.emit("remove", end === undefined ? { value, reason } : { value, index: end === "first" ? 0 : next.size, reason }),
+    );
 
     return new Proxy(next, {
       get(target, prop, receiver) {
@@ -129,24 +158,34 @@ export function eventedList<T>(): Middleware<
 
         if (typeof value === "function") {
           switch (prop) {
+            // A layer below can refuse the element (reject, drop-newest): then no event
             case "add":
             case "push":
               return function (element: T): any {
+                const size = target.size;
+                const all = heard.all;
                 const result = (value as Function).call(target, element);
-                emitter.emit("add", { value: element });
+                if (added(target.size, size, heard, all)) emitter.emit("add", { value: element });
                 return result;
               };
 
             case "unshift":
               return function (element: T): void {
+                const size = target.size;
+                const all = heard.all;
                 (value as Function).call(target, element);
-                emitter.emit("add", { value: element, index: 0 });
+                if (added(target.size, size, heard, all)) emitter.emit("add", { value: element, index: 0 });
               };
 
             case "insert":
               return function (index: number, element: T): void {
+                const size = target.size;
+                const all = heard.all;
+                const first = heard.first;
                 (value as Function).call(target, index, element);
-                emitter.emit("add", { value: element, index });
+                if (!added(target.size, size, heard, all)) return;
+                // A drop of the first element below moved each later index one place lower
+                emitter.emit("add", { value: element, index: heard.first > first ? Math.max(0, index - 1) : index });
               };
 
             case "set":
@@ -175,7 +214,8 @@ export function eventedList<T>(): Middleware<
             case "pop":
               return function (): T {
                 const removed = (value as Function).call(target);
-                emitter.emit("remove", { value: removed });
+                // The last element had the index that is now the size
+                emitter.emit("remove", { value: removed, index: target.size });
                 return removed;
               };
 
@@ -226,6 +266,7 @@ export function eventedQueue<T>(): Middleware<
 > {
   return (next: Queue<T>) => {
     const emitter = new Emitter<QueueEvents<T>>();
+    hear<ElementRemoval<T>>(next, ({ value, reason }) => emitter.emit("dequeue", { value, reason }));
 
     return new Proxy(next, {
       get(target, prop, receiver) {
@@ -284,6 +325,9 @@ export function eventedDeque<T>(): Middleware<
 > {
   return (next: Deque<T>) => {
     const emitter = new Emitter<DequeEvents<T>>();
+    const heard = hear<ElementRemoval<T>>(next, ({ value, end, reason }) =>
+      emitter.emit(end === "last" ? "removeLast" : "removeFirst", { value, reason }),
+    );
 
     return new Proxy(next, {
       get(target, prop, receiver) {
@@ -295,22 +339,21 @@ export function eventedDeque<T>(): Middleware<
 
         if (typeof value === "function") {
           switch (prop) {
+            // push of a deque adds at the end (see Deque.push). A layer below can refuse the element.
             case "addFirst":
             case "offerFirst":
-            case "push":
-              return function (element: T): any {
-                const result = (value as Function).call(target, element);
-                emitter.emit("addFirst", { value: element });
-                return result;
-              };
-
             case "addLast":
             case "offerLast":
             case "offer":
             case "add":
+            case "push":
               return function (element: T): any {
+                const size = target.size;
+                const all = heard.all;
                 const result = (value as Function).call(target, element);
-                emitter.emit("addLast", { value: element });
+                if (added(target.size, size, heard, all)) {
+                  emitter.emit(prop === "addFirst" || prop === "offerFirst" ? "addFirst" : "addLast", { value: element });
+                }
                 return result;
               };
 
@@ -365,6 +408,7 @@ export function eventedMap<K, V>(): Middleware<
 > {
   return (next: MapLike<K, V>) => {
     const emitter = new Emitter<MapEvents<K, V>>();
+    const heard = hear<MapRemoval<K, V>>(next, ({ key, value, reason }) => emitter.emit("delete", { key, value, reason }));
 
     return new Proxy(next, {
       get(target, prop, receiver) {
@@ -378,8 +422,13 @@ export function eventedMap<K, V>(): Middleware<
           switch (prop) {
             case "set":
               return function (key: K, val: V): V | undefined {
+                const size = target.size;
+                const all = heard.all;
                 const oldValue = (value as Function).call(target, key, val);
-                emitter.emit("set", { key, value: val, oldValue });
+                // A new key that a layer below refused (reject, drop-newest) gives no event
+                if (oldValue !== undefined || added(target.size, size, heard, all)) {
+                  emitter.emit("set", { key, value: val, oldValue });
+                }
                 return oldValue;
               };
 
@@ -420,6 +469,7 @@ export function evented<T>(): Middleware<
 > {
   return (next: Collection<T>) => {
     const emitter = new Emitter<CollectionEvents<T>>();
+    hear<ElementRemoval<T>>(next, ({ value, reason }) => emitter.emit("remove", { value, reason }));
 
     return new Proxy(next, {
       get(target, prop, receiver) {

package/src/behaviors/lru.ts

@@ -18,6 +18,7 @@ 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";
+import { removals, removalSource, type MapRemoval } from "../core/removals.js";
 
 /**
  * Options for LRU behavior.
@@ -133,9 +134,15 @@ export function lruMap<K, V>(
       nodeMap.delete(node.key);
     };
 
-    // A layer below this one (for example ttlMap, in compose(lruMap, ttlMap)) can remove an
-    // entry without this layer seeing it. Its node is then stale: the list must not keep it
-    // (it holds the value, and it would grow without bound) and evicting it is not an eviction.
+    // A removal below (for example an expiry of ttlMap, in compose(lruMap, ttlMap)) removes the node of its key
+    const source = removalSource<MapRemoval<K, V>>(next, ({ key }) => {
+      const node = nodeMap.get(key);
+      if (node) removeNode(node);
+    });
+
+    // A layer below with no removal channel can remove an entry without this layer seeing it. Its node is
+    // then stale: the list must not keep it (it holds the value, and it would grow without bound) and evicting
+    // it is not an eviction. With the channel, no node is stale and these checks find nothing.
     const dropStaleNodes = (): void => {
       for (const node of [...nodeMap.values()]) {
         if (!next.has(node.key)) {
@@ -161,12 +168,16 @@ export function lruMap<K, V>(
             timestamp: candidate.lastAccessed,
           });
         }
+        source.emit({ key: candidate.key, value: candidate.value, reason: "evict" });
         return;
       }
     };
 
     return new Proxy(next, {
       get(target, prop, receiver) {
+        if (prop === removals) {
+          return source.channel;
+        }
         // Add isFull property
         if (prop === "isFull") {
           return target.size >= capacity;
@@ -185,17 +196,7 @@ export function lruMap<K, V>(
           switch (prop) {
             case "get":
               return function (key: K): V {
-                let result: V;
-                try {
-                  result = (value as Function).call(target, key);
-                } catch (error) {
-                  // The entry is gone below (for example expired): forget its node
-                  const stale = nodeMap.get(key);
-                  if (stale) {
-                    removeNode(stale);
-                  }
-                  throw error;
-                }
+                const result: V = (value as Function).call(target, key);
                 // Update access time
                 const node = nodeMap.get(key);
                 if (node) {
@@ -208,14 +209,9 @@ export function lruMap<K, V>(
               return function (key: K): boolean {
                 const result = (value as Function).call(target, key);
                 const node = nodeMap.get(key);
-                if (node) {
-                  if (result) {
-                    // Update access time
-                    moveToHead(node);
-                  } else {
-                    // The entry is gone below (for example expired): forget its node
-                    removeNode(node);
-                  }
+                if (node && result) {
+                  // Update access time
+                  moveToHead(node);
                 }
                 return result;
               };
@@ -240,8 +236,10 @@ export function lruMap<K, V>(
                   if (stale) {
                     removeNode(stale);
                   }
-                  // Keep the node list bounded: when it reaches capacity, drop stale nodes first
-                  if (nodeMap.size >= capacity) {
+                  // Keep the node list bounded. At most `capacity` nodes are live, so at twice the capacity a scan
+                  // removes at least `capacity` stale nodes: the cost of a set is amortized O(1). A scan at the
+                  // capacity read each node at each set into a full map (C10). evictLRU skips the other stale nodes.
+                  if (nodeMap.size >= 2 * capacity) {
                     dropStaleNodes();
                   }
                   if (target.size >= capacity) {