mvc-kit 2.12.0 → 2.12.2

package/src/ViewModel.async.test.ts

@@ -0,0 +1,813 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ViewModel } from './ViewModel';
+import { HttpError } from './errors';
+
+// ============================================================================
+// Test Helpers
+// ============================================================================
+
+function defer<T = void>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+function abortError(): DOMException {
+  return new DOMException('The operation was aborted', 'AbortError');
+}
+
+// ============================================================================
+// Test Setup Classes
+// ============================================================================
+
+interface TestState {
+  count: number;
+  data: string | null;
+}
+
+class AsyncVM extends ViewModel<TestState> {
+  async fetchData(): Promise<string> {
+    const result = await Promise.resolve('data');
+    this.set({ data: result });
+    return result;
+  }
+
+  async failingMethod(): Promise<void> {
+    throw new Error('something went wrong');
+  }
+
+  async abortableMethod(signal?: AbortSignal): Promise<string> {
+    if (signal?.aborted) throw abortError();
+    return 'done';
+  }
+
+  syncMethod(): number {
+    return 42;
+  }
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe('ViewModel async tracking', () => {
+  // ── Basic loading/error state ──────────────────────────────────
+
+  describe('basic loading/error tracking', () => {
+    it('starts with default TaskState { loading: false, error: null }', () => {
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+      expect(vm.async.fetchData).toEqual({ loading: false, error: null, errorCode: null });
+    });
+
+    it('sets loading: true when async method starts', async () => {
+      const d = defer<string>();
+
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<string> {
+          return d.promise;
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      const p = vm.load();
+      expect(vm.async.load).toEqual({ loading: true, error: null, errorCode: null });
+
+      d.resolve('ok');
+      await p;
+      expect(vm.async.load).toEqual({ loading: false, error: null, errorCode: null });
+    });
+
+    it('captures error message on rejection', async () => {
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+
+      await expect(vm.failingMethod()).rejects.toThrow('something went wrong');
+      expect(vm.async.failingMethod).toEqual({
+        loading: false,
+        error: 'something went wrong',
+        errorCode: 'unknown',
+      });
+    });
+
+    it('clears error on retry', async () => {
+      const d = defer<void>();
+      let shouldFail = true;
+
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> {
+          if (shouldFail) throw new Error('fail');
+          return d.promise;
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      // First call fails
+      await expect(vm.load()).rejects.toThrow('fail');
+      expect(vm.async.load.error).toBe('fail');
+
+      // Retry succeeds — error cleared
+      shouldFail = false;
+      const p = vm.load();
+      expect(vm.async.load).toEqual({ loading: true, error: null, errorCode: null });
+
+      d.resolve();
+      await p;
+      expect(vm.async.load).toEqual({ loading: false, error: null, errorCode: null });
+    });
+  });
+
+  // ── Return value preservation ──────────────────────────────────
+
+  describe('return value preservation', () => {
+    it('returns the resolved value on success', async () => {
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+
+      const result = await vm.fetchData();
+      expect(result).toBe('data');
+    });
+
+    it('re-throws the error on rejection', async () => {
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+
+      await expect(vm.failingMethod()).rejects.toThrow('something went wrong');
+    });
+
+    it('returns undefined for AbortError (swallowed)', async () => {
+      class VM extends ViewModel<TestState> {
+        async abortable(): Promise<string> {
+          throw abortError();
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      const result = await vm.abortable();
+      expect(result).toBeUndefined();
+    });
+  });
+
+  // ── Concurrent calls ──────────────────────────────────────────
+
+  describe('concurrent calls (counter-based loading)', () => {
+    it('stays loading until all concurrent calls resolve', async () => {
+      const d1 = defer<void>();
+      const d2 = defer<void>();
+      let callCount = 0;
+
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> {
+          callCount++;
+          if (callCount === 1) return d1.promise;
+          return d2.promise;
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      const p1 = vm.load();
+      const p2 = vm.load();
+
+      expect(vm.async.load.loading).toBe(true);
+
+      d1.resolve();
+      await p1;
+      // Still loading because p2 is pending
+      expect(vm.async.load.loading).toBe(true);
+
+      d2.resolve();
+      await p2;
+      expect(vm.async.load.loading).toBe(false);
+    });
+  });
+
+  // ── AbortError swallowing ─────────────────────────────────────
+
+  describe('AbortError swallowing', () => {
+    it('does not set error for AbortError', async () => {
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> {
+          throw abortError();
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      await vm.load();
+      expect(vm.async.load.error).toBeNull();
+      expect(vm.async.load.loading).toBe(false);
+    });
+
+    it('does not re-throw AbortError', async () => {
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> {
+          throw abortError();
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      // Should not reject
+      await expect(vm.load()).resolves.toBeUndefined();
+    });
+  });
+
+  // ── Sync method pruning ───────────────────────────────────────
+
+  describe('sync method pruning', () => {
+    it('prunes sync methods on first call', () => {
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+
+      const result = vm.syncMethod();
+      expect(result).toBe(42);
+
+      // After pruning, method is replaced with bound original
+      expect('syncMethod' in vm.async).toBe(false);
+    });
+
+    it('pruned method still works correctly on subsequent calls', () => {
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+
+      vm.syncMethod(); // first call prunes
+      expect(vm.syncMethod()).toBe(42); // subsequent call
+      expect(vm.syncMethod()).toBe(42); // another
+    });
+  });
+
+  // ── subscribeAsync ────────────────────────────────────────────
+
+  describe('subscribeAsync notifications', () => {
+    it('notifies on loading start and end', async () => {
+      const listener = vi.fn();
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+      vm.subscribeAsync(listener);
+
+      await vm.fetchData();
+      // Called at least twice: loading start + loading end
+      expect(listener.mock.calls.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it('unsubscribe stops notifications', async () => {
+      const listener = vi.fn();
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+      const unsub = vm.subscribeAsync(listener);
+
+      unsub();
+      await vm.fetchData();
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('returns no-op if disposed', () => {
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+      vm.dispose();
+      const unsub = vm.subscribeAsync(() => {});
+      expect(typeof unsub).toBe('function');
+      expect(() => unsub()).not.toThrow();
+    });
+  });
+
+  // ── async proxy ───────────────────────────────────────────────
+
+  describe('async proxy', () => {
+    it('returns frozen TaskState snapshots', async () => {
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+
+      await vm.fetchData();
+      const state = vm.async.fetchData;
+      expect(Object.isFrozen(state)).toBe(true);
+    });
+
+    it('returns DEFAULT_TASK_STATE for unknown keys', () => {
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+      expect((vm.async as any).nonExistent).toEqual({
+        loading: false,
+        error: null,
+        errorCode: null,
+      });
+    });
+
+    it('Object.keys returns tracked methods', async () => {
+      const d = defer<string>();
+
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<string> { return d.promise; }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      const p = vm.load();
+      expect(Object.keys(vm.async)).toContain('load');
+
+      d.resolve('ok');
+      await p;
+    });
+
+    it('"in" operator works for tracked methods', async () => {
+      const d = defer<string>();
+
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<string> { return d.promise; }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      const p = vm.load();
+      expect('load' in vm.async).toBe(true);
+
+      d.resolve('ok');
+      await p;
+    });
+
+    it('snapshot reference changes on each state update', async () => {
+      const d = defer<void>();
+
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> { return d.promise; }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      const before = vm.async.load;
+      const p = vm.load();
+      const during = vm.async.load;
+      expect(during).not.toBe(before);
+
+      d.resolve();
+      await p;
+      const after = vm.async.load;
+      expect(after).not.toBe(during);
+    });
+  });
+
+  // ── Disposal ──────────────────────────────────────────────────
+
+  describe('disposal', () => {
+    it('methods become no-ops after dispose', () => {
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+      vm.dispose();
+
+      const result = vm.fetchData();
+      expect(result).toBeUndefined();
+    });
+
+    it('in-flight work fizzles — no state updates after dispose', async () => {
+      const d = defer<void>();
+
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> {
+          await d.promise;
+          this.set({ data: 'loaded' });
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      const p = vm.load();
+
+      // Dispose while in-flight
+      vm.dispose();
+
+      d.resolve();
+      await p.catch(() => {}); // may reject or resolve
+
+      expect(vm.state.data).toBeNull(); // no state change
+    });
+
+    it('subscribeAsync listeners cleared on dispose', async () => {
+      const listener = vi.fn();
+      const d = defer<void>();
+
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> { return d.promise; }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+      vm.subscribeAsync(listener);
+
+      const p = vm.load();
+      listener.mockClear();
+
+      vm.dispose();
+      d.resolve();
+      await p.catch(() => {});
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── Lifecycle guards ──────────────────────────────────────────
+
+  describe('lifecycle guards (DEV)', () => {
+    it('warns when calling method after dispose', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+      vm.dispose();
+
+      vm.fetchData();
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('"fetchData" called after dispose')
+      );
+
+      warnSpy.mockRestore();
+    });
+
+    it('warns when calling method before init', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      // Need to manually wrap since _wrapMethods runs in init
+      // Pre-init warning only fires for methods on VMs that have been
+      // constructed but not yet init'd — since _wrapMethods() runs in init(),
+      // this path is only reachable if someone calls init(), then resets _initialized
+      // Actually, since wrapping happens in init(), pre-init calls go to unwrapped methods.
+      // The guard is for the scenario where init() runs but _initialized flag is somehow false.
+      // In practice, this is a safety net. Let's verify wrapping only happens after init.
+
+      const vm = new AsyncVM({ count: 0, data: null });
+      // Before init, methods are NOT wrapped — no warning
+      const result = vm.syncMethod();
+      expect(result).toBe(42);
+
+      warnSpy.mockRestore();
+    });
+  });
+
+  // ── Reserved key guard ────────────────────────────────────────
+
+  describe('reserved key guard', () => {
+    it('throws when subclass defines "async" method on prototype', () => {
+      expect(() => {
+        class BadVM extends ViewModel<TestState> {
+          // @ts-expect-error
+          async() { return 'bad'; }
+        }
+        new BadVM({ count: 0, data: null });
+      }).toThrow('"async" is a reserved property');
+    });
+
+    it('throws when subclass defines "subscribeAsync" method on prototype', () => {
+      expect(() => {
+        class BadVM extends ViewModel<TestState> {
+          subscribeAsync() { return () => {}; }
+        }
+        new BadVM({ count: 0, data: null });
+      }).toThrow('"subscribeAsync" is a reserved property');
+    });
+
+    it('throws when subclass defines "async" as class field', () => {
+      class BadVM extends ViewModel<TestState> {
+        // @ts-expect-error
+        async = 'bad';
+      }
+      const vm = new BadVM({ count: 0, data: null });
+      expect(() => vm.init()).toThrow('"async" is a reserved property');
+    });
+  });
+
+  // ── Inheritance ───────────────────────────────────────────────
+
+  describe('inheritance', () => {
+    it('tracks methods from parent and child classes', async () => {
+      class ParentVM extends ViewModel<TestState> {
+        async parentLoad(): Promise<string> {
+          return 'parent';
+        }
+      }
+
+      class ChildVM extends ParentVM {
+        async childLoad(): Promise<string> {
+          return 'child';
+        }
+      }
+
+      const vm = new ChildVM({ count: 0, data: null });
+      vm.init();
+
+      await vm.parentLoad();
+      await vm.childLoad();
+
+      // Both are tracked
+      expect(vm.async.parentLoad).toEqual({ loading: false, error: null, errorCode: null });
+      expect(vm.async.childLoad).toEqual({ loading: false, error: null, errorCode: null });
+    });
+
+    it('child override wins (most-derived)', async () => {
+      class ParentVM extends ViewModel<TestState> {
+        async load(): Promise<string> {
+          return 'parent';
+        }
+      }
+
+      class ChildVM extends ParentVM {
+        async load(): Promise<string> {
+          return 'child';
+        }
+      }
+
+      const vm = new ChildVM({ count: 0, data: null });
+      vm.init();
+
+      const result = await vm.load();
+      expect(result).toBe('child');
+    });
+
+    it('does not track base ViewModel methods', () => {
+      const vm = new AsyncVM({ count: 0, data: null });
+      vm.init();
+
+      // init, dispose, subscribe, etc. should not be in async proxy
+      expect('init' in vm.async).toBe(false);
+      expect('dispose' in vm.async).toBe(false);
+      expect('subscribe' in vm.async).toBe(false);
+    });
+  });
+
+  // ── Ghost detection (DEV, fake timers) ────────────────────────
+
+  describe('ghost detection', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('warns about pending operations after GHOST_TIMEOUT', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const d = defer<void>();
+
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> {
+          return d.promise;
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      vm.load(); // start but don't resolve
+
+      vm.dispose();
+
+      // Ghost check not yet fired
+      expect(warnSpy).not.toHaveBeenCalledWith(
+        expect.stringContaining('Ghost async operation')
+      );
+
+      vi.advanceTimersByTime(3000);
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Ghost async operation detected: "load"')
+      );
+
+      warnSpy.mockRestore();
+      d.resolve(); // cleanup
+    });
+
+    it('respects custom GHOST_TIMEOUT', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const d = defer<void>();
+
+      class VM extends ViewModel<TestState> {
+        static override GHOST_TIMEOUT = 5000;
+        async load(): Promise<void> { return d.promise; }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+      vm.load();
+      vm.dispose();
+
+      vi.advanceTimersByTime(3000);
+      expect(warnSpy).not.toHaveBeenCalledWith(
+        expect.stringContaining('Ghost')
+      );
+
+      vi.advanceTimersByTime(2000);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Ghost async operation detected: "load"')
+      );
+
+      warnSpy.mockRestore();
+      d.resolve();
+    });
+  });
+
+  // ── Integration with reactive derived state management ─────────────────────────
+
+  describe('integration with reactive derived state management', () => {
+    it('async method calling set() triggers getter invalidation', async () => {
+      class VM extends ViewModel<TestState> {
+        get uppercaseData(): string | null {
+          return this.state.data?.toUpperCase() ?? null;
+        }
+
+        async loadData(): Promise<void> {
+          this.set({ data: 'hello' });
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      expect(vm.uppercaseData).toBeNull();
+
+      await vm.loadData();
+      expect(vm.uppercaseData).toBe('HELLO');
+    });
+
+    it('_notifyAsync does NOT bump _revision (getters not invalidated by async state)', async () => {
+      let computeCount = 0;
+
+      class VM extends ViewModel<TestState> {
+        get derived(): number {
+          computeCount++;
+          return this.state.count * 2;
+        }
+
+        async load(): Promise<void> {
+          await Promise.resolve();
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      // Prime the getter cache
+      expect(vm.derived).toBe(0);
+      computeCount = 0;
+
+      // Async operation — should NOT recompute getter
+      await vm.load();
+
+      expect(vm.derived).toBe(0);
+      expect(computeCount).toBe(0); // cached, not recomputed
+    });
+  });
+
+  // ── set() no-op after dispose ─────────────────────────────────
+
+  describe('set() after dispose', () => {
+    it('is a no-op (does not throw)', () => {
+      class VM extends ViewModel<TestState> {
+        update() {
+          this.set({ count: 99 });
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.dispose();
+      expect(() => vm.update()).not.toThrow();
+      expect(vm.state.count).toBe(0);
+    });
+  });
+
+  // ── Non-Error rejection ───────────────────────────────────────
+
+  describe('non-Error rejection', () => {
+    it('captures string error', async () => {
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> {
+          throw 'string error';
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      await vm.load().catch(() => {});
+      expect(vm.async.load.error).toBe('string error');
+      expect(vm.async.load.errorCode).toBe('unknown');
+    });
+  });
+
+  // ── Error classification ───────────────────────────────────────
+
+  describe('error classification (errorCode)', () => {
+    it('classifies HttpError(401) as unauthorized', async () => {
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> {
+          throw new HttpError(401, 'Unauthorized');
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      await vm.load().catch(() => {});
+      expect(vm.async.load.error).toBe('Unauthorized');
+      expect(vm.async.load.errorCode).toBe('unauthorized');
+    });
+
+    it('classifies HttpError(500) as server_error', async () => {
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> {
+          throw new HttpError(500, 'Internal Server Error');
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      await vm.load().catch(() => {});
+      expect(vm.async.load.error).toBe('Internal Server Error');
+      expect(vm.async.load.errorCode).toBe('server_error');
+    });
+
+    it('classifies TypeError("Failed to fetch") as network', async () => {
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> {
+          throw new TypeError('Failed to fetch');
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      await vm.load().catch(() => {});
+      expect(vm.async.load.error).toBe('Failed to fetch');
+      expect(vm.async.load.errorCode).toBe('network');
+    });
+
+    it('classifies generic Error as unknown', async () => {
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> {
+          throw new Error('something broke');
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      await vm.load().catch(() => {});
+      expect(vm.async.load.error).toBe('something broke');
+      expect(vm.async.load.errorCode).toBe('unknown');
+    });
+
+    it('classifies non-Error string as unknown', async () => {
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> {
+          throw 'raw string';
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      await vm.load().catch(() => {});
+      expect(vm.async.load.error).toBe('raw string');
+      expect(vm.async.load.errorCode).toBe('unknown');
+    });
+
+    it('clears errorCode on successful retry', async () => {
+      let shouldFail = true;
+
+      class VM extends ViewModel<TestState> {
+        async load(): Promise<void> {
+          if (shouldFail) throw new HttpError(500, 'Server Error');
+        }
+      }
+
+      const vm = new VM({ count: 0, data: null });
+      vm.init();
+
+      await vm.load().catch(() => {});
+      expect(vm.async.load.errorCode).toBe('server_error');
+
+      shouldFail = false;
+      await vm.load();
+      expect(vm.async.load.errorCode).toBeNull();
+      expect(vm.async.load.error).toBeNull();
+    });
+  });
+});