mvc-kit 2.13.1 → 2.14.0

package/src/react/use-model.md

@@ -125,11 +125,20 @@ function UserForm() {
 
 ## Model Inside a ViewModel
 
-The typical form-page pattern: a [ViewModel](../ViewModel.md) handles async operations (load, save, delete) and coordination, while the Model handles the editing state. The ViewModel owns the Model and disposes it in `onDispose()`.
+The typical form pattern: a [ViewModel](../ViewModel.md) handles async operations (save, delete) and coordination, while the Model handles the editing state. The ViewModel owns the Model and disposes it in `onDispose()`. Which shape you use depends on whether the form's initial data is already available:
+
+| If the initial data is... | Shape |
+|---|---|
+| **Available at construction** (create modal, edit modal receiving an entity prop) | Create the Model in the **constructor** as `readonly`. Non-nullable, no guard. |
+| **Fetched by ID** after mount (edit page that loads from the server) | Declare it `\| null = null` and create it in `onInit()`. Component must guard. |
+
+> **Never** write `public model!: FormModel`. The `!` lies to TypeScript about runtime state — first render runs before `onInit`, `vm.model` is `undefined`, and `useField`/`useModel` crash. Pick one of the two shapes below.
+
+### Shape 1 — Data available at construction (preferred when applicable)
 
 ```typescript
 interface EditState {
-  draft: UserState | null;
+  existing: UserState | null;  // null → create, non-null → edit
 }
 
 interface EditEvents {
@@ -137,7 +146,45 @@ interface EditEvents {
 }
 
 class EditUserViewModel extends ViewModel<EditState, EditEvents> {
-  public model!: UserFormModel;
+  // `readonly` refers to the reference — the model's state still changes via set().
+  public readonly model: UserFormModel;
+  private service = singleton(UserService);
+
+  constructor(initialState: EditState) {
+    super(initialState);
+    this.model = new UserFormModel(initialState.existing ?? INITIAL_FORM_STATE);
+  }
+
+  async save() {
+    if (!this.model.valid) return;
+    const result = await this.service.save(this.model.state, this.disposeSignal);
+    this.model.commit();
+    this.emit('saved', { id: result.id });
+  }
+
+  protected onDispose() {
+    this.model.dispose();
+  }
+}
+```
+
+```tsx
+function EditUserModal({ existing, onClose }: Props) {
+  const [, vm] = useLocal(EditUserViewModel, { existing });
+  const { loading: saving } = vm.async.save;
+
+  useEvent(vm, 'saved', onClose);
+
+  // No guard — vm.model exists from the first render.
+  return <EditUserForm model={vm.model} onSave={vm.save} saving={saving} />;
+}
+```
+
+### Shape 2 — Data fetched by ID
+
+```typescript
+class EditUserViewModel extends ViewModel<EditState, EditEvents> {
+  public model: UserFormModel | null = null;
   private service = singleton(UserService);
 
   protected async onInit() {
@@ -147,7 +194,7 @@ class EditUserViewModel extends ViewModel<EditState, EditEvents> {
   }
 
   async save() {
-    if (!this.model.valid) return;
+    if (!this.model || !this.model.valid) return;
     await this.service.update(this.userId, this.model.state, this.disposeSignal);
     this.model.commit();
     this.emit('saved', { id: this.userId });

package/src/react/use-model.test.tsx

@@ -392,3 +392,89 @@ describe('type-level: useField rejects invalid field names', () => {
     _useField(model, 'age');
   });
 });
+
+describe('DEV assertions: undefined/null model', () => {
+  // React logs render errors to console.error even when an ErrorBoundary catches them.
+  // Silence the noise for these expected-throw tests.
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+  beforeEach(() => {
+    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+  afterEach(() => {
+    errorSpy.mockRestore();
+  });
+
+  class ErrorBoundary extends (require('react').Component as typeof import('react').Component)<
+    { children: import('react').ReactNode; onError: (e: Error) => void },
+    { err: Error | null }
+  > {
+    state = { err: null as Error | null };
+    static getDerivedStateFromError(err: Error) { return { err }; }
+    componentDidCatch(err: Error) { this.props.onError(err); }
+    render() {
+      return this.state.err ? null : this.props.children;
+    }
+  }
+
+  it('useField throws a diagnostic error when model is undefined', () => {
+    function Child({ model }: { model: any }) {
+      useField(model, 'name');
+      return null;
+    }
+    let caught: Error | null = null;
+    render(
+      <ErrorBoundary onError={e => { caught = e; }}>
+        <Child model={undefined} />
+      </ErrorBoundary>,
+    );
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toContain('useField');
+    expect(caught!.message).toContain('undefined/null model');
+    expect(caught!.message).toContain('public model!');
+  });
+
+  it('useField throws when model is null', () => {
+    function Child({ model }: { model: any }) {
+      useField(model, 'name');
+      return null;
+    }
+    let caught: Error | null = null;
+    render(
+      <ErrorBoundary onError={e => { caught = e; }}>
+        <Child model={null} />
+      </ErrorBoundary>,
+    );
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toContain('useField');
+  });
+
+  it('useModel throws when factory returns undefined', () => {
+    function Child() {
+      useModel(() => undefined as any);
+      return null;
+    }
+    let caught: Error | null = null;
+    render(
+      <ErrorBoundary onError={e => { caught = e; }}>
+        <Child />
+      </ErrorBoundary>,
+    );
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toContain('useModel');
+  });
+
+  it('useModelRef throws when factory returns undefined', () => {
+    function Child() {
+      useModelRef(() => undefined as any);
+      return null;
+    }
+    let caught: Error | null = null;
+    render(
+      <ErrorBoundary onError={e => { caught = e; }}>
+        <Child />
+      </ErrorBoundary>,
+    );
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toContain('useModelRef');
+  });
+});

package/src/react/use-model.ts

@@ -4,6 +4,23 @@ import type { ValidationErrors } from '../types';
 import type { StateOf } from './types';
 import { isInitializable } from './guards';
 
+const __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;
+
+function assertModelExists(
+  model: unknown,
+  hookName: 'useModel' | 'useModelRef' | 'useField',
+): asserts model {
+  if (model) return;
+  throw new Error(
+    `${hookName}: received an undefined/null model. ` +
+    'This usually means the component rendered before the ViewModel finished creating the model. ' +
+    'Either (a) create the model in the ViewModel constructor when the initial data is available ' +
+    '(so it exists from the first render), or (b) if the model is created in onInit() after an async ' +
+    'fetch, guard the component render with `if (!vm.model) return <Spinner />` before calling this hook. ' +
+    'Do not use `public model!: FormModel` — the `!` lies to TypeScript about runtime state.',
+  );
+}
+
 /** Return type of `useModel`, providing state, validation, and model access. */
 export interface ModelHandle<S extends object, M extends Model<S>> {
   state: S;
@@ -22,25 +39,35 @@ export function useModel<M extends Model<any>>(
   const modelRef = useRef<M | null>(null);
   const mountedRef = useRef(false);
 
-  if (!modelRef.current || modelRef.current.disposed) {
-    modelRef.current = factory();
+  let model = modelRef.current;
+  if (!model || model.disposed) {
+    model = factory();
+    if (__DEV__) assertModelExists(model, 'useModel');
+    modelRef.current = model;
   }
 
   const modelSubscribe = useCallback(
-    (onStoreChange: () => void) => modelRef.current!.subscribe(onStoreChange),
+    (onStoreChange: () => void) => {
+      const m = modelRef.current;
+      return m ? m.subscribe(onStoreChange) : () => {};
+    },
     []
   );
   const modelSnapshot = useCallback(
-    () => modelRef.current!.state,
+    () => {
+      const m = modelRef.current;
+      if (!m) throw new Error('useModel: model accessed before creation');
+      return m.state;
+    },
     []
   );
   useSyncExternalStore(modelSubscribe, modelSnapshot, modelSnapshot);
 
   useEffect(() => {
+    const m = modelRef.current;
+    if (!m) return;
     mountedRef.current = true;
-    if (isInitializable(modelRef.current)) {
-      modelRef.current.init();
-    }
+    if (isInitializable(m)) m.init();
     return () => {
       mountedRef.current = false;
       setTimeout(() => {
@@ -51,8 +78,6 @@ export function useModel<M extends Model<any>>(
     };
   }, []);
 
-  const model = modelRef.current;
-
   return {
     state: model.state,
     errors: model.errors,
@@ -74,15 +99,18 @@ export function useModelRef<M extends Model<any>>(factory: () => M): M {
   const modelRef = useRef<M | null>(null);
   const mountedRef = useRef(false);
 
-  if (!modelRef.current || modelRef.current.disposed) {
-    modelRef.current = factory();
+  let model = modelRef.current;
+  if (!model || model.disposed) {
+    model = factory();
+    if (__DEV__) assertModelExists(model, 'useModelRef');
+    modelRef.current = model;
   }
 
   useEffect(() => {
+    const m = modelRef.current;
+    if (!m) return;
     mountedRef.current = true;
-    if (isInitializable(modelRef.current)) {
-      modelRef.current.init();
-    }
+    if (isInitializable(m)) m.init();
     return () => {
       mountedRef.current = false;
       setTimeout(() => {
@@ -93,7 +121,7 @@ export function useModelRef<M extends Model<any>>(factory: () => M): M {
     };
   }, []);
 
-  return modelRef.current;
+  return model;
 }
 
 /** Return type of `useField`, providing a single field's value, error, and setter. */
@@ -110,6 +138,7 @@ export function useField<S extends object, K extends keyof S>(
   model: Model<S>,
   field: K
 ): FieldHandle<S[K]> {
+  if (__DEV__) assertModelExists(model, 'useField');
   // Track the field value and error for comparison
   const getSnapshot = useCallback(() => {
     return {

package/src/react/use-subscribe-only.ts

@@ -21,18 +21,19 @@ export function useSubscribeOnly(
 
   if (!ref.current || ref.current.target !== target) {
     const version = { current: ref.current?.version ?? 0 };
-    ref.current = {
+    const entry: SubscribeOnlyRef = {
       target,
       version: version.current,
       subscribe: (onStoreChange: () => void) => {
         return target.subscribe(() => {
           version.current++;
-          ref.current!.version = version.current;
+          entry.version = version.current;
           onStoreChange();
         });
       },
       getSnapshot: () => version.current,
     };
+    ref.current = entry;
   }
 
   useSyncExternalStore(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);