@statezero/core 0.2.31 → 0.2.32

package/dist/syncEngine/registries/querysetStoreGraph.d.ts

@@ -21,11 +21,21 @@ export class QuerysetStoreGraph {
     /**
      * Check if parent queryset is a valid data source for creating an edge.
      * Parent must have data that is a superset of what child needs.
+     * Child with offset must sync independently (can't derive window from parent).
      *
      * @param {Object} parentOpts - Parent's serializerOptions
      * @param {Object} childOpts - Child's serializerOptions
+     * @param {Array|undefined} parentOrderBy - Parent's ordering
+     * @param {Array|undefined} childOrderBy - Child's ordering
      * @returns {boolean} - True if parent is valid for edge creation
      */
-    _isValidParentForEdge(parentOpts?: Object, childOpts?: Object): boolean;
+    _isValidParentForEdge(parentOpts: Object | undefined, childOpts: Object | undefined, parentOrderBy: any[] | undefined, childOrderBy: any[] | undefined): boolean;
+    /**
+     * Check if two orderings are equivalent.
+     * @param {Array|undefined} orderBy1
+     * @param {Array|undefined} orderBy2
+     * @returns {boolean}
+     */
+    _orderingsMatch(orderBy1: any[] | undefined, orderBy2: any[] | undefined): boolean;
     clear(): void;
 }

package/dist/syncEngine/registries/querysetStoreGraph.js

