@statezero/core 0.2.51 → 0.2.53

package/dist/models/default/django_app/updateonlyitem.js

@@ -0,0 +1,69 @@
+/**
+ * This file was auto-generated. Do not make direct changes to the file.
+ */
+import { Model, Manager, QuerySet, getModelClass } from '../../../../src';
+import { wrapReactiveModel } from '../../../../src';
+import schemaData from './updateonlyitem.schema.json';
+/**
+ * Model-specific QuerySet implementation
+ */
+export class UpdateOnlyItemQuerySet extends QuerySet {
+}
+/**
+ * Model-specific Manager implementation
+ */
+export class UpdateOnlyItemManager extends Manager {
+    constructor(ModelClass) {
+        super(ModelClass, UpdateOnlyItemQuerySet);
+    }
+    newQuerySet() {
+        return new UpdateOnlyItemQuerySet(this.ModelClass);
+    }
+}
+/**
+ * Implementation of the UpdateOnlyItem model
+ */
+export class UpdateOnlyItem extends Model {
+    constructor(data) {
+        UpdateOnlyItem.validateFields(data);
+        super(data);
+        // Define getters and setters for all fields
+        this._defineProperties();
+        return wrapReactiveModel(this);
+    }
+    /**
+     * Define property getters and setters for all model fields
+     * @private
+     */
+    _defineProperties() {
+        // For each field, define a property that gets/sets from internal storage
+        UpdateOnlyItem.fields.forEach(field => {
+            Object.defineProperty(this, field, {
+                get: function () {
+                    return this.getField(field);
+                },
+                set: function (value) {
+                    this.setField(field, value);
+                },
+                enumerable: true, // Make sure fields are enumerable for serialization
+                configurable: true
+            });
+        });
+        // Add a special read-only getter for the repr field
+        Object.defineProperty(this, 'repr', {
+            get: function () {
+                return this.getField('repr');
+            },
+            enumerable: true, // Make sure repr is enumerable
+            configurable: true
+        });
+    }
+}
+// Bind this model to its backend
+UpdateOnlyItem.configKey = 'default';
+UpdateOnlyItem.modelName = 'django_app.updateonlyitem';
+UpdateOnlyItem.primaryKeyField = 'id';
+UpdateOnlyItem.objects = new UpdateOnlyItemManager(UpdateOnlyItem);
+UpdateOnlyItem.fields = ['id', 'name', 'value'];
+UpdateOnlyItem.schema = schemaData;
+UpdateOnlyItem.relationshipFields = new Map([]);

package/dist/models/default/django_app/updateonlyitem.schema.json

@@ -0,0 +1,88 @@
+{
+    "model_name": "django_app.updateonlyitem",
+    "title": "Update Only Item",
+    "class_name": "UpdateOnlyItem",
+    "plural_title": "Update Only Items",
+    "primary_key_field": "id",
+    "filterable_fields": [
+        "value",
+        "id",
+        "name"
+    ],
+    "searchable_fields": [
+        "name"
+    ],
+    "ordering_fields": [
+        "value",
+        "name"
+    ],
+    "properties": {
+        "id": {
+            "type": "integer",
+            "title": "Id",
+            "required": true,
+            "description": null,
+            "nullable": false,
+            "format": "id",
+            "max_length": null,
+            "choices": null,
+            "default": null,
+            "validators": [],
+            "max_digits": null,
+            "decimal_places": null,
+            "read_only": true,
+            "ref": null
+        },
+        "name": {
+            "type": "string",
+            "title": "Name",
+            "required": true,
+            "description": null,
+            "nullable": false,
+            "format": null,
+            "max_length": 100,
+            "choices": null,
+            "default": null,
+            "validators": [],
+            "max_digits": null,
+            "decimal_places": null,
+            "read_only": false,
+            "ref": null
+        },
+        "value": {
+            "type": "integer",
+            "title": "Value",
+            "required": false,
+            "description": null,
+            "nullable": false,
+            "format": null,
+            "max_length": null,
+            "choices": null,
+            "default": 0,
+            "validators": [],
+            "max_digits": null,
+            "decimal_places": null,
+            "read_only": false,
+            "ref": null
+        }
+    },
+    "relationships": {},
+    "default_ordering": null,
+    "definitions": {
+        "MoneyField": {
+            "type": "object",
+            "properties": {
+                "amount": {
+                    "type": "number"
+                },
+                "currency": {
+                    "type": "string"
+                }
+            }
+        }
+    },
+    "datetime_format": "iso-8601",
+    "date_format": "iso-8601",
+    "time_format": "iso-8601",
+    "display": null
+}

