@procedures/collections 0.46.0 → 0.47.2

package/src/behaviors/bounded.ts

@@ -1,485 +0,0 @@
-/**
- * Bounded behavior - Enforces capacity limits on collections.
- *
- * Wraps collections to prevent them from exceeding a maximum size.
- * Provides various overflow policies to handle full collections.
- *
- * @example
- * const list = compose(
- *   boundedList({ capacity: 100, policy: 'drop-oldest' })
- * )(arrayList<number>())
- *
- * // Add 101 elements - first element will be dropped
- * for (let i = 0; i < 101; i++) {
- *   list.add(i)
- * }
- */
-
-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 type { Collection } from "../interfaces/collection.js";
-import type {
-  OverflowPolicy,
-  OverflowHandler,
-  OverflowContext,
-} from "../core/policies.js";
-
-/**
- * Options for bounded behavior.
- */
-export interface BoundedOptions<T> {
-  /**
-   * Maximum number of elements the collection can hold.
-   */
-  capacity: number;
-
-  /**
-   * Policy for handling overflow when collection is full.
-   * @default 'throw'
-   */
-  policy?: OverflowPolicy;
-
-  /**
-   * Optional callback invoked when overflow occurs.
-   * Called before the policy is applied.
-   */
-  onOverflow?: OverflowHandler<T>;
-}
-
-/**
- * Marker interface for bounded collections.
- */
-export interface BoundedCollection {
-  readonly capacity: number;
-  readonly isFull: boolean;
-  readonly remainingCapacity: number;
-}
-
-/**
- * Creates a bounded List middleware.
- *
- * Intercepts add operations to enforce capacity limits.
- * Supports multiple overflow policies.
- */
-export function boundedList<T>(
-  options: BoundedOptions<T>
-): Middleware<List<T>, List<T> & BoundedCollection> {
-  const { capacity, policy = "throw", onOverflow } = options;
-
-  return (next: List<T>): List<T> & BoundedCollection => {
-    // 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
-      if (onOverflow) {
-        const context: OverflowContext<T> = {
-          newElement: element,
-          currentSize: next.size,
-          capacity,
-          timestamp: Date.now(),
-        };
-        onOverflow(context);
-      }
-
-      // Apply policy
-      switch (policy) {
-        case "throw":
-          throw new Error(`List is full (capacity: ${capacity})`);
-
-        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();
-          }
-          break;
-
-        case "drop-newest":
-          // Don't add the new element (do nothing)
-          return;
-
-        case "reject":
-          // Silently reject (return false for add operations)
-          return;
-
-        case "grow":
-          // Allow growth (do nothing, element will be added)
-          return;
-
-        case "block":
-          throw new Error("Block policy not supported for sync collections");
-
-        default:
-          throw new Error(`Unknown overflow policy: ${policy}`);
-      }
-    };
-
-    // After drop-oldest removed the first element, an index of the caller is one place lower
-    const shifted = (index: number): number => (policy === "drop-oldest" ? Math.max(0, index - 1) : index);
-
-    return new Proxy(next, {
-      get(target, prop, receiver) {
-        // Capacity property
-        if (prop === "capacity") {
-          return capacity;
-        }
-
-        // isFull property
-        if (prop === "isFull") {
-          return target.size >= capacity;
-        }
-
-        // remainingCapacity property
-        if (prop === "remainingCapacity") {
-          return Math.max(0, capacity - target.size);
-        }
-
-        const value = Reflect.get(target, prop, receiver);
-
-        // Intercept methods that add elements
-        if (typeof value === "function") {
-          switch (prop) {
-            case "add":
-              return function (element: T): boolean {
-                if (target.size >= capacity && policy !== "grow") {
-                  handleOverflow(element);
-                  if (policy === "reject" || policy === "drop-newest") {
-                    return false;
-                  }
-                }
-                return (value as Function).call(target, element);
-              };
-
-            case "push":
-              return function (element: T): void {
-                if (target.size >= capacity && policy !== "grow") {
-                  handleOverflow(element);
-                  if (policy === "reject" || policy === "drop-newest") {
-                    return;
-                  }
-                }
-                (value as Function).call(target, element);
-              };
-
-            case "unshift":
-              return function (element: T): void {
-                if (target.size >= capacity && policy !== "grow") {
-                  // One element goes: the last one (before, the first and the last went: audit pass 2)
-                  handleOverflow(element, "last");
-                  if (policy === "reject" || policy === "drop-newest") {
-                    return;
-                  }
-                }
-                (value as Function).call(target, element);
-              };
-
-            case "insert":
-              return function (index: number, element: T): void {
-                let at = index;
-                if (target.size >= capacity && policy !== "grow") {
-                  handleOverflow(element);
-                  if (policy === "reject" || policy === "drop-newest") {
-                    return;
-                  }
-                  at = shifted(at);
-                }
-                (value as Function).call(target, at, element);
-              };
-
-            case "addAll":
-            case "insertAll":
-              return function (...args: any[]): boolean {
-                const elements = args[args.length - 1] as Iterable<T>;
-                const elementsArray = Array.from(elements);
-
-                // Check if adding all elements would exceed capacity
-                if (target.size + elementsArray.length > capacity && policy !== "grow") {
-                  // Add elements one by one with overflow handling. An insert keeps the order of
-                  // the elements, at an index that follows each drop.
-                  let added = false;
-                  let at = args[0] as number;
-                  for (const element of elementsArray) {
-                    if (target.size >= capacity) {
-                      handleOverflow(element);
-                      if (policy === "reject" || policy === "drop-newest") {
-                        break;
-                      }
-                      at = shifted(at);
-                    }
-                    if (prop === "addAll") {
-                      target.add(element);
-                    } else {
-                      target.insert(at, element);
-                      at++;
-                    }
-                    added = true;
-                  }
-                  return added;
-                }
-
-                return (value as Function).apply(target, args);
-              };
-          }
-        }
-
-        return value;
-      },
-    }) as List<T> & BoundedCollection;
-  };
-}
-
-/**
- * Creates a bounded Queue middleware.
- */
-export function boundedQueue<T>(
-  options: BoundedOptions<T>
-): Middleware<Queue<T>, Queue<T> & BoundedCollection> {
-  const { capacity, policy = "throw", onOverflow } = options;
-
-  return (next: Queue<T>): Queue<T> & BoundedCollection => {
-    const handleOverflow = (element: T): void => {
-      if (onOverflow) {
-        const context: OverflowContext<T> = {
-          newElement: element,
-          currentSize: next.size,
-          capacity,
-          timestamp: Date.now(),
-        };
-        onOverflow(context);
-      }
-
-      switch (policy) {
-        case "throw":
-          throw new Error(`Queue is full (capacity: ${capacity})`);
-        case "drop-oldest":
-          if (!next.isEmpty) {
-            next.poll();
-          }
-          break;
-        case "drop-newest":
-        case "reject":
-          return;
-        case "grow":
-          return;
-        case "block":
-          throw new Error("Block policy not supported for sync collections");
-        default:
-          throw new Error(`Unknown overflow policy: ${policy}`);
-      }
-    };
-
-    return new Proxy(next, {
-      get(target, prop, receiver) {
-        if (prop === "capacity") return capacity;
-        if (prop === "isFull") return target.size >= capacity;
-        if (prop === "remainingCapacity") return Math.max(0, capacity - target.size);
-
-        const value = Reflect.get(target, prop, receiver);
-
-        if (typeof value === "function") {
-          switch (prop) {
-            case "offer":
-            case "enqueue":
-            case "add":
-              return function (element: T): boolean {
-                if (target.size >= capacity && policy !== "grow") {
-                  handleOverflow(element);
-                  if (policy === "reject" || policy === "drop-newest") {
-                    return false;
-                  }
-                }
-                return (value as Function).call(target, element);
-              };
-          }
-        }
-
-        return value;
-      },
-    }) as Queue<T> & BoundedCollection;
-  };
-}
-
-/**
- * Creates a bounded Deque middleware.
- */
-export function boundedDeque<T>(
-  options: BoundedOptions<T>
-): Middleware<Deque<T>, Deque<T> & BoundedCollection> {
-  const { capacity, policy = "throw", onOverflow } = options;
-
-  return (next: Deque<T>): Deque<T> & BoundedCollection => {
-    const handleOverflow = (element: T): void => {
-      if (onOverflow) {
-        const context: OverflowContext<T> = {
-          newElement: element,
-          currentSize: next.size,
-          capacity,
-          timestamp: Date.now(),
-        };
-        onOverflow(context);
-      }
-
-      switch (policy) {
-        case "throw":
-          throw new Error(`Deque is full (capacity: ${capacity})`);
-        case "drop-oldest":
-          if (!next.isEmpty) {
-            next.removeFirst();
-          }
-          break;
-        case "drop-newest":
-        case "reject":
-          return;
-        case "grow":
-          return;
-        case "block":
-          throw new Error("Block policy not supported for sync collections");
-        default:
-          throw new Error(`Unknown overflow policy: ${policy}`);
-      }
-    };
-
-    return new Proxy(next, {
-      get(target, prop, receiver) {
-        if (prop === "capacity") return capacity;
-        if (prop === "isFull") return target.size >= capacity;
-        if (prop === "remainingCapacity") return Math.max(0, capacity - target.size);
-
-        const value = Reflect.get(target, prop, receiver);
-
-        if (typeof value === "function") {
-          switch (prop) {
-            case "addFirst":
-            case "addLast":
-            case "offerFirst":
-            case "offerLast":
-            case "push":
-            case "offer":
-            case "add":
-              return function (element: T): any {
-                if (target.size >= capacity && policy !== "grow") {
-                  handleOverflow(element);
-                  if (policy === "reject" || policy === "drop-newest") {
-                    return prop.startsWith("offer") || prop === "add" ? false : undefined;
-                  }
-                }
-                return (value as Function).call(target, element);
-              };
-          }
-        }
-
-        return value;
-      },
-    }) as Deque<T> & BoundedCollection;
-  };
-}
-
-/**
- * Creates a bounded Map middleware.
- */
-export function boundedMap<K, V>(
-  options: Omit<BoundedOptions<V>, "onOverflow"> & {
-    onOverflow?: (context: Omit<OverflowContext<V>, "newElement"> & { key: K; value: V }) => void;
-  }
-): Middleware<MapLike<K, V>, MapLike<K, V> & BoundedCollection> {
-  const { capacity, policy = "throw", onOverflow } = options;
-
-  return (next: MapLike<K, V>): MapLike<K, V> & BoundedCollection => {
-    let insertionOrder: K[] = []; // Track insertion order for drop-oldest
-
-    const handleOverflow = (key: K, value: V): void => {
-      if (onOverflow) {
-        onOverflow({
-          key,
-          value,
-          currentSize: next.size,
-          capacity,
-          timestamp: Date.now(),
-        });
-      }
-
-      switch (policy) {
-        case "throw":
-          throw new Error(`Map is full (capacity: ${capacity})`);
-        case "drop-oldest":
-          // Remove oldest key
-          if (insertionOrder.length > 0) {
-            const oldestKey = insertionOrder.shift()!;
-            next.delete(oldestKey);
-          }
-          break;
-        case "drop-newest":
-        case "reject":
-          return;
-        case "grow":
-          return;
-        case "block":
-          throw new Error("Block policy not supported for sync collections");
-        default:
-          throw new Error(`Unknown overflow policy: ${policy}`);
-      }
-    };
-
-    return new Proxy(next, {
-      get(target, prop, receiver) {
-        if (prop === "capacity") return capacity;
-        if (prop === "isFull") return target.size >= capacity;
-        if (prop === "remainingCapacity") return Math.max(0, capacity - target.size);
-
-        const value = Reflect.get(target, prop, receiver);
-
-        if (typeof value === "function") {
-          switch (prop) {
-            case "set":
-              return function (key: K, val: V): V | undefined {
-                const hadKey = target.has(key);
-
-                if (!hadKey && target.size >= capacity && policy !== "grow") {
-                  handleOverflow(key, val);
-                  if (policy === "reject" || policy === "drop-newest") {
-                    return undefined;
-                  }
-                }
-
-                const result = (value as Function).call(target, key, val);
-
-                // Track insertion order
-                if (!hadKey) {
-                  insertionOrder.push(key);
-                }
-
-                return result;
-              };
-
-            case "delete":
-              return function (key: K): V | undefined {
-                const result = (value as Function).call(target, key);
-                // Remove from insertion order tracking
-                insertionOrder = insertionOrder.filter((k) => !target.keyEq(k, key));
-                return result;
-              };
-
-            case "clear":
-              return function (): void {
-                (value as Function).call(target);
-                insertionOrder = [];
-              };
-          }
-        }
-
-        return value;
-      },
-    }) as MapLike<K, V> & BoundedCollection;
-  };
-}
-
-/**
- * Generic bounded collection middleware.
- * Works with any collection type.
- */
-export function bounded<C extends Collection<any>>(
-  options: BoundedOptions<any>
-): Middleware<C, C & BoundedCollection> {
-  return boundedList(options) as any;
-}

