@procedures/collections 0.0.0-stage → 0.1.0

package/src/behaviors/ttl.ts

@@ -0,0 +1,462 @@
+/**
+ * TTL (Time-To-Live) expiration behavior.
+ *
+ * Automatically expires elements after a specified time period.
+ * Perfect for temporary caches and time-limited data.
+ *
+ * @example
+ * const cache = compose(
+ *   ttlMap({ ttl: 60000 }) // 60 seconds
+ * )(hashMap<string, Data>())
+ *
+ * cache.set('key', data)
+ * // After 60 seconds, 'key' is automatically removed
+ */
+
+import type { Middleware } from "../core/middleware.js";
+import type { MapLike } from "../interfaces/map.js";
+import { compositeMapMethod } from "./composite.js";
+import type { Collection } from "../interfaces/collection.js";
+
+/**
+ * Start the background expiration checker without keeping a Node.js process alive.
+ * (In a browser, setInterval returns a number and there is nothing to unref.)
+ */
+function startExpirationTimer(check: () => void, interval: number): ReturnType<typeof setInterval> {
+  const timer = setInterval(check, interval);
+  (timer as unknown as { unref?: () => void }).unref?.();
+  return timer;
+}
+
+/**
+ * Options for TTL behavior.
+ */
+export interface TTLOptions {
+  /**
+   * Time-to-live in milliseconds.
+   * Elements expire after this duration.
+   */
+  ttl: number;
+
+  /**
+   * Interval for checking expired elements (in milliseconds).
+   * @default 1000 (check every second)
+   */
+  checkInterval?: number;
+
+  /**
+   * Optional callback invoked when an element expires.
+   */
+  onExpire?: (info: { key: any; value: any; createdAt: number; expiredAt: number }) => void;
+}
+
+/**
+ * Metadata for TTL tracking.
+ */
+interface TTLEntry<V> {
+  value: V;
+  expiresAt: number;
+  createdAt: number;
+}
+
+/**
+ * Creates a TTL Map middleware.
+ *
+ * Automatically removes entries after TTL expires.
+ * Uses a background interval to check for expired entries.
+ */
+export function ttlMap<K, V>(
+  options: TTLOptions
+): Middleware<MapLike<K, V>, MapLike<K, V> & { readonly dispose: () => void }> {
+  const { ttl, checkInterval = 1000, onExpire } = options;
+
+  return (
+    next: MapLike<K, V>
+  ): MapLike<K, V> & { readonly dispose: () => void } => {
+    const metadata = new Map<K, TTLEntry<V>>();
+    let intervalId: ReturnType<typeof setInterval> | null = null;
+
+    const checkExpired = (): 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,
+            });
+          }
+        }
+      }
+    };
+
+    // Start background expiration checker
+    intervalId = startExpirationTimer(checkExpired, checkInterval);
+
+    const dispose = (): void => {
+      if (intervalId) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+    };
+
+    return new Proxy(next, {
+      get(target, prop, receiver) {
+        // Add dispose method
+        if (prop === "dispose") {
+          return dispose;
+        }
+
+        // Composite methods (setIfAbsent, compute, merge, putAll and others) go through this
+        // proxy's own primitives, so they keep the expiry 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 {
+                // 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();
+              };
+          }
+        }
+
+        return value;
+      },
+    }) as MapLike<K, V> & { readonly dispose: () => void };
+  };
+}
+
+/**
+ * Creates a TTL Collection middleware.
+ *
+ * Note: This is less precise than TTL map because collections don't have keys.
+ * Elements are tracked by reference, which may not work for primitive types.
+ */
+export function ttlCollection<T>(
+  options: Omit<TTLOptions, "onExpire"> & {
+    onExpire?: (info: { element: T; createdAt: number; expiredAt: number }) => void;
+  }
+): Middleware<Collection<T>, Collection<T> & { readonly dispose: () => void }> {
+  const { ttl, checkInterval = 1000, onExpire } = options;
+
+  return (
+    next: Collection<T>
+  ): Collection<T> & { readonly dispose: () => void } => {
+    const metadata = new Map<T, { expiresAt: number; createdAt: number }>();
+    let intervalId: ReturnType<typeof setInterval> | null = null;
+
+    const checkExpired = (): void => {
+      const now = Date.now();
+      const expired: T[] = [];
+
+      for (const [element, entry] of metadata) {
+        if (now >= entry.expiresAt) {
+          expired.push(element);
+        }
+      }
+
+      for (const element of expired) {
+        const entry = metadata.get(element);
+        if (entry) {
+          next.remove(element);
+          metadata.delete(element);
+
+          if (onExpire) {
+            onExpire({
+              element,
+              createdAt: entry.createdAt,
+              expiredAt: now,
+            });
+          }
+        }
+      }
+    };
+
+    intervalId = startExpirationTimer(checkExpired, checkInterval);
+
+    const dispose = (): void => {
+      if (intervalId) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+    };
+
+    return new Proxy(next, {
+      get(target, prop, receiver) {
+        if (prop === "dispose") {
+          return dispose;
+        }
+
+        const value = Reflect.get(target, prop, receiver);
+
+        if (typeof value === "function") {
+          switch (prop) {
+            case "add":
+              return function (element: T): boolean {
+                const result = (value as Function).call(target, element);
+                if (result) {
+                  const now = Date.now();
+                  metadata.set(element, {
+                    expiresAt: now + ttl,
+                    createdAt: now,
+                  });
+                }
+                return result;
+              };
+
+            case "remove":
+              return function (element: T): boolean {
+                const result = (value as Function).call(target, element);
+                if (result) {
+                  metadata.delete(element);
+                }
+                return result;
+              };
+
+            case "clear":
+              return function (): void {
+                (value as Function).call(target);
+                metadata.clear();
+              };
+          }
+        }
+
+        return value;
+      },
+    }) as Collection<T> & { readonly dispose: () => void };
+  };
+}
+
+/**
+ * Standalone TTL cache with Map-like API.
+ *
+ * @example
+ * const cache = new TTLCache<string, number>(60000) // 60 second TTL
+ * cache.set('key', 42)
+ * setTimeout(() => {
+ *   cache.get('key') // undefined (expired)
+ * }, 61000)
+ */
+export class TTLCache<K, V> {
+  private map = new Map<K, TTLEntry<V>>();
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    private readonly ttl: number,
+    private readonly checkInterval: number = 1000,
+    private readonly onExpire?: (key: K, value: V) => void
+  ) {
+    this.startExpirationCheck();
+  }
+
+  get size(): number {
+    this.cleanup();
+    return this.map.size;
+  }
+
+  get(key: K): V | undefined {
+    const entry = this.map.get(key);
+    if (!entry) return undefined;
+
+    if (Date.now() >= entry.expiresAt) {
+      this.map.delete(key);
+      if (this.onExpire) {
+        this.onExpire(key, entry.value);
+      }
+      return undefined;
+    }
+
+    return entry.value;
+  }
+
+  set(key: K, value: V, customTTL?: number): void {
+    const now = Date.now();
+    const ttlToUse = customTTL !== undefined ? customTTL : this.ttl;
+
+    this.map.set(key, {
+      value,
+      expiresAt: now + ttlToUse,
+      createdAt: now,
+    });
+  }
+
+  has(key: K): boolean {
+    return this.get(key) !== undefined;
+  }
+
+  delete(key: K): boolean {
+    return this.map.delete(key);
+  }
+
+  clear(): void {
+    this.map.clear();
+  }
+
+  /**
+   * Manually trigger cleanup of expired entries.
+   */
+  cleanup(): void {
+    const now = Date.now();
+    const expired: K[] = [];
+
+    for (const [key, entry] of this.map) {
+      if (now >= entry.expiresAt) {
+        expired.push(key);
+      }
+    }
+
+    for (const key of expired) {
+      const entry = this.map.get(key);
+      if (entry) {
+        this.map.delete(key);
+        if (this.onExpire) {
+          this.onExpire(key, entry.value);
+        }
+      }
+    }
+  }
+
+  /**
+   * Get remaining TTL for a key in milliseconds.
+   * Returns undefined if key doesn't exist or is expired.
+   */
+  getTTL(key: K): number | undefined {
+    const entry = this.map.get(key);
+    if (!entry) return undefined;
+
+    const remaining = entry.expiresAt - Date.now();
+    return remaining > 0 ? remaining : undefined;
+  }
+
+  /**
+   * Update TTL for an existing key.
+   */
+  touch(key: K, customTTL?: number): boolean {
+    const entry = this.map.get(key);
+    if (!entry) return false;
+
+    if (Date.now() >= entry.expiresAt) {
+      this.map.delete(key);
+      return false;
+    }
+
+    const ttlToUse = customTTL !== undefined ? customTTL : this.ttl;
+    entry.expiresAt = Date.now() + ttlToUse;
+    return true;
+  }
+
+  private startExpirationCheck(): void {
+    this.intervalId = startExpirationTimer(() => this.cleanup(), this.checkInterval);
+  }
+
+  /**
+   * Stop the background expiration checker and clean up.
+   */
+  dispose(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+
+  *keys(): IterableIterator<K> {
+    this.cleanup();
+    yield* this.map.keys();
+  }
+
+  *values(): IterableIterator<V> {
+    this.cleanup();
+    for (const entry of this.map.values()) {
+      yield entry.value;
+    }
+  }
+
+  *entries(): IterableIterator<[K, V]> {
+    this.cleanup();
+    for (const [key, entry] of this.map) {
+      yield [key, entry.value];
+    }
+  }
+}
+
+/**
+ * Factory function to create a TTL cache.
+ */
+export function ttlCache<K, V>(
+  ttl: number,
+  options?: {
+    checkInterval?: number;
+    onExpire?: (key: K, value: V) => void;
+  }
+): TTLCache<K, V> {
+  return new TTLCache(
+    ttl,
+    options?.checkInterval,
+    options?.onExpire
+  );
+}

