@procedures/collections 0.0.0-stage → 0.2.0

package/dist/behaviors/lru.js

@@ -0,0 +1,376 @@
+/**
+ * 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 { compositeMapMethod } from "./composite.js";
+/**
+ * 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(options) {
+    const { capacity, onEvict } = options;
+    return (next) => {
+        // Doubly-linked list for LRU tracking
+        let head = null;
+        let tail = null;
+        const nodeMap = new Map();
+        const moveToHead = (node) => {
+            // 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, value) => {
+            const node = {
+                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) => {
+            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 = () => {
+            for (const node of [...nodeMap.values()]) {
+                if (!next.has(node.key)) {
+                    removeNode(node);
+                }
+            }
+        };
+        const evictLRU = () => {
+            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, prop);
+                if (composite) {
+                    return composite;
+                }
+                const value = Reflect.get(target, prop, receiver);
+                if (typeof value === "function") {
+                    switch (prop) {
+                        case "get":
+                            return function (key) {
+                                let result;
+                                try {
+                                    result = value.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) {
+                                const result = value.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, val) {
+                                const hadKey = target.has(key);
+                                if (hadKey) {
+                                    // Update existing
+                                    const oldValue = value.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.call(target, key, val);
+                                    addNode(key, val);
+                                    return result;
+                                }
+                            };
+                        case "delete":
+                            return function (key) {
+                                const result = value.call(target, key);
+                                const node = nodeMap.get(key);
+                                if (node) {
+                                    removeNode(node);
+                                }
+                                return result;
+                            };
+                        case "clear":
+                            return function () {
+                                value.call(target);
+                                head = null;
+                                tail = null;
+                                nodeMap.clear();
+                            };
+                    }
+                }
+                return value;
+            },
+        });
+    };
+}
+/**
+ * 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 {
+    capacity;
+    onEvict;
+    map = new Map();
+    head = null;
+    tail = null;
+    constructor(capacity, onEvict) {
+        this.capacity = capacity;
+        this.onEvict = onEvict;
+    }
+    get size() {
+        return this.map.size;
+    }
+    get isFull() {
+        return this.map.size >= this.capacity;
+    }
+    get(key) {
+        const entry = this.map.get(key);
+        if (!entry)
+            return undefined;
+        this.moveToHead(entry.node);
+        return entry.value;
+    }
+    set(key, value) {
+        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 = {
+                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) {
+        return this.map.has(key);
+    }
+    delete(key) {
+        const entry = this.map.get(key);
+        if (!entry)
+            return false;
+        this.removeNode(entry.node);
+        this.map.delete(key);
+        return true;
+    }
+    clear() {
+        this.map.clear();
+        this.head = null;
+        this.tail = null;
+    }
+    moveToHead(node) {
+        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();
+    }
+    removeNode(node) {
+        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;
+        }
+    }
+    evictLRU() {
+        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() {
+        let node = this.head;
+        while (node) {
+            yield node.key;
+            node = node.next;
+        }
+    }
+    /**
+     * Returns entries in LRU order (most recent first).
+     */
+    *entries() {
+        let node = this.head;
+        while (node) {
+            yield [node.key, node.value];
+            node = node.next;
+        }
+    }
+}
+/**
+ * Factory function to create an LRU cache.
+ */
+export function lruCache(capacity, onEvict) {
+    return new LRUCache(capacity, onEvict);
+}
+//# sourceMappingURL=lru.js.map

package/dist/behaviors/lru.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru.js","sourceRoot":"","sources":["../../src/behaviors/lru.ts"],"names":[],"mappings":"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"}

