mvc-kit 2.12.0 → 2.12.1

package/src/Collection.ts

@@ -0,0 +1,653 @@
+import type { Listener, Subscribable } from './types';
+import { bindPublicMethods } from './bindPublicMethods';
+
+const __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;
+const PROTECTED_KEYS = new Set(['addCleanup']);
+
+function freeze<T>(obj: T): T {
+  return __DEV__ ? Object.freeze(obj) as T : obj;
+}
+
+type CollectionState<T> = T[];
+type CollectionListener<T> = Listener<CollectionState<T>>;
+
+/**
+ * Reactive typed array with CRUD and query methods.
+ */
+export class Collection<T extends { id: string | number }> implements Subscribable<CollectionState<T>> {
+  /** Maximum number of items before FIFO eviction. 0 = unlimited. */
+  static MAX_SIZE = 0;
+  /** Time-to-live in milliseconds. 0 = no expiry. */
+  static TTL = 0;
+
+  private _items: readonly T[] = [];
+  private _disposed = false;
+  private _listeners = new Set<CollectionListener<T>>();
+  private _index = new Map<T['id'], T>();
+  private _abortController: AbortController | null = null;
+  private _cleanups: (() => void)[] | null = null;
+  private _timestamps: Map<T['id'], number> | null = null;
+  private _evictionTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(initialItems: T[] = []) {
+    let result = [...initialItems];
+
+    if (this._ttl > 0) {
+      this._timestamps = new Map();
+      const now = Date.now();
+      for (const item of result) {
+        this._timestamps.set(item.id, now);
+      }
+    }
+
+    if (this._maxSize > 0 && result.length > this._maxSize) {
+      // FIFO: trim from the front (oldest items)
+      const excess = result.length - this._maxSize;
+      const evicted = result.slice(0, excess);
+      result = result.slice(excess);
+      for (const item of evicted) {
+        this._timestamps?.delete(item.id);
+      }
+    }
+
+    this._items = freeze(result);
+    this._rebuildIndex();
+    this._scheduleEvictionTimer();
+    bindPublicMethods(this, Object.prototype, PROTECTED_KEYS);
+  }
+
+  /**
+   * Alias for Subscribable compatibility.
+   */
+  get state(): T[] {
+    return this._items as T[];
+  }
+
+  /** The raw array of items. */
+  get items(): T[] {
+    return this._items as T[];
+  }
+
+  /** Number of items in the collection. */
+  get length(): number {
+    return this._items.length;
+  }
+
+  /** Whether this instance has been disposed. */
+  get disposed(): boolean {
+    return this._disposed;
+  }
+
+  /** AbortSignal that fires when this instance is disposed. Lazily created. */
+  get disposeSignal(): AbortSignal {
+    if (!this._abortController) {
+      this._abortController = new AbortController();
+    }
+    return this._abortController.signal;
+  }
+
+  // ── Config Accessors ──
+
+  private get _maxSize(): number {
+    return (this.constructor as typeof Collection).MAX_SIZE;
+  }
+
+  private get _ttl(): number {
+    return (this.constructor as typeof Collection).TTL;
+  }
+
+  // ── CRUD Methods (notify listeners) ──
+
+  /**
+   * Add one or more items. Items with existing IDs are silently skipped.
+   */
+  add(...items: T[]): void {
+    if (this._disposed) {
+      throw new Error('Cannot add to disposed Collection');
+    }
+
+    if (items.length === 0) {
+      return;
+    }
+
+    // Fast path: single item (most common case)
+    if (items.length === 1) {
+      const item = items[0];
+      if (this._index.has(item.id)) return;
+      const prev = this._items;
+      let result = [...prev, item];
+      this._index.set(item.id, item);
+      if (this._timestamps) this._timestamps.set(item.id, Date.now());
+      if (this._maxSize > 0 && result.length > this._maxSize) {
+        result = this._evictForCapacity(result);
+      }
+      this._items = freeze(result);
+      this._notify(prev);
+      this._scheduleEvictionTimer();
+      return;
+    }
+
+    // Multi-item path
+    const seen = new Set<T['id']>();
+    const newItems: T[] = [];
+    for (const item of items) {
+      if (!this._index.has(item.id) && !seen.has(item.id)) {
+        newItems.push(item);
+        seen.add(item.id);
+      }
+    }
+    if (newItems.length === 0) return;
+
+    const prev = this._items;
+    let result = [...prev, ...newItems];
+
+    for (const item of newItems) {
+      this._index.set(item.id, item);
+    }
+
+    // Record timestamps for TTL
+    if (this._timestamps) {
+      const now = Date.now();
+      for (const item of newItems) {
+        this._timestamps.set(item.id, now);
+      }
+    }
+
+    // Enforce capacity before freeze/notify
+    if (this._maxSize > 0 && result.length > this._maxSize) {
+      result = this._evictForCapacity(result);
+    }
+
+    this._items = freeze(result);
+    this._notify(prev);
+    this._scheduleEvictionTimer();
+  }
+
+  /**
+   * Add or replace items by ID. Existing items are replaced in-place
+   * (preserving array position); new items are appended. Deduplicates
+   * input — last occurrence wins. No-op if nothing changed (reference
+   * comparison).
+   */
+  upsert(...items: T[]): void {
+    if (this._disposed) {
+      throw new Error('Cannot upsert on disposed Collection');
+    }
+    if (items.length === 0) return;
+
+    // Fast path: single item (most common case — channel messages, real-time updates)
+    if (items.length === 1) {
+      const item = items[0];
+      const existing = this._index.get(item.id);
+
+      if (existing) {
+        // Replace in-place — skip if same reference
+        if (existing === item) return;
+        const prev = this._items;
+        const idx = this._items.indexOf(existing);
+        const newItems = [...prev];
+        newItems[idx] = item;
+        this._index.set(item.id, item);
+        if (this._timestamps) this._timestamps.set(item.id, Date.now());
+        this._items = freeze(newItems);
+        this._notify(prev);
+      } else {
+        // New item — append (with capacity enforcement)
+        const prev = this._items;
+        let result = [...prev, item];
+        this._index.set(item.id, item);
+        if (this._timestamps) this._timestamps.set(item.id, Date.now());
+        if (this._maxSize > 0 && result.length > this._maxSize) {
+          result = this._evictForCapacity(result);
+        }
+        this._items = freeze(result);
+        this._notify(prev);
+        this._scheduleEvictionTimer();
+      }
+      return;
+    }
+
+    // Multi-item path: deduplicate input — last occurrence wins
+    const incoming = new Map<T['id'], T>();
+    for (const item of items) {
+      incoming.set(item.id, item);
+    }
+
+    const prev = this._items;
+    let changed = false;
+    const replaced = new Set<T['id']>();
+    const newArray: T[] = [];
+
+    // Replace existing items in-place
+    for (const existing of prev) {
+      if (incoming.has(existing.id)) {
+        const replacement = incoming.get(existing.id)!;
+        if (replacement !== existing) changed = true;
+        newArray.push(replacement);
+        replaced.add(existing.id);
+      } else {
+        newArray.push(existing);
+      }
+    }
+
+    // Append genuinely new items
+    for (const [id, item] of incoming) {
+      if (!replaced.has(id)) {
+        newArray.push(item);
+        changed = true;
+      }
+    }
+
+    if (!changed) return;
+
+    // Record/refresh timestamps for TTL (upsert refreshes existing)
+    if (this._timestamps) {
+      const now = Date.now();
+      for (const [id] of incoming) {
+        this._timestamps.set(id, now);
+      }
+    }
+
+    for (const [id, item] of incoming) {
+      this._index.set(id, item);
+    }
+
+    // Enforce capacity before freeze/notify
+    let result = newArray;
+    if (this._maxSize > 0 && result.length > this._maxSize) {
+      result = this._evictForCapacity(result);
+    }
+
+    this._items = freeze(result);
+    this._notify(prev);
+    this._scheduleEvictionTimer();
+  }
+
+  /**
+   * Remove items by id(s).
+   */
+  remove(...ids: T['id'][]): void {
+    if (this._disposed) {
+      throw new Error('Cannot remove from disposed Collection');
+    }
+
+    if (ids.length === 0) {
+      return;
+    }
+
+    // Fast path: single id (most common case)
+    if (ids.length === 1) {
+      const id = ids[0];
+      if (!this._index.has(id)) return;
+      const prev = this._items;
+      this._items = freeze(prev.filter(item => item.id !== id));
+      this._index.delete(id);
+      this._timestamps?.delete(id);
+      this._notify(prev);
+      this._scheduleEvictionTimer();
+      return;
+    }
+
+    // Multi-id path
+    const idSet = new Set(ids);
+    const filtered = this._items.filter(item => !idSet.has(item.id));
+
+    if (filtered.length === this._items.length) {
+      return; // No items removed
+    }
+
+    const prev = this._items;
+    this._items = freeze(filtered);
+
+    for (const id of ids) {
+      this._index.delete(id);
+      this._timestamps?.delete(id);
+    }
+
+    this._notify(prev);
+    this._scheduleEvictionTimer();
+  }
+
+  /**
+   * Update an item by id with partial changes.
+   */
+  update(id: T['id'], changes: Partial<T>): void {
+    if (this._disposed) {
+      throw new Error('Cannot update disposed Collection');
+    }
+
+    // O(1) existence check via index Map
+    const existing = this._index.get(id);
+    if (!existing) return;
+
+    // Check if anything actually changed (before any array work)
+    const keys = Object.keys(changes) as (keyof T)[];
+    const hasChanges = keys.some(key => changes[key] !== existing[key]);
+    if (!hasChanges) return;
+
+    const updated = { ...existing, ...changes, id };
+    const prev = this._items;
+    const idx = this._items.indexOf(existing);
+    const newItems = [...prev];
+    newItems[idx] = updated;
+    this._items = freeze(newItems);
+    this._index.set(id, updated);
+
+    this._notify(prev);
+  }
+
+  /**
+   * Replace all items.
+   */
+  reset(items: T[]): void {
+    if (this._disposed) {
+      throw new Error('Cannot reset disposed Collection');
+    }
+
+    const prev = this._items;
+
+    // Record timestamps for TTL
+    if (this._timestamps) {
+      this._timestamps.clear();
+      const now = Date.now();
+      for (const item of items) {
+        this._timestamps.set(item.id, now);
+      }
+    }
+
+    let result = [...items];
+
+    // Enforce capacity before freeze/notify
+    if (this._maxSize > 0 && result.length > this._maxSize) {
+      result = this._evictForCapacity(result);
+    }
+
+    this._items = freeze(result);
+    this._rebuildIndex();
+
+    this._notify(prev);
+    this._scheduleEvictionTimer();
+  }
+
+  /**
+   * Remove all items.
+   */
+  clear(): void {
+    if (this._disposed) {
+      throw new Error('Cannot clear disposed Collection');
+    }
+
+    if (this._items.length === 0) {
+      return;
+    }
+
+    const prev = this._items;
+    this._items = freeze([] as T[]);
+    this._index.clear();
+    this._timestamps?.clear();
+    this._clearEvictionTimer();
+
+    this._notify(prev);
+  }
+
+  /**
+   * Snapshot current state, apply callback mutations, and return a rollback function.
+   * Rollback restores items to pre-callback state regardless of later mutations.
+   */
+  optimistic(callback: () => void): () => void {
+    if (this._disposed) {
+      throw new Error('Cannot perform optimistic update on disposed Collection');
+    }
+
+    const snapshot = this._items;
+    const timestampSnapshot = this._timestamps ? new Map(this._timestamps) : null;
+    callback();
+
+    let rolledBack = false;
+    return () => {
+      if (rolledBack || this._disposed) return;
+      rolledBack = true;
+
+      const prev = this._items;
+      this._items = snapshot;
+      if (timestampSnapshot) {
+        this._timestamps = timestampSnapshot;
+      }
+      this._rebuildIndex();
+      this._notify(prev);
+      this._scheduleEvictionTimer();
+    };
+  }
+
+  // ── Query Methods (pure, no notification) ──
+
+  /**
+   * Get item by id.
+   */
+  get(id: T['id']): T | undefined {
+    return this._index.get(id);
+  }
+
+  /**
+   * Check if item exists by id.
+   */
+  has(id: T['id']): boolean {
+    return this._index.has(id);
+  }
+
+  /**
+   * Find first item matching predicate.
+   */
+  find(predicate: (item: T) => boolean): T | undefined {
+    return this._items.find(predicate);
+  }
+
+  /**
+   * Filter items matching predicate.
+   */
+  filter(predicate: (item: T) => boolean): T[] {
+    return this._items.filter(predicate) as T[];
+  }
+
+  /**
+   * Return sorted copy.
+   */
+  sorted(compareFn: (a: T, b: T) => number): T[] {
+    return [...this._items].sort(compareFn);
+  }
+
+  /**
+   * Map items to new array.
+   */
+  map<U>(fn: (item: T) => U): U[] {
+    return this._items.map(fn);
+  }
+
+  // ── Subscribable interface ──
+
+  /** Subscribes to state changes. Returns an unsubscribe function. */
+  subscribe(listener: CollectionListener<T>): () => void {
+    if (this._disposed) {
+      return () => {};
+    }
+
+    this._listeners.add(listener);
+
+    return () => {
+      this._listeners.delete(listener);
+    };
+  }
+
+  /** Tears down the instance, releasing all subscriptions and resources. */
+  dispose(): void {
+    if (this._disposed) {
+      return;
+    }
+
+    this._disposed = true;
+    this._clearEvictionTimer();
+    this._abortController?.abort();
+    if (this._cleanups) {
+      for (const fn of this._cleanups) fn();
+      this._cleanups = null;
+    }
+    this.onDispose?.();
+    this._listeners.clear();
+    this._index.clear();
+    this._timestamps?.clear();
+  }
+
+  /** Registers a cleanup function to be called on dispose. @protected */
+  protected addCleanup(fn: () => void): void {
+    if (!this._cleanups) {
+      this._cleanups = [];
+    }
+    this._cleanups.push(fn);
+  }
+
+  /** Lifecycle hook called during dispose(). Override for custom teardown. @protected */
+  protected onDispose?(): void;
+
+  /**
+   * Called before items are auto-evicted by capacity or TTL.
+   * Override to filter which items get evicted, or veto entirely.
+   *
+   * @param items - Candidates for eviction
+   * @param reason - Why eviction is happening
+   * @returns void to proceed with all, false to veto, or T[] subset to evict only those
+   */
+  protected onEvict?(items: T[], reason: 'capacity' | 'ttl'): T[] | false | void;
+
+  private _notify(prev: readonly T[]): void {
+    for (const listener of this._listeners) {
+      listener(this._items as T[], prev as T[]);
+    }
+  }
+
+  private _rebuildIndex(): void {
+    this._index.clear();
+    for (const item of this._items) {
+      this._index.set(item.id, item);
+    }
+  }
+
+  // ── Eviction Internals ──
+
+  private _evictForCapacity(items: T[]): T[] {
+    const excess = items.length - this._maxSize;
+    if (excess <= 0) return items;
+
+    const candidates = items.slice(0, excess);
+    const toEvict = this._applyOnEvict(candidates, 'capacity');
+
+    if (toEvict === false) return items; // veto
+
+    if (toEvict.length === 0) return items; // nothing to evict
+
+    const evictIds = new Set(toEvict.map(item => item.id));
+    const result = items.filter(item => !evictIds.has(item.id));
+
+    // Clean up index and timestamps for evicted items
+    for (const item of toEvict) {
+      this._index.delete(item.id);
+      this._timestamps?.delete(item.id);
+    }
+
+    return result;
+  }
+
+  private _applyOnEvict(candidates: T[], reason: 'capacity' | 'ttl'): T[] | false {
+    if (!this.onEvict) return candidates;
+
+    const result = this.onEvict(candidates, reason);
+    if (result === false) {
+      // DEV warning when veto causes collection to exceed 2x MAX_SIZE
+      if (__DEV__ && reason === 'capacity' && this._maxSize > 0) {
+        const currentSize = this._items.length + candidates.length;
+        if (currentSize > this._maxSize * 2) {
+          console.warn(
+            `[mvc-kit] Collection exceeded 2x MAX_SIZE (${currentSize}/${this._maxSize}). ` +
+            `onEvict is vetoing eviction — this may cause unbounded growth.`
+          );
+        }
+      }
+      return false;
+    }
+    if (Array.isArray(result)) {
+      // Only include items that are actually in the current items
+      const candidateIds = new Set(candidates.map(c => c.id));
+      return result.filter(item => candidateIds.has(item.id));
+    }
+    return candidates; // void = proceed with all
+  }
+
+  private _sweepExpired(): void {
+    if (this._disposed || !this._timestamps || this._ttl <= 0) return;
+
+    const now = Date.now();
+    const ttl = this._ttl;
+    const expired: T[] = [];
+
+    for (const item of this._items) {
+      const ts = this._timestamps.get(item.id);
+      if (ts !== undefined && (now - ts) >= ttl) {
+        expired.push(item);
+      }
+    }
+
+    if (expired.length === 0) {
+      this._scheduleEvictionTimer();
+      return;
+    }
+
+    const toEvict = this._applyOnEvict(expired, 'ttl');
+
+    if (toEvict === false) {
+      this._scheduleEvictionTimer();
+      return;
+    }
+
+    if (toEvict.length === 0) {
+      this._scheduleEvictionTimer();
+      return;
+    }
+
+    const evictIds = new Set(toEvict.map(item => item.id));
+    const prev = this._items;
+    this._items = freeze(
+      (prev as T[]).filter((item: T) => !evictIds.has(item.id))
+    );
+
+    for (const item of toEvict) {
+      this._index.delete(item.id);
+      this._timestamps.delete(item.id);
+    }
+
+    this._notify(prev);
+    this._scheduleEvictionTimer();
+  }
+
+  private _scheduleEvictionTimer(): void {
+    this._clearEvictionTimer();
+
+    if (this._disposed || !this._timestamps || this._ttl <= 0 || this._timestamps.size === 0) return;
+
+    const now = Date.now();
+    const ttl = this._ttl;
+    let earliest = Infinity;
+
+    for (const ts of this._timestamps.values()) {
+      if (ts < earliest) earliest = ts;
+    }
+
+    const delay = Math.max(0, (earliest + ttl) - now);
+    this._evictionTimer = setTimeout(() => this._sweepExpired(), delay);
+  }
+
+  private _clearEvictionTimer(): void {
+    if (this._evictionTimer !== null) {
+      clearTimeout(this._evictionTimer);
+      this._evictionTimer = null;
+    }
+  }
+}