@@ -28,7 +28,7 @@ export class QuerysetStoreGraph {
                 // Determine if we can create an edge to parent
                 // Parent must be a valid data source (superset of child's data needs)
                 const canLinkToParent = currentKey !== parentKey &&
-                    this._isValidParentForEdge(current.__parent._serializerOptions, current._serializerOptions);
+                    this._isValidParentForEdge(current.__parent._serializerOptions, current._serializerOptions, current.__parent._orderBy, current._orderBy);
                 if (canLinkToParent) {
                     this.graph.setEdge(currentKey, parentKey);
                 }
@@ -98,17 +98,35 @@ export class QuerysetStoreGraph {
     /**
      * Check if parent queryset is a valid data source for creating an edge.
      * Parent must have data that is a superset of what child needs.
+     * Child with offset must sync independently (can't derive window from parent).
      *
      * @param {Object} parentOpts - Parent's serializerOptions
      * @param {Object} childOpts - Child's serializerOptions
+     * @param {Array|undefined} parentOrderBy - Parent's ordering
+     * @param {Array|undefined} childOrderBy - Child's ordering
      * @returns {boolean} - True if parent is valid for edge creation
      */
-    _isValidParentForEdge(parentOpts = {}, childOpts = {}) {
-        // Cannot link if parent has pagination (limit/offset)
-        // Paginated parent only has a subset of data
-        if (parentOpts.limit != null || parentOpts.offset != null) {
+    _isValidParentForEdge(parentOpts = {}, childOpts = {}, parentOrderBy, childOrderBy) {
+        // Cannot link if parent has offset > 0 (paginated parent has subset of data)
+        // Note: offset: 0 is treated as no offset (start from beginning)
+        if (parentOpts.offset != null && parentOpts.offset > 0) {
             return false;
         }
+        // Cannot link if parent has limit - child may need items beyond parent's limit window
+        // (filtered items matching child could exist beyond parent's limit cutoff)
+        // If child has same filter + same limit, they'd have same semanticKey (no edge needed)
+        if (parentOpts.limit != null) {
+            return false;
+        }
+        // Cannot link if child has offset > 0 - must sync independently
+        // We can't derive which items are at positions N-M from the parent's full data
+        // because that requires the server's ordering logic
+        // Note: offset: 0 is treated as no offset (start from beginning)
+        if (childOpts.offset != null && childOpts.offset > 0) {
+            return false;
+        }
+        // Note: ordering doesn't matter for linking since parent has no limit (checked above)
+        // Parent has all items, so child can re-sort locally regardless of ordering
         // Cannot link if parent has different depth
         // Different depth means different nested data structure
         if (parentOpts.depth != null && parentOpts.depth !== childOpts.depth) {
@@ -130,6 +148,25 @@ export class QuerysetStoreGraph {
         }
         return true;
     }
+    /**
+     * Check if two orderings are equivalent.
+     * @param {Array|undefined} orderBy1
+     * @param {Array|undefined} orderBy2
+     * @returns {boolean}
+     */
+    _orderingsMatch(orderBy1, orderBy2) {
+        // Both undefined/null = match
+        if (!orderBy1 && !orderBy2)
+            return true;
+        // One defined, one not = no match
+        if (!orderBy1 || !orderBy2)
+            return false;
+        // Different lengths = no match
+        if (orderBy1.length !== orderBy2.length)
+            return false;
+        // Compare each field
+        return orderBy1.every((field, i) => field === orderBy2[i]);
+    }
     clear() {
         this.graph = new Graph({ directed: true });
         this.processedQuerysets = new Set();

package/dist/syncEngine/stores/operation.d.ts

@@ -24,6 +24,11 @@ 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;
@@ -72,6 +77,7 @@ export class Operation {
 export const operationRegistry: OperationRegistry;
 declare class OperationRegistry {
     _operations: Map<any, any>;
+    _querysetStates: Map<any, any>;
     /**
      * Registers a pre-constructed Operation instance in the registry.
      * Ensures the operationId is unique within the registry.
@@ -93,9 +99,41 @@ declare class OperationRegistry {
      * @returns {boolean} True if the operation exists, false otherwise.
      */
     has(operationId: string): boolean;
+    /**
+     * 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
+     */
+    setQuerysetState(operationId: string, semanticKey: string, state: string): void;
+    /**
+     * Gets 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
+     * @returns {string|undefined} The membership state, or undefined if not set
+     */
+    getQuerysetState(operationId: string, semanticKey: string): string | undefined;
+    /**
+     * Gets all queryset states for an operation.
+     * @param {string} operationId - The operation ID
+     * @returns {Map<string, string>|undefined} Map of semanticKey -> state, or undefined
+     */
+    getQuerysetStates(operationId: string): Map<string, string> | undefined;
     /**
      * Clears all operations from the registry.
      */
     clear(): void;
+    /**
+     * Gets the most recently registered operation.
+     * Useful for testing when you need to find the operation created by the last action.
+     * @returns {Operation | undefined} The most recent operation or undefined if empty.
+     */
+    getLatest(): Operation | undefined;
+    /**
+     * Gets the most recently registered operation of a specific type.
+     * @param {string} type - The operation type (e.g., Type.CREATE, Type.UPDATE)
+     * @returns {Operation | undefined} The most recent operation of that type or undefined.
+     */
+    getLatestByType(type: string): Operation | undefined;
 }
 export {};

package/dist/syncEngine/stores/operation.js

@@ -42,6 +42,15 @@ export const Type = {
     SUM: 'sum',
     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.
+ */
+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 class Operation {
     constructor(data, restore = false) {
         _Operation__instances.set(this, void 0);
@@ -182,6 +191,8 @@ _Operation__instances = new WeakMap(), _Operation__frozenInstances = new WeakMap
 class OperationRegistry {
     constructor() {
         this._operations = new Map();
+        // Map<operationId, Map<semanticKey, OperationMembership>>
+        this._querysetStates = new Map();
     }
     /**
      * Registers a pre-constructed Operation instance in the registry.
@@ -219,13 +230,62 @@ class OperationRegistry {
     has(operationId) {
         return this._operations.has(operationId);
     }
+    /**
+     * 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
+     */
+    setQuerysetState(operationId, semanticKey, state) {
+        if (!this._querysetStates.has(operationId)) {
+            this._querysetStates.set(operationId, new Map());
+        }
+        this._querysetStates.get(operationId).set(semanticKey, state);
+    }
+    /**
+     * Gets 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
+     * @returns {string|undefined} The membership state, or undefined if not set
+     */
+    getQuerysetState(operationId, semanticKey) {
+        const states = this._querysetStates.get(operationId);
+        return states ? states.get(semanticKey) : undefined;
+    }
+    /**
+     * Gets all queryset states for an operation.
+     * @param {string} operationId - The operation ID
+     * @returns {Map<string, string>|undefined} Map of semanticKey -> state, or undefined
+     */
+    getQuerysetStates(operationId) {
+        return this._querysetStates.get(operationId);
+    }
     /**
      * Clears all operations from the registry.
      */
     clear() {
         console.log("OperationRegistry: Clearing all operations.");
         this._operations.clear();
+        this._querysetStates.clear();
         operationEvents.emit(Status.CLEAR);
     }
+    /**
+     * Gets the most recently registered operation.
+     * Useful for testing when you need to find the operation created by the last action.
+     * @returns {Operation | undefined} The most recent operation or undefined if empty.
+     */
+    getLatest() {
+        const ops = Array.from(this._operations.values());
+        return ops.length > 0 ? ops[ops.length - 1] : undefined;
+    }
+    /**
+     * Gets the most recently registered operation of a specific type.
+     * @param {string} type - The operation type (e.g., Type.CREATE, Type.UPDATE)
+     * @returns {Operation | undefined} The most recent operation of that type or undefined.
+     */
+    getLatestByType(type) {
+        const ops = Array.from(this._operations.values()).filter(op => op.type === type);
+        return ops.length > 0 ? ops[ops.length - 1] : undefined;
+    }
 }
 export const operationRegistry = new OperationRegistry();

package/dist/syncEngine/stores/operationEventHandlers.js

@@ -1,4 +1,4 @@
-import { operationEvents, Status, Type } from './operation.js';
+import { operationEvents, Status, Type, operationRegistry, OperationMembership } from './operation.js';
 import { modelStoreRegistry } from '../registries/modelStoreRegistry.js';
 import { querysetStoreRegistry } from '../registries/querysetStoreRegistry.js';
 import { metricRegistry } from '../registries/metricRegistry.js';
@@ -6,22 +6,136 @@ import { getFingerprint } from './utils.js';
 import { QuerySet } from '../../flavours/django/querySet.js';
 import { isEqual, isNil } from 'lodash-es';
 import hash from 'object-hash';
+import { filter } from '../../filtering/localFiltering.js';
 /**
- * Returns all querysets (stores) for the same model.
- * Each queryset has its own ground truth and applies local filtering.
- * @param {QuerySet} queryset
- * @returns {Map<QuerySet, Store>}
+ * Evaluates and routes a CREATE operation to querysets, tracking membership state.
+ *
+ * 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)
+ *
+ * @param {Operation} operation - The CREATE operation to route
+ * @param {Function} applyAction - Function to apply the operation to a store
+ */
+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)
+            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);
+            return;
+        }
+        // Evaluate if instances match this queryset's filter
+        const ast = store.queryset.build();
+        const matchingInstances = filter(instances, ast, modelClass, false);
+        if (matchingInstances.length === 0) {
+            // No instances match - mark DEFINITELY_NO (no need to sync this queryset)
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+            return;
+        }
+        // Item matches filter - check limit
+        if (limit != null) {
+            const currentCount = store.groundTruthPks?.length || 0;
+            // At capacity: check if ordering could affect position
+            if (currentCount >= limit) {
+                const hasCustomOrdering = store.queryset._orderBy && store.queryset._orderBy.length > 0;
+                if (hasCustomOrdering) {
+                    // With ordering, new item could displace existing items - can't know without server
+                    operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.MAYBE);
+                }
+                else {
+                    // No ordering - new items go at end, won't be in first N
+                    operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+                }
+                return;
+            }
+            // Room for some or all items - continue to DEFINITELY_YES below
+        }
+        // Matches filter, has room or no limit - DEFINITELY_YES
+        applyAction(store);
+        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_YES);
+    });
+}
+/**
+ * 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
+ *
+ * @param {Operation} operation - The UPDATE operation
  */
-function getAllQuerysets(queryset) {
-    const modelClass = queryset.ModelClass;
-    const result = new Map();
-    // Route to all stores for this model
+function routeUpdateOperation(operation) {
+    const modelClass = operation.queryset.ModelClass;
+    const beforeInstances = operation.frozenInstances;
+    const afterInstances = operation.instances;
     Array.from(querysetStoreRegistry._stores.entries()).forEach(([semanticKey, store]) => {
         if (store.modelClass !== modelClass)
             return;
-        result.set(store.queryset, store);
+        // 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 (!matchedBefore && !matchesAfter) {
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+            return;
+        }
+        // Item matches filter - now check offset
+        const serializerOptions = store.queryset?._serializerOptions || {};
+        const { offset } = serializerOptions;
+        if (offset != null && offset > 0) {
+            // Can't determine position in paginated window
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.MAYBE);
+            return;
+        }
+        // Item matched before OR matches after, no offset - definitely affected
+        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_YES);
+    });
+}
+/**
+ * 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
+ *
+ * @param {Operation} operation - The DELETE operation
+ */
+function routeDeleteOperation(operation) {
+    const modelClass = operation.queryset.ModelClass;
+    const beforeInstances = operation.frozenInstances;
+    Array.from(querysetStoreRegistry._stores.entries()).forEach(([semanticKey, store]) => {
+        if (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 (!matchedBefore) {
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+            return;
+        }
+        // Item matched filter - now check offset
+        const serializerOptions = store.queryset?._serializerOptions || {};
+        const { offset } = serializerOptions;
+        if (offset != null && offset > 0) {
+            // Can't determine position in paginated window
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.MAYBE);
+            return;
+        }
+        // Item matched before, no offset - definitely affected
+        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_YES);
     });
