@statezero/core 0.2.7 → 0.2.8

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

@@ -159,6 +159,13 @@ export class Manager {
      * @returns {QuerySet} A new QuerySet instance with the search applied.
      */
     search(searchQuery: string, searchFields?: string[]): QuerySet<any>;
+    /**
+     * Returns a QuerySet marked as optimistic-only, meaning operations will only
+     * update local state without making backend API calls.
+     *
+     * @returns {QuerySet} A new QuerySet with optimistic-only mode enabled.
+     */
+    get optimistic(): QuerySet<any>;
 }
 export type SerializerOptions = {
     /**

package/dist/flavours/django/manager.js

@@ -202,4 +202,13 @@ export class Manager {
     search(searchQuery, searchFields) {
         return this.newQuerySet().search(searchQuery, searchFields);
     }
+    /**
+     * Returns a QuerySet marked as optimistic-only, meaning operations will only
+     * update local state without making backend API calls.
+     *
+     * @returns {QuerySet} A new QuerySet with optimistic-only mode enabled.
+     */
+    get optimistic() {
+        return this.newQuerySet()._optimistic();
+    }
 }

package/dist/flavours/django/operationFactory.js

@@ -29,6 +29,7 @@ export class OperationFactory {
             instances: [{ ...data, [primaryKeyField]: tempPk }],
             queryset: queryset,
             args: { data },
+            localOnly: queryset._optimisticOnly || false,
         });
     }
     /**
@@ -53,6 +54,7 @@ export class OperationFactory {
             instances: instances,
             queryset: queryset,
             args: { data: dataList },
+            localOnly: queryset._optimisticOnly || false,
         });
     }
     /**
@@ -96,6 +98,7 @@ export class OperationFactory {
             instances: optimisticInstances,
             queryset: queryset,
             args: { filter, data },
+            localOnly: queryset._optimisticOnly || false,
         });
     }
     /**
@@ -117,6 +120,7 @@ export class OperationFactory {
             instances: instances,
             queryset: queryset,
             args: {},
+            localOnly: queryset._optimisticOnly || false,
         });
     }
     /**
@@ -139,6 +143,7 @@ export class OperationFactory {
             instances: instances,
             queryset: queryset,
             args: { data },
+            localOnly: queryset._optimisticOnly || false,
         });
     }
     /**
@@ -156,6 +161,7 @@ export class OperationFactory {
             instances: [instanceData],
             queryset: queryset,
             args: instanceData,
+            localOnly: queryset._optimisticOnly || false,
         });
     }
     /**
@@ -195,6 +201,7 @@ export class OperationFactory {
             instances: [instanceData],
             queryset: queryset,
             args: { lookup, defaults },
+            localOnly: queryset._optimisticOnly || false,
         });
     }
     /**
@@ -235,6 +242,7 @@ export class OperationFactory {
             instances: [instanceData],
             queryset: queryset,
             args: { lookup, defaults },
+            localOnly: queryset._optimisticOnly || false,
         });
     }
 }

package/dist/flavours/django/queryExecutor.js

@@ -123,6 +123,11 @@ export class QueryExecutor {
             ? 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) => {
@@ -223,7 +228,12 @@ export class QueryExecutor {
         };
         const operation = OperationFactory.createUpdateOperation(querySet, apiCallArgs.data, querySet.build().filter);
         const estimatedCount = operation.instances.length;
-        let liveResult = [estimatedCount, { [modelName]: estimatedCount }, []];
+        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 || {};
@@ -258,7 +268,12 @@ export class QueryExecutor {
         const operation = OperationFactory.createDeleteOperation(querySet);
         // live placeholder: assume we delete all existing pks
         const estimatedCount = operation.instances.length;
-        let liveResult = [estimatedCount, { [modelName]: estimatedCount }, []];
+        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;
@@ -298,6 +313,11 @@ export class QueryExecutor {
         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;
@@ -359,6 +379,11 @@ export class QueryExecutor {
             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;
@@ -421,6 +446,11 @@ export class QueryExecutor {
         // 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) => {
@@ -468,7 +498,12 @@ export class QueryExecutor {
         // Use factory to create operation
         const operation = OperationFactory.createDeleteInstanceOperation(querySet, args);
         // 1) placeholder result
-        let liveResult = [1, { [modelName]: 1 }, []];
+        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) => {

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

@@ -40,6 +40,7 @@ export class QuerySet<T> {
     _initialQueryset: string | undefined;
     _serializerOptions: any;
     _materialized: boolean;
+    _optimisticOnly: any;
     __uuid: string;
     __parent: any;
     __reactivityId: any;
@@ -196,6 +197,19 @@ export class QuerySet<T> {
      * @returns {QuerySet} A new QuerySet with the serializer options applied.
      */
     all(serializerOptions?: SerializerOptions): QuerySet<any>;
