@statezero/core 0.2.38 → 0.2.40

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

@@ -0,0 +1,39 @@
+/**
+ * Serializes an action payload based on the action's input schema.
+ * Automatically handles model instances (extracts PK), files, dates, etc.
+ *
+ * @param {Object} payload - The raw payload with potentially model instances
+ * @param {Object} inputProperties - The action's input_properties schema
+ * @returns {Object} Serialized payload ready for API transmission
+ */
+export function serializeActionPayload(payload: Object, inputProperties: Object): Object;
+export namespace fileFieldSerializer {
+    function toInternal(value: any, context?: {}): any;
+    function toLive(value: any, context?: {}): any;
+}
+export namespace dateFieldSerializer {
+    export function toInternal_1(value: any, context?: {}): string | null | undefined;
+    export { toInternal_1 as toInternal };
+    export function toLive_1(value: any, context?: {}): any;
+    export { toLive_1 as toLive };
+}
+export namespace relationshipFieldSerializer {
+    export function toInternal_2(value: any, context?: {}): string | number | null | undefined;
+    export { toInternal_2 as toInternal };
+    export function toLive_2(value: any, context?: {}): any;
+    export { toLive_2 as toLive };
+}
+export namespace m2mFieldSerializer {
+    export function toInternal_3(value: any, context?: {}): (string | number)[] | null | undefined;
+    export { toInternal_3 as toInternal };
+    export function toLive_3(value: any, context?: {}): any;
+    export { toLive_3 as toLive };
+}
+export class ModelSerializer {
+    constructor(modelClass: any);
+    modelClass: any;
+    toInternalField(field: any, value: any, context?: {}): any;
+    toInternal(data: any): {};
+    toLiveField(field: any, value: any, context?: {}): any;
+    toLive(data: any): {};
+}

package/dist/flavours/django/serializers.js

