@statezero/core 0.2.51 → 0.2.53

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

@@ -1,2 +1,2 @@
-export function useQueryset(querysetFactory: any): import("vue").ComputedRef<any>;
+export function useQueryset(querysetFactory: any): import("vue").Ref<any, any> | import("vue").ComputedRef<any>;
 export const querysets: Map<any, any>;

package/dist/adaptors/vue/composables.js

@@ -1,6 +1,6 @@
-import { computed, getCurrentInstance, onBeforeUnmount } from 'vue';
+import { computed, isRef, getCurrentInstance, onBeforeUnmount } from 'vue';
 import { querysetStoreRegistry } from '../../syncEngine/registries/querysetStoreRegistry.js';
-import { metricRegistry } from '../../syncEngine/registries/metricRegistry.js';
+import { metricRegistry, LiveMetric } from '../../syncEngine/registries/metricRegistry.js';
 import { syncManager } from '../../syncEngine/sync.js';
 import { registerAdapterReset } from '../../reset.js';
 import { v7 } from 'uuid';
@@ -22,6 +22,12 @@ export function useQueryset(querysetFactory) {
         querysets.delete(composableId);
         updateSyncManager();
     });
+    const result = querysetFactory();
+    // Metrics: the adaptor already returns a ref(scalar) — return it directly.
+    // Wrapping in another computed would cause .value.value in templates.
+    if (isRef(result) && result.original instanceof LiveMetric) {
+        return result;
+    }
     return computed(() => {
         const result = querysetFactory();
         const original = result?.original || result;

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

@@ -16,3 +16,4 @@ 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 function resetVueAdaptors(): void;

package/dist/adaptors/vue/reactivity.js

@@ -123,15 +123,26 @@ export function QuerySetAdaptor(liveQuerySet, reactivityFn = reactive) {
     wrapper.__version = 0;
     const eventName = `${configKey}::${modelName}::queryset::render`;
     // Handler bumps version to trigger Vue reactivity when this queryset updates
+    const pkField = queryset.ModelClass.primaryKeyField;
     const renderHandler = (eventData) => {
         if (eventData && eventData.ast && isEqual(querysetAst, eventData.ast)) {
-            console.log(`[sz] queryset update: ${modelName}`, { count: liveQuerySet.length, version: wrapper.__version + 1 });
+            const newData = [...liveQuerySet];
+            const newPks = newData.map(item => item[pkField]);
+            const currentArray = reactivityFn === ref ? wrapper.value : wrapper;
+            const oldPks = currentArray.map(item => item[pkField]);
+            // Skip if PKs haven't changed — field-level updates on existing items
+            // are already handled by Vue's deep reactivity via model touch().
+            // Bumping __version here would cause useQueryset's computed to
+            // re-evaluate and re-run the factory, risking circular reactive loops.
+            if (isEqual(oldPks, newPks))
+                return;
+            console.log(`[sz] queryset update: ${modelName}`, { count: newData.length, version: wrapper.__version + 1 });
             if (reactivityFn === ref) {
-                wrapper.value = [...liveQuerySet];
+                wrapper.value = newData;
             }
             else {
                 wrapper.splice(0, wrapper.length);
-                wrapper.push(...liveQuerySet);
+                wrapper.push(...newData);
             }
             // Bump version so computed/watch can track changes
             wrapper.__version++;
@@ -162,7 +173,7 @@ export function MetricAdaptor(metric) {
         return wrappedMetricCache.get(cacheKey);
     }
     // Create a reactive reference with the initial value
-    const wrapper = ref(metric.value);
+    const wrapper = ref(metric.valueOf());
     wrapper.original = metric;
     // Single handler for metric render events
     const metricRenderHandler = (eventData) => {
@@ -172,9 +183,9 @@ export function MetricAdaptor(metric) {
             eventData.field === metric.field &&
             eventData.ast === hash(querysetAst) &&
             eventData.valueChanged === true) {
-            console.log(`[sz] metric update: ${modelName}.${metric.field} (${metric.metricType}) =`, metric.value);
+            console.log(`[sz] metric update: ${modelName}.${metric.field} (${metric.metricType}) =`, metric.valueOf());
             // Update the wrapper value with the latest metric value
-            wrapper.value = metric.value;
+            wrapper.value = metric.valueOf();
         }
     };
     // Only listen for metric render events
@@ -185,7 +196,8 @@ export function MetricAdaptor(metric) {
     }
     return wrapper;
 }
-registerAdapterReset(() => {
+export function resetVueAdaptors() {
     wrappedQuerysetCache.clear();
     wrappedMetricCache.clear();
-});
+}
+registerAdapterReset(resetVueAdaptors);

package/dist/cli/commands/syncActions.js

@@ -768,6 +768,38 @@ export declare namespace getCurrentUser {
     return generatedFiles;
 }
 // ================================================================================================
+// SYNC TOKEN ERROR HANDLING
+// ================================================================================================
+function maskToken(token) {
+    if (!token || token.length <= 4)
+        return token || '';
+    return token.slice(0, 4) + '...';
+}
+function handleSyncFetchError(error, backend, endpoint) {
+    const status = error.response?.status;
+    const syncToken = backend.SYNC_TOKEN;
+    if (status === 409) {
+        console.error(`\n❌ Sync token mismatch for backend '${backend.NAME}' (${endpoint}).` +
+            `\n   The token sent was: '${maskToken(syncToken)}'.` +
+            `\n   Check that SYNC_TOKEN in your statezero config matches STATEZERO_SYNC_TOKEN on the server.`);
+    }
+    else if (status === 403) {
+        if (syncToken) {
+            console.error(`\n❌ Schema access denied for backend '${backend.NAME}' (${endpoint}).` +
+                `\n   Sync token sent: '${maskToken(syncToken)}'.` +
+                `\n   The server may not have STATEZERO_SYNC_TOKEN configured, or the token doesn't match.`);
+        }
+        else {
+            console.error(`\n❌ Schema access denied for backend '${backend.NAME}' (${endpoint}).` +
+                `\n   No sync token was sent.` +
+                `\n   Set SYNC_TOKEN in your statezero config to match STATEZERO_SYNC_TOKEN on the server, or enable DEBUG=True on the backend.`);
+        }
+    }
+    else {
+        console.error(`❌ Error fetching ${endpoint} from ${backend.NAME}: ${error.message}`);
+    }
+}
+// ================================================================================================
 // MAIN SCRIPT RUNNER
 // ================================================================================================
 async function main() {
@@ -789,7 +821,7 @@ async function main() {
             return { backend, actions: response.data.actions || {} };
         }
         catch (error) {
-            console.error(`❌ Error fetching actions from ${backend.NAME}: ${error.message}`);
+            handleSyncFetchError(error, backend, '/actions-schema/');
             return { backend, actions: {} };
         }
     });

package/dist/cli/commands/syncModels.js

@@ -794,7 +794,7 @@ function generateImportAlias(backendKey, modelName, className) {
  * @param {Object.<string, BackendConfig>} backendConfigs
  * @returns {Promise<void>}
  */
-async function generateModelRegistry(generatedFiles, backendConfigs) {
+async function generateModelRegistry(generatedFiles, backendConfigs, schemaChecksums = {}) {
     const registryByBackend = {};
     const allUniqueImports = new Set();
     for (const file of generatedFiles) {
@@ -876,6 +876,10 @@ export function getModelClass(modelName, configKey) {
   return null;
 }
 `;
+    // Add schema checksums if any were captured during sync
+    if (Object.keys(schemaChecksums).length > 0) {
+        registryContent += `\ngetModelClass.SYNC_CHECKSUMS = ${JSON.stringify(schemaChecksums)};\n`;
+    }
     // --- Write the file ---
     const rootDir = process.cwd();
     const registryFilePath = path.join(rootDir, "model-registry.js");
@@ -1027,6 +1031,38 @@ export * from './default/index.js';
     console.log(`✨ Generated top-level index for 'default' backend`);
 }
 // --------------------
+// Sync Token Error Handling
+// --------------------
+function maskToken(token) {
+    if (!token || token.length <= 4)
+        return token || '';
+    return token.slice(0, 4) + '...';
+}
+function handleSyncFetchError(error, backend, endpoint) {
+    const status = error.response?.status;
+    const syncToken = backend.SYNC_TOKEN;
+    if (status === 409) {
+        console.error(`\n❌ Sync token mismatch for backend '${backend.NAME}' (${endpoint}).` +
+            `\n   The token sent was: '${maskToken(syncToken)}'.` +
+            `\n   Check that SYNC_TOKEN in your statezero config matches STATEZERO_SYNC_TOKEN on the server.`);
+    }
+    else if (status === 403) {
+        if (syncToken) {
+            console.error(`\n❌ Schema access denied for backend '${backend.NAME}' (${endpoint}).` +
+                `\n   Sync token sent: '${maskToken(syncToken)}'.` +
+                `\n   The server may not have STATEZERO_SYNC_TOKEN configured, or the token doesn't match.`);
+        }
+        else {
+            console.error(`\n❌ Schema access denied for backend '${backend.NAME}' (${endpoint}).` +
+                `\n   No sync token was sent.` +
+                `\n   Set SYNC_TOKEN in your statezero config to match STATEZERO_SYNC_TOKEN on the server, or enable DEBUG=True on the backend.`);
+        }
+    }
+    else {
+        console.error(`Error fetching ${endpoint} from backend ${backend.NAME}:`, error.message);
+    }
+}
+// --------------------
 // Main Runner: Fetch models and prompt selection
 // --------------------
 async function main() {
@@ -1035,16 +1071,21 @@ async function main() {
     // Retrieve the validated configuration from the global config singleton.
     const configData = configInstance.getConfig();
     const backendConfigs = configData.backendConfigs;
+    const schemaChecksums = {};
     const fetchPromises = Object.keys(backendConfigs).map(async (key) => {
         const backend = backendConfigs[key];
         backend.NAME = key;
         try {
             const headers = backend.SYNC_TOKEN ? { "X-Sync-Token": backend.SYNC_TOKEN } : {};
             const response = await axios.get(`${backend.API_URL}/models/`, { headers });
+            const checksum = response.headers['x-statezero-schema-checksum'];
+            if (checksum) {
+                schemaChecksums[key] = checksum;
+            }
             return { backend, models: response.data };
         }
         catch (error) {
-            console.error(`Error fetching models from backend ${backend.NAME}:`, error.message);
+            handleSyncFetchError(error, backend, '/models/');
             return { backend, models: [] };
         }
     });
@@ -1105,7 +1146,7 @@ async function main() {
     // Generate an index file per app
     await generateAppLevelIndexFiles(allGeneratedFiles, backendConfigs);
     // Generate model registry
-    await generateModelRegistry(allGeneratedFiles, backendConfigs);
+    await generateModelRegistry(allGeneratedFiles, backendConfigs, schemaChecksums);
     // Generate top-level index for 'default' backend if it exists
     await generateDefaultBackendIndex(backendConfigs);
     console.log(`✨ Generated JavaScript files with TypeScript declarations for ${selectedModels.length} models across ${Object.keys(backendConfigs).length} backends.`);

package/dist/filtering/localFiltering.js

@@ -2,6 +2,7 @@ import sift, { createEqualsOperation } from 'sift';
 import { configInstance } from '../config.js';
 import { DateTime } from 'luxon';
 import { ModelSerializer } from '../flavours/django/serializers.js';
+import { ValidationError } from '../flavours/django/errors.js';
 /**
  * Gets the backend timezone for a model class
  * @param {Class} ModelClass - The model class
@@ -54,7 +55,7 @@ function processFieldPath(fieldPath, value, ModelClass, options = {}) {
     const knownLookups = [
         'exact', 'iexact', 'contains', 'icontains', 'startswith',
         'istartswith', 'endswith', 'iendswith', 'in', 'gt', 'gte',
-        'lt', 'lte', 'isnull', 'regex', 'iregex', 'year', 'month',
+        'lt', 'lte', 'isnull', 'year', 'month',
         'day', 'week_day', 'hour', 'minute', 'second', 'date', 'time'
     ];
     // Date part lookups that can be followed by comparison lookups
@@ -627,7 +628,7 @@ function convertToSiftCriteria(conditions, ModelClass) {
             }
         }
         catch (error) {
-            throw new Error(`Failed to process field '${key}': ${error.message}`);
+            throw new ValidationError(`Failed to process field '${key}': ${error.message}`);
         }
     }
     // Merge M2M conditions: all conditions on same M2M field go into single $elemMatch

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

@@ -88,6 +88,18 @@ export class MultipleObjectsReturned extends StateZeroError {
      */
     constructor(detail?: IErrorDetail | Object | string, status?: number);
 }
+/**
+ * Error class for database conflict errors (integrity/constraint violations).
+ */
+export class ConflictError extends StateZeroError {
+    /**
+     * Creates a new ConflictError.
+     *
+     * @param {IErrorDetail|Object|string} [detail="A database conflict occurred."] - The error details.
+     * @param {number} [status=409] - The HTTP status code.
+     */
+    constructor(detail?: IErrorDetail | Object | string, status?: number);
+}
 /**
  * Error class for AST validation errors.
  */

package/dist/flavours/django/errors.js

@@ -116,6 +116,21 @@ export class MultipleObjectsReturned extends StateZeroError {
         this.name = "MultipleObjectsReturned";
     }
 }
+/**
+ * Error class for database conflict errors (integrity/constraint violations).
+ */
+export class ConflictError extends StateZeroError {
+    /**
+     * Creates a new ConflictError.
+     *
+     * @param {IErrorDetail|Object|string} [detail="A database conflict occurred."] - The error details.
+     * @param {number} [status=409] - The HTTP status code.
+     */
+    constructor(detail = "A database conflict occurred.", status = 409) {
+        super("Conflict", "conflict", detail, status);
+        this.name = "ConflictError";
+    }
+}
 /**
  * Error class for AST validation errors.
  */
@@ -169,6 +184,8 @@ export function parseStateZeroError(errorResponse) {
             return new MultipleObjectsReturned(detail, status);
         case "PermissionDenied":
             return new PermissionDenied(detail, status);
+        case "ConflictError":
+            return new ConflictError(detail, status);
         case "ASTValidationError":
             return new ASTValidationError(detail, status);
         case "ConfigError":
@@ -189,6 +206,9 @@ export function parseStateZeroError(errorResponse) {
             else if (status === 404) {
                 return new DoesNotExist(detail, status);
             }
+            else if (status === 409) {
+                return new ConflictError(detail, status);
+            }
             return new StateZeroError("Unknown error", "unknown", detail, status);
     }
 }

package/dist/flavours/django/f.js

@@ -1,4 +1,3 @@
-import { ValidationError } from './errors.js';
 import * as math from 'mathjs';
 // Create a math instance
 const mathInstance = math.create();
@@ -8,7 +7,7 @@ const allowedFunctions = ['abs', 'round', 'floor', 'ceil', 'min', 'max'];
 const ALLOWED_OPERATORS = ['+', '-', '*', '/', '%', '^'];
 export function F(expression) {
     if (typeof expression !== 'string' || !expression) {
-        throw new ValidationError('F expression requires a non-empty string');
+        throw new Error('F expression requires a non-empty string');
     }
     try {
         const node = math.parse(expression);
@@ -20,7 +19,9 @@ export function F(expression) {
         };
     }
     catch (err) {
-        throw new ValidationError(`Invalid F expression: ${err.message}`);
+        if (err instanceof Error)
+            throw err;
+        throw new Error(`Invalid F expression: ${err}`);
     }
 }
 function validateExpression(node) {
@@ -28,19 +29,19 @@ function validateExpression(node) {
         return;
     if (node.type === 'OperatorNode') {
         if (!ALLOWED_OPERATORS.includes(node.op)) {
-            throw new ValidationError(`Unsupported operator: ${node.op}`);
+            throw new Error(`Unsupported operator: ${node.op}`);
         }
         node.args.forEach(validateExpression);
     }
     else if (node.type === 'FunctionNode') {
         if (!allowedFunctions.includes(node.name)) {
-            throw new ValidationError(`Function not allowed: ${node.name}`);
+            throw new Error(`Function not allowed: ${node.name}`);
         }
         node.args.forEach(validateExpression);
     }
     else if (node.type === 'SymbolNode') {
         if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(node.name)) {
-            throw new ValidationError(`Invalid field name: ${node.name}`);
+            throw new Error(`Invalid field name: ${node.name}`);
         }
     }
     else if (node.type === 'ConstantNode') {
@@ -50,31 +51,31 @@ function validateExpression(node) {
         validateExpression(node.content);
     }
     else if (node.type === 'ConditionalNode') {
-        throw new ValidationError('Conditional expressions are not supported in F expressions');
+        throw new Error('Conditional expressions are not supported in F expressions');
     }
     else if (node.type === 'AssignmentNode') {
-        throw new ValidationError('Assignment expressions are not supported in F expressions');
+        throw new Error('Assignment expressions are not supported in F expressions');
     }
     else if (node.type === 'BlockNode') {
-        throw new ValidationError('Block expressions are not supported in F expressions');
+        throw new Error('Block expressions are not supported in F expressions');
     }
     else if (node.type === 'AccessorNode') {
-        throw new ValidationError('Accessor expressions are not supported in F expressions');
+        throw new Error('Accessor expressions are not supported in F expressions');
     }
     else if (node.type === 'IndexNode') {
-        throw new ValidationError('Index expressions are not supported in F expressions');
+        throw new Error('Index expressions are not supported in F expressions');
     }
     else if (node.type === 'RangeNode') {
-        throw new ValidationError('Range expressions are not supported in F expressions');
+        throw new Error('Range expressions are not supported in F expressions');
     }
     else if (node.type === 'ArrayNode') {
-        throw new ValidationError('Array expressions are not supported in F expressions');
+        throw new Error('Array expressions are not supported in F expressions');
     }
     else if (node.type === 'ObjectNode') {
-        throw new ValidationError('Object expressions are not supported in F expressions');
+        throw new Error('Object expressions are not supported in F expressions');
     }
     else {
-        throw new ValidationError(`Unsupported node type: ${node.type}`);
+        throw new Error(`Unsupported node type: ${node.type}`);
     }
 }
 export function evaluateExpression(expr, data) {

package/dist/index.d.ts

@@ -18,6 +18,7 @@ import { ValidationError } from "./flavours/django/errors.js";
 import { DoesNotExist } from "./flavours/django/errors.js";
 import { PermissionDenied } from "./flavours/django/errors.js";
 import { MultipleObjectsReturned } from "./flavours/django/errors.js";
+import { ConflictError } from "./flavours/django/errors.js";
 import { ASTValidationError } from "./flavours/django/errors.js";
 import { ConfigError } from "./flavours/django/errors.js";
 import { parseStateZeroError } from "./flavours/django/errors.js";
@@ -43,4 +44,4 @@ import { setupTestStateZero } from "./testing.js";
 import { createActionMocker } from "./testing.js";
 import { seedRemote } from "./testing.js";
 import { resetRemote } from "./testing.js";
-export { EventType, PusherEventReceiver, setEventReceiver, getEventReceiver, setNamespaceResolver, setupStateZero, resetStateZero, FileObject, querysetStoreRegistry, modelStoreRegistry, metricRegistry, syncManager, Operation, operationRegistry, Q, StateZeroError, ValidationError, DoesNotExist, PermissionDenied, MultipleObjectsReturned, ASTValidationError, ConfigError, parseStateZeroError, QuerySet, Manager, ResultTuple, Model, setConfig, getConfig, setBackendConfig, initializeEventReceiver, configInstance, getModelClass, initEventHandler, cleanupEventHandler, setAdapters, wrapReactiveModel, wrapReactiveQuerySet, serializeActionPayload, onStateZeroError, createTestConfig, setupTestStateZero, createActionMocker, seedRemote, resetRemote };
+export { EventType, PusherEventReceiver, setEventReceiver, getEventReceiver, setNamespaceResolver, setupStateZero, resetStateZero, FileObject, querysetStoreRegistry, modelStoreRegistry, metricRegistry, syncManager, Operation, operationRegistry, Q, StateZeroError, ValidationError, DoesNotExist, PermissionDenied, MultipleObjectsReturned, ConflictError, ASTValidationError, ConfigError, parseStateZeroError, QuerySet, Manager, ResultTuple, Model, setConfig, getConfig, setBackendConfig, initializeEventReceiver, configInstance, getModelClass, initEventHandler, cleanupEventHandler, setAdapters, wrapReactiveModel, wrapReactiveQuerySet, serializeActionPayload, onStateZeroError, createTestConfig, setupTestStateZero, createActionMocker, seedRemote, resetRemote };

package/dist/index.js

@@ -3,7 +3,7 @@ import { EventType, PusherEventReceiver, setEventReceiver, getEventReceiver, set
 import { setupStateZero } from "./setup.js";
 // Django flavor modules
 import { Q } from "./flavours/django/q.js";
-import { StateZeroError, ValidationError, DoesNotExist, PermissionDenied, MultipleObjectsReturned, ASTValidationError, ConfigError, parseStateZeroError, } from "./flavours/django/errors.js";
+import { StateZeroError, ValidationError, DoesNotExist, PermissionDenied, MultipleObjectsReturned, ConflictError, ASTValidationError, ConfigError, parseStateZeroError, } from "./flavours/django/errors.js";
 import { querysetStoreRegistry } from "./syncEngine/registries/querysetStoreRegistry.js";
 import { modelStoreRegistry } from "./syncEngine/registries/modelStoreRegistry.js";
 import { metricRegistry } from "./syncEngine/registries/metricRegistry.js";
@@ -35,7 +35,7 @@ querysetStoreRegistry, modelStoreRegistry, metricRegistry, syncManager,
 // Operations
 Operation, operationRegistry, 
 // Django flavor modules
-Q, StateZeroError, ValidationError, DoesNotExist, PermissionDenied, MultipleObjectsReturned, ASTValidationError, ConfigError, parseStateZeroError, QuerySet, Manager, ResultTuple, Model, 
+Q, StateZeroError, ValidationError, DoesNotExist, PermissionDenied, MultipleObjectsReturned, ConflictError, ASTValidationError, ConfigError, parseStateZeroError, QuerySet, Manager, ResultTuple, Model, 
 // Configuration
 setConfig, getConfig, setBackendConfig, initializeEventReceiver, configInstance, getModelClass, 
 // Reactivity framework integration