@statezero/core 0.2.9 → 0.2.10

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

@@ -16,3 +16,29 @@ 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,9 +4,154 @@ 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.
@@ -23,17 +168,15 @@ 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 bumps version to trigger Vue reactivity when this instance updates
+    // Handler queues touch calls through the batcher for optimal batching
     const renderHandler = (eventData) => {
         const isRef = reactivityFn === ref;
         const model = isRef ? wrapper.value : wrapper;
         if (eventData.pk === model[pkField]) {
-            if (isRef) {
-                wrapper.value.touch();
-            }
-            else {
-                wrapper.touch();
-            }
+            // 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);
         }
     };
     // Subscribe to model events indefinitely
@@ -127,4 +270,5 @@ export function MetricAdaptor(metric) {
 registerAdapterReset(() => {
     wrappedQuerysetCache.clear();
     wrappedMetricCache.clear();
+    modelEventBatcher.clear();
 });

package/package.json

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