@statezero/core 0.2.10 → 0.2.11

package/dist/adaptors/vue/reactivity.d.ts

@@ -16,29 +16,3 @@ export function ModelAdaptor(modelInstance: Object, reactivityFn?: Function): an
  */
 export function QuerySetAdaptor(liveQuerySet: Object, reactivityFn?: Function): any | import("vue").Ref;
 export function MetricAdaptor(metric: any): any;
-export const modelEventBatcher: ModelEventBatcher;
-export const BATCH_THRESHOLD: 50;
-/**
- * Batches model events and decides whether to use fine-grained (touch) or
- * coarse-grained (queryset refresh) reactivity based on batch size.
- */
-declare class ModelEventBatcher {
-    pendingTouches: Map<any, any>;
-    debounceTimers: Map<any, any>;
-    maxWaitTimers: Map<any, any>;
-    processQueue: PQueue<import("p-queue/dist/priority-queue.js").default, import("p-queue").QueueAddOptions>;
-    /**
-     * Queue a touch call for batching
-     */
-    queueTouch(configKey: any, modelName: any, pk: any, wrapper: any): void;
-    _resetDebounce(modelKey: any): void;
-    _ensureMaxWait(modelKey: any): void;
-    _clearTimers(modelKey: any): void;
-    _flush(modelKey: any): void;
-    _processBatch(modelKey: any, touchBatch: any): void;
-    _touchModels(touchBatch: any): void;
-    _refreshQuerysets(modelKey: any): void;
-    clear(): void;
-}
-import PQueue from "p-queue";
-export {};

package/dist/adaptors/vue/reactivity.js

@@ -4,154 +4,9 @@ import { initEventHandler } from "../../syncEngine/stores/operationEventHandlers
 import { isEqual, isNil } from 'lodash-es';
 import hash from 'object-hash';
 import { registerAdapterReset } from "../../reset.js";
-import PQueue from "p-queue";
 initEventHandler();
 const wrappedQuerysetCache = new Map();
 const wrappedMetricCache = new Map();
