@statezero/core 0.1.19 → 0.1.21

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

@@ -0,0 +1,21 @@
+/**
+ * Simple graph for tracking queryset store ancestry
+ */
+export class QuerysetStoreGraph {
+    constructor(hasStoreFn?: null);
+    graph: any;
+    hasStoreFn: () => boolean;
+    processedQuerysets: Set<any>;
+    setHasStoreFn(hasStoreFn: any): void;
+    /**
+     * Add a queryset and its parent relationship to the graph
+     */
+    addQueryset(queryset: any): void;
+    /**
+     * Find the root store for a queryset
+     * @param {Object} queryset - The queryset to analyze
+     * @returns {Object} { isRoot: boolean, root: semanticKey|null }
+     */
+    findRoot(queryset: Object): Object;
+    clear(): void;
+}

package/dist/syncEngine/registries/querysetStoreGraph.js

@@ -0,0 +1,93 @@
+import { Graph } from "graphlib";
+/**
+ * Simple graph for tracking queryset store ancestry
+ */
+export class QuerysetStoreGraph {
+    constructor(hasStoreFn = null) {
+        this.graph = new Graph({ directed: true });
+        this.hasStoreFn = hasStoreFn || (() => false);
+        this.processedQuerysets = new Set(); // Track UUIDs of processed querysets
+    }
+    setHasStoreFn(hasStoreFn) {
+        this.hasStoreFn = hasStoreFn;
+    }
+    /**
+     * Add a queryset and its parent relationship to the graph
+     */
+    addQueryset(queryset) {
+        if (!queryset)
+            return;
+        if (this.processedQuerysets.has(queryset.key)) {
+            return; // Already processed, skip
+        }
+        let current = queryset;
+        while (current && !this.processedQuerysets.has(current.key)) {
+            const currentKey = current.semanticKey;
+            const currentUuid = current.key;
+            this.processedQuerysets.add(currentUuid);
+            this.graph.setNode(currentKey);
+            if (current.__parent) {
+                const parentKey = current.__parent.semanticKey;
+                this.graph.setNode(parentKey);
+                this.graph.setEdge(currentKey, parentKey); // child -> parent
+                current = current.__parent;
+            }
+            else {
+                break;
+            }
+        }
+    }
+    /**
+     * Find the root store for a queryset
+     * @param {Object} queryset - The queryset to analyze
+     * @returns {Object} { isRoot: boolean, root: semanticKey|null }
+     */
+    findRoot(queryset) {
+        // Validate input - null/undefined is a programming error
+        if (!queryset) {
+            throw new Error("findRoot was called with a null object, instead of a queryset");
+        }
+        // Handle queryset without semanticKey
+        if (!queryset.semanticKey) {
+            throw new Error("findRoot was called on an object without a semanticKey, which means its not a queryset. findRoot only works on querysets");
+        }
+        const semanticKey = queryset.semanticKey;
+        if (!this.graph.hasNode(semanticKey)) {
+            this.addQueryset(queryset);
+        }
+        // Traverse ALL the way up to find the HIGHEST ancestor with a store
+        const visited = new Set();
+        let current = semanticKey;
+        let highestAncestorWithStore = null;
+        while (current && !visited.has(current)) {
+            visited.add(current);
+            // Check if current node has a store
+            if (this.hasStoreFn(current)) {
+                highestAncestorWithStore = current;
+            }
+            // Move to parent
+            const parents = this.graph.successors(current) || [];
+            if (parents.length > 0) {
+                current = parents[0]; // Follow the parent chain
+            }
+            else {
+                break; // No more parents
+            }
+        }
+        if (highestAncestorWithStore) {
+            if (highestAncestorWithStore === semanticKey) {
+                // This queryset itself is the highest with a store
+                return { isRoot: true, root: semanticKey };
+            }
+            else {
+                // Found a higher ancestor with a store
+                return { isRoot: false, root: highestAncestorWithStore };
+            }
+        }
+        // No stores found anywhere in the chain
+        return { isRoot: true, root: null };
+    }
+    clear() {
+        this.graph = new Graph({ directed: true });
+    }
+}

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

