@mark1russell7/collections 0.8.0 → 0.9.1

package/package.json

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

package/src/async/channels.ts

@@ -27,6 +27,8 @@ import { asyncQueue, type AsyncQueue } from "./async-queue.js";
  *
  * The channels of Go are the model. This class gives send/receive operations
  * that can block until the other side is ready.
+ *
+ * @deprecated Import `Channel` from `@mark1russell7/service/channel`. The next MINOR version of collections removes it.
  */
 export class Channel<T> {
   private queue: AsyncQueue<T>;
@@ -140,6 +142,8 @@ export class Channel<T> {
 
 /**
  * SelectCase represents a case in a select statement.
+ *
+ * @deprecated Import `SelectCase` from `@mark1russell7/service/channel`. The next MINOR version of collections removes it.
  */
 export interface SelectCase<R> {
   channel: Channel<any>;
@@ -212,6 +216,8 @@ function firstOf(waits: readonly Wait[]): Promise<{ index: number; value: unknow
  *   ch2.case((v) => `ch2: ${v}`),
  *   timeout(1000).case(() => 'timeout')
  * )
+ *
+ * @deprecated Import `select` from `@mark1russell7/service/channel`. The next MINOR version of collections removes it.
  */
 export async function select<R>(...cases: SelectCase<R>[]): Promise<R> {
   const { index, value } = await firstOf(
@@ -229,6 +235,8 @@ export async function select<R>(...cases: SelectCase<R>[]): Promise<R> {
  *   dataChannel.case((v) => v),
  *   timeout(5000).case(() => 'timeout!')
  * )
+ *
+ * @deprecated Import `timeout` from `@mark1russell7/service/channel`. The next MINOR version of collections removes it.
  */
 export function timeout(ms: number): Channel<void> {
   const ch = new Channel<void>();
@@ -247,6 +255,8 @@ export function timeout(ms: number): Channel<void> {
  * for await (const t of tick) {
  *   console.log('Tick:', t)
  * }
+ *
+ * @deprecated Import `ticker` from `@mark1russell7/service/channel`. The next MINOR version of collections removes it.
  */
 export function ticker(ms: number): Channel<number> & { stop: () => void } {
   const ch = new Channel<number>(1);
@@ -273,6 +283,8 @@ export function ticker(ms: number): Channel<number> & { stop: () => void } {
  *
  * await input.send(5)
  * const result = await output.receive() // 10
+ *
+ * @deprecated Import `pipeline` from `@mark1russell7/service/channel`. The next MINOR version of collections removes it.
  */
 export function pipeline<T, U>(
   input: Channel<T>,
@@ -305,6 +317,8 @@ export function pipeline<T, U>(
  * const [out1, out2, out3] = fanOut(input, 3)
  *
  * // Each output gets a copy of every input value
+ *
+ * @deprecated Import `fanOut` from `@mark1russell7/service/channel`. The next MINOR version of collections removes it.
  */
 export function fanOut<T>(input: Channel<T>, count: number, bufferSize: number = 0): Channel<T>[] {
   const outputs = Array.from({ length: count }, () => new Channel<T>(bufferSize));
@@ -331,6 +345,8 @@ export function fanOut<T>(input: Channel<T>, count: number, bufferSize: number =
  * const merged = fanIn(ch1, ch2)
  *
  * // merged receives values from both ch1 and ch2
+ *
+ * @deprecated Import `fanIn` from `@mark1russell7/service/channel`. The next MINOR version of collections removes it.
  */
 export function fanIn<T>(...inputs: Channel<T>[]): Channel<T> {
   const output = new Channel<T>();
@@ -356,6 +372,8 @@ export function fanIn<T>(...inputs: Channel<T>[]): Channel<T> {
  * It takes one value at a time, from the inputs in turn. It keeps no receive on an input while
  * it waits for the reader of the output. Thus each value of each input reaches the output one
  * time, in the order of its input, or stays in its input.
+ *
+ * @deprecated Import `merge` from `@mark1russell7/service/channel`. The next MINOR version of collections removes it.
  */
 export function merge<T>(...inputs: Channel<T>[]): Channel<T> {
   const output = new Channel<T>();
@@ -389,6 +407,8 @@ export function merge<T>(...inputs: Channel<T>[]): Channel<T> {
 
 /**
  * Buffered channel with specified capacity.
+ *
+ * @deprecated Import `buffered` from `@mark1russell7/service/channel`. The next MINOR version of collections removes it.
  */
 export function buffered<T>(capacity: number): Channel<T> {
   return new Channel<T>(capacity);
@@ -397,6 +417,8 @@ export function buffered<T>(capacity: number): Channel<T> {
 /**
  * Unbuffered channel (rendezvous point).
  * Sends block until receiver is ready.
+ *
+ * @deprecated Import `unbuffered` from `@mark1russell7/service/channel`. The next MINOR version of collections removes it.
  */
 export function unbuffered<T>(): Channel<T> {
   return new Channel<T>(0);
@@ -408,6 +430,8 @@ export function unbuffered<T>(): Channel<T> {
  * @example
  * const ch = channel<number>()
  * const bufferedCh = channel<string>(10)
+ *
+ * @deprecated Import `channel` from `@mark1russell7/service/channel`. The next MINOR version of collections removes it.
  */
 export function channel<T>(bufferSize: number = 0): Channel<T> {
   return new Channel<T>(bufferSize);
@@ -424,6 +448,8 @@ export function channel<T>(bufferSize: number = 0): Channel<T> {
  * )
  *
  * // 4 workers concurrently process jobs from jobChannel
+ *
+ * @deprecated Import `workerPool` from `@mark1russell7/service/channel`. The next MINOR version of collections removes it.
  */
 export function workerPool<T, R>(
   jobs: Channel<T>,

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