@statezero/core 0.2.38 → 0.2.40

package/dist/flavours/django/model.js

@@ -0,0 +1,366 @@
+import { Manager } from "./manager.js";
+import { ValidationError } from "./errors.js";
+import { modelStoreRegistry } from "../../syncEngine/registries/modelStoreRegistry.js";
+import { isNil } from "lodash-es";
+import { QueryExecutor } from "./queryExecutor.js";
+import { wrapReactiveModel } from "../../reactiveAdaptor.js";
+import { DateParsingHelpers } from "./dates.js";
+import { FileObject } from './files.js';
+import { configInstance } from "../../config.js";
+import { ModelSerializer } from "./serializers.js";
+import { parseStateZeroError, MultipleObjectsReturned, DoesNotExist, } from "./errors.js";
+import axios from "axios";
+/**
+ * A constructor for a Model.
+ *
+ * @typedef {Function} ModelConstructor
+ * @param {any} data - Data to initialize the model.
+ * @returns {Model}
+ *
+ * @property {Manager} objects - The model's manager.
+ * @property {string} configKey - The configuration key.
+ * @property {string} modelName - The model name.
+ * @property {string} primaryKeyField - The primary key field (default 'id').
+ */
+/**
+ * Base Model class with integrated API implementation.
+ *
+ * @abstract
+ */
+export class Model {
+    constructor(data = {}) {
+        this.serializer = new ModelSerializer(this.constructor);
+        const serializedData = this.serializer.toInternal(data);
+        this._data = serializedData;
+        this._pk = serializedData[this.constructor.primaryKeyField] || undefined;
+        this.__version = 0;
+        return wrapReactiveModel(this);
+    }
+    /**
+     * Remote-only manager that skips local store updates.
+     */
+    static get remote() {
+        return this.objects.remote();
+    }
+    touch() {
+        this.__version++;
+    }
+    /**
+     * Returns the primary key of the model instance.
+     *
+     * @returns {number|undefined} The primary key.
+     */
+    get pk() {
+        return this._pk;
+    }
+    /**
+     * Sets the primary key of the model instance.
+     *
+     * @param {number|undefined} value - The new primary key value.
+     */
+    set pk(value) {
+        this._pk = value;
+        this.touch();
+    }
+    /**
+     * Instantiate from pk using queryset scoped singletons
+     */
+    static fromPk(pk, querySet) {
+        let qsId = querySet ? querySet.__uuid : "";
+        let key = `${qsId}__${this.configKey}__${this.modelName}__${pk}`;
+        if (!this.instanceCache.has(key)) {
+            const instance = new this();
+            instance.pk = pk;
+            this.instanceCache.set(key, instance);
+        }
+        return this.instanceCache.get(key);
+    }
+    /**
+     * Gets a field value from the internal data store
+     *
+     * @param {string} field - The field name
+     * @returns {any} The field value
+     */
+    getField(field) {
+        // Access the reactive __version property to establish dependency for vue integration
+        const trackVersion = this.__version;
+        const ModelClass = this.constructor;
+        if (ModelClass.primaryKeyField === field)
+            return this._pk;
+        // check local overrides
+        let value = this._data[field];
+        // if its not been overridden, get it from the store
+        if (value === undefined && !isNil(this._pk)) {
+            let storedValue = modelStoreRegistry.getEntity(ModelClass, this._pk);
+            if (storedValue)
+                value = storedValue[field]; // if stops null -> undefined
+        }
+        // Use serializer to convert internal format to live format
+        return this.serializer.toLiveField(field, value);
+    }
+    /**
+     * Sets a field value in the internal data store
+     *
+     * @param {string} field - The field name
+     * @param {any} value - The field value to set
+     */
+    setField(field, value) {
+        const ModelClass = this.constructor;
+        // Use serializer to convert live format to internal format
+        const internalValue = this.serializer.toInternalField(field, value);
+        if (ModelClass.primaryKeyField === field) {
+            this._pk = internalValue;
+        }
+        else {
+            this._data[field] = internalValue;
+        }
+    }
+    /**
+     * Validates that the provided data object only contains keys
+     * defined in the model's allowed fields. Supports nested fields
+     * using double underscore notation (e.g., author__name).
+     *
+     * @param {Object} data - The object to validate.
+     * @throws {ValidationError} If an unknown key is found.
+     */
+    static validateFields(data) {
+        if (isNil(data))
+            return;
+        const allowedFields = this.fields;
+        for (const key of Object.keys(data)) {
+            if (key === "repr" || key === "type")
+                continue;
+            // Handle nested fields by splitting on double underscore
+            // and taking just the base field name
+            const baseField = key.split("__")[0];
+            if (!allowedFields.includes(baseField)) {
+                let errorMsg = `Invalid field: ${baseField}. Allowed fields are: ${allowedFields.join(", ")}`;
+                console.error(errorMsg);
+                throw new ValidationError(errorMsg);
+            }
+        }
+    }
+    /**
+     * Serializes the model instance.
+     *
+     * By default, it returns all enumerable own properties.
+     * Subclasses should override this to return specific keys.
+     *
+     * @param {boolean} includeRepr - Whether to include the repr field (for caching). Default: false.
+     * @returns {Object} The serialized model data.
+     */
+    serialize(includeRepr = false) {
+        const ModelClass = this.constructor;
+        const data = {};
+        // Collect all field values (already in internal format)
+        for (const field of ModelClass.fields) {
+            if (field === ModelClass.primaryKeyField) {
+                data[field] = this._pk;
+            }
+            else {
+                let value = this._data[field];
+                // Get from store if not in local data
+                if (value === undefined && !isNil(this._pk)) {
+                    const storedData = modelStoreRegistry.getEntity(ModelClass, this._pk);
+                    if (storedData) {
+                        value = storedData[field];
+                    }
+                }
+                data[field] = value;
+            }
+        }
+        // Include repr field if requested (for caching purposes)
+        if (includeRepr && !isNil(this._pk)) {
+            const storedData = modelStoreRegistry.getEntity(ModelClass, this._pk);
+            if (storedData && storedData.repr) {
+                data.repr = storedData.repr;
+            }
+        }
+        // Data is already in internal format, so return as-is for API transmission
+        return data;
+    }
+    /**
+     * Saves the model instance by either creating a new record or updating an existing one.
+     *
+     * @returns {Promise<Model>} A promise that resolves to the updated model instance.
+     */
+    async save() {
+        const ModelClass = this.constructor;
+        const pkField = ModelClass.primaryKeyField;
+        const querySet = !this.pk
+            ? ModelClass.objects.newQuerySet()
+            : ModelClass.objects.filter({ [pkField]: this.pk });
+        const data = this.serialize();
+        let instance;
+        if (!this.pk) {
+            // Create new instance
+            instance = await QueryExecutor.execute(querySet, "create", { data });
+        }
+        else {
+            // Update existing instance
+            instance = await QueryExecutor.execute(querySet, "update_instance", {
+                data,
+            });
+        }
+        this._pk = instance.pk;
+        this._data = {};
+        return this;
+    }
+    /**
+     * Deletes the instance from the database.
+     *
+     * Returns a tuple with the number of objects deleted and an object mapping
+     * model names to the number of objects deleted, matching Django's behavior.
+     *
+     * @returns {Promise<[number, Object]>} A promise that resolves to the deletion result.
+     * @throws {Error} If the instance has not been saved (no primary key).
+     */
+    async delete() {
+        if (!this.pk) {
+            throw new Error("Cannot delete unsaved instance");
+        }
+        const ModelClass = this.constructor;
+        const pkField = ModelClass.primaryKeyField;
+        const querySet = ModelClass.objects.filter({ [pkField]: this.pk });
+        // Pass the instance data with primary key as the args
+        const args = { [pkField]: this.pk };
+        const result = await QueryExecutor.execute(querySet, "delete_instance", args);
+        // result -> [deletedCount, { [modelName]: deletedCount }];
+        return result;
+    }
+    /**
+     * Refreshes the model instance with data from the database.
+     *
+     * @returns {Promise<void>} A promise that resolves when the instance has been refreshed.
+     * @throws {Error} If the instance has not been saved (no primary key).
+     */
+    async refreshFromDb() {
+        if (!this.pk) {
+            throw new Error("Cannot refresh unsaved instance");
+        }
+        const ModelClass = this.constructor;
+        const fresh = await ModelClass.objects.get({
+            [ModelClass.primaryKeyField]: this.pk,
+        });
+        // clear the current data and fresh data will flow
+        this._data = {};
+    }
+    /**
+     * Validates the model instance using the same serialize behavior as save()
+     * @param {string} validateType - 'create' or 'update' (defaults to auto-detect)
+     * @param {boolean} partial - Whether to allow partial validation
+     * @returns {Promise<boolean>} Promise that resolves to true if valid, throws error if invalid
+     */
+    async validate(validateType = null, partial = false) {
+        const ModelClass = this.constructor;
+        if (!validateType) {
+            validateType = this.pk ? "update" : "create";
+        }
+        // Validate the validateType parameter
+        if (!["update", "create"].includes(validateType)) {
+            throw new Error(`Validation type must be 'update' or 'create', not '${validateType}'`);
+        }
+        // Use the same serialize logic as save()
+        const data = this.serialize();
+        // Delegate to static method
+        return ModelClass.validate(data, validateType, partial);
+    }
+    /**
+     * Static method to validate data without creating an instance
+     * @param {Object} data - Data to validate
+     * @param {string} validateType - 'create' or 'update'
+     * @param {boolean} partial - Whether to allow partial validation
+     * @returns {Promise<boolean>} Promise that resolves to true if valid, throws error if invalid
+     */
+    static async validate(data, validateType = "create", partial = false) {
+        const ModelClass = this;
+        // Validate the validateType parameter
+        if (!["update", "create"].includes(validateType)) {
+            throw new Error(`Validation type must be 'update' or 'create', not '${validateType}'`);
+        }
+        // Get backend config and check if it exists
+        const config = configInstance.getConfig();
+        const backend = config.backendConfigs[ModelClass.configKey];
+        if (!backend) {
+            throw new Error(`No backend configuration found for key: ${ModelClass.configKey}`);
+        }
+        // Build URL for validate endpoint
+        const baseUrl = backend.API_URL.replace(/\/+$/, "");
+        const url = `${baseUrl}/${ModelClass.modelName}/validate/`;
+        // Prepare headers
+        const headers = {
+            "Content-Type": "application/json",
+            ...(backend.getAuthHeaders ? backend.getAuthHeaders() : {}),
+        };
+        // Make direct API call to validate endpoint
+        try {
+            const response = await axios.post(url, {
+                data: data,
+                validate_type: validateType,
+                partial: partial,
+            }, { headers });
+            // Backend returns {"valid": true} on success
+            return response.data.valid === true;
+        }
+        catch (error) {
+            if (error.response && error.response.data) {
+                const parsedError = parseStateZeroError(error.response.data);
+                if (Error.captureStackTrace) {
+                    Error.captureStackTrace(parsedError, ModelClass.validate);
+                }
+                throw parsedError;
+            }
+            throw new Error(`Validation failed: ${error.message}`);
+        }
+    }
+    /**
+     * Get field permissions for the current user (cached on the class)
+     * @param {boolean} refresh - Force refresh the cached permissions
+     * @returns {Promise<{visible_fields: string[], creatable_fields: string[], editable_fields: string[]}>}
+     */
+    static async getFieldPermissions(refresh = false) {
+        const ModelClass = this;
+        // Return cached permissions if available and not forcing refresh
+        if (!refresh && ModelClass._fieldPermissionsCache) {
+            return ModelClass._fieldPermissionsCache;
+        }
+        // Get backend config and check if it exists
+        const config = configInstance.getConfig();
+        const backend = config.backendConfigs[ModelClass.configKey];
+        if (!backend) {
+            throw new Error(`No backend configuration found for key: ${ModelClass.configKey}`);
+        }
+        // Build URL for field permissions endpoint
+        const baseUrl = backend.API_URL.replace(/\/+$/, "");
+        const url = `${baseUrl}/${ModelClass.modelName}/field-permissions/`;
+        // Prepare headers
+        const headers = {
+            "Content-Type": "application/json",
+            ...(backend.getAuthHeaders ? backend.getAuthHeaders() : {}),
+        };
+        // Make direct API call to field permissions endpoint
+        try {
+            const response = await axios.get(url, { headers });
+            // Cache the permissions on the class
+            ModelClass._fieldPermissionsCache = response.data;
+            // Backend returns {visible_fields: [], creatable_fields: [], editable_fields: []}
+            return response.data;
+        }
+        catch (error) {
+            if (error.response && error.response.data) {
+                const parsedError = parseStateZeroError(error.response.data);
+                if (Error.captureStackTrace) {
+                    Error.captureStackTrace(parsedError, ModelClass.getFieldPermissions);
+                }
+                throw parsedError;
+            }
+            throw new Error(`Failed to get field permissions: ${error.message}`);
+        }
+    }
+}
+/**
+ * Creates a new Model instance.
+ *
+ * @param {any} [data={}] - The data for initialization.
+ */
+Model.instanceCache = new Map();

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

