@mark1russell7/collections 0.8.0 → 0.9.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/collections",
-  "version": "0.8.0",
+  "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;
         }
@@ -254,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> = {
@@ -270,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":
@@ -287,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);
@@ -332,6 +337,7 @@ export function boundedDeque<T>(
   const capacity = checkCapacity(options.capacity, "boundedDeque");
 
   return (next: Deque<T>): Deque<T> & BoundedCollection => {
+    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) {
@@ -349,8 +355,8 @@ export function boundedDeque<T>(
           throw new Error(`Deque is full (capacity: ${capacity})`);
         case "drop-oldest":
           if (!next.isEmpty) {
-            if (dropFrom === "last") next.removeLast();
-            else next.removeFirst();
+            const value = dropFrom === "last" ? next.removeLast() : next.removeFirst();
+            source.emit({ value, end: dropFrom, reason: "drop" });
           }
           break;
         case "drop-newest":
@@ -367,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);
@@ -419,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) {
@@ -436,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":
@@ -455,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;
               };

package/src/behaviors/ttl.ts

@@ -16,6 +16,7 @@
 import type { Middleware } from "../core/middleware.js";
 import type { Entry, MapLike } from "../interfaces/map.js";
 import { compositeMapMethod } from "./composite.js";
+import { removals, removalSource, type ElementRemoval, type MapRemoval } from "../core/removals.js";
 import type { Collection } from "../interfaces/collection.js";
 
 /**
@@ -81,6 +82,8 @@ export function ttlMap<K, V>(
     // The times of the live keys, in the order of expiry: a set deletes its key before it adds it again
     const metadata = new Map<K, TTLEntry<V>>();
     let intervalId: ReturnType<typeof setInterval> | null = null;
+    // A removal below (for example an eviction of lruMap) ends the time of its key, so it never expires
+    const source = removalSource<MapRemoval<K, V>>(next, ({ key }) => void metadata.delete(key));
 
     // This function removes the expired entries from the front of the order, and stops at the first live entry
     const sweep = (): void => {
@@ -90,6 +93,7 @@ export function ttlMap<K, V>(
         metadata.delete(key);
         next.delete(key);
         onExpire?.({ key, value: entry.value, createdAt: entry.createdAt, expiredAt: now });
+        source.emit({ key, value: entry.value, reason: "expire" });
       }
     };
 
@@ -107,6 +111,9 @@ export function ttlMap<K, V>(
         if (prop === "dispose") {
           return dispose;
         }
+        if (prop === removals) {
+          return source.channel;
+        }
 
         // Composite methods (setIfAbsent, compute, merge, putAll and others) go through this
         // proxy's own primitives, so they keep the expiry rules (BUGS-2026-07 L13)
@@ -205,6 +212,7 @@ export function ttlCollection<T>(
   ): Collection<T> & { readonly dispose: () => void } => {
     const metadata = new Map<T, { expiresAt: number; createdAt: number }>();
     let intervalId: ReturnType<typeof setInterval> | null = null;
+    const source = removalSource<ElementRemoval<T>>(next, ({ value }) => void metadata.delete(value));
 
     const checkExpired = (): void => {
       const now = Date.now();
@@ -229,6 +237,7 @@ export function ttlCollection<T>(
               expiredAt: now,
             });
           }
+          source.emit({ value: element, reason: "expire" });
         }
       }
     };
@@ -247,6 +256,9 @@ export function ttlCollection<T>(
         if (prop === "dispose") {
           return dispose;
         }
+        if (prop === removals) {
+          return source.channel;
+        }
 
         const value = Reflect.get(target, prop, receiver);
 

package/src/core/removals.ts

@@ -0,0 +1,85 @@
+/**
+ * The removal channel of a stack of layers (C23).
+ *
+ * Some layers remove entries or elements by themselves. The bounded layers drop one when they are full.
+ * `lruMap` evicts one, and `ttlMap` removes an expired one. A layer
+ * above them does not call these removals, so it cannot see them. The removal channel tells it.
+ *
+ * - Each removing layer gives its channel under the key `removals`. Its channel gives its own removals and the
+ *   removals of the channel below it.
+ * - A layer that does not remove forwards the channel below it: a proxy gives each unknown key of its target.
+ * - `eventedMap` and the other evented layers emit an event for each removal of the channel below them.
+ *
+ * @example
+ * const cache = compose(eventedMap<string, number>(), lruMap({ capacity: 2 }))(hashMap());
+ * cache.on("delete", ({ key, reason }) => console.log(key, reason)); // an eviction gives the reason "evict"
+ */
+
+import type { Listener, Unsubscribe } from "./events.js";
+
+/** The key of the removal channel on a layer. */
+export const removals: unique symbol = Symbol.for("@mark1russell7/collections/removals");
+
+/**
+ * The cause of a removal: a bounded layer drops, `lruMap` evicts and `ttlMap` removes an expired entry.
+ */
+export type RemovalReason = "drop" | "evict" | "expire";
+
+/** A removal from a map: the key and the value that the layer removed. */
+export interface MapRemoval<K, V> {
+  readonly key: K;
+  readonly value: V;
+  readonly reason: RemovalReason;
+}
+
+/**
+ * A removal of an element: the element and the end that it left. A removal from a collection with no ends,
+ * for example by `ttlCollection`, has no `end`.
+ */
+export interface ElementRemoval<T> {
+  readonly value: T;
+  readonly end?: "first" | "last";
+  readonly reason: RemovalReason;
+}
+
+/** A channel of removals. The listener gets each removal after the collection changed. */
+export interface RemovalChannel<R> {
+  on(listener: Listener<R>): Unsubscribe;
+}
+
+/** The channel of a removing layer, and the function that sends its own removals. */
+export interface RemovalSource<R> {
+  readonly channel: RemovalChannel<R>;
+  emit(removal: R): void;
+}
+
+/**
+ * This function gives the removal channel of a collection, or `undefined` when no layer of it removes.
+ */
+export function removalsOf<R>(collection: object): RemovalChannel<R> | undefined {
+  const channel: unknown = (collection as { readonly [removals]?: unknown })[removals];
+  if (typeof channel !== "object" || channel === null) return undefined;
+  return typeof (channel as { on?: unknown }).on === "function" ? (channel as RemovalChannel<R>) : undefined;
+}
+
+/**
+ * This function makes the channel of a removing layer over `next`.
+ * The channel forwards each removal below. It calls `below` first, so the layer corrects its own state first.
+ */
+export function removalSource<R>(next: object, below?: (removal: R) => void): RemovalSource<R> {
+  const listeners = new Set<Listener<R>>();
+  const emit = (removal: R): void => {
+    for (const listener of [...listeners]) listener(removal);
+  };
+  removalsOf<R>(next)?.on((removal) => {
+    below?.(removal);
+    emit(removal);
+  });
+  const channel: RemovalChannel<R> = {
+    on(listener) {
+      listeners.add(listener);
+      return () => void listeners.delete(listener);
+    },
+  };
+  return { channel, emit };
+}

package/src/index.ts

@@ -13,6 +13,7 @@ export * from "./core/traits.js";
 export * from "./core/policies.js";
 export * from "./core/middleware.js";
 export * from "./core/events.js";
+export * from "./core/removals.js";
 // ============================================================================
 // Interfaces
 // ============================================================================