package/src/contracts/model.ts

@@ -0,0 +1,44 @@
+/**
+ * Helpers for the contract tests: random operation sequences that run against an implementation
+ * and a plain JavaScript model, with a check after each operation (ARCHITECTURE-PROPOSALS P8).
+ */
+
+import fc from "fast-check";
+
+/** One operation of a sequence: it changes the implementation and the model in the same way. */
+export interface Step<S, M> {
+  readonly label: string;
+  run(sut: S, model: M): void;
+}
+
+/** Small integers: many duplicates and collisions, so the edge cases come up often. */
+export const smallInt: fc.Arbitrary<number> = fc.integer({ min: -20, max: 20 });
+
+/**
+ * This function runs random sequences of steps against a new implementation and a new model,
+ * and calls `check` after each step. fast-check shrinks a failure to a short sequence.
+ */
+export function runModel<S, M>(options: {
+  create: () => { sut: S; model: M };
+  steps: fc.Arbitrary<Step<S, M>>;
+  check: (sut: S, model: M) => void;
+  maxSteps?: number;
+  numRuns?: number;
+}): void {
+  fc.assert(
+    fc.property(fc.array(options.steps, { maxLength: options.maxSteps ?? 120 }), (steps) => {
+      const { sut, model } = options.create();
+      options.check(sut, model);
+      for (const step of steps) {
+        step.run(sut, model);
+        options.check(sut, model);
+      }
+    }),
+    { numRuns: options.numRuns ?? 200 },
+  );
+}
+
+/** A step with a label that shows in a failure report. */
+export function step<S, M>(label: string, run: (sut: S, model: M) => void): Step<S, M> {
+  return { label, run, toString: () => label } as Step<S, M>;
+}