-// =============================================================================
-// Model Event Batcher - Batches rapid model events to prevent watcher overload
-// =============================================================================
-const BATCH_THRESHOLD = 50; // Above this, use queryset refresh instead of individual touch
-const DEBOUNCE_MS = 16; // ~1 frame, gather rapid events
-const MAX_WAIT_MS = 100; // Don't wait longer than this to flush
-/**
- * Batches model events and decides whether to use fine-grained (touch) or
- * coarse-grained (queryset refresh) reactivity based on batch size.
- */
-class ModelEventBatcher {
-    constructor() {
-        // Queue of pending touch calls: Map<modelKey, Map<pk, Set<wrapper>>>
-        this.pendingTouches = new Map();
-        // Debounce timers per model
-        this.debounceTimers = new Map();
-        // Max wait timers per model
-        this.maxWaitTimers = new Map();
-        // Rate-limited queue for processing
-        this.processQueue = new PQueue({
-            concurrency: 1,
-            interval: 16, // ~1 frame
-            intervalCap: 10 // max 10 flushes per frame
-        });
-    }
-    /**
-     * Queue a touch call for batching
-     */
-    queueTouch(configKey, modelName, pk, wrapper) {
-        const modelKey = `${configKey}::${modelName}`;
-        // Initialize maps if needed
-        if (!this.pendingTouches.has(modelKey)) {
-            this.pendingTouches.set(modelKey, new Map());
-        }
-        const pkMap = this.pendingTouches.get(modelKey);
-        if (!pkMap.has(pk)) {
-            pkMap.set(pk, new Set());
-        }
-        pkMap.get(pk).add(wrapper);
-        // Reset debounce timer
-        this._resetDebounce(modelKey);
-        // Start max wait timer if not already running
-        this._ensureMaxWait(modelKey);
-    }
-    _resetDebounce(modelKey) {
-        // Clear existing debounce
-        if (this.debounceTimers.has(modelKey)) {
-            clearTimeout(this.debounceTimers.get(modelKey));
-        }
-        // Set new debounce
-        const timer = setTimeout(() => {
-            this._flush(modelKey);
-        }, DEBOUNCE_MS);
-        this.debounceTimers.set(modelKey, timer);
-    }
-    _ensureMaxWait(modelKey) {
-        if (this.maxWaitTimers.has(modelKey)) {
-            return; // Already waiting
-        }
-        const timer = setTimeout(() => {
-            this._flush(modelKey);
-        }, MAX_WAIT_MS);
-        this.maxWaitTimers.set(modelKey, timer);
-    }
-    _clearTimers(modelKey) {
-        if (this.debounceTimers.has(modelKey)) {
-            clearTimeout(this.debounceTimers.get(modelKey));
-            this.debounceTimers.delete(modelKey);
-        }
-        if (this.maxWaitTimers.has(modelKey)) {
-            clearTimeout(this.maxWaitTimers.get(modelKey));
-            this.maxWaitTimers.delete(modelKey);
-        }
-    }
-    _flush(modelKey) {
-        this._clearTimers(modelKey);
-        const pkMap = this.pendingTouches.get(modelKey);
-        if (!pkMap || pkMap.size === 0) {
-            return;
-        }
-        // Take the pending touches and clear
-        const touchBatch = new Map(pkMap);
-        pkMap.clear();
-        // Queue for rate-limited processing
-        this.processQueue.add(() => this._processBatch(modelKey, touchBatch));
-    }
-    _processBatch(modelKey, touchBatch) {
-        const batchSize = touchBatch.size;
-        if (batchSize < BATCH_THRESHOLD) {
-            // Small batch: fine-grained touch for each model
-            this._touchModels(touchBatch);
-        }
-        else {
-            // Large batch: refresh all querysets for this model instead
-            this._refreshQuerysets(modelKey);
-        }
-    }
-    _touchModels(touchBatch) {
-        // Call touch() on each wrapper
-        for (const [pk, wrappers] of touchBatch) {
-            for (const wrapper of wrappers) {
-                try {
-                    wrapper.touch();
-                }
-                catch (e) {
-                    console.warn('[ModelEventBatcher] Error touching model:', e);
-                }
-            }
-        }
-    }
-    _refreshQuerysets(modelKey) {
-        // Find all cached querysets for this model and refresh them
-        // modelKey is "configKey::modelName"
-        const [configKey, modelName] = modelKey.split('::');
-        for (const [semanticKey, wrapper] of wrappedQuerysetCache) {
-            const liveQuerySet = wrapper.original;
-            if (!liveQuerySet)
-                continue;
-            const qs = liveQuerySet.queryset;
-            if (qs?.ModelClass?.configKey === configKey &&
-                qs?.ModelClass?.modelName === modelName) {
-                // Refresh this queryset's reactive wrapper
-                try {
-                    wrapper.splice(0, wrapper.length);
-                    wrapper.push(...liveQuerySet);
-                }
-                catch (e) {
-                    console.warn('[ModelEventBatcher] Error refreshing queryset:', e);
-                }
-            }
-        }
-    }
-    clear() {
-        // Clear all pending state
-        for (const modelKey of this.pendingTouches.keys()) {
-            this._clearTimers(modelKey);
-        }
-        this.pendingTouches.clear();
-        this.processQueue.clear();
-    }
-}
-const modelEventBatcher = new ModelEventBatcher();
-// Export for testing
-export { modelEventBatcher, BATCH_THRESHOLD };
 /**
  * Adapts a model instance to a Vue reactive object by directly wrapping
  * the instance and incrementing an internal version on relevant events.
@@ -168,15 +23,19 @@ export function ModelAdaptor(modelInstance, reactivityFn = reactive) {
     // Make the model instance reactive using the specified function
     const wrapper = reactivityFn(modelInstance);
     const eventName = `${configKey}::${modelName}::render`;
-    // Handler queues touch calls through the batcher for optimal batching
+    // Handler bumps version to trigger Vue reactivity when this instance updates
     const renderHandler = (eventData) => {
         const isRef = reactivityFn === ref;
         const model = isRef ? wrapper.value : wrapper;
-        if (eventData.pk === model[pkField]) {
-            // Queue the touch through the batcher instead of calling directly
-            // This allows batching of rapid events and smart routing to queryset refresh for bulk ops
-            const targetWrapper = isRef ? wrapper.value : wrapper;
-            modelEventBatcher.queueTouch(configKey, modelName, eventData.pk, targetWrapper);
+        const modelPk = model[pkField];
+        // Check if this model's pk is in the event's pks array
+        if (eventData.pks && eventData.pks.includes(modelPk)) {
+            if (isRef) {
+                wrapper.value.touch();
+            }
+            else {
+                wrapper.touch();
+            }
         }
     };
     // Subscribe to model events indefinitely
@@ -270,5 +129,4 @@ export function MetricAdaptor(metric) {
 registerAdapterReset(() => {
     wrappedQuerysetCache.clear();
     wrappedMetricCache.clear();
-    modelEventBatcher.clear();
 });

package/dist/flavours/django/makeApiCall.js

@@ -44,10 +44,9 @@ export function processIncludedEntities(modelStoreRegistry, included, ModelClass
                     pksSet.add(Number(pk));
                 }
             }
-            // Register each entity in the model store
-            for (const [pk, entity] of Object.entries(entityMap)) {
-                modelStoreRegistry.setEntity(EntityClass, pk, entity);
-            }
+            // Register all entities in the model store in a single batch call
+            const entities = Object.values(entityMap);
+            modelStoreRegistry.setEntities(EntityClass, entities);
         }
     }
     catch (error) {

package/dist/flavours/django/tempPk.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Register a callback to be notified when a temp pk is resolved to a real pk
+ * @param {Function} callback - Called with (tempPk, realPk) when resolved
+ * @returns {Function} - Unsubscribe function
+ */
+export function onTempPkResolved(callback: Function): Function;
 /**
  * Check if a string contains a temporary PK template
  * @param {string} str - The string to check
@@ -12,6 +18,12 @@ export function createTempPk(uuid: any): string;
  * Register a real PK for a temporary PK
  */
 export function setRealPk(uuid: any, realPk: any): void;
