@statezero/core 0.2.42 → 0.2.43

package/dist/adaptors/vue/composables.js

@@ -32,6 +32,9 @@ export function useQueryset(querysetFactory) {
             updateSyncManager();
             lastQueryset = queryset;
         }
+        // Access __version to establish Vue dependency tracking for watch()
+        // This makes the computed re-evaluate when queryset data changes
+        const _ = result?.__version;
         return result;
     });
 }

package/dist/adaptors/vue/reactivity.js

@@ -1,3 +1,56 @@
+/**
+ * Vue Reactivity Adapters for StateZero
+ *
+ * This module bridges StateZero's event-based reactivity (mitt) with Vue's reactivity system.
+ *
+ * ## How It Works
+ *
+ * StateZero emits events via mitt when data changes. These adapters:
+ * 1. Wrap data in Vue's reactive() or ref()
+ * 2. Listen for mitt events
+ * 3. Update the reactive wrapper when events fire
+ *
+ * ## Queryset Reactivity
+ *
+ * Querysets are wrapped as **stable reactive arrays**. The same object reference is
+ * maintained across updates - data is mutated in place via splice/push. This is
+ * intentional:
+ *
+ * - Templates automatically re-render (Vue tracks array mutations)
+ * - Object identity stays stable (no stale references in UI code)
+ * - Cached wrappers are reused for the same queryset
+ *
+ * ### Watching Querysets
+ *
+ * Because the object reference is stable, Vue's shallow watch won't detect changes.
+ * Use one of these patterns:
+ *
+ * ```js
+ * const messages = useQueryset(() => baseQs.value.fetch())
+ *
+ * // Option 1: Deep watch (recommended)
+ * watch(messages, (newMessages) => {
+ *   scrollToBottom()
+ * }, { deep: true })
+ *
+ * // Option 2: Watch a derived value
+ * watch(() => messages.value.length, (newLen) => {
+ *   scrollToBottom()
+ * })
+ * ```
+ *
+ * ### The __version Mechanism
+ *
+ * Each queryset wrapper has a `__version` counter that increments on every update.
+ * The `useQueryset` composable accesses this to establish Vue dependency tracking,
+ * ensuring the computed re-evaluates when data changes. This makes `{ deep: true }`
+ * watches work correctly.
+ *
+ * ## Model Reactivity
+ *
+ * Models use a similar `__version` / `touch()` mechanism. When a model is updated,
+ * `touch()` increments the version, triggering Vue to re-render dependent components.
+ */
 import { reactive, ref, nextTick } from "vue";
 import { modelEventEmitter, querysetEventEmitter, metricEventEmitter } from "../../syncEngine/stores/reactivity.js";
 import { initEventHandler } from "../../syncEngine/stores/operationEventHandlers.js";
@@ -66,6 +119,7 @@ export function QuerySetAdaptor(liveQuerySet, reactivityFn = reactive) {
     // Make the queryset reactive using the specified function
     const wrapper = reactivityFn([...liveQuerySet]);
     wrapper.original = liveQuerySet;
+    wrapper.__version = 0;
     const eventName = `${configKey}::${modelName}::queryset::render`;
     // Handler bumps version to trigger Vue reactivity when this queryset updates
     const renderHandler = (eventData) => {
@@ -77,6 +131,8 @@ export function QuerySetAdaptor(liveQuerySet, reactivityFn = reactive) {
                 wrapper.splice(0, wrapper.length);
                 wrapper.push(...liveQuerySet);
             }
+            // Bump version so computed/watch can track changes
+            wrapper.__version++;
         }
     };
     // Subscribe to queryset events indefinitely

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statezero/core",
-  "version": "0.2.42",
+  "version": "0.2.43",
   "type": "module",
   "module": "ESNext",
   "description": "The type-safe frontend client for StateZero - connect directly to your backend models with zero boilerplate",
@@ -115,8 +115,10 @@
     "@types/yargs": "^17.0.32",
     "@vitejs/plugin-vue": "^6.0.4",
     "@vitest/coverage-v8": "^3.0.5",
+    "@vue/test-utils": "^2.4.6",
     "fake-indexeddb": "^6.0.0",
     "fast-glob": "^3.3.3",
+    "happy-dom": "^20.5.0",
     "react": "^18.2.0",
     "rimraf": "^5.0.5",
     "ts-node": "^10.9.2",