@statezero/core 0.2.41 → 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/dist/syncEngine/stores/operation.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Creates a membership state for a queryset with respect to an operation.
+ *
+ * @param {boolean} optimistic - Should we show this item immediately in the UI?
+ * @param {boolean} verify - Should remote sync check this queryset?
+ * @returns {{ optimistic: boolean, verify: boolean }}
+ *
+ * Usage patterns:
+ * - { optimistic: true, verify: false }  - Certain it belongs, show immediately
+ * - { optimistic: false, verify: false } - Certain it doesn't belong, skip entirely
+ * - { optimistic: false, verify: true }  - Uncertain, verify with server
+ */
+export function createMembershipState(optimistic: boolean, verify: boolean): {
+    optimistic: boolean;
+    verify: boolean;
+};
 export const operationEvents: any;
 export namespace Status {
     let CREATED: string;
@@ -24,11 +40,6 @@ export namespace Type {
     let SUM: string;
     let AGGREGATE: string;
 }
-export namespace OperationMembership {
-    let DEFINITELY_YES: string;
-    let DEFINITELY_NO: string;
-    let MAYBE: string;
-}
 export class Operation {
     constructor(data: any, restore?: boolean);
     operationId: any;
@@ -103,9 +114,12 @@ declare class OperationRegistry {
      * Sets the membership state for a queryset with respect to an operation.
      * @param {string} operationId - The operation ID
      * @param {string} semanticKey - The queryset's semantic key
-     * @param {string} state - One of OperationMembership values
+     * @param {{ optimistic: boolean, verify: boolean }} state - Membership state flags
      */
-    setQuerysetState(operationId: string, semanticKey: string, state: string): void;
+    setQuerysetState(operationId: string, semanticKey: string, state: {
+        optimistic: boolean;
+        verify: boolean;
+    }): void;
     /**
      * Gets the membership state for a queryset with respect to an operation.
      * @param {string} operationId - The operation ID

package/dist/syncEngine/stores/operation.js

@@ -43,14 +43,20 @@ export const Type = {
     AGGREGATE: 'aggregate',
 };
 /**
- * Membership state for a queryset with respect to an operation.
- * Used to track whether a queryset was evaluated for an operation and the result.
+ * Creates a membership state for a queryset with respect to an operation.
+ *
+ * @param {boolean} optimistic - Should we show this item immediately in the UI?
+ * @param {boolean} verify - Should remote sync check this queryset?
+ * @returns {{ optimistic: boolean, verify: boolean }}
+ *
+ * Usage patterns:
+ * - { optimistic: true, verify: false }  - Certain it belongs, show immediately
+ * - { optimistic: false, verify: false } - Certain it doesn't belong, skip entirely
+ * - { optimistic: false, verify: true }  - Uncertain, verify with server
  */
-export const OperationMembership = {
-    DEFINITELY_YES: 'definitely_yes', // Item matches filter, included in queryset
-    DEFINITELY_NO: 'definitely_no', // Item doesn't match filter, excluded from queryset
-    MAYBE: 'maybe', // Impossible to know based on slicing, needs server sync
-};
+export function createMembershipState(optimistic, verify) {
+    return { optimistic, verify };
+}
 export class Operation {
     constructor(data, restore = false) {
         _Operation__instances.set(this, void 0);
@@ -191,7 +197,7 @@ _Operation__instances = new WeakMap(), _Operation__frozenInstances = new WeakMap
 class OperationRegistry {
     constructor() {
         this._operations = new Map();
-        // Map<operationId, Map<semanticKey, OperationMembership>>
+        // Map<operationId, Map<semanticKey, { optimistic: boolean, verify: boolean }>>
         this._querysetStates = new Map();
     }
     /**
@@ -234,7 +240,7 @@ class OperationRegistry {
      * Sets the membership state for a queryset with respect to an operation.
      * @param {string} operationId - The operation ID
      * @param {string} semanticKey - The queryset's semantic key
-     * @param {string} state - One of OperationMembership values
+     * @param {{ optimistic: boolean, verify: boolean }} state - Membership state flags
      */
     setQuerysetState(operationId, semanticKey, state) {
         if (!this._querysetStates.has(operationId)) {

package/dist/syncEngine/stores/operationEventHandlers.js

@@ -1,4 +1,4 @@
-import { operationEvents, Status, Type, operationRegistry, OperationMembership } from './operation.js';
+import { operationEvents, Status, Type, operationRegistry, createMembershipState } from './operation.js';
 import { modelStoreRegistry } from '../registries/modelStoreRegistry.js';
 import { querysetStoreRegistry } from '../registries/querysetStoreRegistry.js';
 import { metricRegistry } from '../registries/metricRegistry.js';
@@ -7,14 +7,27 @@ import { QuerySet } from '../../flavours/django/querySet.js';
 import { isEqual, isNil } from 'lodash-es';
 import hash from 'object-hash';
 import { filter, applyOrderBy } from '../../filtering/localFiltering.js';
+/**
+ * Check if two model classes represent the same model.
+ * Uses property comparison instead of reference equality to handle
+ * cases where different instances represent the same model.
+ */
+function isSameModel(modelClassA, modelClassB) {
+    return modelClassA.modelName === modelClassB.modelName &&
+        modelClassA.configKey === modelClassB.configKey;
+}
 /**
  * Evaluates and routes a CREATE operation to querysets, tracking membership state.
  *
+ * Membership state has two flags:
+ * - optimistic: Should we show this item immediately in the UI?
+ * - verify: Should remote sync check this queryset?
+ *
  * For each queryset:
- * - If offset > 0: mark as MAYBE (can't determine position based on slicing)
- * - If item doesn't match filter: mark DEFINITELY_NO
- * - If item matches filter AND (no limit OR count < limit): mark DEFINITELY_YES
- * - If item matches filter AND count >= limit: mark MAYBE (ordering determines inclusion)
+ * - If offset > 0: { optimistic: false, verify: true } - can't determine position
+ * - If local filter says no match: { optimistic: false, verify: true } - local filtering unreliable
+ * - If item matches filter AND has room: { optimistic: true, verify: false } - show it
+ * - If at limit and ordering excludes: { optimistic: false, verify: false } - certain it's out
  *
  * @param {Operation} operation - The CREATE operation to route
  * @param {Function} applyAction - Function to apply the operation to a store
@@ -23,21 +36,23 @@ function routeCreateOperation(operation, applyAction) {
     const modelClass = operation.queryset.ModelClass;
     const instances = operation.instances;
     Array.from(querysetStoreRegistry._stores.entries()).forEach(([semanticKey, store]) => {
-        if (store.modelClass !== modelClass)
+        if (!isSameModel(store.modelClass, modelClass))
             return;
         const serializerOptions = store.queryset?._serializerOptions || {};
         const { offset, limit } = serializerOptions;
         // Offset > 0: can't determine position based on slicing
         if (offset != null && offset > 0) {
-            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.MAYBE);
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, true));
             return;
         }
         // Evaluate if instances match this queryset's filter
+        // Use fromPk to get live representation with proper FK structure
+        const liveInstances = instances.map(inst => modelClass.fromPk(inst[modelClass.primaryKeyField])).filter(Boolean);
         const ast = store.queryset.build();
-        const matchingInstances = filter(instances, ast, modelClass, true);
+        const matchingInstances = filter(liveInstances, ast, modelClass, true);
         if (matchingInstances.length === 0) {
-            // No instances match - mark DEFINITELY_NO (no need to sync this queryset)
-            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+            // Local filter says no match - trust it (local filtering is robust)
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, false));
             return;
         }
         // Item matches filter - check limit
@@ -59,7 +74,7 @@ function routeCreateOperation(operation, applyAction) {
                     const currentItems = renderedItems.filter(Boolean);
                     // If some ground truth items couldn't be rendered, we can't trust local sort
                     if (currentItems.length < store.groundTruthPks.length) {
-                        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.MAYBE);
+                        operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, true));
                         return;
                     }
                     const allItems = [...currentItems, ...matchingInstances];
@@ -72,15 +87,15 @@ function routeCreateOperation(operation, applyAction) {
                     const anyInTopN = newItemPks.some(pk => topNPks.has(pk));
                     if (anyInTopN) {
                         applyAction(store);
-                        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_YES);
+                        operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(true, false));
                     }
                     else {
-                        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+                        operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, false));
                     }
                 }
                 else {
                     // No ordering - new items go at end, won't be in first N
-                    operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+                    operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, false));
                 }
                 return;
             }
@@ -88,33 +103,35 @@ function routeCreateOperation(operation, applyAction) {
         }
         // Matches filter, has room or no limit - DEFINITELY_YES
         applyAction(store);
-        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_YES);
+        operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(true, false));
     });
 }
 /**
  * Evaluates and tracks membership state for UPDATE operations.
  *
- * For UPDATE, we check filter FIRST (optimization), then offset:
- * - If item didn't match before AND doesn't match after: DEFINITELY_NO (regardless of offset)
- * - If item matched before OR matches after AND offset > 0: MAYBE (can't determine position)
- * - If item matched before OR matches after AND offset = 0: DEFINITELY_YES
+ * For UPDATE, we check filter FIRST, then offset:
+ * - If local filter says no match: { optimistic: false, verify: true } - local filtering unreliable
+ * - If matched AND offset > 0: { optimistic: false, verify: true } - can't determine position
+ * - If matched AND offset = 0: { optimistic: true, verify: false } - show it
  *
  * @param {Operation} operation - The UPDATE operation
  */
 function routeUpdateOperation(operation) {
     const modelClass = operation.queryset.ModelClass;
+    // frozenInstances is already serialized with proper FK structure
     const beforeInstances = operation.frozenInstances;
-    const afterInstances = operation.instances;
+    // For after state, use fromPk to get current live representation
+    const afterInstances = operation.instances.map(inst => modelClass.fromPk(inst[modelClass.primaryKeyField])).filter(Boolean);
     Array.from(querysetStoreRegistry._stores.entries()).forEach(([semanticKey, store]) => {
-        if (store.modelClass !== modelClass)
+        if (!isSameModel(store.modelClass, modelClass))
             return;
         // Check filter match FIRST (optimization: skip offset check if no match)
         const ast = store.queryset.build();
         const matchedBefore = filter(beforeInstances, ast, modelClass, false).length > 0;
         const matchesAfter = filter(afterInstances, ast, modelClass, false).length > 0;
-        // If item never matched filter, definitely not affected (regardless of offset)
+        // If local filter says no match before AND after, trust it
         if (!matchedBefore && !matchesAfter) {
-            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, false));
             return;
         }
         // Item matches filter - now check offset
@@ -122,35 +139,36 @@ function routeUpdateOperation(operation) {
         const { offset } = serializerOptions;
         if (offset != null && offset > 0) {
             // Can't determine position in paginated window
-            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.MAYBE);
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, true));
             return;
         }
         // Item matched before OR matches after, no offset - definitely affected
-        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_YES);
+        operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(true, false));
     });
 }
 /**
  * Evaluates and tracks membership state for DELETE operations.
  *
- * For DELETE, we check filter FIRST (optimization), then offset:
- * - If item didn't match before: DEFINITELY_NO (regardless of offset)
- * - If item matched before AND offset > 0: MAYBE (can't determine position)
- * - If item matched before AND offset = 0: DEFINITELY_YES
+ * For DELETE, we check filter FIRST, then offset:
+ * - If local filter says no match: { optimistic: false, verify: true } - local filtering unreliable
+ * - If matched AND offset > 0: { optimistic: false, verify: true } - can't determine position
+ * - If matched AND offset = 0: { optimistic: true, verify: false } - show deletion
  *
  * @param {Operation} operation - The DELETE operation
  */
 function routeDeleteOperation(operation) {
     const modelClass = operation.queryset.ModelClass;
+    // frozenInstances is already serialized with proper FK structure
     const beforeInstances = operation.frozenInstances;
     Array.from(querysetStoreRegistry._stores.entries()).forEach(([semanticKey, store]) => {
-        if (store.modelClass !== modelClass)
+        if (!isSameModel(store.modelClass, modelClass))
             return;
         // Check filter match FIRST (optimization: skip offset check if no match)
         const ast = store.queryset.build();
         const matchedBefore = filter(beforeInstances, ast, modelClass, false).length > 0;
-        // If item never matched filter, definitely not affected (regardless of offset)
+        // If local filter says no match before, trust it
         if (!matchedBefore) {
-            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, false));
             return;
         }
         // Item matched filter - now check offset
@@ -158,11 +176,11 @@ function routeDeleteOperation(operation) {
         const { offset } = serializerOptions;
         if (offset != null && offset > 0) {
             // Can't determine position in paginated window
-            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.MAYBE);
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(false, true));
             return;
         }
         // Item matched before, no offset - definitely affected
-        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_YES);
+        operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(true, false));
     });
 }
 /**

package/dist/syncEngine/sync.d.ts

@@ -37,10 +37,11 @@ export class SyncManager {
     manageRegistry(registry: any): void;
     removeRegistry(registry: any): void;
     /**
-     * Sync querysets that were marked MAYBE for a local operation.
+     * Sync querysets that need verification for a local operation.
      * Called when a backend event arrives for an operation we initiated locally.
+     * Checks the `verify` flag on membership state to determine which querysets need syncing.
      */
