@procedures/collections 0.0.0-stage → 0.2.0

package/src/behaviors/lru.ts

@@ -0,0 +1,447 @@
+/**
+ * LRU (Least Recently Used) eviction behavior.
+ *
+ * Tracks access times and automatically evicts the least recently used
+ * elements when capacity is reached. Perfect for caching.
+ *
+ * @example
+ * const cache = compose(
+ *   lruMap({ capacity: 100 })
+ * )(hashMap<string, Data>())
+ *
+ * cache.set('key1', data1) // Accessed
+ * cache.get('key1')        // Accessed again (moves to front)
+ * // When full, least recently accessed keys are evicted
+ */
+
+import type { Middleware } from "../core/middleware.js";
+import type { MapLike } from "../interfaces/map.js";
+import { compositeMapMethod } from "./composite.js";
+
+/**
+ * Options for LRU behavior.
+ */
+export interface LRUOptions {
+  /**
+   * Maximum capacity. When exceeded, least recently used items are evicted.
+   */
+  capacity: number;
+
+  /**
+   * Optional callback invoked when an item is evicted.
+   */
+  onEvict?: (info: { key: any; value: any; timestamp: number }) => void;
+}
+
+/**
+ * Metadata for tracking LRU access.
+ */
+interface LRUNode<K, V> {
+  key: K;
+  value: V;
+  lastAccessed: number;
+  prev: LRUNode<K, V> | null;
+  next: LRUNode<K, V> | null;
+}
+
+/**
+ * Creates an LRU Map middleware.
+ *
+ * Maintains a doubly-linked list to track access order.
+ * Most recently accessed items are at the head.
+ * When capacity is exceeded, items at the tail are evicted.
+ */
+export function lruMap<K, V>(
+  options: LRUOptions
+): Middleware<MapLike<K, V>, MapLike<K, V> & { readonly isFull: boolean }> {
+  const { capacity, onEvict } = options;
+
+  return (next: MapLike<K, V>): MapLike<K, V> & { readonly isFull: boolean } => {
+    // Doubly-linked list for LRU tracking
+    let head: LRUNode<K, V> | null = null;
+    let tail: LRUNode<K, V> | null = null;
+    const nodeMap = new Map<K, LRUNode<K, V>>();
+
+    const moveToHead = (node: LRUNode<K, V>): void => {
+      // Remove from current position
+      if (node.prev) {
+        node.prev.next = node.next;
+      } else {
+        head = node.next;
+      }
+
+      if (node.next) {
+        node.next.prev = node.prev;
+      } else {
+        tail = node.prev;
+      }
+
+      // Add to head
+      node.prev = null;
+      node.next = head;
+      if (head) {
+        head.prev = node;
+      }
+      head = node;
+
+      if (!tail) {
+        tail = node;
+      }
+
+      node.lastAccessed = Date.now();
+    };
+
+    const addNode = (key: K, value: V): void => {
+      const node: LRUNode<K, V> = {
+        key,
+        value,
+        lastAccessed: Date.now(),
+        prev: null,
+        next: head,
+      };
+
+      if (head) {
+        head.prev = node;
+      }
+      head = node;
+
+      if (!tail) {
+        tail = node;
+      }
+
+      nodeMap.set(key, node);
+    };
+
+    const removeNode = (node: LRUNode<K, V>): void => {
+      if (node.prev) {
+        node.prev.next = node.next;
+      } else {
+        head = node.next;
+      }
+
+      if (node.next) {
+        node.next.prev = node.prev;
+      } else {
+        tail = node.prev;
+      }
+
+      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.
+    const dropStaleNodes = (): void => {
+      for (const node of [...nodeMap.values()]) {
+        if (!next.has(node.key)) {
+          removeNode(node);
+        }
+      }
+    };
+
+    const evictLRU = (): void => {
+      while (tail) {
+        const candidate = tail;
+        removeNode(candidate);
+        if (!next.has(candidate.key)) {
+          // Already removed below: skip it and evict the next least recently used entry
+          continue;
+        }
+        next.delete(candidate.key);
+
+        if (onEvict) {
+          onEvict({
+            key: candidate.key,
+            value: candidate.value,
+            timestamp: candidate.lastAccessed,
+          });
+        }
+        return;
+      }
+    };
+
+    return new Proxy(next, {
+      get(target, prop, receiver) {
+        // Add isFull property
+        if (prop === "isFull") {
+          return target.size >= capacity;
+        }
+
+        // Composite methods (setIfAbsent, compute, merge, putAll and others) go through this
+        // proxy's own primitives, so they keep this behavior's rules (BUGS-2026-07 L13)
+        const composite = compositeMapMethod(receiver as MapLike<K, V>, prop);
+        if (composite) {
+          return composite;
+        }
+
+        const value = Reflect.get(target, prop, receiver);
+
+        if (typeof value === "function") {
+          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;
+                }
+                // Update access time
+                const node = nodeMap.get(key);
+                if (node) {
+                  moveToHead(node);
+                }
+                return result;
+              };
+
+            case "has":
+              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);
+                  }
+                }
+                return result;
+              };
+
+            case "set":
+              return function (key: K, val: V): V | undefined {
+                const hadKey = target.has(key);
+
+                if (hadKey) {
+                  // Update existing
+                  const oldValue = (value as Function).call(target, key, val);
+                  const node = nodeMap.get(key);
+                  if (node) {
+                    node.value = val;
+                    moveToHead(node);
+                  }
+                  return oldValue;
+                } else {
+                  // Add new. A stale node for this key (its entry was removed below) must not
+                  // stay in the list: evicting it later would delete the new node's map entry.
+                  const stale = nodeMap.get(key);
+                  if (stale) {
+                    removeNode(stale);
+                  }
+                  // Keep the node list bounded: when it reaches capacity, drop stale nodes first
+                  if (nodeMap.size >= capacity) {
+                    dropStaleNodes();
+                  }
+                  if (target.size >= capacity) {
+                    evictLRU();
+                  }
+                  const result = (value as Function).call(target, key, val);
+                  addNode(key, val);
+                  return result;
+                }
+              };
+
+            case "delete":
+              return function (key: K): V | undefined {
+                const result = (value as Function).call(target, key);
+                const node = nodeMap.get(key);
+                if (node) {
+                  removeNode(node);
+                }
+                return result;
+              };
+
+            case "clear":
+              return function (): void {
+                (value as Function).call(target);
+                head = null;
+                tail = null;
+                nodeMap.clear();
+              };
+          }
+        }
+
+        return value;
+      },
+    }) as MapLike<K, V> & { readonly isFull: boolean };
+  };
+}
+
+/**
+ * Creates an LRU cache with a simpler API.
+ * This is a standalone LRU cache implementation.
+ *
+ * @example
+ * const cache = lruCache<string, Data>(100)
+ * cache.set('key', value)
+ * cache.get('key') // Moves to front
+ */
+export class LRUCache<K, V> {
+  private map: Map<K, { value: V; node: LRUNode<K, V> }> = new Map();
+  private head: LRUNode<K, V> | null = null;
+  private tail: LRUNode<K, V> | null = null;
+
+  constructor(
+    private readonly capacity: number,
+    private readonly onEvict?: (key: K, value: V) => void
+  ) {}
+
+  get size(): number {
+    return this.map.size;
+  }
+
+  get isFull(): boolean {
+    return this.map.size >= this.capacity;
+  }
+
+  get(key: K): V | undefined {
+    const entry = this.map.get(key);
+    if (!entry) return undefined;
+
+    this.moveToHead(entry.node);
+    return entry.value;
+  }
+
+  set(key: K, value: V): void {
+    const entry = this.map.get(key);
+
+    if (entry) {
+      // Update existing
+      entry.value = value;
+      entry.node.value = value;
+      this.moveToHead(entry.node);
+    } else {
+      // Add new
+      if (this.map.size >= this.capacity) {
+        this.evictLRU();
+      }
+
+      const node: LRUNode<K, V> = {
+        key,
+        value,
+        lastAccessed: Date.now(),
+        prev: null,
+        next: this.head,
+      };
+
+      if (this.head) {
+        this.head.prev = node;
+      }
+      this.head = node;
+
+      if (!this.tail) {
+        this.tail = node;
+      }
+
+      this.map.set(key, { value, node });
+    }
+  }
+
+  has(key: K): boolean {
+    return this.map.has(key);
+  }
+
+  delete(key: K): boolean {
+    const entry = this.map.get(key);
+    if (!entry) return false;
+
+    this.removeNode(entry.node);
+    this.map.delete(key);
+    return true;
+  }
+
+  clear(): void {
+    this.map.clear();
+    this.head = null;
+    this.tail = null;
+  }
+
+  private moveToHead(node: LRUNode<K, V>): void {
+    if (node === this.head) return;
+
+    // Remove from current position
+    if (node.prev) {
+      node.prev.next = node.next;
+    }
+    if (node.next) {
+      node.next.prev = node.prev;
+    } else {
+      this.tail = node.prev;
+    }
+
+    // Add to head
+    node.prev = null;
+    node.next = this.head;
+    if (this.head) {
+      this.head.prev = node;
+    }
+    this.head = node;
+
+    node.lastAccessed = Date.now();
+  }
+
+  private removeNode(node: LRUNode<K, V>): void {
+    if (node.prev) {
+      node.prev.next = node.next;
+    } else {
+      this.head = node.next;
+    }
+
+    if (node.next) {
+      node.next.prev = node.prev;
+    } else {
+      this.tail = node.prev;
+    }
+  }
+
+  private evictLRU(): void {
+    if (!this.tail) return;
+
+    const evicted = this.tail;
+    this.removeNode(evicted);
+    this.map.delete(evicted.key);
+
+    if (this.onEvict) {
+      this.onEvict(evicted.key, evicted.value);
+    }
+  }
+
+  /**
+   * Returns keys in LRU order (most recent first).
+   */
+  *keys(): IterableIterator<K> {
+    let node = this.head;
+    while (node) {
+      yield node.key;
+      node = node.next;
+    }
+  }
+
+  /**
+   * Returns entries in LRU order (most recent first).
+   */
+  *entries(): IterableIterator<[K, V]> {
+    let node = this.head;
+    while (node) {
+      yield [node.key, node.value];
+      node = node.next;
+    }
+  }
+}
+
+/**
+ * Factory function to create an LRU cache.
+ */
+export function lruCache<K, V>(
+  capacity: number,
+  onEvict?: (key: K, value: V) => void
+): LRUCache<K, V> {
+  return new LRUCache(capacity, onEvict);
+}

