@mark1russell7/collections 0.0.0-stage → 0.1.0

package/src/behaviors/bounded.ts

@@ -0,0 +1,485 @@
+/**
+ * Bounded behavior - Enforces capacity limits on collections.
+ *
+ * This module wraps collections to prevent them from exceeding a maximum size.
+ * This module gives 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.
+   * The behavior calls this function before it applies the policy.
+   */
+  onOverflow?: OverflowHandler<T>;
+}
+
+/**
+ * Marker interface for bounded collections.
+ */
+export interface BoundedCollection {
+  readonly capacity: number;
+  readonly isFull: boolean;
+  readonly remainingCapacity: number;
+}
+
+/**
+ * This function makes a bounded List middleware.
+ *
+ * Intercepts add operations to enforce capacity limits.
+ * This function 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;
+  };
+}
+
+/**
+ * This function makes 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;
+  };
+}
+
+/**
+ * This function makes 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;
+  };
+}
+
+/**
+ * This function makes 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

@@ -0,0 +1,99 @@
+/**
+ * Composite map methods built on `has`, `get`, `set` and `delete`.
+ *
+ * A map behavior (lruMap, ttlMap) intercepts the primitive methods. It gives these
+ * implementations for the composite methods, bound to the behavior's own proxy.
+ * Thus a call like `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;
+}