mvc-kit 2.12.0 → 2.12.1

package/src/Collection.md

@@ -0,0 +1,533 @@
+# Collection
+
+A reactive typed array that serves as the shared in-memory data cache. Collections hold entity data, notify subscribers on mutation, and provide query methods for read access.
+
+---
+
+## Role
+
+Collections are the single source of truth for entity data. Multiple ViewModels can subscribe to the same Collection and stay in sync without coordinating with each other. Services fetch data, ViewModels write it into Collections, and ViewModel getters derive views from it.
+
+```
+Service → ViewModel → Collection → (subscribers notified) → other ViewModels react
+```
+
+Collections are never accessed directly by components.
+
+---
+
+## Type Constraint
+
+Every item must have an `id` field of type `string | number`. This is enforced by the generic constraint:
+
+```typescript
+class Collection<T extends { id: string | number }>
+```
+
+The `id` is used for indexing (`get`, `has`) and targeted mutations (`update`, `remove`).
+
+---
+
+## Creating a Collection
+
+### Empty
+
+```typescript
+const collection = new Collection<Todo>();
+// collection.items → []
+// collection.length → 0
+```
+
+### With Initial Items
+
+```typescript
+const collection = new Collection<Todo>([
+  { id: '1', text: 'Buy milk', done: false },
+  { id: '2', text: 'Walk dog', done: true },
+]);
+// collection.length → 2
+```
+
+### As a Singleton (typical usage)
+
+Define a thin subclass for singleton identity:
+
+```typescript
+export class TodosCollection extends Collection<Todo> {}
+```
+
+Resolve inside ViewModels:
+
+```typescript
+private collection = singleton(TodosCollection);
+```
+
+The subclass gives the singleton registry a unique class key. Don't add methods — query logic belongs in ViewModel getters.
+
+---
+
+## Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `items` | `T[]` | The current frozen array of items |
+| `state` | `T[]` | Alias for `items` (Subscribable compatibility) |
+| `length` | `number` | Number of items |
+| `disposed` | `boolean` | Whether `dispose()` has been called |
+| `disposeSignal` | `AbortSignal` | Lazily created; aborted on `dispose()` |
+
+`items` is always a frozen array (`Object.freeze`). You cannot mutate it in place — use the CRUD methods below.
+
+---
+
+## CRUD Methods
+
+All CRUD methods notify subscribers when they produce an actual change. No-op mutations (removing an ID that doesn't exist, updating with identical values, clearing an already-empty collection) are silent.
+
+### add(...items)
+
+Appends one or more items. Items with IDs that already exist in the collection are silently skipped. Duplicate IDs within a single batch are also deduplicated (first occurrence wins). Notifies once.
+
+```typescript
+collection.add({ id: '1', text: 'First', done: false });
+collection.add(
+  { id: '2', text: 'Second', done: false },
+  { id: '3', text: 'Third', done: true },
+);
+
+// Duplicates are skipped — no error, no notification:
+collection.add({ id: '1', text: 'Duplicate', done: true }); // no-op
+```
+
+No-op when called with zero arguments or when all items already exist.
+
+### upsert(...items)
+
+Add-or-replace by ID. Existing items are replaced in-place (preserving array position); new items are appended. Deduplicates input — last occurrence wins. Single notification. No-op if nothing changed (reference comparison).
+
+```typescript
+// Add new items:
+collection.upsert({ id: '4', text: 'New', done: false });
+
+// Replace existing + add new in one call:
+collection.upsert(
+  { id: '1', text: 'Updated', done: true },   // replaces in position
+  { id: '5', text: 'Also new', done: false },  // appended
+);
+```
+
+This is the primary method for **paginated or incremental data loading** — each page of results can be upserted without destroying data from previous pages or other ViewModels:
+
+```typescript
+async loadPage(page: number) {
+  const data = await this.service.getPage(page, this.disposeSignal);
+  this.collection.upsert(...data);
+}
+```
+
+Unlike `update()` which does a partial merge, `upsert()` does a **full replacement** of the item object.
+
+No-op when called with zero arguments or when all items are reference-identical to existing ones.
+
+### remove(...ids)
+
+Removes items by ID. Accepts one or more IDs. Notifies once.
+
+```typescript
+collection.remove('1');
+collection.remove('2', '3');
+```
+
+No-op when called with zero arguments or when none of the IDs match.
+
+### update(id, changes)
+
+Applies a partial update to an existing item. Preserves the original `id` even if `changes` includes an `id` field. Notifies once.
+
+```typescript
+collection.update('1', { done: true });
+collection.update('1', { text: 'Updated', done: false });
+```
+
+No-op when:
+- The `id` is not found.
+- Every value in `changes` is identical to the current item (shallow equality check).
+
+### reset(items)
+
+Replaces the entire collection. Rebuilds the internal index. Always notifies (even if the new array has the same content).
+
+```typescript
+collection.reset([
+  { id: '4', text: 'Fresh start', done: false },
+]);
+```
+
+Use `reset()` for full replacement loads. For paginated or incremental loads, prefer `upsert()` which preserves existing data.
+
+### clear()
+
+Removes all items. Notifies once.
+
+```typescript
+collection.clear();
+```
+
+No-op when the collection is already empty.
+
+---
+
+## Query Methods
+
+Query methods are pure reads. They never notify subscribers.
+
+### get(id): T | undefined
+
+O(1) lookup by ID via internal index.
+
+```typescript
+const user = collection.get(2);
+```
+
+### has(id): boolean
+
+O(1) existence check.
+
+```typescript
+if (collection.has(userId)) { /* ... */ }
+```
+
+### find(predicate): T | undefined
+
+Returns the first item matching the predicate.
+
+```typescript
+const admin = collection.find(u => u.role === 'admin');
+```
+
+### filter(predicate): T[]
+
+Returns all items matching the predicate.
+
+```typescript
+const active = collection.filter(u => u.status === 'active');
+```
+
+### sorted(compareFn): T[]
+
+Returns a sorted copy. Does not modify the collection.
+
+```typescript
+const byAge = collection.sorted((a, b) => a.age - b.age);
+```
+
+### map(fn): U[]
+
+Transforms items into a new array.
+
+```typescript
+const names = collection.map(u => u.name);
+```
+
+---
+
+## Subscriptions
+
+Collection implements `Subscribable<T[]>`. Listeners receive `(currentItems, previousItems)` on every mutation.
+
+```typescript
+const unsubscribe = collection.subscribe((items, prev) => {
+  console.log(`Changed from ${prev.length} to ${items.length} items`);
+});
+
+// Later:
+unsubscribe();
+```
+
+In practice, ViewModels subscribe using `this.subscribeTo(collection, callback)` which auto-cleans up on dispose.
+
+Subscribing to a disposed collection returns a no-op unsubscribe function (does not throw).
+
+---
+
+## Optimistic Updates
+
+`optimistic(callback)` snapshots the current state, executes the callback (which should contain CRUD calls), and returns a rollback function. If the server call fails, call rollback to restore the pre-callback state.
+
+```typescript
+async toggleDone(id: string) {
+  const rollback = this.collection.optimistic(() => {
+    this.collection.update(id, { done: true });
+  });
+  try {
+    await this.service.update(id, { done: true }, this.disposeSignal);
+  } catch (e) {
+    if (!isAbortError(e)) rollback(); // guard needed — rollback affects shared Collection
+    throw e;
+  }
+}
+```
+
+### Behavior
+
+- **Mutations inside the callback apply immediately** and notify subscribers normally — the UI updates instantly.
+- **Snapshot is free** — `items` is always frozen, so the snapshot is a reference capture, not a deep clone.
+- **Rollback restores the exact pre-callback state** regardless of any mutations that happened after the callback (including additional `add`, `update`, `remove` calls).
+- **Rollback rebuilds the index** so `get()` and `has()` are consistent after restore.
+- **Rollback notifies subscribers** with `(restoredItems, preRollbackItems)`.
+- **Rollback is idempotent** — calling it multiple times is safe; only the first call has effect.
+- **Rollback is no-op when disposed** — safe to call in async cleanup after the collection is torn down.
+- **Nesting works** — each `optimistic()` call captures its own independent snapshot. Rolling back inner before outer restores to the intermediate state.
+
+### Nested Example
+
+```typescript
+const rollback1 = collection.optimistic(() => {
+  collection.update('1', { text: 'Outer' });
+});
+// collection.get('1').text → 'Outer'
+
+const rollback2 = collection.optimistic(() => {
+  collection.update('1', { text: 'Inner' });
+});
+// collection.get('1').text → 'Inner'
+
+rollback2();
+// collection.get('1').text → 'Outer'
+
+rollback1();
+// collection.get('1').text → 'First' (original)
+```
+
+---
+
+## Lifecycle
+
+### disposeSignal
+
+Lazily created `AbortSignal` that aborts when `dispose()` is called. If `disposeSignal` is never accessed, no `AbortController` is allocated (zero cost).
+
+```typescript
+const signal = collection.disposeSignal;
+// signal.aborted → false
+
+collection.dispose();
+// signal.aborted → true
+```
+
+The signal is aborted *before* `onDispose()` runs, so subclass cleanup can check it.
+
+### addCleanup(fn)
+
+Protected method for subclasses to register teardown callbacks. Cleanups fire on `dispose()` before `onDispose()`.
+
+```typescript
+class MyCollection extends Collection<Item> {
+  setup() {
+    const unsub = someExternalSource.subscribe(data => { /* ... */ });
+    this.addCleanup(unsub);
+  }
+}
+```
+
+### onDispose()
+
+Protected optional hook for subclass-specific teardown. Called once during the first `dispose()` call, after cleanups run and after the signal aborts.
+
+```typescript
+class MyCollection extends Collection<Item> {
+  protected onDispose(): void {
+    // custom teardown
+  }
+}
+```
+
+### dispose()
+
+Tears down the collection:
+
+1. Sets `disposed` to `true`
+2. Aborts the `AbortController` (if created)
+3. Runs all `addCleanup` callbacks
+4. Calls `onDispose()` (if defined)
+5. Clears all subscribers
+6. Clears the internal index
+
+Dispose is **idempotent** — calling it multiple times is safe. Only the first call has effect.
+
+All CRUD methods throw after dispose:
+
+```
+"Cannot add to disposed Collection"
+"Cannot upsert on disposed Collection"
+"Cannot remove from disposed Collection"
+"Cannot update disposed Collection"
+"Cannot reset disposed Collection"
+"Cannot clear disposed Collection"
+"Cannot perform optimistic update on disposed Collection"
+```
+
+---
+
+## Notification Semantics
+
+Listeners are called with `(currentItems, previousItems)`. Both are frozen arrays. This enables diffing when needed. ViewModel getters that read from a collection are auto-tracked — they recompute when the collection changes without explicit subscription wiring.
+
+### When Notifications Fire
+
+| Method | Notifies? |
+|---|---|
+| `add(...items)` | Yes, unless zero items, all duplicates, or all already exist |
+| `upsert(...items)` | Yes, unless zero items or all reference-identical |
+| `remove(...ids)` | Yes, unless zero IDs or no matches |
+| `update(id, changes)` | Yes, unless ID not found or values unchanged |
+| `reset(items)` | Always |
+| `clear()` | Yes, unless already empty |
+| `optimistic()` callback | Via the CRUD calls inside it |
+| Rollback function | Yes (once) |
+| `get`, `has`, `find`, `filter`, `sorted`, `map` | Never |
+
+---
+
+## Internal Index
+
+Collection maintains a `Map<id, T>` for O(1) `get()` and `has()` lookups. The index is rebuilt automatically on `reset()` and on `optimistic()` rollback. Individual `add`, `upsert`, `remove`, and `update` calls maintain the index incrementally.
+
+---
+
+## Eviction & TTL
+
+Collections can auto-evict items based on capacity limits and/or time-to-live. Both features are opt-in via static property overrides and have **zero overhead** when not configured — no timers, no timestamp maps, no extra work in CRUD methods.
+
+### Configuration
+
+Override static properties on your subclass (follows the Channel pattern for `RECONNECT_BASE`, etc.):
+
+```typescript
+class MessagesCollection extends Collection<Message> {
+  static MAX_SIZE = 500;   // FIFO eviction when exceeded
+  static TTL = 5 * 60_000; // 5 minutes
+}
+```
+
+| Static Property | Default | Description |
+|---|---|---|
+| `MAX_SIZE` | `0` | Maximum items before FIFO eviction. `0` = unlimited. |
+| `TTL` | `0` | Time-to-live in milliseconds. `0` = no expiry. |
+
+### Capacity Eviction (MAX_SIZE)
+
+When `add()`, `upsert()`, or `reset()` would push the collection over `MAX_SIZE`, excess items are evicted from the **front of the array** (FIFO — oldest first). Eviction happens synchronously before `Object.freeze()` and notification, so subscribers see a single change (add + eviction combined, not two separate events).
+
+```typescript
+class RecentLogs extends Collection<LogEntry> {
+  static MAX_SIZE = 1000;
+}
+
+const logs = singleton(RecentLogs);
+// Adding item 1001 evicts item 1 — single notification
+```
+
+### TTL (Time-to-Live)
+
+When `TTL > 0`, the collection tracks insertion timestamps and schedules a single `setTimeout` for the earliest expiry. When the timer fires, all expired items are swept and subscribers are notified.
+
+- `add()` and `upsert()` record timestamps. `upsert()` **refreshes** the timestamp (fresh data from server).
+- `update()` does **not** refresh the timestamp (partial merge, not a fresh item).
+- `remove()` and `clear()` clean up timestamps.
+- `reset()` clears all timestamps and records new ones.
+- `dispose()` cancels the timer.
+
+```typescript
+class NotificationsCollection extends Collection<Notification> {
+  static TTL = 10 * 60_000; // 10 minutes
+}
+```
+
+### onEvict Hook
+
+Override `onEvict` to control which items get evicted:
+
+```typescript
+class ActiveOrdersCollection extends Collection<Order> {
+  static MAX_SIZE = 200;
+
+  protected onEvict(items: Order[], reason: 'capacity' | 'ttl') {
+    // Keep in-progress orders, evict the rest
+    return items.filter(o => o.status !== 'in_progress');
+  }
+}
+```
+
+| Return Value | Effect |
+|---|---|
+| `void` / `undefined` | Proceed with all candidates |
+| `T[]` | Evict only the returned subset |
+| `false` | Veto eviction entirely |
+
+The `reason` parameter is `'capacity'` for `MAX_SIZE` eviction and `'ttl'` for expiry eviction, allowing different behavior for each.
+
+**DEV warning**: When `onEvict` vetoes capacity eviction and the collection exceeds 2x `MAX_SIZE`, a console warning is logged to flag potential unbounded growth.
+
+### Optimistic Rollback
+
+`optimistic()` snapshots timestamps alongside items. Rollback restores both, and the TTL timer is rescheduled.
+
+### Zero-Overhead Guarantee
+
+When `MAX_SIZE = 0` and `TTL = 0` (the defaults):
+- No `_timestamps` Map is allocated
+- No `setTimeout` is scheduled
+- CRUD methods execute the same code paths as before
+
+---
+
+## Best Practices
+
+**One Collection per entity type.** `UsersCollection`, `LocationsCollection`, `OrdersCollection`. Keep them thin.
+
+**Don't add methods to Collection subclasses.** Filtering and sorting belong in ViewModel getters. Collections are data stores, not query engines.
+
+**Always use `singleton()` for resolution.** Collections are shared across ViewModels. Creating a collection directly (`new UsersCollection()`) breaks the shared-cache guarantee.
+
+**Use `reset()` for initial loads, `upsert()` for paginated/incremental loads, and `add`/`update`/`remove` for granular mutations.**
+
+**Read collection data via getters, not `subscribeTo` + `set()`.** Auto-tracking handles reactivity when getters read from collection members. Use `subscribeTo()` only for imperative side effects.
+
+**Use `collection.optimistic()` for instant UI feedback.** Don't manually snapshot and restore — it's error-prone and verbose.
+
+**Check `collection.length > 0` in `onInit` before fetching.** Another ViewModel may have already loaded the data.
+
+```typescript
+get items(): Item[] {
+  return this.collection.items as Item[];
+}
+
+protected onInit() {
+  if (this.collection.length === 0) this.load();
+}
+```
+
+**Clean up singletons in tests.** Call `teardownAll()` in `beforeEach` to reset the singleton registry between test cases.
+
+> See `BEST_PRACTICES.md` for encapsulation patterns, optimistic update best practices, and Collection subscription conventions.
+
+---
+
+## Persistence
+
+For Collections that need to cache/repopulate from storage across sessions, extend `PersistentCollection<T>` instead. See `src/PersistentCollection.md` for the full API and adapter details.
+
+Available adapters:
+- **`WebStorageCollection`** (`mvc-kit/web`) — localStorage/sessionStorage, auto-hydrates
+- **`IndexedDBCollection`** (`mvc-kit/web`) — IndexedDB, per-item storage, requires `hydrate()`
+- **`NativeCollection`** (`mvc-kit/react-native`) — configurable async backend, requires `hydrate()`
+
+## Method Binding
+
+All public methods are auto-bound in the constructor. You can pass them point-free as callbacks without losing `this` context:
+
+```tsx
+const { add, upsert } = collection;
+channel.on("update", upsert); // point-free works
+```