package/dist/behaviors/readonly.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare function readonlyList<T>(options?: ReadonlyOptions): Middleware<ReadonlyList<T>>;
+/**
+ * Creates a readonly Queue middleware.
+ */
+export declare function readonlyQueue<T>(options?: ReadonlyOptions): Middleware<ReadonlyQueue<T>>;
+/**
+ * Creates a readonly Map middleware.
+ */
+export declare function readonlyMap<K, V>(options?: ReadonlyOptions): Middleware<ReadonlyMapLike<K, V>>;
+/**
+ * Creates a readonly Collection middleware.
+ *
+ * Generic version that works with any collection type.
+ */
+export declare function readonlyCollection<T>(options?: ReadonlyOptions): Middleware<ReadonlyCollection<T>>;
+/**
+ * Generic readonly middleware.
+ * Alias for readonlyCollection.
+ */
+export declare function readonly<C extends object>(options?: ReadonlyOptions): Middleware<C>;
+/**
+ * Alias for Java compatibility: unmodifiableList
+ */
+export declare const unmodifiableList: typeof readonlyList;
+/**
+ * Alias for Java compatibility: unmodifiableMap
+ */
+export declare const unmodifiableMap: typeof readonlyMap;
+/**
+ * Alias for Java compatibility: unmodifiableCollection
+ */
+export declare const unmodifiableCollection: typeof readonlyCollection;
+//# sourceMappingURL=readonly.d.ts.map

package/dist/behaviors/readonly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readonly.d.ts","sourceRoot":"","sources":["../../src/behaviors/readonly.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAuHD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,OAAO,GAAE,eAAoB,GAC5B,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAG7B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,OAAO,GAAE,eAAoB,GAC5B,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAG9B;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAC9B,OAAO,GAAE,eAAoB,GAC5B,UAAU,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAGnC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,OAAO,GAAE,eAAoB,GAC5B,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAGnC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvC,OAAO,GAAE,eAAoB,GAC5B,UAAU,CAAC,CAAC,CAAC,CAGf;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAG,OAAO,YAA2B,CAAC;AAEnE;;GAEG;AACH,eAAO,MAAM,eAAe,EAAG,OAAO,WAAyB,CAAC;AAEhE;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAG,OAAO,kBAAuC,CAAC"}

package/dist/behaviors/readonly.js

@@ -0,0 +1,177 @@
+/**
+ * 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
+ */
+/**
+ * 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(errorMessage = "Cannot modify readonly collection") {
+    return (next) => {
+        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 (...args) {
+                        const result = value.apply(target, args);
+                        // Recursively apply readonly to the result
+                        return createReadonly(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(options = {}) {
+    const errorMessage = options.errorMessage ?? "Cannot modify readonly list";
+    return createReadonly(errorMessage);
+}
+/**
+ * Creates a readonly Queue middleware.
+ */
+export function readonlyQueue(options = {}) {
+    const errorMessage = options.errorMessage ?? "Cannot modify readonly queue";
+    return createReadonly(errorMessage);
+}
+/**
+ * Creates a readonly Map middleware.
+ */
+export function readonlyMap(options = {}) {
+    const errorMessage = options.errorMessage ?? "Cannot modify readonly map";
+    return createReadonly(errorMessage);
+}
+/**
+ * Creates a readonly Collection middleware.
+ *
+ * Generic version that works with any collection type.
+ */
+export function readonlyCollection(options = {}) {
+    const errorMessage = options.errorMessage ?? "Cannot modify readonly collection";
+    return createReadonly(errorMessage);
+}
+/**
+ * Generic readonly middleware.
+ * Alias for readonlyCollection.
+ */
+export function readonly(options = {}) {
+    const errorMessage = options.errorMessage ?? "Cannot modify readonly collection";
+    return createReadonly(errorMessage);
+}
+/**
+ * Alias for Java compatibility: unmodifiableList
+ */
+export const unmodifiableList = readonlyList;
+/**
+ * Alias for Java compatibility: unmodifiableMap
+ */
+export const unmodifiableMap = readonlyMap;
+/**
+ * Alias for Java compatibility: unmodifiableCollection
+ */
+export const unmodifiableCollection = readonlyCollection;
+//# sourceMappingURL=readonly.js.map

package/dist/behaviors/readonly.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readonly.js","sourceRoot":"","sources":["../../src/behaviors/readonly.ts"],"names":[],"mappings":"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"}