-    return result;
 }
 /**
  * Process an operation in the model store
@@ -77,32 +191,40 @@ function processQuerysetStores(operation, actionType) {
         }
     };
     let querysetStoreMap;
-    // Route to all querysets for the model - each applies local filtering
+    // Route to querysets based on operation type
+    // All operation types track membership state for sync optimization
+    // CREATE: adds operation to store + tracks membership
+    // UPDATE/DELETE: only tracks membership (model store + reactivity handles rendering)
     switch (operation.type) {
         case Type.CREATE:
         case Type.BULK_CREATE:
         case Type.GET_OR_CREATE:
         case Type.UPDATE_OR_CREATE:
-            // For creates, route to all querysets (each checks if new item matches its filter)
-            querysetStoreMap = getAllQuerysets(queryset);
-            break;
+            // For creates, evaluate each queryset and track membership state
+            // This allows us to skip syncing querysets that we know don't contain the item
+            routeCreateOperation(operation, applyAction);
+            return;
         case Type.UPDATE:
         case Type.UPDATE_INSTANCE:
+            // Track membership for sync optimization
+            // Check both before (frozenInstances) and after (instances) state
+            routeUpdateOperation(operation);
+            return;
         case Type.DELETE:
         case Type.DELETE_INSTANCE:
-            // Model store handles the change, querysets re-render via local filtering
-            querysetStoreMap = new Map();
-            break;
+            // Track membership for sync optimization
+            // Check before state only (item being deleted)
+            routeDeleteOperation(operation);
+            return;
         case Type.CHECKPOINT:
             // Model store handles the change, querysets re-render via local filtering
-            querysetStoreMap = new Map();
-            break;
+            // No membership tracking needed for checkpoints
+            return;
         default:
-            // For other operation types, route to all querysets
-            querysetStoreMap = getAllQuerysets(queryset);
-            break;
+            // For other operation types, route like creates
+            routeCreateOperation(operation, applyAction);
+            return;
     }
-    Array.from(querysetStoreMap.values()).forEach(applyAction);
 }
 /**
  * Process an operation in the metric stores

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statezero/core",
-  "version": "0.2.31",
+  "version": "0.2.32",
   "type": "module",
   "module": "ESNext",
   "description": "The type-safe frontend client for StateZero - connect directly to your backend models with zero boilerplate",