package/dist/schemaIntegrity.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Background check that compares stored schema checksums (from sync time)
+ * against the current checksums returned by the backend.
+ *
+ * Warns via console if schemas have drifted. Silently skips on network error.
+ *
+ * @param {Object.<string, Object>} backendConfigs - Backend configuration map from configInstance
+ * @param {Object.<string, string>} checksums - Map of backend key to checksum from sync time
+ */
+export function checkSchemaIntegrity(backendConfigs: {
+    [x: string]: Object;
+}, checksums: {
+    [x: string]: string;
+}): Promise<void>;

package/dist/schemaIntegrity.js

@@ -0,0 +1,29 @@
+import axios from "axios";
+/**
+ * Background check that compares stored schema checksums (from sync time)
+ * against the current checksums returned by the backend.
+ *
+ * Warns via console if schemas have drifted. Silently skips on network error.
+ *
+ * @param {Object.<string, Object>} backendConfigs - Backend configuration map from configInstance
+ * @param {Object.<string, string>} checksums - Map of backend key to checksum from sync time
+ */
+export async function checkSchemaIntegrity(backendConfigs, checksums) {
+    for (const [backendKey, expectedChecksum] of Object.entries(checksums)) {
+        const backend = backendConfigs[backendKey];
+        if (!backend)
+            continue;
+        try {
+            const headers = backend.getAuthHeaders ? backend.getAuthHeaders() : {};
+            const response = await axios.get(`${backend.API_URL}/models/`, { headers });
+            const currentChecksum = response.headers['x-statezero-schema-checksum'];
+            if (currentChecksum && currentChecksum !== expectedChecksum) {
+                console.warn(`[StateZero] Schema drift detected for backend '${backendKey}'. ` +
+                    `Run 'npx statezero sync' to update your generated types.`);
+            }
+        }
+        catch {
+            // Silently skip — this is a non-blocking background check
+        }
+    }
+}

package/dist/setup.js

@@ -5,6 +5,7 @@ import { initEventHandler } from "./syncEngine/stores/operationEventHandlers.js"
 import { querysetStoreRegistry } from "./syncEngine/registries/querysetStoreRegistry.js";
 import { modelStoreRegistry } from "./syncEngine/registries/modelStoreRegistry.js";
 import { metricRegistry } from "./syncEngine/registries/metricRegistry.js";
