mvc-kit 2.12.0 → 2.12.2

package/src/Resource.ts

@@ -0,0 +1,231 @@
+import { Collection } from './Collection';
+import { walkPrototypeChain } from './walkPrototypeChain';
+import { wrapAsyncMethods } from './wrapAsyncMethods';
+import type { InternalTaskState } from './wrapAsyncMethods';
+import type { Listener, TaskState } from './types';
+
+const __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;
+
+// ── Async tracking types ────────────────────────────────────────
+
+const DEFAULT_TASK_STATE: TaskState = Object.freeze({ loading: false, error: null, errorCode: null });
+
+export type ResourceAsyncMethodKeys<T> = {
+  [K in Exclude<keyof T, keyof Resource<any>>]: T[K] extends (...args: any[]) => Promise<any> ? K : never;
+}[Exclude<keyof T, keyof Resource<any>>];
+
+type ResourceAsyncMap<T> = {
+  readonly [K in ResourceAsyncMethodKeys<T>]: TaskState;
+};
+
+const RESERVED_ASYNC_KEYS = ['async', 'subscribeAsync'] as const;
+const LIFECYCLE_HOOKS = new Set(['onInit', 'onDispose']);
+
+// ── Resource ────────────────────────────────────────────────────
+
+/**
+ * Collection + async tracking toolkit. Extends Collection with lifecycle
+ * (init/dispose) and automatic async method tracking. Optionally delegates
+ * to an external Collection for shared data scenarios.
+ */
+export class Resource<T extends { id: string | number }> extends Collection<T> {
+  private _external: Collection<T> | null = null;
+  private _initialized = false;
+
+  // ── Async tracking fields ──
+  private _asyncStates = new Map<string, InternalTaskState>();
+  private _asyncSnapshots = new Map<string, TaskState>();
+  private _asyncListeners = new Set<() => void>();
+  private _asyncProxy: ResourceAsyncMap<this> | null = null;
+  private _activeOps: Map<string, number> | null = null;
+
+  /** DEV-only timeout (ms) for detecting ghost async operations after dispose. */
+  static GHOST_TIMEOUT = 3000;
+
+  constructor(collectionOrItems?: Collection<T> | T[]) {
+    const isExternal = collectionOrItems != null && !Array.isArray(collectionOrItems);
+    super(isExternal ? [] : (collectionOrItems as T[]) ?? []);
+
+    if (isExternal) {
+      this._external = collectionOrItems as Collection<T>;
+
+      if (__DEV__) {
+        const Ctor = this.constructor as typeof Resource;
+        if (Ctor.MAX_SIZE > 0 || Ctor.TTL > 0) {
+          console.warn(
+            `[mvc-kit] Resource "${Ctor.name}" has MAX_SIZE or TTL set but uses an ` +
+            `injected Collection. Configure these on the Collection instead.`
+          );
+        }
+      }
+    }
+
+    this._guardReservedKeys();
+  }
+
+  // ── Lifecycle ─────────────────────────────────────────────────
+
+  /** Whether init() has been called. */
+  get initialized(): boolean {
+    return this._initialized;
+  }
+
+  /** Initializes the instance. Called automatically by React hooks after mount. */
+  init(): void | Promise<void> {
+    if (this._initialized || this.disposed) return;
+    this._initialized = true;
+
+    if (__DEV__) {
+      this._activeOps = new Map();
+    }
+
+    wrapAsyncMethods({
+      instance: this,
+      stopPrototype: Resource.prototype,
+      reservedKeys: RESERVED_ASYNC_KEYS,
+      lifecycleHooks: LIFECYCLE_HOOKS,
+      isDisposed: () => this.disposed,
+      isInitialized: () => this._initialized,
+      asyncStates: this._asyncStates,
+      asyncSnapshots: this._asyncSnapshots,
+      asyncListeners: this._asyncListeners,
+      notifyAsync: () => this._notifyAsync(),
+      addCleanup: (fn) => this.addCleanup(fn),
+      ghostTimeout: (this.constructor as typeof Resource).GHOST_TIMEOUT,
+      className: 'Resource',
+      activeOps: this._activeOps,
+    });
+
+    return this.onInit?.();
+  }
+
+  /** Lifecycle hook called at the end of init(). Override to load initial data. @protected */
+  protected onInit?(): void | Promise<void>;
+
+  // ── Collection delegation ─────────────────────────────────────
+
+  /** Current items array. Delegates to external Collection when injected. */
+  get state(): T[] {
+    return this._external ? this._external.state : super.state;
+  }
+
+  /** The raw array of items. Delegates to external Collection when injected. */
+  get items(): T[] {
+    return this._external ? this._external.items : super.items;
+  }
+
+  /** Number of items. Delegates to external Collection when injected. */
+  get length(): number {
+    return this._external ? this._external.length : super.length;
+  }
+
+  add(...items: T[]): void {
+    this._external ? this._external.add(...items) : super.add(...items);
+  }
+
+  upsert(...items: T[]): void {
+    this._external ? this._external.upsert(...items) : super.upsert(...items);
+  }
+
+  update(id: T['id'], changes: Partial<T>): void {
+    this._external ? this._external.update(id, changes) : super.update(id, changes);
+  }
+
+  remove(...ids: T['id'][]): void {
+    this._external ? this._external.remove(...ids) : super.remove(...ids);
+  }
+
+  reset(items: T[]): void {
+    this._external ? this._external.reset(items) : super.reset(items);
+  }
+
+  clear(): void {
+    this._external ? this._external.clear() : super.clear();
+  }
+
+  optimistic(callback: () => void): () => void {
+    return this._external ? this._external.optimistic(callback) : super.optimistic(callback);
+  }
+
+  get(id: T['id']): T | undefined {
+    return this._external ? this._external.get(id) : super.get(id);
+  }
+
+  has(id: T['id']): boolean {
+    return this._external ? this._external.has(id) : super.has(id);
+  }
+
+  find(predicate: (item: T) => boolean): T | undefined {
+    return this._external ? this._external.find(predicate) : super.find(predicate);
+  }
+
+  filter(predicate: (item: T) => boolean): T[] {
+    return this._external ? this._external.filter(predicate) : super.filter(predicate);
+  }
+
+  sorted(compareFn: (a: T, b: T) => number): T[] {
+    return this._external ? this._external.sorted(compareFn) : super.sorted(compareFn);
+  }
+
+  map<U>(fn: (item: T) => U): U[] {
+    return this._external ? this._external.map(fn) : super.map(fn);
+  }
+
+  subscribe(listener: Listener<T[]>): () => void {
+    if (this.disposed) return () => {};
+    return this._external ? this._external.subscribe(listener) : super.subscribe(listener);
+  }
+
+  // ── Async tracking API ────────────────────────────────────────
+
+  /** Proxy providing `TaskState` (loading, error, errorCode) per async method. */
+  get async(): ResourceAsyncMap<this> {
+    if (!this._asyncProxy) {
+      const self = this;
+      this._asyncProxy = new Proxy({} as ResourceAsyncMap<this>, {
+        get(_, prop: string) {
+          return self._asyncSnapshots.get(prop) ?? DEFAULT_TASK_STATE;
+        },
+        has(_, prop: string) {
+          return self._asyncSnapshots.has(prop);
+        },
+        ownKeys() {
+          return Array.from(self._asyncSnapshots.keys());
+        },
+        getOwnPropertyDescriptor(_, prop: string) {
+          if (self._asyncSnapshots.has(prop)) {
+            return { configurable: true, enumerable: true, value: self._asyncSnapshots.get(prop) };
+          }
+          return undefined;
+        },
+      });
+    }
+    return this._asyncProxy;
+  }
+
+  /** Subscribes to async state changes. Used by `useInstance` for React integration. */
+  subscribeAsync(listener: () => void): () => void {
+    if (this.disposed) return () => {};
+    this._asyncListeners.add(listener);
+    return () => { this._asyncListeners.delete(listener); };
+  }
+
+  // ── Private: async tracking internals ─────────────────────────
+
+  private _notifyAsync(): void {
+    for (const listener of this._asyncListeners) {
+      listener();
+    }
+  }
+
+  private _guardReservedKeys(): void {
+    walkPrototypeChain(this, Resource.prototype, (key) => {
+      if (RESERVED_ASYNC_KEYS.includes(key as any)) {
+        throw new Error(
+          `[mvc-kit] "${key}" is a reserved property on Resource and cannot be overridden.`
+        );
+      }
+    });
+  }
+
+}