+/**
+ * Get the real PK for a temp PK if it exists in the registry
+ * @param {any} pk - The pk to resolve (may be temp or real)
+ * @returns {any} - The real pk if found, otherwise the original pk
+ */
+export function resolveToRealPk(pk: any): any;
 /**
  * Replace all temporary PKs in an object (or string) with their real values
  */

package/dist/flavours/django/tempPk.js

@@ -2,6 +2,17 @@ import Handlebars from 'handlebars';
 import superjson from 'superjson';
 // Simple map to store temporary PK to real PK mappings
 export const tempPkMap = new Map();
+// Callbacks to notify when a temp pk is resolved to a real pk
+const onResolveCallbacks = new Set();
+/**
+ * Register a callback to be notified when a temp pk is resolved to a real pk
+ * @param {Function} callback - Called with (tempPk, realPk) when resolved
+ * @returns {Function} - Unsubscribe function
+ */
+export function onTempPkResolved(callback) {
+    onResolveCallbacks.add(callback);
+    return () => onResolveCallbacks.delete(callback);
+}
 /**
  * Check if a string contains a temporary PK template
  * @param {string} str - The string to check
@@ -22,9 +33,41 @@ export function createTempPk(uuid) {
  * Register a real PK for a temporary PK
  */
 export function setRealPk(uuid, realPk) {
+    const tempPk = `{{TempPK_${uuid}}}`;
     const key = `"TempPK_${uuid}"`;
     const value = typeof realPk === 'string' ? `"${realPk}"` : String(realPk);
     tempPkMap.set(key, value);
+    // Notify listeners so they can migrate cache entries
+    for (const cb of onResolveCallbacks) {
+        try {
+            cb(tempPk, realPk);
+        }
+        catch (e) {
+            console.warn('[tempPk] onResolve callback error:', e);
+        }
+    }
+}
+/**
+ * Get the real PK for a temp PK if it exists in the registry
+ * @param {any} pk - The pk to resolve (may be temp or real)
+ * @returns {any} - The real pk if found, otherwise the original pk
+ */
+export function resolveToRealPk(pk) {
+    if (!containsTempPk(String(pk)))
+        return pk;
+    // Extract the uuid from {{TempPK_uuid}}
+    const match = String(pk).match(/\{\{\s*TempPK_([^}\s]+)\s*\}\}/);
+    if (!match)
+        return pk;
+    const key = `"TempPK_${match[1]}"`;
+    const realPkStr = tempPkMap.get(key);
+    if (!realPkStr)
+        return pk;
+    // Parse the real pk (remove quotes if string, parse if number)
+    if (realPkStr.startsWith('"') && realPkStr.endsWith('"')) {
+        return realPkStr.slice(1, -1);
+    }
+    return parseInt(realPkStr, 10);
 }
 /**
  * Replace all temporary PKs in an object (or string) with their real values

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

@@ -6,5 +6,6 @@ export class ModelStoreRegistry {
     getStore(modelClass: any): any;
     getEntity(modelClass: any, pk: any): any;
     setEntity(modelClass: any, pk: any, data: any): any;
+    setEntities(modelClass: any, entities: any): void;
 }
 export const modelStoreRegistry: ModelStoreRegistry;

package/dist/syncEngine/registries/modelStoreRegistry.js

@@ -20,7 +20,7 @@ export class ModelStoreRegistry {
             const fetchModels = async ({ pks, modelClass }) => {
                 return await modelClass.objects.filter({
                     [`${modelClass.primaryKeyField}__in`]: pks
-                }).fetch();
+                }).fetch().serialize();
             };
             this._stores.set(modelClass, new ModelStore(modelClass, fetchModels, null, null));
             this.syncManager.followModel(this, modelClass);
@@ -51,6 +51,13 @@ export class ModelStoreRegistry {
         store.addToGroundTruth([data]);
         return data;
     }
+    // Batch add or update entities in the store ground truth
+    setEntities(modelClass, entities) {
+        if (isNil(modelClass) || !entities?.length)
+            return;
+        const store = this.getStore(modelClass);
+        store.addToGroundTruth(entities);
+    }
 }
 // Export singleton instance
 export const modelStoreRegistry = new ModelStoreRegistry();

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

@@ -9,6 +9,7 @@ export class ModelStore {
     modelCache: Cache;
     _lastRenderedData: Map<any, any>;
     renderCallbacks: Set<any>;
+    _unsubscribeTempPk: Function;
     registerRenderCallback(callback: any): () => boolean;
     /**
      * Load operations from data and add them to the operations map,
@@ -44,7 +45,9 @@ export class ModelStore {
      * @param {QuerysetStoreRegistry} querysetStoreRegistry - The registry to check for queryset references
      */
     pruneUnreferencedInstances(querysetStoreRegistry: QuerysetStoreRegistry): void;
