mvc-kit 2.12.0 → 2.12.1

package/src/react-native/NativeCollection.ts

@@ -0,0 +1,138 @@
+import { PersistentCollection } from '../PersistentCollection';
+
+const __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;
+
+interface StorageAdapter {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+
+let _adapter: StorageAdapter | null = null;
+
+/**
+ * PersistentCollection for React Native, backed by any async key-value store.
+ * Uses blob strategy (full state as a single JSON string under `storageKey`).
+ *
+ * **Requires manual `hydrate()` call** (async storage).
+ *
+ * ## Setup (once at app startup)
+ *
+ * ```ts
+ * import { NativeCollection } from 'mvc-kit/react-native';
+ * import AsyncStorage from '@react-native-async-storage/async-storage';
+ *
+ * NativeCollection.configure({
+ *   getItem: (key) => AsyncStorage.getItem(key),
+ *   setItem: (key, value) => AsyncStorage.setItem(key, value),
+ *   removeItem: (key) => AsyncStorage.removeItem(key),
+ * });
+ * ```
+ *
+ * ## Usage
+ *
+ * ```ts
+ * class TodosCollection extends NativeCollection<Todo> {
+ *   protected readonly storageKey = 'todos';
+ * }
+ * ```
+ *
+ * ## Per-class override (edge cases)
+ *
+ * ```ts
+ * class SecureCollection extends NativeCollection<Secret> {
+ *   protected readonly storageKey = 'secrets';
+ *   protected async getItem(key: string) { return SecureStore.getItem(key); }
+ *   protected async setItem(key: string, value: string) { await SecureStore.setItem(key, value); }
+ *   protected async removeItem(key: string) { await SecureStore.removeItem(key); }
+ * }
+ * ```
+ */
+export abstract class NativeCollection<
+  T extends { id: string | number },
+> extends PersistentCollection<T> {
+  /**
+   * Configure the default storage adapter for all NativeCollection subclasses.
+   * Call once at app startup. Per-class method overrides take priority.
+   */
+  static configure(adapter: StorageAdapter): void {
+    _adapter = adapter;
+  }
+
+  /** Reset the configured adapter (for testing). */
+  static resetAdapter(): void {
+    _adapter = null;
+  }
+
+  // ── Per-class override points ──
+
+  /** Read a value from the storage adapter. Override for custom storage backends. @protected */
+  protected getItem(key: string): Promise<string | null> {
+    if (_adapter) return _adapter.getItem(key);
+    if (__DEV__) {
+      throw new Error(
+        `[mvc-kit] No storage adapter configured for "${this.constructor.name}". ` +
+          `Call NativeCollection.configure() at app startup, or override getItem/setItem/removeItem.`,
+      );
+    }
+    throw new Error('[mvc-kit] No storage adapter configured.');
+  }
+
+  /** Write a value to the storage adapter. Override for custom storage backends. @protected */
+  protected setItem(key: string, value: string): Promise<void> {
+    if (_adapter) return _adapter.setItem(key, value);
+    if (__DEV__) {
+      throw new Error(
+        `[mvc-kit] No storage adapter configured for "${this.constructor.name}". ` +
+          `Call NativeCollection.configure() at app startup, or override getItem/setItem/removeItem.`,
+      );
+    }
+    throw new Error('[mvc-kit] No storage adapter configured.');
+  }
+
+  /** Remove a value from the storage adapter. Override for custom storage backends. @protected */
+  protected removeItem(key: string): Promise<void> {
+    if (_adapter) return _adapter.removeItem(key);
+    if (__DEV__) {
+      throw new Error(
+        `[mvc-kit] No storage adapter configured for "${this.constructor.name}". ` +
+          `Call NativeCollection.configure() at app startup, or override getItem/setItem/removeItem.`,
+      );
+    }
+    throw new Error('[mvc-kit] No storage adapter configured.');
+  }
+
+  // ── Persist interface (blob strategy) ──
+
+  protected async persistGetAll(): Promise<T[]> {
+    const raw = await this.getItem(this.storageKey);
+    if (!raw) return [];
+    try {
+      return this.deserialize(raw);
+    } catch {
+      if (__DEV__) {
+        console.warn(
+          `[mvc-kit] Corrupted data in storage key "${this.storageKey}". Ignoring stored data.`,
+        );
+      }
+      return [];
+    }
+  }
+
+  protected async persistGet(id: T['id']): Promise<T | null> {
+    const all = await this.persistGetAll();
+    return all.find((i) => i.id === id) ?? null;
+  }
+
+  protected async persistSet(_items: T[]): Promise<void> {
+    await this.setItem(this.storageKey, this.serialize([...this.items]));
+  }
+
+  protected async persistRemove(_ids: T['id'][]): Promise<void> {
+    await this.setItem(this.storageKey, this.serialize([...this.items]));
+  }
+
+  protected async persistClear(): Promise<void> {
+    await this.removeItem(this.storageKey);
+  }
+}

package/src/react-native/index.ts

@@ -0,0 +1 @@
+export { NativeCollection } from './NativeCollection';

package/src/singleton.md

@@ -0,0 +1,310 @@
+# Singleton Registry
+
+A global registry that ensures exactly one living instance of a class exists at any time. Used to share Services, Collections, EventBuses, and Channels across ViewModels without manual wiring.
+
+---
+
+## API
+
+### singleton(Class, ...args)
+
+Returns the existing instance for `Class`, or creates one if none exists (or the previous one was disposed).
+
+```typescript
+const service = singleton(UserService);
+const collection = singleton(UsersCollection);
+```
+
+Constructor arguments are passed on first creation only. Subsequent calls return the cached instance and **ignore any arguments**:
+
+```typescript
+const vm1 = singleton(CounterViewModel, { count: 0 });
+vm1.increment(); // count is now 1
+
+const vm2 = singleton(CounterViewModel, { count: 100 }); // args ignored
+vm2 === vm1;              // true
+vm2.state.count === 1;    // true — same instance, same state
+```
+
+### Default State
+
+If a class defines `static DEFAULT_STATE`, `singleton()` uses it as the constructor argument when no args are passed. This eliminates repeated object literals at every call site:
+
+```typescript
+class CartViewModel extends ViewModel<CartState> {
+  static DEFAULT_STATE: CartState = { items: [] };
+
+  // ...methods
+}
+
+// No args needed — DEFAULT_STATE is used automatically
+const cart = singleton(CartViewModel);
+cart.state.items; // []
+```
+
+Explicit args override `DEFAULT_STATE`:
+
+```typescript
+const cart = singleton(CartViewModel, { items: [existingItem] }); // uses explicit arg
+```
+
+This is especially useful for singleton ViewModels (auth, cart, theme) where every consumer previously had to repeat the same initial state object.
+
+**Disposed instance replacement:** If the registered instance has been disposed (manually or via `teardown`), the next `singleton()` call creates a fresh instance:
+
+```typescript
+const vm1 = singleton(CounterViewModel, { count: 0 });
+vm1.dispose();
+
+const vm2 = singleton(CounterViewModel, { count: 0 });
+vm2 === vm1;           // false — new instance
+vm2.disposed === false; // true — fresh lifecycle
+```
+
+### hasSingleton(Class)
+
+Returns `true` if a non-disposed instance exists in the registry for `Class`.
+
+```typescript
+hasSingleton(UserService);              // false
+singleton(UserService);
+hasSingleton(UserService);              // true
+
+teardown(UserService);
+hasSingleton(UserService);              // false
+```
+
+Also returns `false` if the instance was manually disposed (without calling `teardown`):
+
+```typescript
+const svc = singleton(UserService);
+svc.dispose();
+hasSingleton(UserService);              // false
+```
+
+### teardown(Class)
+
+Disposes the singleton instance for `Class` and removes it from the registry. Safe to call when no instance exists — it's a no-op.
+
+```typescript
+const svc = singleton(UserService);
+teardown(UserService);
+
+svc.disposed === true;                  // true
+hasSingleton(UserService) === false;    // true
+```
+
+After `teardown`, the next `singleton()` call creates a fresh instance with a fresh `disposeSignal`:
+
+```typescript
+const vm1 = singleton(CounterViewModel, { count: 0 });
+const signal1 = vm1.disposeSignal;
+
+teardown(CounterViewModel);
+signal1.aborted === true;               // true — old signal aborted
+
+const vm2 = singleton(CounterViewModel, { count: 0 });
+vm2.disposeSignal.aborted === false;    // true — fresh signal
+vm2.disposeSignal !== signal1;          // true — different object
+```
+
+### teardownAll()
+
+Disposes every singleton in the registry and clears it. Safe to call on an empty registry.
+
+```typescript
+const svc = singleton(UserService);
+const col = singleton(UsersCollection);
+
+teardownAll();
+
+svc.disposed === true;    // true
+col.disposed === true;    // true
+```
+
+Primary use case is test cleanup:
+
+```typescript
+beforeEach(() => {
+  teardownAll();
+});
+```
+
+---
+
+## How It Works
+
+The registry is a module-level `Map<Class, Instance>`. The class constructor itself is the key — each distinct class maps to at most one instance.
+
+```
+singleton(UserService) → registry.get(UserService)
+  → exists and not disposed? return it
+  → otherwise: new UserService(), store in registry, return it
+```
+
+Key behaviors:
+
+- **Class identity is the key.** Two different classes that extend `Service` are separate entries. Subclasses are distinct from parents.
+- **Disposed instances are treated as absent.** `singleton()` and `hasSingleton()` both check `instance.disposed` before returning or reporting.
+- **Arguments are first-call-only.** The registry stores the instance, not the arguments. On cache hit, arguments are ignored entirely.
+- **Any `Disposable` works.** The registry accepts any class whose instances implement the `Disposable` interface (`disposed`, `disposeSignal`, `dispose()`). This includes ViewModel, Service, Collection, EventBus, Channel, Controller, and Model.
+
+---
+
+## Which Classes Are Singletons
+
+| Class | Singleton? | Why |
+|---|---|---|
+| Service | Yes | Stateless infrastructure — one instance is sufficient |
+| Collection | Yes | Shared data cache — must be the same instance across ViewModels |
+| EventBus (app-level) | Yes | App-wide event dispatch |
+| Channel | Yes | Persistent connection shared across ViewModels |
+| ViewModel | Rarely | Component-scoped by default; singleton only for app-wide state (auth, theme, cart) |
+| Controller | No | Workflow-scoped, tied to a component lifecycle |
+| Model | No | Form-scoped, tied to a specific edit session |
+
+---
+
+## Usage Patterns
+
+### Property Initializer (Recommended)
+
+Resolve singletons as private fields in ViewModel property initializers. This is the standard pattern:
+
+```typescript
+class LocationsViewModel extends ViewModel<State> {
+  private service = singleton(LocationService);
+  private collection = singleton(LocationsCollection);
+  private bus = singleton(AppEventBus);
+
+  protected onInit() {
+    this.subscribeTo(this.collection, () => {
+      this.set({ items: this.collection.items });
+    });
+  }
+}
+```
+
+Every ViewModel that calls `singleton(LocationsCollection)` gets the same instance. When one ViewModel writes data into the collection, all subscribers see the change.
+
+### Pre-Populating in Tests
+
+In tests, call `singleton()` before constructing the ViewModel to pre-populate shared state:
+
+```typescript
+beforeEach(() => teardownAll());
+
+test('filtered getter applies search', () => {
+  const collection = singleton(UsersCollection);
+  collection.reset([
+    { id: '1', firstName: 'Alice', status: 'on_duty' },
+    { id: '2', firstName: 'Bob', status: 'off_duty' },
+  ]);
+
+  const vm = new UsersViewModel({ items: [], search: '' });
+  vm.init();
+
+  // onInit subscribes to the same collection instance
+  expect(vm.state.items).toHaveLength(2);
+
+  vm.dispose();
+});
+```
+
+The ViewModel's `singleton(UsersCollection)` call returns the same instance the test already populated.
+
+### Shared Data via Collection Singletons
+
+Multiple ViewModels stay in sync through a shared collection without knowing about each other:
+
+```typescript
+// UsersViewModel fetches and writes
+async load() {
+  const data = await this.service.getAll(this.disposeSignal);
+  this.collection.reset(data);  // triggers all subscribers
+}
+
+// OnDutyViewModel reads from the same collection
+protected onInit() {
+  this.subscribeTo(this.collection, () => {
+    this.set({ items: this.collection.items });
+  });
+}
+```
+
+Both ViewModels call `singleton(UsersCollection)` and get the same instance. When `UsersViewModel` calls `collection.reset()`, `OnDutyViewModel`'s subscription fires automatically.
+
+---
+
+## Test Cleanup
+
+Always call `teardownAll()` in `beforeEach` to ensure test isolation:
+
+```typescript
+import { singleton, teardownAll } from 'mvc-kit';
+
+beforeEach(() => {
+  teardownAll();
+});
+```
+
+Without this, a singleton created in one test leaks into the next — causing shared state, stale subscriptions, and flaky tests.
+
+Use `teardown(Class)` when you need to reset a single singleton mid-test without affecting others:
+
+```typescript
+test('re-creation after teardown', () => {
+  const svc = singleton(UserService);
+  // ...use service...
+
+  teardown(UserService);
+  // UserService is disposed, but UsersCollection is untouched
+
+  const freshSvc = singleton(UserService);
+  // freshSvc is a new instance with a fresh disposeSignal
+});
+```
+
+---
+
+## Best Practices
+
+**Use property initializers, not `onInit`.** Resolve singletons as class fields so they're available immediately — don't wait for `onInit()`:
+
+```typescript
+// Good: available as soon as the ViewModel is constructed
+private service = singleton(LocationService);
+
+// Unnecessary: delays resolution to init time
+protected onInit() {
+  this.service = singleton(LocationService);
+}
+```
+
+**Don't pass singleton instances as constructor arguments.** Let each class resolve its own dependencies via `singleton()`. This keeps dependencies explicit and avoids manual wiring:
+
+```typescript
+// Bad: manual wiring
+const svc = singleton(UserService);
+const vm = new UsersViewModel(svc, { items: [] });
+
+// Good: ViewModel resolves its own dependencies
+const vm = new UsersViewModel({ items: [] });
+// internally: private service = singleton(UserService);
+```
+
+**Always `teardownAll()` in tests.** A leaked singleton is the most common cause of flaky tests in mvc-kit applications.
+
+**Define `static DEFAULT_STATE` on singleton ViewModels.** When a ViewModel is used as a singleton, declare the initial state once on the class instead of repeating it at every `singleton()` and `useSingleton()` call site:
+
+```typescript
+class AuthViewModel extends ViewModel<AuthState> {
+  static DEFAULT_STATE: AuthState = { user: null, isAuthenticated: false };
+}
+
+// Consumers call without args:
+private auth = singleton(AuthViewModel);
+const [state, vm] = useSingleton(AuthViewModel);
+```
+
+**Don't store derived or temporary objects as singletons.** Singletons are for long-lived shared infrastructure. If an object is scoped to a component or workflow, use `useLocal` or direct construction instead.

package/src/singleton.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ViewModel } from './ViewModel';
+import { singleton, hasSingleton, teardown, teardownAll } from './singleton';
+
+interface CountState {
+  count: number;
+}
+
+class CounterViewModel extends ViewModel<CountState> {
+  increment() {
+    this.set({ count: this.state.count + 1 });
+  }
+}
+
+class AnotherViewModel extends ViewModel<CountState> {
+  decrement() {
+    this.set({ count: this.state.count - 1 });
+  }
+}
+
+describe('singleton', () => {
+  beforeEach(() => {
+    teardownAll();
+  });
+
+  describe('singleton()', () => {
+    it('creates instance on first call', () => {
+      const vm = singleton(CounterViewModel, { count: 0 });
+      expect(vm).toBeInstanceOf(CounterViewModel);
+      expect(vm.state.count).toBe(0);
+    });
+
+    it('returns same instance on subsequent calls', () => {
+      const vm1 = singleton(CounterViewModel, { count: 0 });
+      vm1.increment();
+
+      const vm2 = singleton(CounterViewModel, { count: 100 }); // Args ignored
+      expect(vm2).toBe(vm1);
+      expect(vm2.state.count).toBe(1); // Keeps state from first instance
+    });
+
+    it('creates new instance if previous disposed', () => {
+      const vm1 = singleton(CounterViewModel, { count: 0 });
+      vm1.increment();
+      vm1.dispose();
+
+      const vm2 = singleton(CounterViewModel, { count: 0 });
+      expect(vm2).not.toBe(vm1);
+      expect(vm2.state.count).toBe(0);
+      expect(vm2.disposed).toBe(false);
+    });
+
+    it('maintains separate singletons per class', () => {
+      const counter = singleton(CounterViewModel, { count: 10 });
+      const another = singleton(AnotherViewModel, { count: 20 });
+
+      expect(counter).not.toBe(another);
+      expect(counter.state.count).toBe(10);
+      expect(another.state.count).toBe(20);
+    });
+  });
+
+  describe('hasSingleton()', () => {
+    it('returns false when no singleton exists', () => {
+      expect(hasSingleton(CounterViewModel)).toBe(false);
+    });
+
+    it('returns true when singleton exists', () => {
+      singleton(CounterViewModel, { count: 0 });
+      expect(hasSingleton(CounterViewModel)).toBe(true);
+    });
+
+    it('returns false after singleton is disposed', () => {
+      const vm = singleton(CounterViewModel, { count: 0 });
+      expect(hasSingleton(CounterViewModel)).toBe(true);
+      vm.dispose();
+      expect(hasSingleton(CounterViewModel)).toBe(false);
+    });
+
+    it('returns false after teardown', () => {
+      singleton(CounterViewModel, { count: 0 });
+      expect(hasSingleton(CounterViewModel)).toBe(true);
+      teardown(CounterViewModel);
+      expect(hasSingleton(CounterViewModel)).toBe(false);
+    });
+  });
+
+  describe('teardown()', () => {
+    it('disposes and removes from registry', () => {
+      const vm1 = singleton(CounterViewModel, { count: 0 });
+      vm1.increment();
+
+      teardown(CounterViewModel);
+
+      expect(vm1.disposed).toBe(true);
+
+      const vm2 = singleton(CounterViewModel, { count: 0 });
+      expect(vm2).not.toBe(vm1);
+    });
+
+    it('handles teardown of non-existent singleton', () => {
+      // Should not throw
+      expect(() => teardown(CounterViewModel)).not.toThrow();
+    });
+  });
+
+  describe('teardownAll()', () => {
+    it('disposes all singletons', () => {
+      const counter = singleton(CounterViewModel, { count: 0 });
+      const another = singleton(AnotherViewModel, { count: 0 });
+
+      teardownAll();
+
+      expect(counter.disposed).toBe(true);
+      expect(another.disposed).toBe(true);
+    });
+
+    it('clears registry allowing new instances', () => {
+      const vm1 = singleton(CounterViewModel, { count: 5 });
+      teardownAll();
+
+      const vm2 = singleton(CounterViewModel, { count: 10 });
+      expect(vm2).not.toBe(vm1);
+      expect(vm2.state.count).toBe(10);
+    });
+
+    it('handles empty registry', () => {
+      expect(() => teardownAll()).not.toThrow();
+    });
+  });
+
+  describe('DEFAULT_STATE', () => {
+    class DefaultCounterVM extends ViewModel<CountState> {
+      static DEFAULT_STATE: CountState = { count: 42 };
+
+      increment() {
+        this.set({ count: this.state.count + 1 });
+      }
+    }
+
+    it('uses DEFAULT_STATE when no args passed', () => {
+      const vm = singleton(DefaultCounterVM);
+      expect(vm).toBeInstanceOf(DefaultCounterVM);
+      expect(vm.state.count).toBe(42);
+    });
+
+    it('returns cached instance on subsequent no-arg calls', () => {
+      const vm1 = singleton(DefaultCounterVM);
+      vm1.increment();
+
+      const vm2 = singleton(DefaultCounterVM);
+      expect(vm2).toBe(vm1);
+      expect(vm2.state.count).toBe(43);
+    });
+
+    it('explicit args override DEFAULT_STATE on first creation', () => {
+      const vm = singleton(DefaultCounterVM, { count: 99 });
+      expect(vm.state.count).toBe(99);
+    });
+
+    it('re-creates with DEFAULT_STATE after teardown', () => {
+      const vm1 = singleton(DefaultCounterVM);
+      vm1.increment();
+      teardown(DefaultCounterVM);
+
+      const vm2 = singleton(DefaultCounterVM);
+      expect(vm2).not.toBe(vm1);
+      expect(vm2.state.count).toBe(42);
+    });
+
+    it('re-creates with DEFAULT_STATE after dispose', () => {
+      const vm1 = singleton(DefaultCounterVM);
+      vm1.increment();
+      vm1.dispose();
+
+      const vm2 = singleton(DefaultCounterVM);
+      expect(vm2).not.toBe(vm1);
+      expect(vm2.state.count).toBe(42);
+    });
+
+    it('DEFAULT_STATE object is not mutated by instance operations', () => {
+      const original = { ...DefaultCounterVM.DEFAULT_STATE };
+      const vm = singleton(DefaultCounterVM);
+      vm.increment();
+      vm.increment();
+
+      expect(DefaultCounterVM.DEFAULT_STATE).toEqual(original);
+    });
+  });
+
+  describe('signal lifecycle', () => {
+    it('re-created singleton after teardown has fresh un-aborted signal', () => {
+      const vm1 = singleton(CounterViewModel, { count: 0 });
+      const signal1 = vm1.disposeSignal;
+      teardown(CounterViewModel);
+      expect(signal1.aborted).toBe(true);
+
+      const vm2 = singleton(CounterViewModel, { count: 0 });
+      expect(vm2).not.toBe(vm1);
+      expect(vm2.disposeSignal.aborted).toBe(false);
+      expect(vm2.disposeSignal).not.toBe(signal1);
+    });
+  });
+});