@mark1russell7/collections 0.7.2 → 0.9.0

package/src/behaviors/ttl.ts

@@ -14,8 +14,9 @@
  */
 
 import type { Middleware } from "../core/middleware.js";
-import type { MapLike } from "../interfaces/map.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";
 
 /**
@@ -62,8 +63,13 @@ interface TTLEntry<V> {
 /**
  * This function makes a TTL Map middleware.
  *
- * Automatically removes entries after TTL expires.
- * This function uses a background interval to check for expired entries.
+ * An entry is live while the time is less than the time of its last `set` plus `ttl`.
+ * Each access to the map first removes the expired entries, so each read shows only live entries.
+ * The layer gives each expired entry to `onExpire` one time, in the order of expiry.
+ * A background interval also removes expired entries, so `onExpire` occurs with no access.
+ *
+ * The layer keeps the times in the order of expiry, so the removal before an access is amortized O(1).
+ * This order needs a clock that does not go back. If `Date.now()` goes back, an entry can stay until the entries before it expire.
  */
 export function ttlMap<K, V>(
   options: TTLOptions
@@ -73,39 +79,25 @@ export function ttlMap<K, V>(
   return (
     next: MapLike<K, V>
   ): MapLike<K, V> & { readonly dispose: () => void } => {
+    // 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));
 
-    const checkExpired = (): void => {
+    // This function removes the expired entries from the front of the order, and stops at the first live entry
+    const sweep = (): void => {
       const now = Date.now();
-      const expired: K[] = [];
-
       for (const [key, entry] of metadata) {
-        if (now >= entry.expiresAt) {
-          expired.push(key);
-        }
-      }
-
-      for (const key of expired) {
-        const entry = metadata.get(key);
-        if (entry) {
-          next.delete(key);
-          metadata.delete(key);
-
-          if (onExpire) {
-            onExpire({
-              key,
-              value: entry.value,
-              createdAt: entry.createdAt,
-              expiredAt: now,
-            });
-          }
-        }
+        if (now < entry.expiresAt) return;
+        metadata.delete(key);
+        next.delete(key);
+        onExpire?.({ key, value: entry.value, createdAt: entry.createdAt, expiredAt: now });
+        source.emit({ key, value: entry.value, reason: "expire" });
       }
     };
 
-    // Start background expiration checker
-    intervalId = startExpirationTimer(checkExpired, checkInterval);
+    intervalId = startExpirationTimer(sweep, checkInterval);
 
     const dispose = (): void => {
       if (intervalId) {
@@ -116,10 +108,12 @@ export function ttlMap<K, V>(
 
     return new Proxy(next, {
       get(target, prop, receiver) {
-        // Add dispose method
         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)
@@ -128,64 +122,73 @@ export function ttlMap<K, V>(
           return composite;
         }
 
+        // A getter (size, isEmpty) reads only live entries
+        sweep();
         const value = Reflect.get(target, prop, receiver);
-
-        if (typeof value === "function") {
-          switch (prop) {
-            case "get":
-              return function (key: K): V {
-                // Check if expired before returning
-                const entry = metadata.get(key);
-                if (entry && Date.now() >= entry.expiresAt) {
-                  target.delete(key);
-                  metadata.delete(key);
-                  throw new Error(`Key expired: ${key}`);
-                }
-                return (value as Function).call(target, key);
-              };
-
-            case "has":
-              return function (key: K): boolean {
-                // Check if expired
-                const entry = metadata.get(key);
-                if (entry && Date.now() >= entry.expiresAt) {
-                  target.delete(key);
-                  metadata.delete(key);
-                  return false;
-                }
-                return (value as Function).call(target, key);
-              };
-
-            case "set":
-              return function (key: K, val: V): V | undefined {
-                const now = Date.now();
-                const result = (value as Function).call(target, key, val);
-
-                metadata.set(key, {
-                  value: val,
-                  expiresAt: now + ttl,
-                  createdAt: now,
-                });
-
-                return result;
-              };
-
-            case "delete":
-              return function (key: K): V | undefined {
-                const result = (value as Function).call(target, key);
-                metadata.delete(key);
-                return result;
-              };
-
-            case "clear":
-              return function (): void {
-                (value as Function).call(target);
-                metadata.clear();
-              };
-          }
+        if (typeof value !== "function") {
+          return value;
         }
 
-        return value;
+        switch (prop) {
+          case "set":
+            return function (key: K, val: V): V | undefined {
+              sweep();
+              const result = (value as Function).call(target, key, val);
+              const now = Date.now();
+              metadata.delete(key);
+              metadata.set(key, { value: val, expiresAt: now + ttl, createdAt: now });
+              return result;
+            };
+
+          case "delete":
+            return function (key: K): V | undefined {
+              sweep();
+              metadata.delete(key);
+              return (value as Function).call(target, key);
+            };
+
+          case "clear":
+            return function (): void {
+              metadata.clear();
+              (value as Function).call(target);
+            };
+
+          // The iteration gives the entries that are live when it starts. A removal while it runs (by a read in
+          // the loop, or by the interval between the steps of an async loop) does not change it, so the base
+          // iterator never sees a change and never throws.
+          case Symbol.iterator:
+          case "entries":
+            return function (): IterableIterator<Entry<K, V>> {
+              sweep();
+              return Array.from(target as Iterable<Entry<K, V>>).values();
+            };
+
+          case "keys":
+            return function (): IterableIterator<K> {
+              sweep();
+              return Array.from(target as Iterable<Entry<K, V>>, (e) => e.key).values();
+            };
+
+          case "values":
+            return function (): IterableIterator<V> {
+              sweep();
+              return Array.from(target as Iterable<Entry<K, V>>, (e) => e.value).values();
+            };
+
+          case "forEach":
+            return function (callback: (value: V, key: K, map: MapLike<K, V>) => void): void {
+              sweep();
+              for (const e of Array.from(target as Iterable<Entry<K, V>>)) callback(e.value, e.key, receiver as MapLike<K, V>);
+            };
+
+          default:
+            // Each other method (get, has, getOrUndefined, the iteration) reads only live entries,
+            // also when a caller keeps the method and calls it later
+            return function (this: unknown, ...args: unknown[]): unknown {
+              sweep();
+              return (value as Function).apply(target, args);
+            };
+        }
       },
     }) as MapLike<K, V> & { readonly dispose: () => void };
   };
@@ -209,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();
@@ -233,6 +237,7 @@ export function ttlCollection<T>(
               expiredAt: now,
             });
           }
+          source.emit({ value: element, reason: "expire" });
         }
       }
     };
@@ -251,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
 // ============================================================================