package/src/Selection.md

@@ -0,0 +1,155 @@
+# Selection
+
+Key-based selection state manager. Tracks a set of selected keys with toggle, select-all, and filter semantics. Extends [`Trackable`](./Trackable.md) — subscribable, disposable, and auto-bound.
+
+---
+
+## When to Use
+
+Use Selection as a ViewModel property to manage row/item selection in tables and lists. Auto-tracking ensures ViewModel getters that read from Selection auto-invalidate when selection changes.
+
+---
+
+## Creating a Selection Instance
+
+```typescript
+import { Selection } from 'mvc-kit';
+
+// String keys (default)
+readonly selection = new Selection<string>();
+
+// Numeric keys
+readonly selection = new Selection<number>();
+```
+
+---
+
+## API
+
+### Readable State
+
+#### `selected: ReadonlySet<K>`
+
+The set of selected keys. Returns a new Set reference on each change (safe for React rendering).
+
+#### `count: number`
+
+Number of selected keys.
+
+#### `hasSelection: boolean`
+
+Whether any keys are selected.
+
+### Query
+
+#### `isSelected(key: K): boolean`
+
+Whether the given key is selected.
+
+### Actions
+
+#### `toggle(key: K): void`
+
+Toggle a key in/out of the selection.
+
+#### `select(...keys: K[]): void`
+
+Add keys to the selection. No-op (no notification) if all keys already selected.
+
+#### `deselect(...keys: K[]): void`
+
+Remove keys from the selection. No-op (no notification) if none were selected.
+
+#### `toggleAll(allKeys: K[]): void`
+
+If all `allKeys` are selected, deselect all. Otherwise, select all. Empty `allKeys` array is a no-op.
+
+#### `set(...keys: K[]): void`
+
+Replace the entire selection atomically. Single notification. No-op if the new keys are identical to the current selection.
+
+```typescript
+// Replace selection with specific keys
+vm.selection.set('a', 'c');
+
+// Clear via set (equivalent to clear())
+vm.selection.set();
+```
+
+#### `clear(): void`
+
+Remove all selections. No-op if already empty.
+
+### Utility
+
+#### `selectedFrom<T>(items: T[], keyOf: (item: T) => K): T[]`
+
+Filter items to only those whose key is in the selection.
+
+```typescript
+const selectedUsers = vm.selection.selectedFrom(users, u => u.id);
+```
+
+### Subscribable Interface
+
+#### `subscribe(cb: () => void): () => void`
+
+Subscribe to state changes. Returns an unsubscribe function.
+
+---
+
+## ViewModel Integration
+
+```typescript
+class UsersVM extends ViewModel<FilterState> {
+  readonly selection = new Selection<string>();
+  private users = singleton(UsersResource);
+
+  get selectedUsers(): User[] {
+    return this.selection.selectedFrom(this.users.items, u => u.id);
+  }
+
+  async deleteSelected() {
+    const ids = [...this.selection.selected];
+    await this.usersService.deleteMany(ids, this.disposeSignal);
+    this.selection.clear();
+  }
+}
+```
+
+---
+
+## React Usage
+
+Pass the Selection helper directly to DataTable — it duck-types the interface and handles `toggleAll(allKeys)` automatically:
+
+```tsx
+<DataTable
+  items={vm.items}
+  columns={columns}
+  selection={vm.selection}
+/>
+```
+
+Or use the object-literal form for custom usage:
+
+```tsx
+<DataTable
+  items={vm.items}
+  columns={columns}
+  selection={{
+    selected: vm.selection.selected,
+    onToggle: id => vm.selection.toggle(id),
+    onToggleAll: allKeys => vm.selection.toggleAll(allKeys),
+  }}
+/>
+```
+
+## 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 { toggle, clear } = selection;
+<Checkbox onChange={toggle} /> // point-free works
+```

package/src/Selection.test.ts

@@ -0,0 +1,326 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Selection } from './Selection';
+import { ViewModel } from './ViewModel';
+
+describe('Selection', () => {
+  describe('initial state', () => {
+    it('starts empty', () => {
+      const s = new Selection();
+      expect(s.count).toBe(0);
+      expect(s.hasSelection).toBe(false);
+      expect(s.selected.size).toBe(0);
+    });
+  });
+
+  describe('toggle', () => {
+    it('toggles selection on', () => {
+      const s = new Selection<string>();
+      s.toggle('a');
+      expect(s.isSelected('a')).toBe(true);
+      expect(s.count).toBe(1);
+    });
+
+    it('toggles selection off', () => {
+      const s = new Selection<string>();
+      s.toggle('a');
+      s.toggle('a');
+      expect(s.isSelected('a')).toBe(false);
+      expect(s.count).toBe(0);
+    });
+  });
+
+  describe('select / deselect', () => {
+    it('select adds keys', () => {
+      const s = new Selection<string>();
+      s.select('a', 'b', 'c');
+      expect(s.count).toBe(3);
+      expect(s.isSelected('a')).toBe(true);
+      expect(s.isSelected('b')).toBe(true);
+      expect(s.isSelected('c')).toBe(true);
+    });
+
+    it('select does not notify if keys already selected', () => {
+      const s = new Selection<string>();
+      s.select('a');
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.select('a');
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('deselect removes keys', () => {
+      const s = new Selection<string>();
+      s.select('a', 'b', 'c');
+      s.deselect('b');
+      expect(s.count).toBe(2);
+      expect(s.isSelected('b')).toBe(false);
+    });
+
+    it('deselect does not notify if keys not selected', () => {
+      const s = new Selection<string>();
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.deselect('x');
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('toggleAll', () => {
+    it('selects all when none selected', () => {
+      const s = new Selection<string>();
+      s.toggleAll(['a', 'b', 'c']);
+      expect(s.count).toBe(3);
+    });
+
+    it('selects all when partially selected', () => {
+      const s = new Selection<string>();
+      s.select('a');
+      s.toggleAll(['a', 'b', 'c']);
+      expect(s.count).toBe(3);
+    });
+
+    it('deselects all when all selected', () => {
+      const s = new Selection<string>();
+      s.select('a', 'b', 'c');
+      s.toggleAll(['a', 'b', 'c']);
+      expect(s.count).toBe(0);
+    });
+
+    it('handles empty allKeys', () => {
+      const s = new Selection<string>();
+      s.select('a');
+      s.toggleAll([]);
+      // Empty list: allKeys.every() is vacuously true with no items,
+      // but length check prevents deselecting
+      expect(s.count).toBe(1);
+    });
+  });
+
+  describe('set', () => {
+    it('replaces entire selection atomically', () => {
+      const s = new Selection<string>();
+      s.select('a', 'b');
+      s.set('c', 'd');
+      expect(s.count).toBe(2);
+      expect(s.isSelected('a')).toBe(false);
+      expect(s.isSelected('b')).toBe(false);
+      expect(s.isSelected('c')).toBe(true);
+      expect(s.isSelected('d')).toBe(true);
+    });
+
+    it('fires single notification', () => {
+      const s = new Selection<string>();
+      s.select('a', 'b');
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.set('c', 'd');
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('no-op when keys are identical', () => {
+      const s = new Selection<string>();
+      s.select('a', 'b');
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.set('a', 'b');
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('can set to empty (like clear)', () => {
+      const s = new Selection<string>();
+      s.select('a', 'b');
+      s.set();
+      expect(s.count).toBe(0);
+      expect(s.hasSelection).toBe(false);
+    });
+
+    it('updates selected reference', () => {
+      const s = new Selection<string>();
+      s.select('a');
+      const ref1 = s.selected;
+      s.set('b');
+      const ref2 = s.selected;
+      expect(ref1).not.toBe(ref2);
+    });
+
+    it('detects change when size differs', () => {
+      const s = new Selection<string>();
+      s.select('a');
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.set('a', 'b');
+      expect(listener).toHaveBeenCalledTimes(1);
+      expect(s.count).toBe(2);
+    });
+  });
+
+  describe('clear', () => {
+    it('clears all selections', () => {
+      const s = new Selection<string>();
+      s.select('a', 'b');
+      s.clear();
+      expect(s.count).toBe(0);
+      expect(s.hasSelection).toBe(false);
+    });
+
+    it('does not notify if already empty', () => {
+      const s = new Selection<string>();
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.clear();
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('selectedFrom', () => {
+    it('filters items by selected keys', () => {
+      const s = new Selection<string>();
+      const items = [
+        { id: 'a', name: 'Alice' },
+        { id: 'b', name: 'Bob' },
+        { id: 'c', name: 'Charlie' },
+      ];
+      s.select('a', 'c');
+      const result = s.selectedFrom(items, item => item.id);
+      expect(result).toEqual([
+        { id: 'a', name: 'Alice' },
+        { id: 'c', name: 'Charlie' },
+      ]);
+    });
+  });
+
+  describe('numeric keys', () => {
+    it('works with number keys', () => {
+      const s = new Selection<number>();
+      s.select(1, 2, 3);
+      expect(s.isSelected(1)).toBe(true);
+      s.toggle(2);
+      expect(s.isSelected(2)).toBe(false);
+      expect(s.count).toBe(2);
+    });
+  });
+
+  describe('subscribe notifications', () => {
+    it('notifies on toggle', () => {
+      const s = new Selection<string>();
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.toggle('a');
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on select', () => {
+      const s = new Selection<string>();
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.select('a', 'b');
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on deselect', () => {
+      const s = new Selection<string>();
+      s.select('a');
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.deselect('a');
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on toggleAll', () => {
+      const s = new Selection<string>();
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.toggleAll(['a', 'b']);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on set', () => {
+      const s = new Selection<string>();
+      s.select('a');
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.set('b', 'c');
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('notifies on clear', () => {
+      const s = new Selection<string>();
+      s.select('a');
+      const listener = vi.fn();
+      s.subscribe(listener);
+      s.clear();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('unsubscribe stops notifications', () => {
+      const s = new Selection<string>();
+      const listener = vi.fn();
+      const unsub = s.subscribe(listener);
+      unsub();
+      s.toggle('a');
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('selected returns new reference on change', () => {
+    it('reference changes on mutation', () => {
+      const s = new Selection<string>();
+      s.toggle('a');
+      const ref1 = s.selected;
+      s.toggle('b');
+      const ref2 = s.selected;
+      expect(ref1).not.toBe(ref2);
+    });
+  });
+
+  describe('auto-tracking integration', () => {
+    it('ViewModel getter invalidates when selection changes', () => {
+      let computeCount = 0;
+
+      class TestVM extends ViewModel {
+        readonly selection = new Selection<string>();
+        private _items = [
+          { id: 'a', name: 'Alice' },
+          { id: 'b', name: 'Bob' },
+        ];
+
+        get selectedItems() {
+          computeCount++;
+          return this.selection.selectedFrom(this._items, i => i.id);
+        }
+      }
+
+      const vm = new TestVM();
+      vm.init();
+
+      expect(vm.selectedItems).toEqual([]);
+      expect(computeCount).toBe(1);
+
+      // Cached
+      vm.selectedItems;
+      expect(computeCount).toBe(1);
+
+      // Change selection — getter should recompute
+      vm.selection.select('a');
+      expect(vm.selectedItems).toEqual([{ id: 'a', name: 'Alice' }]);
+      expect(computeCount).toBe(2);
+
+      vm.dispose();
+    });
+  });
+
+  describe('method binding', () => {
+    it('destructured methods work point-free', () => {
+      const selection = new Selection<string>();
+      const { toggle, select, deselect, clear, isSelected } = selection;
+      toggle('a');
+      expect(isSelected('a')).toBe(true);
+      select('b', 'c');
+      expect(selection.count).toBe(3);
+      deselect('b');
+      expect(selection.count).toBe(2);
+      clear();
+      expect(selection.count).toBe(0);
+    });
+  });
+});