@@ -0,0 +1,296 @@
+import { configInstance } from "../../config.js";
+import { isNil } from "lodash-es";
+import { DateParsingHelpers } from "./dates.js";
+/**
+ * Gets the backend timezone for a model class
+ * @param {Class} ModelClass - The model class
+ * @returns {string} The backend timezone or 'UTC' as fallback
+ */
+function getBackendTimezone(ModelClass) {
+    if (!ModelClass || !ModelClass.configKey) {
+        return 'UTC'; // Default fallback
+    }
+    const config = configInstance.getConfig();
+    const backendConfig = config.backendConfigs[ModelClass.configKey] || config.backendConfigs.default;
+    return backendConfig.BACKEND_TZ || 'UTC';
+}
+/**
+ * File field serializer - handles both camelCase (frontend) and snake_case (backend) formats
+ */
+export const fileFieldSerializer = {
+    // Store backend snake_case format internally for consistency with API
+    toInternal: (value, context = {}) => {
+        // Handle plain strings - throw error
+        if (typeof value === "string") {
+            throw new Error("File field expects a file object, not a string path");
+        }
+        if (isNil(value)) {
+            return null;
+        }
+        if (typeof value !== "object" || Array.isArray(value)) {
+            throw new Error(`expected file object, got ${Array.isArray(value) ? "array" : typeof value}`);
+        }
+        value = {
+            file_path: value.filePath || value.file_path,
+            file_name: value.fileName || value.file_name,
+            file_url: value.fileUrl || value.file_url,
+            size: value.size,
+            mime_type: value.mimeType || value.mime_type,
+        };
+        return value;
+    },
+    // Return object with both formats for maximum compatibility
+    toLive: (value, context = {}) => {
+        if (!value || typeof value !== "object")
+            return value;
+        // Build the proper file URL using the same logic as FileObject
+        const backendKey = context.model?.constructor?.configKey || "default";
+        const fullFileUrl = value.file_url
+            ? configInstance.buildFileUrl(value.file_url, backendKey)
+            : null;
+        return {
+            // snake_case (backend format)
+            file_path: value.file_path,
+            file_name: value.file_name,
+            file_url: fullFileUrl, // Use the built URL here
+            size: value.size,
+            mime_type: value.mime_type,
+            // camelCase (frontend format) - for compatibility
+            filePath: value.file_path,
+            fileName: value.file_name,
+            fileUrl: fullFileUrl, // Use the built URL here too
+            mimeType: value.mime_type,
+        };
+    },
+};
+/**
+ * Date/DateTime field serializer - uses DateParsingHelpers like the model does
+ */
+export const dateFieldSerializer = {
+    toInternal: (value, context = {}) => {
+        if (isNil(value))
+            return value;
+        // If it's already a string, keep it (from API)
+        if (typeof value === "string")
+            return value;
+        // If it's a Date object, serialize it using DateParsingHelpers
+        if (value instanceof Date) {
+            const { model, field, fieldSchema } = context;
+            // Use model schema, or create minimal schema from fieldSchema (for actions)
+            const schema = model?.schema || (fieldSchema?.format && {
+                properties: { [field]: { format: fieldSchema.format } }
+            });
+            if (schema) {
+                return DateParsingHelpers.serializeDate(value, field, schema);
+            }
+            // Fallback if no schema context
+            return value.toISOString();
+        }
+        throw new Error(`expected string or Date, got ${typeof value}`);
+    },
+    toLive: (value, context = {}) => {
+        if (isNil(value) || typeof value !== "string")
+            return value;
+        const { model, field } = context;
+        if (model?.schema) {
+            // Get the backend timezone for this model
+            const timezone = getBackendTimezone(model);
+            // Use DateParsingHelpers with timezone awareness
+            // This ensures date strings are parsed in the server timezone, not browser timezone
+            return DateParsingHelpers.parseDate(value, field, model.schema, timezone);
+        }
+        // Fallback parsing if no schema context
+        try {
+            return new Date(value);
+        }
+        catch (e) {
+            console.warn(`Failed to parse date: ${value}`);
+            return value;
+        }
+    },
+};
+/**
+ * Foreign Key / One-to-One field serializer - follows existing relationship logic
+ */
+export const relationshipFieldSerializer = {
+    toInternal: (value, context = {}) => {
+        if (isNil(value))
+            return value;
+        // Extract PK or use value directly
+        const pk = value.pk || value;
+        // Assert it's a valid PK type
+        if (typeof pk !== "string" && typeof pk !== "number") {
+            throw new Error(`Invalid primary key type for relationship field: expected string or number, got ${typeof pk}`);
+        }
+        return pk;
+    },
+    toLive: (value, context = {}) => {
+        if (isNil(value))
+            return value;
+        // Follow the exact same pattern as the original getField code
+        const { model, field } = context;
+        if (model.relationshipFields.has(field) && value) {
+            const fieldInfo = model.relationshipFields.get(field);
+            // For foreign-key and one-to-one, value is guaranteed to be a plain PK
+            return fieldInfo.ModelClass().fromPk(value);
+        }
+        return value;
+    },
+};
+/**
+ * Many-to-Many field serializer - follows existing m2m logic
+ */
+export const m2mFieldSerializer = {
+    toInternal: (value, context = {}) => {
+        if (isNil(value))
+            return value;
+        if (!Array.isArray(value))
+            throw new Error(`expected array, got ${typeof value}`);
+        return value.map((item) => {
+            // Extract PK or use item directly
+            const pk = item.pk || item;
+            // Assert it's a valid PK type
+            if (typeof pk !== "string" && typeof pk !== "number") {
+                throw new Error(`Invalid primary key type for m2m field: expected string or number, got ${typeof pk}`);
+            }
+            return pk;
+        });
+    },
+    toLive: (value, context = {}) => {
+        if (isNil(value))
+            return value;
+        // Follow the exact same pattern as the original getField code
+        const { model, field } = context;
+        if (model.relationshipFields.has(field) && value) {
+            const fieldInfo = model.relationshipFields.get(field);
+            // Data corruption check like the original
+            if (!Array.isArray(value) && value) {
+                throw new Error(`Data corruption: m2m field for ${model.modelName} stored as ${value}`);
+            }
+            // Map each pk to the full model object - exactly like original
+            return value.map((pk) => fieldInfo.ModelClass().fromPk(pk));
+        }
+        return value;
+    },
+};
+const serializers = {
+    string: {
+        "file-path": fileFieldSerializer,
+        "image-path": fileFieldSerializer,
+        "date": dateFieldSerializer,
+        "date-time": dateFieldSerializer,
+        "foreign-key": relationshipFieldSerializer,
+        "one-to-one": relationshipFieldSerializer,
+    },
+    integer: {
+        "foreign-key": relationshipFieldSerializer,
+        "one-to-one": relationshipFieldSerializer,
+    },
+    // Add other PK types as needed
+    uuid: {
+        "foreign-key": relationshipFieldSerializer,
+        "one-to-one": relationshipFieldSerializer,
+    },
+    array: {
+        "many-to-many": m2mFieldSerializer,
+    },
+};
+/**
+ * Serializes an action payload based on the action's input schema.
+ * Automatically handles model instances (extracts PK), files, dates, etc.
+ *
+ * @param {Object} payload - The raw payload with potentially model instances
+ * @param {Object} inputProperties - The action's input_properties schema
+ * @returns {Object} Serialized payload ready for API transmission
+ */
+export function serializeActionPayload(payload, inputProperties) {
+    if (!payload || !inputProperties)
+        return payload;
+    const serializedPayload = {};
+    for (const [field, value] of Object.entries(payload)) {
+        const fieldSchema = inputProperties[field];
+        if (!fieldSchema || value === undefined) {
+            serializedPayload[field] = value;
+            continue;
+        }
+        const { type, format } = fieldSchema;
+        // Check if we have a serializer for this type/format combo
+        const typeSerializers = serializers[type];
+        const serializer = typeSerializers?.[format];
+        if (serializer) {
+            serializedPayload[field] = serializer.toInternal(value, { field, fieldSchema });
+        }
+        else {
+            serializedPayload[field] = value;
+        }
+    }
+    return serializedPayload;
+}
+export class ModelSerializer {
+    constructor(modelClass) {
+        this.modelClass = modelClass;
+    }
+    toInternalField(field, value, context = {}) {
+        const fieldType = this.modelClass.schema?.properties[field]?.type;
+        const fieldFormat = this.modelClass.schema?.properties[field]?.format;
+        if (serializers[fieldType] && serializers[fieldType][fieldFormat]) {
+            return serializers[fieldType][fieldFormat].toInternal(value, {
+                model: this.modelClass,
+                field,
+                ...context,
+            });
+        }
+        // Fallback to default serialization
+        return value;
+    }
+    toInternal(data) {
+        const serializedData = {};
+        for (const field in data) {
+            serializedData[field] = this.toInternalField(field, data[field]);
+        }
+        return serializedData;
+    }
+    toLiveField(field, value, context = {}) {
+        const fieldType = this.modelClass.schema?.properties[field]?.type;
+        const fieldFormat = this.modelClass.schema?.properties[field]?.format;
+        if (serializers[fieldType] && serializers[fieldType][fieldFormat]) {
+            return serializers[fieldType][fieldFormat].toLive(value, {
+                model: this.modelClass,
+                field,
+                ...context,
+            });
+        }
+        // Django-style type coercion for basic types (mimics get_prep_value)
+        if (value !== null && value !== undefined) {
+            if (fieldType === 'integer') {
+                const num = Number(value);
+                return Number.isNaN(num) ? value : Math.trunc(num);
+            }
+            if (fieldType === 'number') {
+                const num = Number(value);
+                return Number.isNaN(num) ? value : num;
+            }
+            if (fieldType === 'boolean') {
+                if (typeof value === 'string') {
+                    const lower = value.toLowerCase();
+                    if (['true', '1', 't', 'yes'].includes(lower))
+                        return true;
+                    if (['false', '0', 'f', 'no', ''].includes(lower))
+                        return false;
+                }
+                return Boolean(value);
+            }
+            if (fieldType === 'string' && typeof value !== 'string') {
+                return String(value);
+            }
+        }
+        return value;
+    }
+    toLive(data) {
+        const serializedData = {};
+        for (const field in data) {
+            serializedData[field] = this.toLiveField(field, data[field]);
+        }
+        return serializedData;
+    }
+}

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