@@ -23,6 +23,7 @@ declare class QuerysetStoreRegistry {
     _tempStores: WeakMap<object, any>;
     followingQuerysets: Map<any, any>;
     syncManager: () => void;
+    querysetStoreGraph: QuerysetStoreGraph;
     clear(): void;
     setSyncManager(syncManager: any): void;
     /**
@@ -30,6 +31,13 @@ declare class QuerysetStoreRegistry {
      */
     addFollowingQueryset(semanticKey: any, queryset: any): void;
     getStore(queryset: any, seed?: boolean): any;
+    /**
+     * Function to return the root store for a queryset
+     */
+    getRootStore(queryset: any): {
+        isRoot: boolean;
+        rootStore: any;
+    };
     /**
      * Get the current state of the queryset, wrapped in a LiveQueryset
      * @param {Object} queryset - The queryset
@@ -52,4 +60,5 @@ declare class QuerysetStoreRegistry {
      */
     getAllStoresForModel(ModelClass: any): any[];
 }
+import { QuerysetStoreGraph } from './querysetStoreGraph.js';
 export {};

package/dist/syncEngine/registries/querysetStoreRegistry.js

@@ -16,11 +16,11 @@ import { wrapReactiveQuerySet } from '../../reactiveAdaptor.js';
 import { processQuery, getRequiredFields, pickRequiredFields } from '../../filtering/localFiltering.js';
 import { filter } from '../../filtering/localFiltering.js';
 import { makeApiCall } from '../../flavours/django/makeApiCall.js';
+import { QuerysetStoreGraph } from './querysetStoreGraph.js';
 import { isNil, pick } from 'lodash-es';
 import hash from 'object-hash';
 import { Operation } from '../stores/operation.js';
 import { Cache } from '../cache/cache.js';
