@statezero/core 0.2.42 → 0.2.44

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/dist/syncEngine/registries/querysetStoreRegistry.js

@@ -17,6 +17,7 @@ import { processQuery, getRequiredFields, pickRequiredFields } from '../../filte
 import { filter } from '../../filtering/localFiltering.js';
 import { makeApiCall } from '../../flavours/django/makeApiCall.js';
 import { QuerysetStoreGraph } from './querysetStoreGraph.js';
+import { getConfig } from '../../config.js';
 import { isNil, pick } from 'lodash-es';
 import hash from 'object-hash';
 import { Operation } from '../stores/operation.js';
@@ -291,10 +292,14 @@ export class QuerysetStoreRegistry {
             return;
         const semanticKey = queryset.semanticKey;
         const ModelClass = queryset.ModelClass;
-        // Convert dbSyncedKeys to semanticKeys if needed
+        // Convert dbSyncedKeys to semanticKeys, filtering to only keys that have stores
+        // A key without a store can never be a valid root (nobody would sync it)
         const subset = new Set();
         for (const item of dbSyncedKeys) {
-            subset.add(typeof item === 'string' ? item : item?.semanticKey);
+            const key = typeof item === 'string' ? item : item?.semanticKey;
+            if (key && this._stores.has(key)) {
+                subset.add(key);
+            }
         }
         // Find the dbSynced root
         const { isRoot, root: rootKey } = this.querysetStoreGraph.findRoot(queryset, subset);
@@ -319,8 +324,34 @@ export class QuerysetStoreRegistry {
             cached.resolve();
         }
         else {
-            // Wait for root to finish
-            await cached.promise;
+            // Wait for root to finish with timeout to prevent deadlocks
+            // Use 2x periodic sync interval (same as SyncManager.withTimeout) or 30s fallback
+            let syncTimeoutMs = 30000;
+            try {
+                const config = getConfig();
+                if (config.periodicSyncIntervalSeconds) {
+                    syncTimeoutMs = config.periodicSyncIntervalSeconds * 2000;
+                }
+            }
+            catch {
+                // Use default if no config
+            }
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => reject(new Error('timeout')), syncTimeoutMs);
+            });
+            let timedOut = false;
+            try {
+                await Promise.race([cached.promise, timeoutPromise]);
+            }
+            catch {
+                timedOut = true;
+            }
+            // Fallback to direct sync on timeout or if root data is missing
+            if (timedOut || !cached.pks) {
+                console.warn(`[groupSync] Falling back to direct sync for: ${semanticKey.substring(0, 60)}`);
+                await store.sync();
+                return;
+            }
             // Filter from cached root data
             const rootInstances = cached.pks.map(pk => ModelClass.fromPk(pk, queryset));
             const ast = queryset.build();

package/dist/syncEngine/sync.js

@@ -161,8 +161,10 @@ export class SyncManager {
             return;
         // Generate operationId for this sync batch - querysets in same chain will coordinate
         const operationId = `periodic-sync-${uuidv7()}`;
-        // Get dbSynced keys (followed querysets)
-        const dbSyncedKeys = new Set([...this.followedQuerysets].map(qs => qs.semanticKey));
+        // Get dbSynced keys (followed querysets that have stores)
+        const dbSyncedKeys = new Set([...this.followedQuerysets]
+            .map(qs => qs.semanticKey)
+            .filter(key => querysetRegistry._stores.has(key)));
         // Collect all stores to sync
         const storesToSync = [];
         for (const [semanticKey, store] of querysetRegistry._stores.entries()) {
@@ -266,7 +268,9 @@ export class SyncManager {
             return;
         console.log(`[SyncManager] Syncing ${storesToSync.length} querysets needing verification for operation ${operationId}`);
         const syncOperationId = `maybe-sync-${uuidv7()}`;
-        const dbSyncedKeys = new Set([...this.followedQuerysets].map(qs => qs.semanticKey));
+        const dbSyncedKeys = new Set([...this.followedQuerysets]
+            .map(qs => qs.semanticKey)
+            .filter(key => registry._stores.has(key)));
         Promise.all(storesToSync.map(store => registry.groupSync(store.queryset, syncOperationId, dbSyncedKeys)));
     }
     processBatch(reason = "unknown") {
@@ -345,8 +349,12 @@ export class SyncManager {
         console.log(`[SyncManager] Syncing ${storesToSync.length} queryset stores for ${representativeEvent.model}`);
         // Generate operationId for this batch - querysets in same chain will coordinate
         const operationId = `remote-event-${uuidv7()}`;
-        // Get dbSynced keys (followed querysets)
-        const dbSyncedKeys = new Set([...this.followedQuerysets].map(qs => qs.semanticKey));
+        // Get dbSynced keys (followed querysets that have stores)
+        // Filter to only include keys with stores - a queryset can be followed but not have
+        // a store if useQueryset doesn't call .fetch() (e.g., base queryset in a chain)
+        const dbSyncedKeys = new Set([...this.followedQuerysets]
+            .map(qs => qs.semanticKey)
+            .filter(key => registry._stores.has(key)));
         // Run all groupSync calls in parallel - they coordinate via shared promise cache
         Promise.all(storesToSync.map(store => registry.groupSync(store.queryset, operationId, dbSyncedKeys)));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statezero/core",
-  "version": "0.2.42",
+  "version": "0.2.44",
   "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",