@@ -0,0 +1,31 @@
+/**
+ * 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
+ * @returns {boolean} - True if the string contains a TempPK tag
+ */
+export function containsTempPk(str: string): boolean;
+/**
+ * Create a temporary PK with handlebars syntax
+ */
+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
+ */
+export function replaceTempPks(payload: any): any;
+export const tempPkMap: Map<any, any>;

package/dist/flavours/django/tempPk.js

@@ -0,0 +1,92 @@
+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
+ * @returns {boolean} - True if the string contains a TempPK tag
+ */
+export function containsTempPk(str) {
+    return (typeof str === 'string' &&
+        /\{\{\s*TempPK_[^}\s]+\s*\}\}/.test(str));
+}
+/**
+ * Create a temporary PK with handlebars syntax
+ */
+export function createTempPk(uuid) {
+    const tempPk = `{{TempPK_${uuid}}}`;
+    return tempPk;
+}
+/**
+ * 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
+ */
+export function replaceTempPks(payload) {
+    if (tempPkMap.size === 0)
+        return payload;
+    const context = Object.fromEntries(tempPkMap);
+    try {
+        if (typeof payload === 'string') {
+            const template = Handlebars.compile(payload, { noEscape: true });
+            return template(context);
+        }
+        const str = superjson.stringify(payload);
+        const template = Handlebars.compile(str, { noEscape: true });
+        const replaced = template(context);
+        return superjson.parse(replaced);
+    }
+    catch (error) {
+        return payload;
+    }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Given a live reactive handle and a Promise, wire them together so
+ * the handle is also thenable.
+ *
+ * @template T
+ * @param {LiveQueryset} live
+ * @param {Promise<T>} promise
+ * @returns {LiveQueryset & Promise<T>}
+ */
+export function makeLiveThenable<T>(live: LiveQueryset, promise: Promise<T>): LiveQueryset & Promise<T>;
+/**
+ * Remove the thenable hooks and clear the optimistic flag in-place, so the object
+ * can be returned without causing a recursive await loop.
+ *
+ * @template T
+ * @param {T} live
+ * @returns {T}
+ */
+export function breakThenable<T>(live: T): T;

package/dist/flavours/django/utils.js

@@ -0,0 +1,29 @@
+/**
+ * Given a live reactive handle and a Promise, wire them together so
+ * the handle is also thenable.
+ *
+ * @template T
+ * @param {LiveQueryset} live
+ * @param {Promise<T>} promise
+ * @returns {LiveQueryset & Promise<T>}
+ */
+export function makeLiveThenable(live, promise) {
+    live.isOptimistic = true;
+    live.then = promise.then.bind(promise);
+    live.catch = promise.catch.bind(promise);
+    return live;
+}
+/**
+ * Remove the thenable hooks and clear the optimistic flag in-place, so the object
+ * can be returned without causing a recursive await loop.
+ *
+ * @template T
+ * @param {T} live
+ * @returns {T}
+ */
+export function breakThenable(live) {
+    delete live.isOptimistic;
+    delete live.then;
+    delete live.catch;
+    return live;
+}

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { EventType } from "./core/eventReceivers.js";
+import { PusherEventReceiver } from "./core/eventReceivers.js";
+import { setEventReceiver } from "./core/eventReceivers.js";
+import { getEventReceiver } from "./core/eventReceivers.js";
+import { setNamespaceResolver } from "./core/eventReceivers.js";
+import { setupStateZero } from "./setup.js";
+import { resetStateZero } from "./reset.js";
+import { FileObject } from "./flavours/django/files.js";
+import { querysetStoreRegistry } from "./syncEngine/registries/querysetStoreRegistry.js";
+import { modelStoreRegistry } from "./syncEngine/registries/modelStoreRegistry.js";
+import { metricRegistry } from "./syncEngine/registries/metricRegistry.js";
+import { syncManager } from "./syncEngine/sync.js";
+import { Operation } from "./syncEngine/stores/operation.js";
+import { operationRegistry } from "./syncEngine/stores/operation.js";
+import { Q } from "./flavours/django/q.js";
+import { StateZeroError } from "./flavours/django/errors.js";
+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 { ASTValidationError } from "./flavours/django/errors.js";
+import { ConfigError } from "./flavours/django/errors.js";
+import { parseStateZeroError } from "./flavours/django/errors.js";
+import { QuerySet } from "./flavours/django/querySet.js";
+import { Manager } from "./flavours/django/manager.js";
+import { ResultTuple } from "./flavours/django/queryExecutor.js";
+import { Model } from "./flavours/django/model.js";
+import { setConfig } from "./config.js";
+import { getConfig } from "./config.js";
+import { setBackendConfig } from "./config.js";
+import { initializeEventReceiver } from "./config.js";
+import { configInstance } from "./config.js";
+import { getModelClass } from "./config.js";
+import { initEventHandler } from "./syncEngine/stores/operationEventHandlers.js";
+import { cleanupEventHandler } from "./syncEngine/stores/operationEventHandlers.js";
+import { setAdapters } from "./reactiveAdaptor.js";
+import { wrapReactiveModel } from "./reactiveAdaptor.js";
+import { wrapReactiveQuerySet } from "./reactiveAdaptor.js";
+import { serializeActionPayload } from "./flavours/django/serializers.js";
+import { onStateZeroError } from "./errorHandler.js";
+import { createTestConfig } from "./testing.js";
+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 };

