@mark1russell7/collections 0.7.2 → 0.8.0

package/package.json

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

@@ -231,6 +231,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.
  */
@@ -294,6 +307,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 +332,8 @@ export function boundedDeque<T>(
   const capacity = checkCapacity(options.capacity, "boundedDeque");
 
   return (next: Deque<T>): Deque<T> & BoundedCollection => {
-    const handleOverflow = (element: T): void => {
+    // 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 +349,8 @@ export function boundedDeque<T>(
           throw new Error(`Deque is full (capacity: ${capacity})`);
         case "drop-oldest":
           if (!next.isEmpty) {
-            next.removeFirst();
+            if (dropFrom === "last") next.removeLast();
+            else next.removeFirst();
           }
           break;
         case "drop-newest":
@@ -363,13 +384,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));
+              };
           }
         }
 

package/src/behaviors/lru.ts

@@ -240,8 +240,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) {

package/src/behaviors/ttl.ts

@@ -14,7 +14,7 @@
  */
 
 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 type { Collection } from "../interfaces/collection.js";
 
@@ -62,8 +62,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 +78,22 @@ 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;
 
-    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 });
       }
     };
 
-    // Start background expiration checker
-    intervalId = startExpirationTimer(checkExpired, checkInterval);
+    intervalId = startExpirationTimer(sweep, checkInterval);
 
     const dispose = (): void => {
       if (intervalId) {
@@ -116,7 +104,6 @@ export function ttlMap<K, V>(
 
     return new Proxy(next, {
       get(target, prop, receiver) {
-        // Add dispose method
         if (prop === "dispose") {
           return dispose;
         }
@@ -128,64 +115,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 };
   };