+    /**
+     * Internal method to create an optimistic-only QuerySet.
+     * @private
+     * @returns {QuerySet} A new QuerySet with optimistic-only mode enabled.
+     */
+    private _optimistic;
+    /**
+     * Returns a QuerySet marked as optimistic-only, meaning operations will only
+     * update local state without making backend API calls.
+     *
+     * @returns {QuerySet} A new QuerySet with optimistic-only mode enabled.
+     */
+    get optimistic(): QuerySet<any>;
     /**
      * Creates a new record in the QuerySet.
      * @param {Object} data - The fields and values for the new record.

package/dist/flavours/django/querySet.js

@@ -36,6 +36,7 @@ export class QuerySet {
         this._initialQueryset = config.initialQueryset;
         this._serializerOptions = config.serializerOptions || {};
         this._materialized = config.materialized || false;
+        this._optimisticOnly = config.optimisticOnly || false;
         this.__uuid = v7();
         this.__parent = parent;
         this.__reactivityId = parent?.__reactivityId;
@@ -56,6 +57,7 @@ export class QuerySet {
             initialQueryset: this._initialQueryset,
             serializerOptions: { ...this._serializerOptions },
             materialized: this._materialized,
+            optimisticOnly: this._optimisticOnly,
         }, this);
     }
     get semanticKey() {
@@ -458,6 +460,27 @@ export class QuerySet {
         }
         return this;
     }
+    /**
+     * Internal method to create an optimistic-only QuerySet.
+     * @private
+     * @returns {QuerySet} A new QuerySet with optimistic-only mode enabled.
+     */
+    _optimistic() {
+        this.ensureNotMaterialized();
+        return new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            optimisticOnly: true,
+        }, this);
+    }
+    /**
+     * Returns a QuerySet marked as optimistic-only, meaning operations will only
+     * update local state without making backend API calls.
+     *
+     * @returns {QuerySet} A new QuerySet with optimistic-only mode enabled.
+     */
+    get optimistic() {
+        return this._optimistic();
+    }
     /**
      * Creates a new record in the QuerySet.
      * @param {Object} data - The fields and values for the new record.
@@ -659,6 +682,7 @@ export class QuerySet {
             aggregations: this._aggregations,
             initialQueryset: this._initialQueryset,
             serializerOptions: this._serializerOptions,
+            optimisticOnly: this._optimisticOnly,
         };
     }
     /**

package/dist/syncEngine/stores/operation.d.ts

@@ -33,6 +33,7 @@ export class Operation {
     args: any;
     timestamp: any;
     doNotPropagate: any;
+    localOnly: any;
     /**
      * Setter for instances
      */

package/dist/syncEngine/stores/operation.js

@@ -60,6 +60,7 @@ export class Operation {
         this.queryset = data.queryset;
         this.args = data.args;
         this.doNotPropagate = data.doNotPropagate || false;
+        this.localOnly = data.localOnly || false;
         let ModelClass = this.queryset.ModelClass;
         let instances = data.instances;
         // guarantee instances is an array

package/package.json

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