-    render(pks?: null, optimistic?: boolean): any[];
+    render(pks?: null, optimistic?: boolean, useCache?: boolean): any;
+    _renderFromCache(pks: any): any;
+    _renderFresh(pks?: null, optimistic?: boolean): any[];
     sync(pks?: null): Promise<void>;
 }
 import { Cache } from '../cache/cache.js';

package/dist/syncEngine/stores/modelStore.js

@@ -2,52 +2,62 @@ import { Operation, Status, Type, operationRegistry } from './operation.js';
 import { isNil, isEmpty, trim, isEqual } from 'lodash-es';
 import { modelEventEmitter } from './reactivity.js';
 import { Cache } from '../cache/cache.js';
-import { replaceTempPks, containsTempPk } from '../../flavours/django/tempPk.js';
-const emitEvents = (store, events) => {
-    if (!Array.isArray(events))
+import { replaceTempPks, containsTempPk, resolveToRealPk, onTempPkResolved } from '../../flavours/django/tempPk.js';
+const emitEvents = (store, event) => {
+    if (!event || !event.pks || event.pks.length === 0)
         return;
-    events.forEach((event) => {
-        const pk = event.pk;
-        if (isNil(pk))
-            return;
-        const newRenderedDataArray = store.render([pk], true);
-        const newRenderedData = newRenderedDataArray.length > 0 ? newRenderedDataArray[0] : null;
-        const lastRenderedData = store._lastRenderedData.get(pk);
-        if (!isEqual(newRenderedData, lastRenderedData)) {
-            store._lastRenderedData.set(pk, newRenderedData);
-            modelEventEmitter.emit(`${store.modelClass.configKey}::${store.modelClass.modelName}::render`, event);
-            store.renderCallbacks.forEach((callback) => {
-                try {
-                    callback();
-                }
-                catch (error) {
-                    console.warn("Error in model store render callback:", error);
-                }
-            });
+    // Get prior values for these pks in one pass (before computing new)
+    const lastRenderedDataArray = event.pks.map(pk => store._lastRenderedData.get(pk) ?? null);
+    // Batch render all pks - useCache=false to get fresh data for comparison
+    const newRenderedDataArray = store.render(event.pks, true, false);
+    // Single equality check on the whole batch
+    if (!isEqual(newRenderedDataArray, lastRenderedDataArray)) {
+        // Update cache for all pks
+        const pkField = store.pkField;
+        for (const item of newRenderedDataArray) {
+            if (item && item[pkField] != null) {
+                store._lastRenderedData.set(item[pkField], item);
+            }
+        }
+        // Also mark any pks that are now null (deleted)
+        for (const pk of event.pks) {
+            if (!newRenderedDataArray.some(item => item && item[pkField] === pk)) {
+                store._lastRenderedData.set(pk, null);
+            }
         }
-    });
+        modelEventEmitter.emit(`${store.modelClass.configKey}::${store.modelClass.modelName}::render`, event);
+        store.renderCallbacks.forEach((callback) => {
+            try {
+                callback();
+            }
+            catch (error) {
+                console.warn("Error in model store render callback:", error);
+            }
+        });
+    }
 };
 class EventData {
-    constructor(ModelClass, pk) {
+    constructor(ModelClass, pks) {
         this.ModelClass = ModelClass;
-        this.pk = pk;
+        this.pks = Array.isArray(pks) ? pks : [pks];
     }
     /**
-     * One event per instance in a single operation
+     * Single event containing all PKs from an operation
      */
     static fromOperation(operation) {
         const ModelClass = operation.queryset.ModelClass;
         const pkField = ModelClass.primaryKeyField;
-        return operation.instances
+        const pks = operation.instances
             .filter(instance => instance != null && typeof instance === 'object' && pkField in instance)
-            .map(instance => new EventData(ModelClass, instance[pkField]));
+            .map(instance => instance[pkField]);
+        return pks.length > 0 ? new EventData(ModelClass, pks) : null;
     }
     /**
-     * One event per unique PK across multiple operations
+     * Single event containing all unique PKs across multiple operations
      */
     static fromOperations(operations) {
         if (!operations.length)
-            return [];
+            return null;
         const ModelClass = operations[0].queryset.ModelClass;
         const pkField = ModelClass.primaryKeyField;
         const uniquePks = new Set();
@@ -58,17 +68,17 @@ class EventData {
                 }
             }
         }
-        return Array.from(uniquePks).map(pk => new EventData(ModelClass, pk));
+        return uniquePks.size > 0 ? new EventData(ModelClass, Array.from(uniquePks)) : null;
     }
     /**
-     * One event per unique PK in an array of instances
+     * Single event containing all unique PKs from an array of instances
      */
     static fromInstances(instances, ModelClass) {
         const pkField = ModelClass.primaryKeyField;
         const uniquePks = new Set(instances
             .filter(inst => inst && inst[pkField] != null)
             .map(inst => inst[pkField]));
-        return Array.from(uniquePks).map(pk => new EventData(ModelClass, pk));
+        return uniquePks.size > 0 ? new EventData(ModelClass, Array.from(uniquePks)) : null;
     }
 }
 export class ModelStore {
@@ -86,6 +96,18 @@ export class ModelStore {
         this.modelCache = new Cache("model-cache", {}, this.onHydrated.bind(this));
         this._lastRenderedData = new Map();
         this.renderCallbacks = new Set();
+        // Migrate cache entries when temp pks are resolved to real pks
+        this._unsubscribeTempPk = onTempPkResolved((tempPk, realPk) => {
+            if (this._lastRenderedData.has(tempPk)) {
+                const data = this._lastRenderedData.get(tempPk);
+                // Update the pk field in the cached data
+                if (data && typeof data === 'object') {
+                    data[this.pkField] = realPk;
+                }
+                this._lastRenderedData.set(realPk, data);
+                this._lastRenderedData.delete(tempPk);
+            }
+        });
     }
     registerRenderCallback(callback) {
         this.renderCallbacks.add(callback);
@@ -435,7 +457,60 @@ export class ModelStore {
         }
     }
     // Render methods
-    render(pks = null, optimistic = true) {
+    render(pks = null, optimistic = true, useCache = true) {
+        // When rendering specific pks, check cache first
+        if (useCache && pks !== null) {
+            const pksArray = Array.isArray(pks) ? pks : [pks];
+            // Resolve temp pks to real pks for cache lookup
+            const resolvedPks = pksArray.map(pk => resolveToRealPk(pk));
+            const uncachedPks = [];
+            for (const pk of resolvedPks) {
+                if (!this._lastRenderedData.has(pk)) {
+                    uncachedPks.push(pk);
+                }
+            }
+            // All pks were cached - return from cache
+            if (uncachedPks.length === 0) {
+                return this._renderFromCache(resolvedPks);
+            }
+            // Some or all pks need fresh render
+            const pkField = this.pkField;
+            if (uncachedPks.length < resolvedPks.length) {
+                // Partial cache hit - get cached and render uncached
+                const cachedPks = resolvedPks.filter(pk => this._lastRenderedData.has(pk));
+                const cached = this._renderFromCache(cachedPks);
+                const fresh = this._renderFresh(uncachedPks, optimistic);
+                // Update cache for freshly rendered items
+                for (const item of fresh) {
+                    if (item && item[pkField] != null) {
+                        this._lastRenderedData.set(item[pkField], item);
+                    }
+                }
+                return [...cached, ...fresh];
+            }
+            else {
+                // All pks uncached - render fresh and update cache
+                const fresh = this._renderFresh(resolvedPks, optimistic);
+                // Update cache for freshly rendered items
+                for (const item of fresh) {
+                    if (item && item[pkField] != null) {
+                        this._lastRenderedData.set(item[pkField], item);
+                    }
+                }
+                return fresh;
+            }
+        }
+        // Full render (no cache, useCache=false, or pks=null for all)
+        return this._renderFresh(pks, optimistic);
+    }
+    _renderFromCache(pks) {
+        // Returns cached rendered data for the given pks
+        // This method can be spied on in tests to track cache hits
+        return pks
+            .map(pk => this._lastRenderedData.get(pk))
+            .filter(item => item !== null && item !== undefined);
+    }
+    _renderFresh(pks = null, optimistic = true) {
         const pksSet = pks === null
             ? null
             : pks instanceof Set

package/dist/syncEngine/stores/operation.js

@@ -14,6 +14,7 @@ import { MAX, v7 as uuidv7 } from "uuid";
 import { isNil } from 'lodash-es';
 import mitt from 'mitt';
 import { tempPkMap } from "../../flavours/django/tempPk";
+import { modelStoreRegistry } from "../registries/modelStoreRegistry.js";
 export const operationEvents = mitt();
 export const Status = {
     CREATED: 'operation:created',
@@ -73,7 +74,11 @@ export class Operation {
             throw new Error(`All operation instances must be objects with the '${pkField}' field`);
         }
         __classPrivateFieldSet(this, _Operation__instances, instances, "f");
-        __classPrivateFieldSet(this, _Operation__frozenInstances, instances.map(i => ModelClass.fromPk(i[ModelClass.primaryKeyField]).serialize()), "f");
+        // Batch render to warm the cache, then serialize each instance to get plain objects
+        const pks = instances.map(i => i[pkField]);
+        const store = modelStoreRegistry.getStore(ModelClass);
+        store.render(pks, true, false);
+        __classPrivateFieldSet(this, _Operation__frozenInstances, instances.map(i => ModelClass.fromPk(i[pkField]).serialize()), "f");
         this.timestamp = data.timestamp || Date.now();
         if (restore)
             return;

package/package.json

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