mvc-kit 2.12.0 → 2.12.2

package/src/Model.md

@@ -0,0 +1,524 @@
+# Model
+
+Reactive entity with field-level validation, dirty tracking, and commit/rollback semantics. Use `Model` for create and edit forms where you need to know which fields are invalid, whether the user has made changes, and the ability to revert or save those changes.
+
+---
+
+## When to Use Model vs ViewModel
+
+| Use a **Model** when... | Use a **ViewModel** when... |
+|---|---|
+| Editing a single entity | Managing UI state, computed properties, and actions for a component |
+| You need field-level validation errors | You need async tracking, derived getters, or collection subscriptions |
+| You need dirty tracking (commit/rollback) | You need imperative events or lifecycle-driven data loading |
+
+Models are often **owned by a ViewModel** — the ViewModel handles async operations (save, delete) while the Model handles the form's editing state.
+
+---
+
+## Defining a Model
+
+Extend `Model<S>` with your state shape. `Model` is abstract — you must subclass it.
+
+```typescript
+import { Model } from 'mvc-kit';
+import type { ValidationErrors } from 'mvc-kit';
+
+interface UserFormState {
+  name: string;
+  email: string;
+  age: number;
+}
+
+class UserFormModel extends Model<UserFormState> {
+  setName(name: string) { this.set({ name }); }
+  setEmail(email: string) { this.set({ email }); }
+  setAge(age: number) { this.set({ age }); }
+
+  protected validate(state: Readonly<UserFormState>): ValidationErrors<UserFormState> {
+    const errors: ValidationErrors<UserFormState> = {};
+    if (!state.name.trim()) errors.name = 'Name is required';
+    if (!state.email.includes('@')) errors.email = 'Invalid email';
+    if (state.age < 0 || state.age > 150) errors.age = 'Age must be between 0 and 150';
+    return errors;
+  }
+}
+```
+
+---
+
+## State
+
+### Initialization
+
+State is passed to the constructor and frozen immediately. Both `state` and `committed` point to the same frozen snapshot.
+
+```typescript
+const model = new UserFormModel({ name: 'Alice', email: 'alice@example.com', age: 30 });
+
+model.state;      // { name: 'Alice', email: 'alice@example.com', age: 30 }
+model.committed;  // same reference as state
+model.dirty;      // false
+```
+
+### Updating State
+
+Call `set()` (protected) with a partial object, an updater function, or a draft mutator. The method is protected — expose it through named setter methods on your subclass.
+
+```typescript
+// Partial object
+this.set({ name: 'Bob' });
+
+// Updater function — return a partial
+this.set(prev => ({ age: prev.age + 1 }));
+
+// Draft mode — mutate the draft, return nothing
+this.set(draft => { draft.age = draft.age + 1 });
+```
+
+When using the function form, the state is wrapped in a copy-on-write draft proxy (see [`produceDraft`](./produceDraft.md)). If the function returns an object, it's used as the partial. If `void`, the draft mutations are applied. Structural sharing is preserved and arrays must be replaced via assignment.
+
+`set()` behavior:
+- **Shallow equality check** — if no values actually changed, the update is skipped and no listeners fire.
+- **Immutable** — produces a new frozen object via `Object.freeze({ ...prev, ...partial })`.
+- **Notifies listeners** — all subscribers receive `(nextState, prevState)` after every real change.
+- **Throws after dispose** — calling `set()` on a disposed Model throws `'Cannot set state on disposed Model'`.
+
+### Reading State
+
+```typescript
+model.state;      // current frozen state
+model.committed;  // baseline state for dirty comparison
+```
+
+---
+
+## Dirty Tracking
+
+A Model is **dirty** when its current `state` differs from its `committed` baseline. The comparison is shallow equality across all keys.
+
+```typescript
+const model = new UserFormModel({ name: 'Alice', email: 'alice@example.com', age: 30 });
+
+model.dirty;  // false
+
+model.setName('Bob');
+model.dirty;  // true — name changed from committed
+
+model.setName('Alice');
+model.dirty;  // false — back to committed values
+```
+
+### commit()
+
+Marks the current state as the new baseline. After `commit()`, `dirty` becomes `false` and `committed` equals `state`.
+
+```typescript
+model.setName('Bob');
+model.dirty;            // true
+
+model.commit();
+model.dirty;            // false
+model.committed.name;   // 'Bob'
+```
+
+Use this after a successful save to mark the persisted state as the new clean baseline.
+
+### rollback()
+
+Reverts state to the committed baseline. If already at the committed state, it's a no-op (no listeners fire).
+
+```typescript
+model.setName('Bob');
+model.setAge(25);
+model.state.name;  // 'Bob'
+
+model.rollback();
+model.state.name;  // 'Alice' (reverted to committed)
+model.dirty;       // false
+```
+
+Rollback **notifies listeners** (unless state was already at committed), making it suitable for a "Discard changes" button.
+
+Both `commit()` and `rollback()` throw on a disposed Model.
+
+---
+
+## Validation
+
+Override the `validate()` method to provide field-level validation. Return an object mapping field keys to error message strings. An empty object means valid.
+
+```typescript
+protected validate(state: Readonly<UserFormState>): ValidationErrors<UserFormState> {
+  const errors: ValidationErrors<UserFormState> = {};
+  if (!state.name.trim()) errors.name = 'Name is required';
+  if (!state.email.includes('@')) errors.email = 'Invalid email';
+  return errors;
+}
+```
+
+### Reading Validation
+
+```typescript
+model.errors;  // { name: 'Name is required', email: 'Invalid email' }
+model.valid;   // false (Object.keys(errors).length === 0)
+```
+
+Both `errors` and `valid` are **computed on access** from the current `state`. When state changes, validation re-evaluates automatically — no manual call needed.
+
+If you don't override `validate()`, the default returns `{}` (always valid).
+
+---
+
+## Lifecycle
+
+### init()
+
+Calling `init()` sets `initialized` to `true` and invokes the `onInit()` hook. It is **idempotent** — subsequent calls are no-ops. It is also a **no-op after dispose**.
+
+```typescript
+class LoadableModel extends Model<UserFormState> {
+  protected onInit() {
+    // Set initial derived state, subscribe to external sources, etc.
+    this.set({ name: 'Initialized' });
+  }
+}
+
+const model = new LoadableModel({ name: '', email: '', age: 0 });
+model.initialized;  // false
+model.init();
+model.initialized;  // true
+model.state.name;   // 'Initialized'
+```
+
+`onInit()` can be **async** — `init()` returns the promise so callers can await it:
+
+```typescript
+protected async onInit() {
+  const data = await fetchInitialData(this.disposeSignal);
+  this.set(data);
+}
+
+await model.init();
+```
+
+### dispose()
+
+Tears down the Model in this order:
+1. Sets `disposed` to `true`
+2. Aborts the `disposeSignal` (if it was accessed)
+3. Runs all registered cleanup functions
+4. Calls `onDispose()` hook
+5. Clears all listeners
+
+Dispose is **idempotent** — calling it multiple times is safe.
+
+```typescript
+model.dispose();
+model.disposed;  // true
+```
+
+After dispose:
+- `set()` throws
+- `commit()` throws
+- `rollback()` throws
+- `subscribe()` returns a no-op unsubscribe function
+
+### onSet(prev, next)
+
+Optional hook called after every state change (from both `set()` and `rollback()`). Receives the previous and next state.
+
+```typescript
+protected onSet(prev: Readonly<State>, next: Readonly<State>) {
+  if (prev.email !== next.email) {
+    console.log('Email changed to', next.email);
+  }
+}
+```
+
+---
+
+## Subscriptions
+
+### subscribe(listener)
+
+Register a listener that fires on every state change with `(nextState, prevState)`. Returns an unsubscribe function.
+
+```typescript
+const unsub = model.subscribe((next, prev) => {
+  console.log('Changed from', prev, 'to', next);
+});
+
+model.setName('Bob');  // listener fires
+
+unsub();
+model.setName('Carol');  // listener does NOT fire
+```
+
+Model implements `Subscribable<S>`, so it can be used with `subscribeTo` on ViewModels and other Models.
+
+### subscribeTo(source, listener)
+
+Subscribe to an external `Subscribable` source (Collection, another Model, Channel, etc.) with automatic cleanup on dispose.
+
+```typescript
+class OrderModel extends Model<OrderState> {
+  setup(priceCollection: Collection<PriceItem>) {
+    this.subscribeTo(priceCollection, (items) => {
+      this.set({ prices: items });
+    });
+  }
+}
+```
+
+Also returns an unsubscribe function for manual early cleanup.
+
+### listenTo(source, event, handler)
+
+Subscribe to a typed event on a Channel or EventBus with automatic cleanup on dispose. The event counterpart to `subscribeTo`.
+
+```typescript
+protected onInit() {
+  this.listenTo(this.bus, 'fieldUpdate', (update) => {
+    this.set({ [update.field]: update.value });
+  });
+}
+```
+
+### addCleanup(fn)
+
+Register a cleanup function that runs on `dispose()`. Used internally by `subscribeTo`, but also available for custom teardown.
+
+```typescript
+protected onInit() {
+  const interval = setInterval(() => this.tick(), 1000);
+  this.addCleanup(() => clearInterval(interval));
+}
+```
+
+---
+
+## Cancellation with disposeSignal
+
+`disposeSignal` is a lazily-created `AbortSignal` that aborts when the Model is disposed. Pass it to `fetch()` or any async API to cancel in-flight operations on teardown.
+
+```typescript
+protected async onInit() {
+  const res = await fetch('/api/data', { signal: this.disposeSignal });
+  this.set({ data: await res.json() });
+}
+```
+
+- **Lazy** — the AbortController is only created when `disposeSignal` is first accessed. Zero cost if never used.
+- **Stable** — returns the same signal on every access.
+- **Aborted before onDispose** — by the time `onDispose()` runs, the signal is already aborted.
+
+---
+
+## React Integration
+
+### useModel
+
+Binds a Model to a component. Creates the instance from a factory, auto-initializes on mount, auto-disposes on unmount, and subscribes to state changes.
+
+```tsx
+import { useModel } from 'mvc-kit/react';
+
+function EditUserForm() {
+  const { state, errors, valid, dirty, model } = useModel(
+    () => new UserFormModel({ name: '', email: '', age: 0 })
+  );
+
+  return (
+    <form>
+      <input value={state.name} onChange={e => model.setName(e.target.value)} />
+      {errors.name && <span className="error">{errors.name}</span>}
+
+      <input value={state.email} onChange={e => model.setEmail(e.target.value)} />
+      {errors.email && <span className="error">{errors.email}</span>}
+
+      <button disabled={!valid || !dirty}>Save</button>
+    </form>
+  );
+}
+```
+
+The returned `ModelHandle` provides:
+
+| Property | Type | Description |
+|---|---|---|
+| `state` | `S` | Current frozen state |
+| `errors` | `ValidationErrors<S>` | Validation errors keyed by field |
+| `valid` | `boolean` | `true` when no validation errors |
+| `dirty` | `boolean` | `true` when state differs from committed |
+| `model` | `M` | The Model instance for calling setters |
+
+### useField
+
+Subscribes to a **single field** with surgical re-renders — the component only re-renders when that specific field's value or error changes. Use this for forms with many fields to avoid re-rendering the entire form on every keystroke.
+
+```tsx
+import { useField } from 'mvc-kit/react';
+
+function NameField({ model }: { model: UserFormModel }) {
+  const { value, error, set } = useField(model, 'name');
+
+  return (
+    <div>
+      <input value={value} onChange={e => set(e.target.value)} />
+      {error && <span className="error">{error}</span>}
+    </div>
+  );
+}
+```
+
+The returned `FieldHandle` provides:
+
+| Property | Type | Description |
+|---|---|---|
+| `value` | `S[K]` | Current value of the field |
+| `error` | `string \| undefined` | Validation error for the field |
+| `set` | `(value: S[K]) => void` | Update the field value |
+
+`useField` is type-safe — invalid field names produce a compile-time error.
+
+---
+
+## Model Inside a ViewModel
+
+The typical pattern for a form page: the ViewModel handles async operations and coordination, the Model handles editing state.
+
+```typescript
+interface EditState {
+  draft: UserState | null;
+}
+
+interface EditEvents {
+  saved: { id: string };
+}
+
+class EditUserViewModel extends ViewModel<EditState, EditEvents> {
+  public model!: UserFormModel;
+  private service = singleton(UserService);
+
+  protected async onInit() {
+    const user = await this.service.getById(this.userId, this.disposeSignal);
+    this.model = new UserFormModel(user);
+    this.set({ draft: user });
+  }
+
+  async save() {
+    if (!this.model.valid) return;
+    await this.service.update(this.userId, this.model.state, this.disposeSignal);
+    this.model.commit();
+    this.emit('saved', { id: this.userId });
+  }
+
+  protected onDispose() {
+    this.model?.dispose();
+  }
+}
+```
+
+The component:
+
+```tsx
+function EditUserPage() {
+  const [state, vm] = useLocal(EditUserViewModel, { draft: null });
+  const loadState = vm.async.onInit;
+  const saveState = vm.async.save;
+
+  if (loadState.loading || !vm.model) return <Spinner />;
+  if (loadState.error) return <ErrorBanner message={loadState.error} />;
+
+  return <EditUserForm model={vm.model} onSave={() => vm.save()} saving={saveState.loading} />;
+}
+
+function EditUserForm({ model, onSave, saving }: Props) {
+  const { state, errors, valid, dirty } = useModel(() => model);
+
+  return (
+    <form onSubmit={e => { e.preventDefault(); onSave(); }}>
+      <input value={state.name} onChange={e => model.setName(e.target.value)} />
+      {errors.name && <span>{errors.name}</span>}
+      <button disabled={!valid || !dirty || saving}>
+        {saving ? 'Saving...' : 'Save'}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## Singleton Usage
+
+Models can be registered as singletons for app-wide entity state (rare, but supported):
+
+```typescript
+import { singleton, teardownAll } from 'mvc-kit';
+
+const model = singleton(UserFormModel, { name: 'Alice', email: 'alice@example.com', age: 30 });
+```
+
+The initial state is only used on the first call. Subsequent `singleton()` calls return the existing instance regardless of the state argument passed.
+
+---
+
+## API Reference
+
+### Constructor
+
+| Signature | Description |
+|---|---|
+| `constructor(initialState: S)` | Creates a new Model with frozen initial state. Sets both `state` and `committed` to the frozen snapshot. |
+
+### Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `state` | `S` | Current frozen state |
+| `committed` | `S` | Baseline state for dirty comparison |
+| `dirty` | `boolean` | `true` if `state` differs from `committed` (shallow equality) |
+| `errors` | `ValidationErrors<S>` | Validation errors for current state |
+| `valid` | `boolean` | `true` if `errors` is empty |
+| `disposed` | `boolean` | `true` after `dispose()` |
+| `initialized` | `boolean` | `true` after `init()` |
+| `disposeSignal` | `AbortSignal` | Lazily-created signal, aborted on dispose |
+
+### Methods
+
+| Method | Description |
+|---|---|
+| `init()` | Set `initialized = true` and call `onInit()`. Idempotent. No-op after dispose. Returns `void \| Promise<void>`. |
+| `commit()` | Set `committed = state`. Throws if disposed. |
+| `rollback()` | Revert `state` to `committed`. Notifies listeners. No-op if already at committed. Throws if disposed. |
+| `subscribe(listener)` | Register a `(next, prev) => void` listener. Returns unsubscribe function. Returns no-op if disposed. |
+| `dispose()` | Tear down: abort signal, run cleanups, call `onDispose()`, clear listeners. Idempotent. |
+
+### Protected Methods
+
+| Method | Description |
+|---|---|
+| `set(partial \| updater \| drafter)` | Update state via object, updater function, or draft mutator. Skips if no values changed. Throws if disposed. |
+| `validate(state)` | Override to return field-level errors. Default returns `{}`. |
+| `addCleanup(fn)` | Register a function to run on dispose. |
+| `subscribeTo(source, listener)` | Subscribe to a `Subscribable` with auto-cleanup. Returns unsubscribe. |
+| `listenTo(source, event, handler)` | Subscribe to a typed event (Channel/EventBus) with auto-cleanup. Returns unsubscribe. |
+
+### Lifecycle Hooks
+
+| Hook | Description |
+|---|---|
+| `onInit()` | Called by `init()`. Can be async. |
+| `onSet(prev, next)` | Called after every state change. |
+| `onDispose()` | Called during `dispose()`, after signal abort and cleanups. |
+
+## 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 { commit, rollback } = model;
+<button onClick={commit}>Save</button> // point-free works
+```