package/src/behaviors/composite.ts

@@ -1,99 +0,0 @@
-/**
- * Composite map methods built on `has`, `get`, `set` and `delete`.
- *
- * A map behavior (lruMap, ttlMap) intercepts the primitive methods. It returns these
- * implementations for the composite methods, bound to the behavior's own proxy, so a call such
- * as `setIfAbsent` goes through the behavior's `set` and keeps its rules: capacity and recency
- * for LRU, expiry for TTL. (BUGS-2026-07 L13: the composite methods went straight to the map
- * below, so they bypassed the behavior.)
- *
- * The semantics follow HashMap. One difference: `replaceEntry` and `deleteEntry` compare
- * values with Object.is, not with a map's custom value equality.
- */
-
-import type { Entry, MapLike } from "../interfaces/map.js";
-
-type AnyFn = (...args: never[]) => unknown;
-
-export function compositeMapMethod<K, V>(map: MapLike<K, V>, name: PropertyKey): AnyFn | undefined {
-  switch (name) {
-    case "setIfAbsent":
-      return ((key: K, value: V): V => {
-        if (map.has(key)) return map.get(key);
-        map.set(key, value);
-        return value;
-      }) as AnyFn;
-
-    case "replace":
-      return ((key: K, value: V): V | undefined => (map.has(key) ? map.set(key, value) : undefined)) as AnyFn;
-
-    case "replaceEntry":
-      return ((key: K, oldValue: V, newValue: V): boolean => {
-        if (!map.has(key) || !Object.is(map.get(key), oldValue)) return false;
-        map.set(key, newValue);
-        return true;
-      }) as AnyFn;
-
-    case "deleteEntry":
-      return ((key: K, value: V): boolean => {
-        if (!map.has(key) || !Object.is(map.get(key), value)) return false;
-        map.delete(key);
-        return true;
-      }) as AnyFn;
-
-    case "computeIfAbsent":
-      return ((key: K, mappingFunction: (key: K) => V): V => {
-        if (map.has(key)) return map.get(key);
-        const value = mappingFunction(key);
-        map.set(key, value);
-        return value;
-      }) as AnyFn;
-
-    case "computeIfPresent":
-      return ((key: K, remapping: (key: K, value: V) => V | undefined): V | undefined => {
-        if (!map.has(key)) return undefined;
-        const value = remapping(key, map.get(key));
-        if (value === undefined) {
-          map.delete(key);
-          return undefined;
-        }
-        map.set(key, value);
-        return value;
-      }) as AnyFn;
-
-    case "compute":
-      return ((key: K, remapping: (key: K, value: V | undefined) => V | undefined): V | undefined => {
-        const present = map.has(key);
-        const value = remapping(key, present ? map.get(key) : undefined);
-        if (value === undefined) {
-          if (present) map.delete(key);
-          return undefined;
-        }
-        map.set(key, value);
-        return value;
-      }) as AnyFn;
-
-    case "merge":
-      return ((key: K, value: V, remapping: (oldValue: V, newValue: V) => V | undefined): V | undefined => {
-        if (!map.has(key)) {
-          map.set(key, value);
-          return value;
-        }
-        const merged = remapping(map.get(key), value);
-        if (merged === undefined) {
-          map.delete(key);
-          return undefined;
-        }
-        map.set(key, merged);
-        return merged;
-      }) as AnyFn;
-
-    case "putAll":
-      return ((other: Iterable<Entry<K, V>>): void => {
-        for (const entry of other) {
-          map.set(entry.key, entry.value);
-        }
-      }) as AnyFn;
-  }
-  return undefined;
-}