+import { checkSchemaIntegrity } from "./schemaIntegrity.js";
 /**
  * Initialize StateZero with the provided configuration
  *
@@ -30,4 +31,9 @@ export function setupStateZero(config, getModelClass, adapters) {
             metricRegistry,
         };
     }
+    // Background schema freshness check (fire-and-forget)
+    if (getModelClass.SYNC_CHECKSUMS) {
+        const cfg = configInstance.getConfig();
+        checkSchemaIntegrity(cfg.backendConfigs, getModelClass.SYNC_CHECKSUMS);
+    }
 }

package/dist/syncEngine/cache/cache.d.ts

@@ -60,7 +60,7 @@ export class IndexedDBStore {
 }
 export class Cache {
     constructor(dbName: any, options?: {}, onHydrated?: null);
-    store: IndexedDBStore;
+    store: any;
     localMap: Map<any, any>;
     hydrate(): Promise<void>;
     get(key: any): any;

package/dist/syncEngine/cache/cache.js

@@ -288,7 +288,14 @@ export class IndexedDBStore {
 }
 export class Cache {
     constructor(dbName, options = {}, onHydrated = null) {
-        this.store = new IndexedDBStore(dbName, options);
+        // Share IndexedDBStore instances across Cache objects with the same dbName
+        if (dbConnections.has(dbName)) {
+            this.store = dbConnections.get(dbName);
+        }
+        else {
+            this.store = new IndexedDBStore(dbName, options);
+            dbConnections.set(dbName, this.store);
+        }
         this.localMap = new Map();
         // don't await - will hydrate during app setup
         this.hydrate()

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

@@ -1,6 +1,13 @@
 /**
- * LiveMetric, a simple wrapper that always returns the latest metric value
- * using a getter for the value property
+ * LiveMetric wraps a metric scalar (count, sum, etc.) and stays live.
+ *
+ * Uses valueOf()/toString() so it coerces to the scalar naturally:
+ *   count + 0    // → 5
+ *   `${count}`   // → "5"
+ *   count > 3    // → true
+ *
+ * Note: typeof returns "object" and === compares identity, not value.
+ * Use == for loose comparison, or +metric for explicit coercion.
  */
 export class LiveMetric {
     constructor(queryset: any, metricType: any, field?: null);
@@ -14,8 +21,12 @@ export class LiveMetric {
      */
     refreshFromDb(): any;
     /**
-     * Getter that always returns the current value from the store
+     * Returns the current metric value from the store.
+     * Called implicitly by JS when coercing to a primitive (arithmetic, template literals, etc.)
      */
+    valueOf(): any;
+    toString(): string;
+    /** @deprecated Use valueOf() coercion instead (e.g. +metric, `${metric}`, metric + 0) */
     get value(): any;
 }
 /**

package/dist/syncEngine/registries/metricRegistry.js

@@ -5,8 +5,15 @@ import { QueryExecutor } from '../../flavours/django/queryExecutor.js';
 import { wrapReactiveMetric } from '../../reactiveAdaptor.js';
 import hash from 'object-hash';
 /**
- * LiveMetric, a simple wrapper that always returns the latest metric value
- * using a getter for the value property
+ * LiveMetric wraps a metric scalar (count, sum, etc.) and stays live.
+ *
+ * Uses valueOf()/toString() so it coerces to the scalar naturally:
+ *   count + 0    // → 5
+ *   `${count}`   // → "5"
+ *   count > 3    // → true
+ *
+ * Note: typeof returns "object" and === compares identity, not value.
+ * Use == for loose comparison, or +metric for explicit coercion.
  */
 export class LiveMetric {
     constructor(queryset, metricType, field = null) {
@@ -26,17 +33,24 @@ export class LiveMetric {
         return store.sync(true);
     }
     /**
-     * Getter that always returns the current value from the store
+     * Returns the current metric value from the store.
+     * Called implicitly by JS when coercing to a primitive (arithmetic, template literals, etc.)
      */
-    get value() {
-        // Get the latest store from the registry
+    valueOf() {
         const store = metricRegistry.getStore(this.metricType, this.queryset, this.field);
         if (!store) {
             return null;
         }
-        // Render the current value
         return store.render();
     }
+    toString() {
+        const val = this.valueOf();
+        return val === null ? '' : String(val);
+    }
+    /** @deprecated Use valueOf() coercion instead (e.g. +metric, `${metric}`, metric + 0) */
+    get value() {
+        return this.valueOf();
+    }
 }
 /**
  * Registry to manage metric stores

package/dist/syncEngine/stores/operationEventHandlers.js

@@ -203,7 +203,7 @@ function routeCreateOperation(operation, applyAction) {
  *
  * @param {Operation} operation - The UPDATE operation
  */
-function routeUpdateOperation(operation) {
+function routeUpdateOperation(operation, applyAction) {
     const modelClass = operation.queryset.ModelClass;
     // frozenInstances is already serialized with proper FK structure
     const beforeInstances = operation.frozenInstances;
@@ -230,6 +230,8 @@ function routeUpdateOperation(operation) {
             return;
         }
         // Item matched before OR matches after, no offset - definitely affected
+        // Apply the operation so the queryset can add/remove PKs from its candidate set
+        applyAction(store);
         operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(true, false));
     });
 }
@@ -243,7 +245,7 @@ function routeUpdateOperation(operation) {
  *
  * @param {Operation} operation - The DELETE operation
  */
-function routeDeleteOperation(operation) {
+function routeDeleteOperation(operation, applyAction) {
     const modelClass = operation.queryset.ModelClass;
     // frozenInstances is already serialized with proper FK structure
     const beforeInstances = operation.frozenInstances;
@@ -267,6 +269,7 @@ function routeDeleteOperation(operation) {
             return;
         }
         // Item matched before, no offset - definitely affected
+        applyAction(store);
         operationRegistry.setQuerysetState(operation.operationId, semanticKey, createMembershipState(true, false));
     });
 }
@@ -339,15 +342,14 @@ function processQuerysetStores(operation, actionType) {
             return;
         case Type.UPDATE:
         case Type.UPDATE_INSTANCE:
-            // Track membership for sync optimization
-            // Check both before (frozenInstances) and after (instances) state
-            routeUpdateOperation(operation);
+            // Route update to affected querysets so items can move between filtered sets
+            // (e.g., an item changing name from 'beta' to 'alpha' needs to appear in the alpha queryset)
+            routeUpdateOperation(operation, applyAction);
             return;
         case Type.DELETE:
         case Type.DELETE_INSTANCE:
-            // Track membership for sync optimization
-            // Check before state only (item being deleted)
-            routeDeleteOperation(operation);
+            // Add delete to matching queryset stores for optimistic removal
+            routeDeleteOperation(operation, applyAction);
             return;
         case Type.CHECKPOINT:
             // Model store handles the change, querysets re-render via local filtering

package/dist/syncEngine/stores/querysetStore.js

@@ -46,11 +46,17 @@ export class QuerysetStore {
         return this.queryset.semanticKey;
     }
     onHydrated(hydratedData) {
-        if (this.groundTruthPks.length === 0 && this.operationsMap.size === 0) {
-            const cached = this.qsCache.get(this.cacheKey);
-            if (!isNil(cached) && !isEmpty(cached)) {
-                this.setGroundTruth(cached);
-            }
+        // Only use cached data if we haven't synced yet and have no ground truth.
+        // This prevents stale cache from overwriting real server data.
+        if (this.lastSync !== null)
+            return;
+        if (this.groundTruthPks.length > 0 || this.operationsMap.size > 0)
+            return;
+        const cached = this.qsCache.get(this.cacheKey);
+        if (!isNil(cached) && !isEmpty(cached)) {
+            // Set ground truth WITHOUT updating lastSync — hydration is not a real sync
+            this.groundTruthPks = Array.isArray(cached) ? cached : [];
+            this._emitRenderEvent();
         }
     }
     setCache(result) {
@@ -125,6 +131,10 @@ export class QuerysetStore {
     }
     async setGroundTruth(groundTruthPks) {
         this.groundTruthPks = Array.isArray(groundTruthPks) ? groundTruthPks : [];
+        if (this.groundTruthPks.length > 500) {
+            const limit = this.queryset?._serializerOptions?.limit;
+            console.warn(`[statezero] ⚠️ ${this.modelClass.modelName} (${this.queryset.semanticKey}) received ${this.groundTruthPks.length} items${limit ? ` (limit: ${limit})` : ' with NO limit'}. Live querysets re-render on every change — at this size, this WILL cause UI freezes on mobile. Add .fetch({ limit }) or use narrower filters.`);
+        }
         this.lastSync = Date.now();
         this._emitRenderEvent();
     }
@@ -203,7 +213,13 @@ export class QuerysetStore {
         // If no ground truth AND hasn't been synced, render from model store
         // This handles chained optimistic filters, newly created stores, etc.
         // (If synced with empty results, that's valid ground truth)
-        const pks = this.groundTruthPks.length === 0 && this.lastSync === null
+        // Skip model store seeding for paginated querysets (offset > 0) — the model
+        // store contains items from other pages, so seeding would show wrong results.
+        const offset = this.queryset.build().serializerOptions?.offset;
+        const canSeedFromModelStore = this.groundTruthPks.length === 0
+            && this.lastSync === null
+            && !(offset != null && offset > 0);
+        const pks = canSeedFromModelStore
             ? this.renderFromModelStore()
             : this.renderFromData(optimistic);
         // Validate against model store and apply local filtering/sorting
@@ -269,8 +285,13 @@ export class QuerysetStore {
                     currentPks.add(pk);
                     break;
                 case Type.CHECKPOINT:
+                    break;
                 case Type.UPDATE:
                 case Type.UPDATE_INSTANCE:
+                    // Add PKs as candidates so items can move into this queryset
+                    // when an update makes them match the filter.
+                    // _getValidatedAndFilteredPks will filter out non-matching items.
+                    currentPks.add(pk);
                     break;
                 case Type.DELETE:
                 case Type.DELETE_INSTANCE:

package/package.json

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