@yiin/reactive-proxy-state 2.0.0 → 3.0.0

package/dist/integrations/vue3.d.ts

@@ -1,6 +1,8 @@
 import type { StateEvent } from "../types";
 export type DiffErrorContext = {
+    /** The first key of `path`, or '' when the failure is in the root object itself. */
     key: string;
+    /** Path of the event whose listener threw, or of the object whose scan failed. */
     path: (string | number | symbol)[];
     error: unknown;
 };
@@ -9,22 +11,26 @@ export type TrackVueReactiveEventsOptions = {
     onDiffError?: (ctx: DiffErrorContext) => void;
 };
 export type VueTrackingControl = {
-    /** Stop all effects permanently. */
+    /** Stop tracking for good. A stopped tracker cannot restart: pause() and resume() after stop() only warn. */
     stop: () => void;
-    /** Stop all effects temporarily. No diffing overhead while paused. */
+    /** Stop sending events. Writes still keep the tracker's copy of the state in step, so resume() costs nothing. */
     pause: () => void;
-    /** Rebuild snapshots from current state and re-create effects. */
+    /** Send events again. Writes made while paused are never sent. */
     resume: () => void;
 };
 /**
  * Observe a Vue 3 reactive object and emit RPS-compatible StateEvents
  * for each mutation performed through Vue reactivity.
  *
- * Uses per-key watchEffect partitioning: one effect per root key so that
- * only the affected subtree is diffed on mutation. A root structural effect
- * tracks Object.keys() for key add/delete at the top level.
+ * Every object and array in the state gets its own small Vue effect (a node)
+ * that reads only its own entries, so a write re-runs only the node it changed.
+ * Each node keeps a plain copy of its entries and diffs against it with the
+ * rules 2.0.0 used, so the events are the same: leaf-level sets, deletes,
+ * array grows as per-index sets, shrinks as one `length` set, a type change as
+ * one whole-value set. A Map or Set is one node that reads the whole collection
+ * and emits `map-set` / `set-add` with whole values.
  *
- * Returns a control object with stop/pause/resume. Use pause/resume to
- * suppress diffing while applying external mutations (e.g. server events).
+ * Returns a control object with stop/pause/resume. Use pause/resume around
+ * writes that must not be sent back (e.g. server events).
  */
 export declare function trackVueReactiveEvents<T extends object>(vueState: T, emit: (event: StateEvent) => void, options?: TrackVueReactiveEventsOptions): VueTrackingControl;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yiin/reactive-proxy-state",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "author": "Yiin <stanislovas@yiin.lt>",
   "repository": {
     "type": "git",
@@ -10,13 +10,20 @@
   "module": "dist/index.js",
   "type": "module",
   "devDependencies": {
+    "@vue/reactivity": "^3.5.13",
     "bun-types": "^1.2.8",
     "typescript": "^5.0.4",
     "vitepress": "^1.6.3",
     "vue": "^3.5.13"
   },
   "peerDependencies": {
-    "vue": ">=3.2.0"
+    "@vue/reactivity": "^3.5.0",
+    "vue": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@vue/reactivity": {
+      "optional": true
+    }
   },
   "exports": {
     ".": {
@@ -52,7 +59,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target node --format esm --external vue && bun build src/index.ts --outfile dist/index.cjs --target node --format cjs --external vue && tsc --emitDeclarationOnly --outDir dist",
+    "build": "bun build src/index.ts --outdir dist --target node --format esm --external vue --external @vue/reactivity && bun build src/index.ts --outfile dist/index.cjs --target node --format cjs --external vue --external @vue/reactivity && tsc --emitDeclarationOnly --outDir dist",
     "test": "bun test",
     "test:watch": "bun test --watch",
     "test:bench": "bun --bun ./benchmarks/state-sync.bench.ts",