@procedures/collections 0.47.1 → 0.48.0

package/src/behaviors/ttl.ts

@@ -1,462 +0,0 @@
-/**
- * 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

@@ -1,44 +0,0 @@
-/**
- * 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>;
-}