package/src/behaviors/readonly.ts

@@ -0,0 +1,224 @@
+/**
+ * Readonly behavior - Creates immutable views of collections.
+ *
+ * Wraps collections to prevent modifications by throwing errors
+ * on any mutation attempt. Mirrors Java's Collections.unmodifiable*() methods.
+ *
+ * @example
+ * const list = compose(
+ *   readonlyList()
+ * )(arrayList([1, 2, 3]))
+ *
+ * list.get(0) // OK: 1
+ * list.add(4) // Error: Cannot modify readonly list
+ */
+
+import type { Middleware } from "../core/middleware.js";
+import type { ReadonlyList } from "../interfaces/list.js";
+import type { ReadonlyQueue } from "../interfaces/queue.js";
+import type { ReadonlyMapLike } from "../interfaces/map.js";
+import type { ReadonlyCollection } from "../interfaces/collection.js";
+
+/**
+ * Options for readonly behavior.
+ */
+export interface ReadonlyOptions {
+  /**
+   * Custom error message to throw on mutation attempts.
+   * @default 'Cannot modify readonly collection'
+   */
+  errorMessage?: string;
+}
+
+/**
+ * Set of method names that mutate collections.
+ */
+const MUTATING_METHODS = new Set([
+  // Collection mutations
+  "add",
+  "addAll",
+  "remove",
+  "removeAll",
+  "retainAll",
+  "clear",
+
+  // List mutations
+  "set",
+  "insert",
+  "insertAll",
+  "removeAt",
+  "removeRange",
+  "push",
+  "pop",
+  "shift",
+  "unshift",
+  "sort",
+  "reverse",
+
+  // Queue/Deque mutations
+  "offer",
+  "offerFirst",
+  "offerLast",
+  "poll",
+  "pollFirst",
+  "pollLast",
+  "enqueue",
+  "dequeue",
+  "addFirst",
+  "addLast",
+  "removeFirst",
+  "removeLast",
+
+  // Map mutations
+  "set",
+  "setIfAbsent",
+  "forcePut",
+  "pollFirstEntry",
+  "pollLastEntry",
+  "delete",
+  "deleteEntry",
+  "replace",
+  "replaceEntry",
+  "computeIfAbsent",
+  "computeIfPresent",
+  "compute",
+  "merge",
+  "putAll",
+]);
+
+/** Methods that return a view of the collection: the view is readonly too. */
+const VIEW_METHODS = new Set([
+  "subList",
+  "subMap",
+  "subSet",
+  "headMap",
+  "tailMap",
+  "headSet",
+  "tailSet",
+  "descendingMap",
+  "descendingSet",
+  "inverse",
+]);
+
+/**
+ * Creates a readonly middleware for any collection type.
+ */
+function createReadonly<C extends object>(
+  errorMessage: string = "Cannot modify readonly collection"
+): Middleware<C> {
+  return (next: C): C => {
+    return new Proxy(next, {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+
+        // Block mutating methods
+        if (typeof prop === "string" && MUTATING_METHODS.has(prop)) {
+          if (typeof value === "function") {
+            return () => {
+              throw new Error(errorMessage);
+            };
+          }
+        }
+
+        // A view (a sublist, a submap, a head or tail set, a descending map) is readonly too.
+        // Before, only subList and subMap were wrapped, and setIfAbsent, pollFirstEntry and
+        // pollLastEntry were not blocked (BUGS-2026-07 L14).
+        if (typeof value === "function" && typeof prop === "string" && VIEW_METHODS.has(prop)) {
+          return function (this: any, ...args: any[]) {
+            const result = value.apply(target, args);
+            // Recursively apply readonly to the result
+            return createReadonly<typeof result>(errorMessage)(result);
+          };
+        }
+
+        return value;
+      },
+
+      set(_target, _prop, _value, _receiver) {
+        // Block property assignments
+        throw new Error(errorMessage);
+      },
+
+      deleteProperty(_target, _prop) {
+        // Block property deletions
+        throw new Error(errorMessage);
+      },
+    });
+  };
+}
+
+/**
+ * Creates a readonly List middleware.
+ *
+ * All mutation methods will throw an error.
+ * Read operations work normally.
+ *
+ * @example
+ * const readonlyNumbers = compose(
+ *   readonlyList()
+ * )(arrayList([1, 2, 3]))
+ */
+export function readonlyList<T>(
+  options: ReadonlyOptions = {}
+): Middleware<ReadonlyList<T>> {
+  const errorMessage = options.errorMessage ?? "Cannot modify readonly list";
+  return createReadonly<any>(errorMessage);
+}
+
+/**
+ * Creates a readonly Queue middleware.
+ */
+export function readonlyQueue<T>(
+  options: ReadonlyOptions = {}
+): Middleware<ReadonlyQueue<T>> {
+  const errorMessage = options.errorMessage ?? "Cannot modify readonly queue";
+  return createReadonly<any>(errorMessage);
+}
+
+/**
+ * Creates a readonly Map middleware.
+ */
+export function readonlyMap<K, V>(
+  options: ReadonlyOptions = {}
+): Middleware<ReadonlyMapLike<K, V>> {
+  const errorMessage = options.errorMessage ?? "Cannot modify readonly map";
+  return createReadonly<any>(errorMessage);
+}
+
+/**
+ * Creates a readonly Collection middleware.
+ *
+ * Generic version that works with any collection type.
+ */
+export function readonlyCollection<T>(
+  options: ReadonlyOptions = {}
+): Middleware<ReadonlyCollection<T>> {
+  const errorMessage = options.errorMessage ?? "Cannot modify readonly collection";
+  return createReadonly<any>(errorMessage);
+}
+
+/**
+ * Generic readonly middleware.
+ * Alias for readonlyCollection.
+ */
+export function readonly<C extends object>(
+  options: ReadonlyOptions = {}
+): Middleware<C> {
+  const errorMessage = options.errorMessage ?? "Cannot modify readonly collection";
+  return createReadonly<C>(errorMessage);
+}
+
+/**
+ * Alias for Java compatibility: unmodifiableList
+ */
+export const unmodifiableList : typeof readonlyList = readonlyList;
+
+/**
+ * Alias for Java compatibility: unmodifiableMap
+ */
+export const unmodifiableMap : typeof readonlyMap = readonlyMap;
+
+/**
+ * Alias for Java compatibility: unmodifiableCollection
+ */
+export const unmodifiableCollection : typeof readonlyCollection = readonlyCollection;