package/dist/index.js

@@ -0,0 +1,48 @@
+// Core event receivers
+import { EventType, PusherEventReceiver, setEventReceiver, getEventReceiver, setNamespaceResolver, } from "./core/eventReceivers.js";
+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 { querysetStoreRegistry } from "./syncEngine/registries/querysetStoreRegistry.js";
+import { modelStoreRegistry } from "./syncEngine/registries/modelStoreRegistry.js";
+import { metricRegistry } from "./syncEngine/registries/metricRegistry.js";
+import { QueryExecutor, ResultTuple } from "./flavours/django/queryExecutor.js";
+import { Operation, operationRegistry } from "./syncEngine/stores/operation.js";
+import { QuerySet } from "./flavours/django/querySet.js";
+import { Manager } from "./flavours/django/manager.js";
+import { Model } from "./flavours/django/model.js";
+import { FileObject } from "./flavours/django/files.js";
+import { serializeActionPayload } from "./flavours/django/serializers.js";
+// Configuration
+import { setConfig, getConfig, setBackendConfig, initializeEventReceiver, configInstance, getModelClass, } from "./config.js";
+import { setAdapters, wrapReactiveModel, wrapReactiveQuerySet, } from "./reactiveAdaptor.js";
+import { syncManager } from "./syncEngine/sync.js";
+import { initEventHandler, cleanupEventHandler, } from "./syncEngine/stores/operationEventHandlers.js";
+import { resetStateZero } from "./reset.js";
+import { onStateZeroError } from "./errorHandler.js";
+import { createTestConfig, setupTestStateZero, createActionMocker, seedRemote, resetRemote, } from "./testing.js";
+// Explicitly export everything
+export { 
+// Core event receivers
+EventType, PusherEventReceiver, setEventReceiver, getEventReceiver, setNamespaceResolver, 
+// Setup
+setupStateZero, resetStateZero, 
+// Files
+FileObject, 
+// Registry
+querysetStoreRegistry, modelStoreRegistry, metricRegistry, syncManager, 
+// Operations
+Operation, operationRegistry, 
+// Django flavor modules
+Q, StateZeroError, ValidationError, DoesNotExist, PermissionDenied, MultipleObjectsReturned, ASTValidationError, ConfigError, parseStateZeroError, QuerySet, Manager, ResultTuple, Model, 
+// Configuration
+setConfig, getConfig, setBackendConfig, initializeEventReceiver, configInstance, getModelClass, 
+// Reactivity framework integration
+initEventHandler, cleanupEventHandler, setAdapters, wrapReactiveModel, wrapReactiveQuerySet, 
+// Action utilities
+serializeActionPayload, 
+// Error handling
+onStateZeroError, 
+// Testing helpers
+createTestConfig, setupTestStateZero, createActionMocker, seedRemote, resetRemote, };