@statezero/core 0.2.37 → 0.2.38

package/dist/flavours/django/queryExecutor.js

@@ -1,590 +0,0 @@
-import axios from 'axios';
-import { configInstance } from '../../config.js';
-import { parseStateZeroError, MultipleObjectsReturned, DoesNotExist } from './errors.js';
-import { modelStoreRegistry } from '../../syncEngine/registries/modelStoreRegistry.js';
-import { querysetStoreRegistry } from '../../syncEngine/registries/querysetStoreRegistry.js';
-import { metricRegistry } from '../../syncEngine/registries/metricRegistry.js';
-import { Status } from '../../syncEngine/stores/operation.js';
-import { breakThenable, makeLiveThenable } from './utils.js';
-import { setRealPk } from './tempPk.js';
-import { isNil } from 'lodash-es';
-import { Model } from './model.js';
-import { v7 as uuid7 } from 'uuid';
-import { makeApiCall, processIncludedEntities } from './makeApiCall.js';
-import { OperationFactory } from './operationFactory.js';
-const getModelClass = configInstance.getModelClass;
-/**
- * A custom data structure that behaves as an augmented array.
- * It stores [instance, created] and also provides named properties for clarity.
- *
- * @class ResultTuple
- * @extends {Array}
- */
-export class ResultTuple extends Array {
-    /**
-     * Creates a new ResultTuple.
-     *
-     * @param {*} instance - The model instance.
-     * @param {boolean} created - Whether the instance was created.
-     */
-    constructor(instance, created) {
-        // Create an array with length 2.
-        super(2);
-        // Set array indices directly instead of using push.
-        this[0] = instance;
-        this[1] = created;
-        // Set named properties.
-        this.instance = instance;
-        this.created = created;
-    }
-}
-/**
- * Handles query execution against the backend, and parsing the response into the correct format.
- */
-export class QueryExecutor {
-    /**
-     * Executes a get operation (get, first, last) with the QuerySet.
-     *
-     * @param {QuerySet} querySet - The QuerySet to execute.
-     * @param {string} operationType - The specific get operation type.
-     * @param {Object} args - Additional arguments for the operation.
-     * @returns {Promise<Object>} The model instance.
-     */
-    static executeGet(querySet, operationType, args = {}) {
-        const ModelClass = querySet.ModelClass;
-        const store = querysetStoreRegistry.getStore(querySet);
-        const existing = store.render();
-        const tempPk = Array.isArray(existing) && existing.length === 1 ? existing[0] : null;
-        // always return a Model instance (pk might be null)
-        const live = ModelClass.fromPk(tempPk, querySet);
-        const promise = makeApiCall(querySet, operationType, args).then((resp) => {
-            const { data, included, model_name } = resp.data;
-            if (isNil(data) || (Array.isArray(data) && data.length === 0)) {
-                return null;
-            }
-            processIncludedEntities(modelStoreRegistry, included, ModelClass, querySet);
-            const realPk = Array.isArray(data) ? data[0] : data;
-            // swap in the real PK on the same instance, will trigger reactivity
-            live.pk = realPk;
-            breakThenable(live);
-            return live;
-        });
-        return makeLiveThenable(live, promise);
-    }
-    /**
-     * Execute a list-style API call for the given QuerySet, update the in‑memory store with the returned primary keys,
-     * process any included entities, and return a live‑thenable that keeps the local "live" collection in sync.
-     *
-     * @template T  The model type of the QuerySet
-     * @param {QuerySet<T>} qs
-     *   The QuerySet to execute.
-     * @param {string} [op="list"]
-     *   The operation to perform. Defaults to `"list"`, but could be overridden for other list‑style endpoints.
-     * @param {Object} [args={}]
-     *   Additional arguments to pass through to the underlying API call (e.g. filters, pagination).
-     * @returns {LiveThenable<import('./makeLiveThenable').Result<T[]>>}
-     *   A live‑thenable wrapping an array of primary‑key values for the fetched models. The live part remains
-     *   synchronized with the in‑memory store.
-     */
-    static executeList(qs, op = "list", args = {}) {
-        const live = querysetStoreRegistry.getEntity(qs);
-        const promise = makeApiCall(qs, op, args).then((resp) => {
-            const { data, included } = resp.data;
-            processIncludedEntities(modelStoreRegistry, included, qs.ModelClass, qs);
-            const pks = Array.isArray(data) ? data : [];
-            querysetStoreRegistry.setEntity(qs, pks);
-            breakThenable(live);
-            return live;
-        });
-        return makeLiveThenable(live, promise);
-    }
-    /**
-     * Executes a get_or_create or update_or_create operation with the QuerySet.
-     *
-     * @param {QuerySet} querySet - The QuerySet to execute.
-     * @param {string} operationType - The specific operation type ('get_or_create' or 'update_or_create').
-     * @param {Object} args - Additional arguments for the operation.
-     * @returns {Promise<ResultTuple>} Tuple with instance and created flag.
-     */
-    static executeOrCreate(querySet, operationType, args = {}) {
-        const ModelClass = querySet.ModelClass;
-        const primaryKeyField = ModelClass.primaryKeyField;
-        const apiCallArgs = {
-            lookup: args.lookup || {},
-            defaults: args.defaults || {},
-        };
-        // Use the factory to create the operation (which includes local filtering logic)
-        const operation = operationType === 'get_or_create'
-            ? OperationFactory.createGetOrCreateOperation(querySet, apiCallArgs.lookup, apiCallArgs.defaults)
-            : OperationFactory.createUpdateOrCreateOperation(querySet, apiCallArgs.lookup, apiCallArgs.defaults);
-        // Determine if we're creating new based on the operation type
-        const isCreatingNew = operation.type === 'create';
-        // Create optimistic instance and result
-        const live = isCreatingNew
-            ? ModelClass.fromPk(operation.instances[0][primaryKeyField], querySet)
-            : ModelClass.fromPk(operation.instances[0][primaryKeyField], querySet);
-        let liveResult = new ResultTuple(live, isCreatingNew);
-        // If optimistic-only, skip API call and immediately confirm
-        if (operation.localOnly) {
-            operation.updateStatus(Status.CONFIRMED, operation.instances);
-            return liveResult;
-        }
-        // Make API call with original operation type for backend
-        const promise = makeApiCall(querySet, operationType, apiCallArgs, operation.operationId)
-            .then((response) => {
-            const { data, included, model_name } = response.data;
-            const created = response.metadata.created;
-            // Process included entities
-            processIncludedEntities(modelStoreRegistry, included, ModelClass, querySet);
-            // Get the real PK
-            const pk = Array.isArray(data) ? data[0] : data;
-            // Update PK if we created a new instance
-            if (isCreatingNew) {
-                live.pk = pk;
-            }
-            // Confirm operation
-            const entityMap = included[model_name] || {};
-            const entityData = entityMap[pk];
-            if (entityData) {
-                operation.mutate({
-                    instances: [entityData],
-                    status: Status.CONFIRMED,
-                });
-            }
-            // Update result with actual created flag
-            liveResult = new ResultTuple(live, created);
-            breakThenable(liveResult);
-            return liveResult;
-        })
-            .catch((error) => {
-            operation.updateStatus(Status.REJECTED);
-            throw error;
-        });
-        return makeLiveThenable(liveResult, promise);
-    }
-    /**
-     * Executes an aggregation operation with the QuerySet.
-     *
-     * @param {QuerySet} querySet - The QuerySet to execute.
-     * @param {string} operationType - The specific aggregation operation type.
-     * @param {Object} args - Additional arguments for the operation.
-     * @returns {LiveMetric} The LiveMetric instance that updates optimistically.
-     */
-    static executeAgg(querySet, operationType, args = {}) {
-        const ModelClass = querySet.ModelClass;
-        const field = operationType === 'count'
-            ? (args.field || ModelClass.primaryKeyField)
-            : args.field;
-        // Only include defined properties
-        if (operationType !== 'exists' && operationType !== 'count' && field === undefined) {
-            throw new Error(`Field parameter is required for ${operationType} operation`);
-        }
-        // Get the live metric from the registry
-        const liveMetric = metricRegistry.getEntity(operationType, querySet, field);
-        // Create the API call args
-        const apiCallArgs = {};
-        if (operationType !== 'exists') {
-            apiCallArgs.field = field;
-        }
-        // Perform the async request
-        const promise = makeApiCall(querySet, operationType, apiCallArgs).then((response) => {
-            // The aggregation result should be directly in data
-            const value = response.data;
-            // Update the metric store with the ground truth value and current queryset
-            const dataSlice = querysetStoreRegistry.getEntity(querySet);
-            metricRegistry.setEntity(operationType, querySet, field, value, dataSlice);
-            breakThenable(liveMetric);
-            // Return the value for the promise resolution
-            return value;
-        });
-        // For consistency with other methods, make the liveMetric thenable
-        return makeLiveThenable(liveMetric, promise);
-    }
-    /**
-     * Executes an exists operation with the QuerySet.
-     *
-     * @param {QuerySet} querySet - The QuerySet to execute.
-     * @param {string} operationType - The operation type (always 'exists' for this method).
-     * @param {Object} args - Additional arguments for the operation.
-     * @returns {Promise<boolean>} Whether records exist.
-     */
-    static async executeExists(querySet, operationType = "exists", args = {}) {
-        // exists
-        const apiCallArgs = {};
-        const response = await makeApiCall(querySet, operationType, apiCallArgs);
-        return response.data || false;
-    }
-    /**
-     * Executes an update operation with the QuerySet.
-     *
-     * @param {QuerySet} querySet - The QuerySet to execute.
-     * @param {string} operationType - The operation type (always 'update' for this method).
-     * @param {Object} args - Additional arguments for the operation.
-     * @returns {Promise<Array>} Tuple with count and model counts map.
-     */
-    static executeUpdate(querySet, operationType = "update", args = {}) {
-        const ModelClass = querySet.ModelClass;
-        const modelName = ModelClass.modelName;
-        const apiCallArgs = {
-            data: args.data || {},
-        };
-        const operation = OperationFactory.createUpdateOperation(querySet, apiCallArgs.data, querySet.build().filter);
-        const estimatedCount = operation.instances.length;
-        let liveResult = [estimatedCount, { [modelName]: estimatedCount }, operation.instances];
-        // If optimistic-only, skip API call and immediately confirm
-        if (operation.localOnly) {
-            operation.updateStatus(Status.CONFIRMED, operation.instances);
-            return liveResult;
-        }
-        const promise = makeApiCall(querySet, operationType, apiCallArgs, operation.operationId)
-            .then((response) => {
-            const { data, included } = response.data || {};
-            const fullData = included[modelName] || {};
-            const updatedObjects = Array.isArray(data)
-                ? data.map((pk) => (fullData[`${pk}`]))
-                : [];
-            operation.updateStatus(Status.CONFIRMED, updatedObjects);
-            const updatedCount = response.metadata?.updated_count ?? 0;
-            liveResult = [updatedCount, { [modelName]: updatedCount }, updatedObjects];
-            breakThenable(liveResult);
-            return liveResult;
-        })
-            .catch((err) => {
-            operation.updateStatus(Status.REJECTED);
-            throw err;
-        });
-        return makeLiveThenable(liveResult, promise);
-    }
-    /**
-     * Executes a delete operation with the QuerySet.
-     *
-     * @param {QuerySet} querySet - The QuerySet to execute.
-     * @param {string} operationType - The operation type (always 'delete' for this method).
-     * @param {Object} args - Additional arguments for the operation.
-     * @returns {Promise<Array>} Tuple with count and model counts map.
-     */
-    static executeDelete(querySet, operationType = "delete", args = {}) {
-        const ModelClass = querySet.ModelClass;
-        const modelName = ModelClass.modelName;
-        // Use factory to create operation
-        const operation = OperationFactory.createDeleteOperation(querySet);
-        // live placeholder: assume we delete all existing pks
-        const estimatedCount = operation.instances.length;
-        let liveResult = [estimatedCount, { [modelName]: estimatedCount }, operation.instances];
-        // If optimistic-only, skip API call and immediately confirm
-        if (operation.localOnly) {
-            operation.updateStatus(Status.CONFIRMED, operation.instances);
-            return liveResult;
-        }
-        const promise = makeApiCall(querySet, operationType, {}, operation.operationId)
-            .then((response) => {
-            const deletedCount = response.metadata.deleted_count;
-            const deletedInstances = response.metadata.rows_deleted;
-            operation.updateStatus(Status.CONFIRMED, deletedInstances);
-            liveResult = [deletedCount, { [modelName]: deletedCount }, deletedInstances || []];
-            breakThenable(liveResult);
-            return liveResult;
-        })
-            .catch((err) => {
-            operation.updateStatus(Status.REJECTED);
-            throw err;
-        });
-        return makeLiveThenable(liveResult, promise);
-    }
-    /**
-     * Executes a create operation with the QuerySet.
-     *
-     * @param {QuerySet} querySet - The QuerySet to execute.
-     * @param {string} operationType - The operation type (always 'create' for this method).
-     * @param {Object} args - Additional arguments for the operation.
-     * @returns {LiveThenable<Object>} The live Model instance which resolves to the created model.
-     */
-    static executeCreate(querySet, operationType = "create", args = {}) {
-        const ModelClass = querySet.ModelClass;
-        const operationId = `${uuid7()}`;
-        const apiCallArgs = {
-            data: args.data || {},
-        };
-        // set the data so the operationId matches
-        if (isNil(args.data)) {
-            console.warn(`executeCreate was called with null data`);
-            args.data = {};
-        }
-        // Use factory to create operation
-        const operation = OperationFactory.createCreateOperation(querySet, apiCallArgs.data, operationId);
-        const tempPk = operation.instances[0][ModelClass.primaryKeyField];
-        // 1) placeholder instance
-        const live = ModelClass.fromPk(tempPk, querySet);
-        // If optimistic-only, skip API call and immediately confirm
-        if (operation.localOnly) {
-            operation.updateStatus(Status.CONFIRMED, operation.instances);
-            return live;
-        }
-        // 2) kick off the async call
-        const promise = makeApiCall(querySet, operationType, apiCallArgs, operationId, async (response) => {
-            const { data } = response.data;
-            const pk = Array.isArray(data) ? data[0] : data;
-            setRealPk(operationId, pk);
-        })
-            .then((response) => {
-            const { data, included, model_name } = response.data;
-            // Process included entities
-            processIncludedEntities(modelStoreRegistry, included, ModelClass, querySet);
-            // Get the real PK
-            const pk = Array.isArray(data) ? data[0] : data;
-            live.pk = pk;
-            // Two‑line lookup
-            const entityMap = included[model_name] || {};
-            const entityData = entityMap[pk];
-            if (!entityData) {
-                throw new Error(`Entity data not found for ${model_name} with pk ${pk}`);
-            }
-            // Confirm operation with full entity data
-            operation.mutate({
-                instances: [entityData],
-                status: Status.CONFIRMED,
-            });
-            // Freeze the live instance
-            breakThenable(live);
-            return live;
-        })
-            .catch((error) => {
-            operation.updateStatus(Status.REJECTED);
-            throw error;
-        });
-        // 3) return the live‑thenable
-        return makeLiveThenable(live, promise);
-    }
-    /**
-     * Executes a bulk_create operation with the QuerySet.
-     *
-     * @param {QuerySet} querySet - The QuerySet to execute.
-     * @param {string} operationType - The operation type (always 'bulk_create' for this method).
-     * @param {Object} args - Additional arguments for the operation.
-     * @returns {LiveThenable<Array>} Array of live Model instances.
-     */
-    static executeBulkCreate(querySet, operationType = "bulk_create", args = {}) {
-        const ModelClass = querySet.ModelClass;
-        const operationId = `${uuid7()}`;
-        const primaryKeyField = ModelClass.primaryKeyField;
-        const apiCallArgs = {
-            data: args.data || [],
-        };
-        if (isNil(args.data) || !Array.isArray(args.data)) {
-            console.warn(`executeBulkCreate was called with invalid data`);
-            return Promise.resolve([]);
-        }
-        // Use factory to create operation
-        const operation = OperationFactory.createBulkCreateOperation(querySet, apiCallArgs.data, operationId);
-        // Create placeholder instances for each item
-        const liveInstances = operation.instances.map(instance => {
-            const tempPk = instance[primaryKeyField];
-            return ModelClass.fromPk(tempPk, querySet);
-        });
-        // If optimistic-only, skip API call and immediately confirm
-        if (operation.localOnly) {
-            operation.updateStatus(Status.CONFIRMED, operation.instances);
-            return liveInstances;
-        }
-        // Kick off the async call
-        const promise = makeApiCall(querySet, operationType, apiCallArgs, operationId, async (response) => {
-            const { data } = response.data;
-            const pks = Array.isArray(data) ? data : [];
-            // Set real PKs for all instances
-            pks.forEach((pk, index) => {
-                const tempPkKey = `${operationId}_${index}`;
-                setRealPk(tempPkKey, pk);
-            });
-        })
-            .then((response) => {
-            const { data, included, model_name } = response.data;
-            // Process included entities
-            processIncludedEntities(modelStoreRegistry, included, ModelClass, querySet);
-            // Get the real PKs
-            const pks = Array.isArray(data) ? data : [];
-            // Update each live instance with its real PK
-            pks.forEach((pk, index) => {
-                if (liveInstances[index]) {
-                    liveInstances[index].pk = pk;
-                }
-            });
-            // Get full entity data for all created instances
-            const entityMap = included[model_name] || {};
-            const confirmedInstances = pks.map(pk => entityMap[pk]).filter(Boolean);
-            // Confirm operation with full entity data
-            operation.mutate({
-                instances: confirmedInstances,
-                status: Status.CONFIRMED,
-            });
-            // Freeze all live instances
-            liveInstances.forEach(instance => breakThenable(instance));
-            // Also break the thenable on the array itself
-            breakThenable(liveInstances);
-            return liveInstances;
-        })
-            .catch((error) => {
-            operation.updateStatus(Status.REJECTED);
-            throw error;
-        });
-        // Return a live-thenable array
-        return makeLiveThenable(liveInstances, promise);
-    }
-    /**
-     * Executes an update_instance operation with the QuerySet.
-     *
-     * @param {QuerySet} querySet - The QuerySet to execute.
-     * @param {string} operationType - The operation type (always 'update_instance' for this method).
-     * @param {Object} args - Additional arguments for the operation.
-     * @returns {LiveThenable<Object>} The live Model instance which resolves to the updated model.
-     */
-    static executeUpdateInstance(querySet, operationType = "update_instance", args = {}) {
-        const ModelClass = querySet.ModelClass;
-        const primaryKeyField = ModelClass.primaryKeyField;
-        const store = querysetStoreRegistry.getStore(querySet);
-        const querysetPks = store.render();
-        const data = args.data || {};
-        // Use factory to create operation
-        const operation = OperationFactory.createUpdateInstanceOperation(querySet, data);
-        // 1) placeholder instance
-        const initialPk = Array.isArray(querysetPks) ? querysetPks[0] : null;
-        const live = ModelClass.fromPk(initialPk, querySet);
-        // If optimistic-only, skip API call and immediately confirm
-        if (operation.localOnly) {
-            operation.updateStatus(Status.CONFIRMED, operation.instances);
-            return live;
-        }
-        // 2) async call
-        const promise = makeApiCall(querySet, operationType, { data }, operation.operationId)
-            .then((response) => {
-            const { data: raw, included, model_name } = response.data;
-            // Process included entities
-            processIncludedEntities(modelStoreRegistry, included, ModelClass, querySet);
-            // Swap in the real PK
-            const pk = Array.isArray(raw) ? raw[0] : raw;
-            live.pk = pk;
-            // Two‑line lookup
-            const entityMap = included[model_name] || {};
-            const entityData = entityMap[pk];
-            if (!entityData) {
-                throw new Error(`Entity data not found for ${model_name} with pk ${pk}`);
-            }
-            // Confirm operation with full entity data
-            operation.updateStatus(Status.CONFIRMED, [entityData]);
-            // Freeze the live instance
-            breakThenable(live);
-            return live;
-        })
-            .catch((error) => {
-            operation.updateStatus(Status.REJECTED);
-            throw error;
-        });
-        // 3) return the live‑thenable
-        return makeLiveThenable(live, promise);
-    }
-    /**
-     * Executes a delete_instance operation with the QuerySet.
-     *
-     * @param {QuerySet} querySet - The QuerySet to execute.
-     * @param {string} operationType - The operation type (always 'delete_instance' for this method).
-     * @param {Object} args - Additional arguments for the operation, including the primary key.
-     * @returns {LiveThenable<Array>} A live‑thenable resolving to [deletedCount, { modelName: deletedCount }].
-     */
-    static executeDeleteInstance(querySet, operationType = "delete_instance", args = {}) {
-        const ModelClass = querySet.ModelClass;
-        const modelName = ModelClass.modelName;
-        const primaryKeyField = ModelClass.primaryKeyField;
-        // Validate that the primary key is provided
-        if (args[primaryKeyField] === undefined) {
-            throw new Error(`Primary key '${primaryKeyField}' must be provided in args for delete_instance operation`);
-        }
-        // Use factory to create operation
-        const operation = OperationFactory.createDeleteInstanceOperation(querySet, args);
-        // 1) placeholder result
-        let liveResult = [1, { [modelName]: 1 }, operation.instances];
-        // If optimistic-only, skip API call and immediately confirm
-        if (operation.localOnly) {
-            operation.updateStatus(Status.CONFIRMED, operation.instances);
-            return liveResult;
-        }
-        // 2) async call
-        const promise = makeApiCall(querySet, operationType, args, operation.operationId)
-            .then((response) => {
-            // response.data is the count for delete_instance
-            let deletedCount = 1;
-            if (typeof response.data === "number") {
-                deletedCount = response.data;
-            }
-            // Get deleted instances from metadata if available
-            const deletedInstances = response.metadata?.rows_deleted || [args];
-            // Confirm operation
-            operation.updateStatus(Status.CONFIRMED, [args]);
-            // Swap in real result and freeze
-            liveResult = [deletedCount, { [modelName]: deletedCount }, deletedInstances];
-            breakThenable(liveResult);
-            return liveResult;
-        })
-            .catch((err) => {
-            operation.updateStatus(Status.REJECTED);
-            throw err;
-        });
-        // 3) return live‑thenable
-        return makeLiveThenable(liveResult, promise);
-    }
-    /**
-     * Executes a query operation with the QuerySet.
-     *
-     * @param {QuerySet} querySet - The QuerySet to execute.
-     * @param {string} operationType - The operation type to perform.
-     * @param {Object} args - Additional arguments for the operation.
-     * @returns {Promise<any>} The operation result.
-     */
-    static execute(querySet, operationType = "list", args = {}) {
-        if (querySet._remoteOnly) {
-            return this.executeRemote(querySet, operationType, args);
-        }
-        // execute the query and return the result
-        switch (operationType) {
-            case "get":
-            case "first":
-            case "last":
-                return this.executeGet(querySet, operationType, args);
-            case "update_instance":
-                return this.executeUpdateInstance(querySet, operationType, args);
-            case "delete_instance":
-                return this.executeDeleteInstance(querySet, operationType, args);
-            case "update":
-                return this.executeUpdate(querySet, operationType, args);
-            case "delete":
-                return this.executeDelete(querySet, operationType, args);
-            case "create":
-                return this.executeCreate(querySet, operationType, args);
-            case "bulk_create":
-                return this.executeBulkCreate(querySet, operationType, args);
-            case "get_or_create":
-            case "update_or_create":
-                return this.executeOrCreate(querySet, operationType, args);
-            case "min":
-            case "max":
-            case "avg":
-            case "sum":
-            case "count":
-                return this.executeAgg(querySet, operationType, args);
-            case "exists":
-                return this.executeExists(querySet, operationType, args);
-            case "list":
-                return this.executeList(querySet, operationType, args);
-        }
-        throw new Error(`Invalid operation type: ${operationType}`);
-    }
-    /**
-     * Executes a query operation remotely without updating local stores.
-     *
-     * @param {QuerySet} querySet - The QuerySet to execute.
-     * @param {string} operationType - The operation type to perform.
-     * @param {Object} args - Additional arguments for the operation.
-     * @returns {Promise<any>} The raw API response data.
-     */
-    static executeRemote(querySet, operationType = "list", args = {}) {
-        return makeApiCall(querySet, operationType, args);
-    }
-}