-import { querysetGraph } from '../stores/querysetSemanticGraph.js';
 /**
  * A dynamic wrapper that always returns the latest queryset results
  * This class proxies array operations to always reflect the current state
@@ -107,6 +107,9 @@ class QuerysetStoreRegistry {
         this._tempStores = new WeakMap(); // WeakMap<Queryset, Store>
         this.followingQuerysets = new Map(); // Map<semanticKey, Set<queryset>>
         this.syncManager = () => { console.warn("SyncManager not set for QuerysetStoreRegistry"); };
+        this.querysetStoreGraph = new QuerysetStoreGraph((semanticKey) => {
+            return this._stores.has(semanticKey);
+        });
     }
     clear() {
         this._stores.forEach((store) => {
@@ -114,7 +117,7 @@ class QuerysetStoreRegistry {
         });
         this._stores = new Map();
         this.followingQuerysets = new Map();
-        querysetGraph.clear();
+        this.querysetStoreGraph.clear();
     }
     setSyncManager(syncManager) {
         this.syncManager = syncManager;
@@ -132,6 +135,7 @@ class QuerysetStoreRegistry {
         if (isNil(queryset) || isNil(queryset.ModelClass)) {
             throw new Error("QuerysetStoreRegistry.getStore requires a valid queryset");
         }
+        this.querysetStoreGraph.addQueryset(queryset);
         // Check if we already have a temporary store for this exact QuerySet instance
         if (this._tempStores.has(queryset)) {
             return this._tempStores.get(queryset);
@@ -158,17 +162,39 @@ class QuerysetStoreRegistry {
         let ast = queryset.build();
         let ModelClass = queryset.ModelClass;
         if (queryset.__parent && seed) {
-            let parentLiveQuerySet = this.getEntity(queryset.__parent);
-            initialGroundTruthPks = filter(parentLiveQuerySet, ast, ModelClass, false);
+            const parentKey = queryset.__parent.semanticKey;
+            if (this._stores.has(parentKey)) {
+                let parentLiveQuerySet = this.getEntity(queryset.__parent);
+                initialGroundTruthPks = filter(parentLiveQuerySet, ast, ModelClass, false);
+            }
         }
         // Get the parent registry    
         const store = new QuerysetStore(ModelClass, fetchQueryset, queryset, initialGroundTruthPks, // Initial ground truth PKs
-        null // Initial operations
-        );
+        null, // Initial operations
+        {
+            getRootStore: this.getRootStore.bind(this),
+            isTemp: true,
+        });
         // Store it in the temp store map
         this._tempStores.set(queryset, store);
         return store;
     }
+    /**
+     * Function to return the root store for a queryset
+     */
+    getRootStore(queryset) {
+        if (isNil(queryset)) {
+            throw new Error("QuerysetStoreRegistry.getRootStore requires a valid queryset");
+        }
+        const { isRoot, root } = this.querysetStoreGraph.findRoot(queryset);
+        const rootStore = this._stores.get(root);
+        if (!isRoot && rootStore) {
+            return { isRoot: false, rootStore: rootStore };
+        }
+        else {
+            return { isRoot: true, rootStore: null };
+        }
+    }
     /**
      * Get the current state of the queryset, wrapped in a LiveQueryset
      * @param {Object} queryset - The queryset
@@ -185,12 +211,14 @@ class QuerysetStoreRegistry {
         // If we have a temporary store, promote it
         if (this._tempStores.has(queryset)) {
             store = this._tempStores.get(queryset);
+            store.isTemp = false; // Promote to permanent store
             this._stores.set(semanticKey, store);
             this.syncManager.followModel(this, queryset.ModelClass);
         }
         // Otherwise, ensure we have a permanent store
         else if (!this._stores.has(semanticKey)) {
             store = this.getStore(queryset, seed);
+            store.isTemp = false;
             this._stores.set(semanticKey, store);
             this.syncManager.followModel(this, queryset.ModelClass);
         }
@@ -221,11 +249,13 @@ class QuerysetStoreRegistry {
             // If we have a temp store, promote it
             if (this._tempStores.has(queryset)) {
                 store = this._tempStores.get(queryset);
+                store.isTemp = false; // Promote to permanent store
                 this._stores.set(semanticKey, store);
             }
             else {
                 // Create a new permanent store
                 store = this.getStore(queryset);
+                store.isTemp = false;
                 this._stores.set(semanticKey, store);
             }
         }

package/dist/syncEngine/stores/operationEventHandlers.js

@@ -4,7 +4,6 @@ import { querysetStoreRegistry } from '../registries/querysetStoreRegistry.js';
 import { metricRegistry } from '../registries/metricRegistry.js';
 import { getFingerprint } from './utils.js';
 import { QuerySet } from '../../flavours/django/querySet.js';
-import { querysetGraph } from './querysetSemanticGraph.js';
 import { isEqual, isNil } from 'lodash-es';
 import hash from 'object-hash';
 /**
@@ -13,21 +12,27 @@ import hash from 'object-hash';
  * @returns {Map<QuerySet, Store>}
  */
 function relatedQuerysets(queryset) {
+    // Collect ancestor nodes for comparison
+    let ancestorNodes = [];
+    let current = queryset;
+    while (current) {
+        ancestorNodes.push(current.nodes);
+        current = current.__parent;
+    }
+    const modelClass = queryset.ModelClass;
     const result = new Map();
-    // Use the graph to get semantic ancestors instead of manual traversal
-    const semanticAncestors = querysetGraph.getSemanticAncestors(queryset);
-    // Convert querysets to Map<QuerySet, Store>
-    for (const qs of semanticAncestors) {
+    Array.from(querysetStoreRegistry._stores.entries()).forEach(([queryset, store]) => {
+        if (store.modelClass !== modelClass)
+            return;
         try {
-            const store = querysetStoreRegistry.getStore(qs);
-            if (store) {
-                result.set(qs, store);
+            if (ancestorNodes.some(nodes => isEqual(nodes, store.queryset.nodes))) {
+                result.set(store.queryset, store);
             }
         }
         catch (e) {
-            console.warn('Error getting store for related queryset', e);
+            console.warn('Error comparing nodes for related querysets', e);
         }
-    }
+    });
     return result;
 }
 /**

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

@@ -6,7 +6,11 @@ export class QuerysetStore {
     operationsMap: Map<any, any>;
     groundTruthPks: never[];
     isSyncing: boolean;
+    lastSync: number | null;
+    needsSync: boolean;
+    isTemp: any;
     pruneThreshold: any;
+    getRootStore: any;
     qsCache: Cache;
     get cacheKey(): any;
     onHydrated(hydratedData: any): void;
@@ -26,6 +30,8 @@ export class QuerysetStore {
     getInflightOperations(): any[];
     prune(): void;
     render(optimistic?: boolean, fromCache?: boolean): any[];
+    renderFromRoot(optimistic: boolean | undefined, rootStore: any): any[];
+    renderFromData(optimistic?: boolean): any[];
     applyOperation(operation: any, currentPks: any): any;
     sync(): Promise<void>;
 }

package/dist/syncEngine/stores/querysetStore.js

@@ -4,16 +4,21 @@ import { isNil, isEmpty, trim } from 'lodash-es';
 import { replaceTempPks, containsTempPk } from '../../flavours/django/tempPk.js';
 import { modelStoreRegistry } from '../registries/modelStoreRegistry.js';
 import { processIncludedEntities } from '../../flavours/django/makeApiCall.js';
-import { querysetGraph } from "./querysetSemanticGraph.js";
 import hash from 'object-hash';
 import { Cache } from '../cache/cache.js';
+import { filter } from "../../filtering/localFiltering.js";
+import { mod } from 'mathjs';
 export class QuerysetStore {
     constructor(modelClass, fetchFn, queryset, initialGroundTruthPks = null, initialOperations = null, options = {}) {
         this.modelClass = modelClass;
         this.fetchFn = fetchFn;
         this.queryset = queryset;
         this.isSyncing = false;
+        this.lastSync = null;
+        this.needsSync = false;
+        this.isTemp = options.isTemp || false;
         this.pruneThreshold = options.pruneThreshold || 10;
+        this.getRootStore = options.getRootStore || null;
         this.groundTruthPks = initialGroundTruthPks || [];
         this.operationsMap = new Map();
         if (Array.isArray(initialOperations)) {
@@ -23,8 +28,7 @@ export class QuerysetStore {
                 this.operationsMap.set(op.operationId, op);
             }
         }
-        this.qsCache = new Cache('queryset-cache', {}, this.onHydrated.bind(this));
-        querysetGraph.add(queryset);
+        this.qsCache = new Cache("queryset-cache", {}, this.onHydrated.bind(this));
     }
     // Caching
     get cacheKey() {
@@ -42,7 +46,7 @@ export class QuerysetStore {
     setCache(result) {
         let nonTempPks = [];
         result.forEach((pk) => {
-            if (typeof pk === 'string' && containsTempPk(pk)) {
+            if (typeof pk === "string" && containsTempPk(pk)) {
                 pk = replaceTempPks(pk);
                 if (isNil(pk) || isEmpty(trim(pk))) {
                     return;
@@ -95,9 +99,7 @@ export class QuerysetStore {
         this._emitRenderEvent();
     }
     async setGroundTruth(groundTruthPks) {
-        this.groundTruthPks = Array.isArray(groundTruthPks)
-            ? groundTruthPks
-            : [];
+        this.groundTruthPks = Array.isArray(groundTruthPks) ? groundTruthPks : [];
         this._emitRenderEvent();
     }
     async setOperations(operations) {
@@ -111,10 +113,10 @@ export class QuerysetStore {
     }
     getTrimmedOperations() {
         const cutoff = Date.now() - 1000 * 60 * 2;
-        return this.operations.filter(op => op.timestamp > cutoff);
+        return this.operations.filter((op) => op.timestamp > cutoff);
     }
     getInflightOperations() {
-        return this.operations.filter(operation => operation.status != Status.CONFIRMED &&
+        return this.operations.filter((operation) => operation.status != Status.CONFIRMED &&
             operation.status != Status.REJECTED);
     }
     prune() {
@@ -129,13 +131,16 @@ export class QuerysetStore {
                 return cachedResult;
             }
         }
-        const renderedPks = this.groundTruthSet;
-        for (const op of this.operations) {
-            if (op.status !== Status.REJECTED && (optimistic || op.status === Status.CONFIRMED)) {
-                this.applyOperation(op, renderedPks);
+        let result;
+        if (this.getRootStore && typeof this.getRootStore === "function" && !this.isTemp) {
+            const { isRoot, rootStore } = this.getRootStore(this.queryset);
+            if (!isRoot && rootStore) {
+                result = this.renderFromRoot(optimistic, rootStore);
             }
         }
-        let result = Array.from(renderedPks);
+        if (isNil(result)) {
+            result = this.renderFromData(optimistic);
+        }
         let limit = this.queryset.build().serializerOptions?.limit;
         if (limit) {
             result = result.slice(0, limit);
@@ -143,12 +148,30 @@ export class QuerysetStore {
         this.setCache(result);
         return result;
     }
+    renderFromRoot(optimistic = true, rootStore) {
+        let renderedPks = rootStore.render(optimistic);
+        let renderedData = renderedPks.map((pk) => {
+            return this.modelClass.fromPk(pk, this.queryset);
+        });
+        let ast = this.queryset.build();
+        let result = filter(renderedData, ast, this.modelClass, false);
+        return result;
+    }
+    renderFromData(optimistic = true) {
+        const renderedPks = this.groundTruthSet;
+        for (const op of this.operations) {
+            if (op.status !== Status.REJECTED &&
+                (optimistic || op.status === Status.CONFIRMED)) {
+                this.applyOperation(op, renderedPks);
+            }
+        }
+        let result = Array.from(renderedPks);
+        return result;
+    }
     applyOperation(operation, currentPks) {
         const pkField = this.pkField;
         for (const instance of operation.instances) {
-            if (!instance ||
-                typeof instance !== 'object' ||
-                !(pkField in instance)) {
+            if (!instance || typeof instance !== "object" || !(pkField in instance)) {
                 console.warn(`[QuerysetStore ${this.modelClass.modelName}] Skipping instance in operation ${operation.operationId} due to missing PK '${String(pkField)}' or invalid format.`);
                 continue;
             }
@@ -177,12 +200,25 @@ export class QuerysetStore {
             console.warn(`[QuerysetStore ${id}] Already syncing, request ignored.`);
             return;
         }
+        // Check if we're delegating to a root store
+        if (this.getRootStore && typeof this.getRootStore === "function" && !this.isTemp) {
+            const { isRoot, rootStore } = this.getRootStore(this.queryset);
+            if (!isRoot && rootStore) {
+                // We're delegating to a root store - don't sync, just mark as needing sync
+                console.log(`[${id}] Delegating to root store, marking sync needed.`);
+                this.needsSync = true;
+                this.lastSync = null; // Clear last sync since we're not actually syncing
+                this.setOperations(this.getInflightOperations());
+                return;
+            }
+        }
+        // We're in independent mode - proceed with normal sync
         this.isSyncing = true;
         console.log(`[${id}] Starting sync...`);
         try {
             const response = await this.fetchFn({
                 ast: this.queryset.build(),
-                modelClass: this.modelClass
+                modelClass: this.modelClass,
             });
             const { data, included } = response;
             console.log(`[${id}] Sync fetch completed. Received: ${JSON.stringify(data)}.`);
@@ -190,10 +226,13 @@ export class QuerysetStore {
             processIncludedEntities(modelStoreRegistry, included, this.modelClass);
             this.setGroundTruth(data);
             this.setOperations(this.getInflightOperations());
+            this.lastSync = Date.now();
+            this.needsSync = false;
             console.log(`[${id}] Sync completed.`);
         }
         catch (e) {
             console.error(`[${id}] Failed to sync ground truth:`, e);
+            this.needsSync = true; // Mark as needing sync on error
         }
         finally {
             this.isSyncing = false;

package/package.json

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

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

@@ -1,21 +0,0 @@
-export const querysetGraph: QuerysetGraph;
-/**
- * Simple graph using graphlib: AST nodes with parent edges
- */
-declare class QuerysetGraph {
-    graph: any;
-    clear(): void;
-    add(queryset: any): void;
-    /**
-     * Gets all querysets that share semantic equivalence with ancestors of the given queryset.
-     *
-     * This traverses up the parent chain to find all ancestor nodes (based on semanticId),
-     * then returns all querysets stored in those nodes that match the same model class.
-     * Querysets with the same semanticId are considered semantically equivalent (same AST structure).
-     *
-     * @param {QuerySet} queryset - The queryset to find semantic ancestors for
-     * @returns {QuerySet[]} Array of querysets that are semantically equivalent to ancestors
-     */
-    getSemanticAncestors(queryset: QuerySet): QuerySet[];
-}
-export {};

package/dist/syncEngine/stores/querysetSemanticGraph.js

@@ -1,58 +0,0 @@
-import { Graph, alg } from "graphlib";
-/**
- * Simple graph using graphlib: AST nodes with parent edges
- */
-class QuerysetGraph {
-    constructor() {
-        this.graph = new Graph({ directed: true });
-    }
-    clear() {
-        this.graph = new Graph({ directed: true });
-    }
-    add(queryset) {
-        const astId = queryset.semanticId;
-        // Get or create node data with Set
-        let nodeData = this.graph.node(astId);
-        if (!nodeData) {
-            nodeData = { querysets: new Set() };
-            this.graph.setNode(astId, nodeData);
-        }
-        // Add queryset to Set (automatically handles duplicates)
-        nodeData.querysets.add(queryset);
-        // Add parent edge if exists
-        if (queryset.__parent) {
-            const parentAstId = queryset.__parent.semanticId;
-            this.graph.setEdge(astId, parentAstId);
-        }
-    }
-    /**
-     * Gets all querysets that share semantic equivalence with ancestors of the given queryset.
-     *
-     * This traverses up the parent chain to find all ancestor nodes (based on semanticId),
-     * then returns all querysets stored in those nodes that match the same model class.
-     * Querysets with the same semanticId are considered semantically equivalent (same AST structure).
-     *
-     * @param {QuerySet} queryset - The queryset to find semantic ancestors for
-     * @returns {QuerySet[]} Array of querysets that are semantically equivalent to ancestors
-     */
-    getSemanticAncestors(queryset) {
-        const modelClass = queryset.ModelClass;
-        const result = [];
-        // Use graphlib to get all ancestors (including the node itself)
-        const ancestorNodeIds = alg.postorder(this.graph, [queryset.semanticId]);
-        // Collect all querysets from ancestor nodes
-        for (const nodeId of ancestorNodeIds) {
-            const nodeData = this.graph.node(nodeId);
-            if (!nodeData || !nodeData.querysets)
-                continue;
-            // Add all querysets from this node that match the model class
-            for (const qs of nodeData.querysets) {
-                if (qs.ModelClass === modelClass) {
-                    result.push(qs);
-                }
-            }
-        }
-        return result;
-    }
-}
-export const querysetGraph = new QuerysetGraph();