@@ -0,0 +1,73 @@
+/**
+ * Factory for creating Operation instances with consistent behavior
+ * across QueryExecutor and hotpath event handling
+ */
+export class OperationFactory {
+    /**
+     * Create a CREATE operation
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Object} data - The data for the new instance
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createCreateOperation(queryset: QuerySet, data?: Object, operationId?: string): Operation;
+    /**
+     * Create a BULK_CREATE operation
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Array<Object>} dataList - Array of data objects for the new instances
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createBulkCreateOperation(queryset: QuerySet, dataList?: Array<Object>, operationId?: string): Operation;
+    /**
+     * Create an UPDATE operation with optimistic instance updates
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Object} data - The update data
+     * @param {Object} filter - Optional filter for the update
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createUpdateOperation(queryset: QuerySet, data?: Object, filter?: Object, operationId?: string): Operation;
+    /**
+     * Create a DELETE operation
+     * @param {QuerySet} queryset - The queryset context
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createDeleteOperation(queryset: QuerySet, operationId?: string): Operation;
+    /**
+     * Create an UPDATE_INSTANCE operation
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Object} data - The update data
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createUpdateInstanceOperation(queryset: QuerySet, data?: Object, operationId?: string): Operation;
+    /**
+     * Create a DELETE_INSTANCE operation
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Object} instanceData - The instance to delete (object with PK)
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createDeleteInstanceOperation(queryset: QuerySet, instanceData: Object, operationId?: string): Operation;
+    /**
+     * Create a GET_OR_CREATE operation with local filtering logic
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Object} lookup - The lookup criteria
+     * @param {Object} defaults - The default values for creation
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createGetOrCreateOperation(queryset: QuerySet, lookup?: Object, defaults?: Object, operationId?: string): Operation;
+    /**
+     * Create an UPDATE_OR_CREATE operation with local filtering logic
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Object} lookup - The lookup criteria
+     * @param {Object} defaults - The default values for creation/update
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createUpdateOrCreateOperation(queryset: QuerySet, lookup?: Object, defaults?: Object, operationId?: string): Operation;
+}
+import { Operation } from '../../syncEngine/stores/operation.js';

package/dist/flavours/django/operationFactory.js

@@ -0,0 +1,248 @@
+import { Operation, Type, Status } from '../../syncEngine/stores/operation.js';
+import { v7 as uuid7 } from 'uuid';
+import { createTempPk } from './tempPk.js';
+import { getRequiredFields, pickRequiredFields, processQuery } from '../../filtering/localFiltering.js';
+import { evaluateExpression } from './f.js';
+import { modelStoreRegistry } from '../../syncEngine/registries/modelStoreRegistry.js';
+import { querysetStoreRegistry } from '../../syncEngine/registries/querysetStoreRegistry.js';
+import { isNil } from 'lodash-es';
+/**
+ * Factory for creating Operation instances with consistent behavior
+ * across QueryExecutor and hotpath event handling
+ */
+export class OperationFactory {
+    /**
+     * Create a CREATE operation
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Object} data - The data for the new instance
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createCreateOperation(queryset, data = {}, operationId = null) {
+        const ModelClass = queryset.ModelClass;
+        const primaryKeyField = ModelClass.primaryKeyField;
+        const opId = operationId || `${uuid7()}`;
+        const tempPk = createTempPk(opId);
+        return new Operation({
+            operationId: opId,
+            type: Type.CREATE,
+            instances: [{ ...data, [primaryKeyField]: tempPk }],
+            queryset: queryset,
+            args: { data },
+            localOnly: queryset._optimisticOnly || false,
+        });
+    }
+    /**
+     * Create a BULK_CREATE operation
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Array<Object>} dataList - Array of data objects for the new instances
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createBulkCreateOperation(queryset, dataList = [], operationId = null) {
+        const ModelClass = queryset.ModelClass;
+        const primaryKeyField = ModelClass.primaryKeyField;
+        const opId = operationId || `${uuid7()}`;
+        // Create temp PKs for each instance
+        const instances = dataList.map((data, index) => {
+            const tempPk = createTempPk(`${opId}_${index}`);
+            return { ...data, [primaryKeyField]: tempPk };
+        });
+        return new Operation({
+            operationId: opId,
+            type: Type.BULK_CREATE,
+            instances: instances,
+            queryset: queryset,
+            args: { data: dataList },
+            localOnly: queryset._optimisticOnly || false,
+        });
+    }
+    /**
+     * Create an UPDATE operation with optimistic instance updates
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Object} data - The update data
+     * @param {Object} filter - Optional filter for the update
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createUpdateOperation(queryset, data = {}, filter = null, operationId = null) {
+        const ModelClass = queryset.ModelClass;
+        const primaryKeyField = ModelClass.primaryKeyField;
+        const store = querysetStoreRegistry.getStore(queryset);
+        const querysetPks = store.render();
+        const opId = operationId || `${uuid7()}`;
+        // Create optimistic instances with F expression evaluation
+        const optimisticInstances = querysetPks.map(pk => {
+            const instance = modelStoreRegistry.getEntity(ModelClass, pk);
+            const updatedInstance = { ...instance };
+            updatedInstance[primaryKeyField] = pk;
+            for (const [key, value] of Object.entries(data)) {
+                if (value && typeof value === 'object' && value.__f_expr) {
+                    const evaluatedValue = evaluateExpression(value, instance);
+                    if (evaluatedValue !== null) {
+                        updatedInstance[key] = evaluatedValue;
+                    }
+                    else {
+                        updatedInstance[key] = instance[key];
+                    }
+                }
+                else {
+                    updatedInstance[key] = value;
+                }
+            }
+            return updatedInstance;
+        });
+        return new Operation({
+            operationId: opId,
+            type: Type.UPDATE,
+            instances: optimisticInstances,
+            queryset: queryset,
+            args: { filter, data },
+            localOnly: queryset._optimisticOnly || false,
+        });
+    }
+    /**
+     * Create a DELETE operation
+     * @param {QuerySet} queryset - The queryset context
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createDeleteOperation(queryset, operationId = null) {
+        const ModelClass = queryset.ModelClass;
+        const primaryKeyField = ModelClass.primaryKeyField;
+        const store = querysetStoreRegistry.getStore(queryset);
+        const querysetPks = store.render();
+        const opId = operationId || `${uuid7()}`;
+        const instances = querysetPks.map((pk) => ({ [primaryKeyField]: pk }));
+        return new Operation({
+            operationId: opId,
+            type: Type.DELETE,
+            instances: instances,
+            queryset: queryset,
+            args: {},
+            localOnly: queryset._optimisticOnly || false,
+        });
+    }
+    /**
+     * Create an UPDATE_INSTANCE operation
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Object} data - The update data
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createUpdateInstanceOperation(queryset, data = {}, operationId = null) {
+        const ModelClass = queryset.ModelClass;
+        const primaryKeyField = ModelClass.primaryKeyField;
+        const store = querysetStoreRegistry.getStore(queryset);
+        const querysetPks = store.render();
+        const opId = operationId || `${uuid7()}`;
+        const instances = querysetPks.map(pk => ({ ...data, [primaryKeyField]: pk }));
+        return new Operation({
+            operationId: opId,
+            type: Type.UPDATE_INSTANCE,
+            instances: instances,
+            queryset: queryset,
+            args: { data },
+            localOnly: queryset._optimisticOnly || false,
+        });
+    }
+    /**
+     * Create a DELETE_INSTANCE operation
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Object} instanceData - The instance to delete (object with PK)
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createDeleteInstanceOperation(queryset, instanceData, operationId = null) {
+        const opId = operationId || `${uuid7()}`;
+        return new Operation({
+            operationId: opId,
+            type: Type.DELETE_INSTANCE,
+            instances: [instanceData],
+            queryset: queryset,
+            args: instanceData,
+            localOnly: queryset._optimisticOnly || false,
+        });
+    }
+    /**
+     * Create a GET_OR_CREATE operation with local filtering logic
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Object} lookup - The lookup criteria
+     * @param {Object} defaults - The default values for creation
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createGetOrCreateOperation(queryset, lookup = {}, defaults = {}, operationId = null) {
+        const ModelClass = queryset.ModelClass;
+        const primaryKeyField = ModelClass.primaryKeyField;
+        const opId = operationId || `${uuid7()}`;
+        // Get all current instances from the store for local filtering
+        const modelStore = modelStoreRegistry.getStore(ModelClass);
+        const allInstances = modelStore.render();
+        // Create a queryset filter for the lookup criteria
+        const lookupFilter = { ...lookup };
+        const lookupQuerySet = new queryset.constructor(ModelClass).filter(lookupFilter);
+        const lookupQuery = lookupQuerySet.build();
+        // Use local filtering to find matching instances
+        const requiredPaths = getRequiredFields(lookupQuery, ModelClass);
+        const prunedData = allInstances.map(inst => pickRequiredFields(requiredPaths, ModelClass.fromPk(inst[primaryKeyField], queryset)));
+        const matchingPks = processQuery(prunedData, lookupQuery, ModelClass);
+        // Find the corresponding instances
+        const matchingInstances = allInstances.filter(inst => matchingPks.includes(inst[primaryKeyField]));
+        const isCreatingNew = matchingInstances.length === 0;
+        const effectiveType = isCreatingNew ? Type.CREATE : Type.UPDATE;
+        // Create the instance data
+        const instanceData = isCreatingNew
+            ? { ...lookup, ...defaults, [primaryKeyField]: opId }
+            : matchingInstances[0];
+        return new Operation({
+            operationId: opId,
+            type: effectiveType,
+            instances: [instanceData],
+            queryset: queryset,
+            args: { lookup, defaults },
+            localOnly: queryset._optimisticOnly || false,
+        });
+    }
+    /**
+     * Create an UPDATE_OR_CREATE operation with local filtering logic
+     * @param {QuerySet} queryset - The queryset context
+     * @param {Object} lookup - The lookup criteria
+     * @param {Object} defaults - The default values for creation/update
+     * @param {string} [operationId] - Optional operation ID (for hotpath events)
+     * @returns {Operation} The created operation
+     */
+    static createUpdateOrCreateOperation(queryset, lookup = {}, defaults = {}, operationId = null) {
+        const ModelClass = queryset.ModelClass;
+        const primaryKeyField = ModelClass.primaryKeyField;
+        const opId = operationId || `${uuid7()}`;
+        // Get all current instances from the store for local filtering
+        const modelStore = modelStoreRegistry.getStore(ModelClass);
+        const allInstances = modelStore.render();
+        // Create a queryset filter for the lookup criteria
+        const lookupFilter = { ...lookup };
+        const lookupQuerySet = new queryset.constructor(ModelClass).filter(lookupFilter);
+        const lookupQuery = lookupQuerySet.build();
+        // Use local filtering to find matching instances
+        const requiredPaths = getRequiredFields(lookupQuery, ModelClass);
+        const prunedData = allInstances.map(inst => pickRequiredFields(requiredPaths, ModelClass.fromPk(inst[primaryKeyField], queryset)));
+        const matchingPks = processQuery(prunedData, lookupQuery, ModelClass);
+        // Find the corresponding instances
+        const matchingInstances = allInstances.filter(inst => matchingPks.includes(inst[primaryKeyField]));
+        const isCreatingNew = matchingInstances.length === 0;
+        const isUpdating = !isCreatingNew;
+        const effectiveType = isCreatingNew ? Type.CREATE : Type.UPDATE;
+        // Create the instance data
+        const instanceData = isCreatingNew
+            ? { ...lookup, ...defaults, [primaryKeyField]: opId }
+            : { ...matchingInstances[0], ...defaults };
+        return new Operation({
+            operationId: opId,
+            type: effectiveType,
+            instances: [instanceData],
+            queryset: queryset,
+            args: { lookup, defaults },
+            localOnly: queryset._optimisticOnly || false,
+        });
+    }
+}