mvc-kit 2.2.1 → 2.2.2

package/README.md

@@ -325,7 +325,9 @@ vm.fetchUsers();  // loading: true (count: 2)
 #### Error handling
 
 - **Normal errors** are captured in `TaskState.error` (as a string message) AND re-thrown — standard Promise rejection behavior is preserved
-- **AbortErrors** are silently swallowed — not captured in `TaskState.error`, not re-thrown
+- **AbortErrors** are silently swallowed by the wrapper — not captured in `TaskState.error`, not re-thrown from the outer promise
+
+For methods without try/catch, AbortError handling is fully automatic. For methods with explicit try/catch, see [Error Utilities](#error-utilities) for when `isAbortError()` is needed.
 
 #### Sync method pruning
 
@@ -364,14 +366,16 @@ import { isAbortError, classifyError, HttpError } from 'mvc-kit';
 // In services — throw typed HTTP errors
 if (!res.ok) throw new HttpError(res.status, res.statusText);
 
-// In ViewModels — replace verbose AbortError checks
-if (isAbortError(e)) return;
+// In ViewModel catch blocks — guard shared-state side effects on abort
+if (!isAbortError(e)) rollback();
 
 // Classify any error into a canonical shape
 const appError = classifyError(error);
 // appError.code: 'unauthorized' | 'network' | 'timeout' | 'abort' | ...
 ```
 
+**When to use `isAbortError()`:** The async tracking wrapper swallows AbortErrors at the outer promise level, but your catch blocks do receive them. Use `isAbortError()` only when the catch block has side effects on shared state (like rolling back optimistic updates on a singleton Collection). You don't need it for `set()` or `emit()` (both are no-ops after dispose), and you never need it in methods without try/catch.
+
 ## Signal & Cleanup
 
 Every class in mvc-kit has a built-in `AbortSignal` and cleanup registration system. This eliminates the need to manually track timers, subscriptions, and in-flight requests.
@@ -685,7 +689,7 @@ function App() {
 |--------|-------------|
 | `AppError` (type) | Canonical error shape with typed `code` field |
 | `HttpError` | Typed HTTP error class for services to throw |
-| `isAbortError(error)` | Guard for AbortError DOMException |
+| `isAbortError(error)` | Guard for AbortError — use in catch blocks with shared-state side effects |
 | `classifyError(error)` | Maps raw errors → `AppError` |
 
 ### React Hooks
@@ -722,7 +726,7 @@ function App() {
 - ViewModel has built-in typed events via optional second generic `E` — `events` getter, `emit()` method
 - After `init()`, all subclass methods are wrapped for automatic async tracking; `vm.async.methodName` returns `TaskState`
 - Sync methods are auto-pruned on first call — zero overhead after detection
-- Async errors are re-thrown (preserves standard Promise rejection); AbortErrors are silently swallowed
+- Async errors are re-thrown (preserves standard Promise rejection); AbortErrors are silently swallowed by the wrapper (but internal catch blocks do receive them — use `isAbortError()` to guard shared-state side effects like Collection rollbacks)
 - `async` and `subscribeAsync` are reserved property names on ViewModel
 - React hooks (`useLocal`, `useModel`, `useSingleton`) auto-call `init()` after mount
 - `singleton()` does **not** auto-call `init()` — call it manually outside React

package/agent-config/claude-code/skills/guide/SKILL.md

@@ -35,7 +35,7 @@ You are assisting a developer using **mvc-kit**, a zero-dependency TypeScript-fi
 
 6. **Lifecycle**: `construct → init() → use → dispose()`. React hooks auto-call `init()`. Use `onInit()` for data loading.
 
-7. **Async tracking is automatic.** After `init()`, all async methods are tracked. `vm.async.methodName` returns `{ loading, error, errorCode }`. AbortErrors are silently swallowed. Other errors are captured AND re-thrown.
+7. **Async tracking is automatic.** After `init()`, all async methods are tracked. `vm.async.methodName` returns `{ loading, error, errorCode }`. AbortErrors are silently swallowed by the wrapper. Other errors are captured AND re-thrown. Internal catch blocks do receive AbortErrors — use `isAbortError()` only to guard shared-state side effects (like Collection rollbacks). `set()` and `emit()` don't need the guard (no-ops after dispose).
 
 8. **Pass `this.disposeSignal`** to every async call for automatic cancellation on unmount.
 

package/agent-config/claude-code/skills/guide/anti-patterns.md

@@ -175,9 +175,7 @@ async save() {
     await this.service.save(this.state.draft, this.disposeSignal);
     this.emit('saved', { id: this.state.draft.id });
   } catch (e) {
-    if (!isAbortError(e)) {
-      this.emit('error', { message: classifyError(e).message });
-    }
+    this.emit('error', { message: classifyError(e).message }); // no isAbortError guard needed — emit() is a no-op after dispose
     throw e; // async tracking captures the error
   }
 }
@@ -243,7 +241,7 @@ async toggleStatus(id: string) {
   try {
     await this.service.update(id, { status: 'done' }, this.disposeSignal);
   } catch (e) {
-    if (!isAbortError(e)) rollback();
+    if (!isAbortError(e)) rollback(); // guard needed — rollback affects shared Collection
     throw e;
   }
 }

package/agent-config/claude-code/skills/guide/api-reference.md

@@ -215,7 +215,7 @@ teardownAll()                 // Dispose all (use in test beforeEach)
 ## Error Utilities
 
 - `HttpError(status: number, statusText: string)` — Throw from services.
-- `isAbortError(error: unknown): boolean` — Guard for AbortError.
+- `isAbortError(error: unknown): boolean` — Guard for AbortError. Only needed in catch blocks with shared-state side effects (e.g., Collection rollbacks). Not needed for `set()`/`emit()` (no-ops after dispose) or methods without try/catch.
 - `classifyError(error: unknown): AppError` — Returns `{ code, message, status? }`.
   - Codes: `'unauthorized'`, `'forbidden'`, `'not_found'`, `'network'`, `'timeout'`, `'abort'`, `'server_error'`, `'unknown'`
 

package/agent-config/claude-code/skills/guide/patterns.md

@@ -104,18 +104,17 @@ async load() {
 
 No try/catch. No `set({ loading: true })`. No AbortError check. The framework handles it.
 
-**Only add try/catch** for imperative events on error:
+**Only add try/catch** for imperative events on error or optimistic rollbacks:
 
 ```typescript
+// Imperative events — no isAbortError guard needed (emit is a no-op after dispose)
 async save() {
   try {
     const result = await this.service.save(this.state.draft, this.disposeSignal);
     this.collection.update(result.id, result);
     this.emit('saved', { id: result.id });
   } catch (e) {
-    if (!isAbortError(e)) {
-      this.emit('error', { message: classifyError(e).message });
-    }
+    this.emit('error', { message: classifyError(e).message });
     throw e; // MUST re-throw so async tracking captures it
   }
 }
@@ -235,7 +234,7 @@ async toggleStatus(id: string) {
   try {
     await this.service.update(id, { status: 'done' }, this.disposeSignal);
   } catch (e) {
-    if (!isAbortError(e)) rollback();
+    if (!isAbortError(e)) rollback(); // guard needed — rollback affects shared Collection
     throw e; // re-throw for async tracking
   }
 }

package/agent-config/claude-code/skills/review/checklist.md

@@ -7,7 +7,7 @@
 2. **No derived state in State** — State must not contain values computable from other state (filtered lists, counts, flags). Use getters.
 3. **No `set()` inside getters** — Creates infinite loop. Derived values must be pure computations.
 4. **`disposeSignal` on async calls** — Every `fetch()`, service call, or async operation must receive `this.disposeSignal` or a composed signal.
-5. **Re-throw in try/catch** — Any explicit try/catch must re-throw the error so async tracking captures it. Only guard with `isAbortError()`.
+5. **Re-throw in try/catch** — Any explicit try/catch must re-throw the error so async tracking captures it. Use `isAbortError()` only to guard shared-state side effects (Collection rollbacks). Not needed for `set()`/`emit()` (no-ops after dispose).
 
 ### Warning
 6. **Section order** — Must follow: Private fields → Computed getters → Lifecycle → Actions → Setters.

package/agent-config/copilot/copilot-instructions.md

@@ -181,7 +181,7 @@ async toggleStatus(id: string) {
   try {
     await this.service.update(id, { status: 'done' }, this.disposeSignal);
   } catch (e) {
-    if (!isAbortError(e)) rollback();
+    if (!isAbortError(e)) rollback(); // guard needed — rollback affects shared Collection
     throw e;
   }
 }
@@ -190,9 +190,11 @@ async toggleStatus(id: string) {
 ## Error Handling Layers
 
 1. **Async tracking** (automatic): Write happy path, read `vm.async.method.error`
-2. **Imperative events** (explicit): try/catch + `emit()` + **re-throw**
+2. **Imperative events** (explicit): try/catch + `emit()` + **re-throw**. No `isAbortError()` guard needed — `emit()` and `set()` are no-ops after dispose.
 3. **Error classification** (services): `throw HttpError`, `classifyError()`
 
+**`isAbortError()` rule:** Only needed in catch blocks that affect shared state (Collection rollbacks). Not needed for `set()`/`emit()` or methods without try/catch.
+
 ## Testing
 
 ```typescript

package/agent-config/cursor/cursorrules

@@ -181,7 +181,7 @@ async toggleStatus(id: string) {
   try {
     await this.service.update(id, { status: 'done' }, this.disposeSignal);
   } catch (e) {
-    if (!isAbortError(e)) rollback();
+    if (!isAbortError(e)) rollback(); // guard needed — rollback affects shared Collection
     throw e;
   }
 }
@@ -190,9 +190,11 @@ async toggleStatus(id: string) {
 ## Error Handling Layers
 
 1. **Async tracking** (automatic): Write happy path, read `vm.async.method.error`
-2. **Imperative events** (explicit): try/catch + `emit()` + **re-throw**
+2. **Imperative events** (explicit): try/catch + `emit()` + **re-throw**. No `isAbortError()` guard needed — `emit()` and `set()` are no-ops after dispose.
 3. **Error classification** (services): `throw HttpError`, `classifyError()`
 
+**`isAbortError()` rule:** Only needed in catch blocks that affect shared state (Collection rollbacks). Not needed for `set()`/`emit()` or methods without try/catch.
+
 ## Testing
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mvc-kit",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "Zero-magic, class-based reactive ViewModel library",
   "type": "module",
   "main": "./dist/mvc-kit.cjs",