-    syncMaybeQuerysets(operationId: any): void;
+    syncQuerysetsNeedingVerification(operationId: any): void;
     handleEvent: (event: any) => void;
     processBatch(reason?: string): void;
     isQuerysetFollowed(queryset: any): boolean;

package/dist/syncEngine/sync.js

@@ -1,5 +1,5 @@
 import { getAllEventReceivers } from "../core/eventReceivers.js";
-import { operationRegistry, OperationMembership } from "./stores/operation.js";
+import { operationRegistry } from "./stores/operation.js";
 import { initializeAllEventReceivers } from "../config.js";
 import { getEventReceiver } from "../core/eventReceivers.js";
 import { querysetStoreRegistry, QuerysetStoreRegistry, } from "./registries/querysetStoreRegistry.js";
@@ -57,7 +57,7 @@ export class SyncManager {
             if (isLocalOperation) {
                 // Check if any querysets were marked MAYBE for this operation
                 // These need to be synced since we couldn't determine membership client-side
-                this.syncMaybeQuerysets(payload.operation_id);
+                this.syncQuerysetsNeedingVerification(payload.operation_id);
                 return;
             }
             // Add to batch for queryset/model processing
@@ -241,10 +241,11 @@ export class SyncManager {
         this.registries.delete(registry.constructor);
     }
     /**
-     * Sync querysets that were marked MAYBE for a local operation.
+     * Sync querysets that need verification for a local operation.
      * Called when a backend event arrives for an operation we initiated locally.
+     * Checks the `verify` flag on membership state to determine which querysets need syncing.
      */
-    syncMaybeQuerysets(operationId) {
+    syncQuerysetsNeedingVerification(operationId) {
         const states = operationRegistry.getQuerysetStates(operationId);
         if (!states)
             return;
@@ -253,7 +254,8 @@ export class SyncManager {
             return;
         const storesToSync = [];
         for (const [semanticKey, membership] of states.entries()) {
-            if (membership === OperationMembership.MAYBE) {
+            // Check the verify flag - if true, this queryset needs server verification
+            if (membership?.verify) {
                 const store = registry._stores.get(semanticKey);
                 if (store) {
                     storesToSync.push(store);
@@ -262,7 +264,7 @@ export class SyncManager {
         }
         if (storesToSync.length === 0)
             return;
-        console.log(`[SyncManager] Syncing ${storesToSync.length} MAYBE querysets for local operation ${operationId}`);
+        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));
         Promise.all(storesToSync.map(store => registry.groupSync(store.queryset, syncOperationId, dbSyncedKeys)));

package/package.json

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