@statezero/core 0.2.32 → 0.2.34

package/dist/flavours/django/makeApiCall.js

@@ -146,6 +146,10 @@ export async function makeApiCall(querySet, operationType, args = {}, operationI
             return response.data;
         }
         catch (error) {
+            if (error?.code === "ECONNREFUSED") {
+                const hint = "Connection refused. If you're running tests, start the test server with `python manage.py statezero_testserver`.";
+                throw new Error(`${hint} (${finalUrl})`);
+            }
             if (error.response && error.response.data) {
                 const parsedError = parseStateZeroError(error.response.data);
                 if (Error.captureStackTrace) {

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

@@ -56,6 +56,12 @@ export class Manager {
      * @returns {QuerySet} A new QuerySet instance.
      */
     all(): QuerySet<any>;
+    /**
+     * Returns a QuerySet that executes remotely without updating local stores.
+     *
+     * @returns {QuerySet} A remote-only QuerySet instance.
+     */
+    remote(): QuerySet<any>;
     /**
      * Deletes records in the QuerySet.
      *

package/dist/flavours/django/manager.js

@@ -71,6 +71,14 @@ export class Manager {
     all() {
         return this.newQuerySet();
     }
+    /**
+     * Returns a QuerySet that executes remotely without updating local stores.
+     *
+     * @returns {QuerySet} A remote-only QuerySet instance.
+     */
+    remote() {
+        return this.newQuerySet().remote();
+    }
     /**
      * Deletes records in the QuerySet.
      *

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

@@ -22,6 +22,10 @@ export class Model {
      * @param {any} [data={}] - The data for initialization.
      */
     static instanceCache: Map<any, any>;
+    /**
+     * Remote-only manager that skips local store updates.
+     */
+    static get remote(): any;
     /**
      * Instantiate from pk using queryset scoped singletons
      */

package/dist/flavours/django/model.js

@@ -36,6 +36,12 @@ export class Model {
         this.__version = 0;
         return wrapReactiveModel(this);
     }
+    /**
+     * Remote-only manager that skips local store updates.
+     */
+    static get remote() {
+        return this.objects.remote();
+    }
     touch() {
         this.__version++;
     }

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

@@ -137,4 +137,13 @@ export class QueryExecutor {
      * @returns {Promise<any>} The operation result.
      */
     static execute(querySet: QuerySet, operationType?: string, args?: Object): Promise<any>;
+    /**
+     * 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: QuerySet, operationType?: string, args?: Object): Promise<any>;
 }

package/dist/flavours/django/queryExecutor.js

@@ -539,6 +539,9 @@ export class QueryExecutor {
      * @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":
@@ -573,4 +576,15 @@ export class QueryExecutor {
         }
         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);
+    }
 }

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

@@ -41,6 +41,7 @@ export class QuerySet<T> {
     _serializerOptions: any;
     _materialized: boolean;
     _optimisticOnly: any;
+    _remoteOnly: any;
     __uuid: string;
     __parent: any;
     __reactivityId: any;
@@ -210,6 +211,13 @@ export class QuerySet<T> {
      * @returns {QuerySet} A new QuerySet with optimistic-only mode enabled.
      */
     get optimistic(): QuerySet<any>;
+    /**
+     * Returns a QuerySet marked as remote-only, meaning operations will
+     * hit the backend but skip local store updates and live thenables.
+     *
+     * @returns {QuerySet} A new QuerySet with remote-only mode enabled.
+     */
+    remote(): 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._serializerOptions = config.serializerOptions || {};
         this._materialized = config.materialized || false;
         this._optimisticOnly = config.optimisticOnly || false;
+        this._remoteOnly = config.remoteOnly || false;
         this.__uuid = v7();
         this.__parent = parent;
         this.__reactivityId = parent?.__reactivityId;
@@ -57,6 +58,7 @@ export class QuerySet {
             serializerOptions: { ...this._serializerOptions },
             materialized: this._materialized,
             optimisticOnly: this._optimisticOnly,
+            remoteOnly: this._remoteOnly,
         }, this);
     }
     get semanticKey() {
@@ -480,6 +482,18 @@ export class QuerySet {
     get optimistic() {
         return this._optimistic();
     }
+    /**
+     * Returns a QuerySet marked as remote-only, meaning operations will
+     * hit the backend but skip local store updates and live thenables.
+     *
+     * @returns {QuerySet} A new QuerySet with remote-only mode enabled.
+     */
+    remote() {
+        return new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            remoteOnly: true,
+        }, this);
+    }
     /**
      * Creates a new record in the QuerySet.
      * @param {Object} data - The fields and values for the new record.
@@ -682,6 +696,7 @@ export class QuerySet {
             initialQueryset: this._initialQueryset,
             serializerOptions: this._serializerOptions,
             optimisticOnly: this._optimisticOnly,
+            remoteOnly: this._remoteOnly,
         };
     }
     /**

package/dist/index.d.ts

@@ -38,4 +38,9 @@ import { wrapReactiveModel } from "./reactiveAdaptor.js";
 import { wrapReactiveQuerySet } from "./reactiveAdaptor.js";
 import { serializeActionPayload } from "./flavours/django/serializers.js";
 import { onStateZeroError } from "./errorHandler.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 };
+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

@@ -21,6 +21,7 @@ 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
@@ -42,4 +43,6 @@ initEventHandler, cleanupEventHandler, setAdapters, wrapReactiveModel, wrapReact
 // Action utilities
 serializeActionPayload, 
 // Error handling
-onStateZeroError, };
+onStateZeroError, 
+// Testing helpers
+createTestConfig, setupTestStateZero, createActionMocker, seedRemote, resetRemote, };

package/dist/syncEngine/stores/operationEventHandlers.js

@@ -45,8 +45,10 @@ function routeCreateOperation(operation, applyAction) {
             const currentCount = store.groundTruthPks?.length || 0;
             // At capacity: check if ordering could affect position
             if (currentCount >= limit) {
-                const hasCustomOrdering = store.queryset._orderBy && store.queryset._orderBy.length > 0;
-                if (hasCustomOrdering) {
+                // Check explicit ordering on queryset OR implicit ordering from Django Meta
+                const hasExplicitOrdering = store.queryset._orderBy && store.queryset._orderBy.length > 0;
+                const hasImplicitOrdering = (modelClass.schema?.default_ordering?.length || 0) > 0;
+                if (hasExplicitOrdering || hasImplicitOrdering) {
                     // With ordering, new item could displace existing items - can't know without server
                     operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.MAYBE);
                 }

package/dist/testing.d.ts

@@ -0,0 +1,63 @@
+export function createTestConfig({ apiUrl, backendKey, generatedTypesDir, generatedActionsDir, getAuthHeaders, testAuthUserId, testAuthHeaders, testAuthHeaderName, eventsType, fileRootURL, fileUploadMode, }: {
+    apiUrl: any;
+    backendKey?: string | undefined;
+    generatedTypesDir?: string | undefined;
+    generatedActionsDir: any;
+    getAuthHeaders: any;
+    testAuthUserId: any;
+    testAuthHeaders: any;
+    testAuthHeaderName?: string | undefined;
+    eventsType?: string | undefined;
+    fileRootURL: any;
+    fileUploadMode: any;
+}): {
+    config: {
+        backendConfigs: {
+            [backendKey]: {
+                API_URL: any;
+                GENERATED_TYPES_DIR: string;
+                getAuthHeaders: () => any;
+                events: {
+                    type: string;
+                };
+            };
+        };
+    };
+    testHeaders: {
+        setSeeding(enabled: any): void;
+        setReset(enabled: any): void;
+        setAuthUserId(userId: any): void;
+        withSeeding(fn: any): any;
+        withReset(fn: any): any;
+        withAuthUserId(userId: any, fn: any): any;
+    };
+};
+export function setupTestStateZero({ apiUrl, backendKey, generatedTypesDir, generatedActionsDir, getAuthHeaders, testAuthUserId, testAuthHeaders, testAuthHeaderName, eventsType, fileRootURL, fileUploadMode, getModelClass, adapters, }: {
+    apiUrl: any;
+    backendKey?: string | undefined;
+    generatedTypesDir?: string | undefined;
+    generatedActionsDir: any;
+    getAuthHeaders: any;
+    testAuthUserId: any;
+    testAuthHeaders: any;
+    testAuthHeaderName: any;
+    eventsType?: string | undefined;
+    fileRootURL: any;
+    fileUploadMode: any;
+    getModelClass: any;
+    adapters: any;
+}): {
+    setSeeding(enabled: any): void;
+    setReset(enabled: any): void;
+    setAuthUserId(userId: any): void;
+    withSeeding(fn: any): any;
+    withReset(fn: any): any;
+    withAuthUserId(userId: any, fn: any): any;
+};
+export function createActionMocker(actionRegistry: any): {
+    mock(actionName: any, handler: any, backendKey?: string): void;
+    restore(actionName: any, backendKey?: string): void;
+    restoreAll(): void;
+};
+export function seedRemote(testHeaders: any, seedFn: any): Promise<any>;
+export function resetRemote(testHeaders: any, resetFn: any): Promise<any>;

package/dist/testing.js

@@ -0,0 +1,175 @@
+import { setupStateZero } from "./setup.js";
+function _normalizeHeaders(headers) {
+    return headers && typeof headers === "object" ? { ...headers } : {};
+}
+function _withFlag(state, key, fn) {
+    const previous = state[key];
+    state[key] = true;
+    try {
+        const result = fn();
+        if (result && typeof result.then === "function") {
+            return result.finally(() => {
+                state[key] = previous;
+            });
+        }
+        state[key] = previous;
+        return result;
+    }
+    catch (error) {
+        state[key] = previous;
+        throw error;
+    }
+}
+export function createTestConfig({ apiUrl, backendKey = "default", generatedTypesDir = "./src/models/", generatedActionsDir, getAuthHeaders, testAuthUserId, testAuthHeaders, testAuthHeaderName = "X-TEST-USER-ID", eventsType = "none", fileRootURL, fileUploadMode, }) {
+    const state = {
+        seeding: false,
+        reset: false,
+        authUserId: undefined,
+    };
+    const testHeaders = {
+        setSeeding(enabled) {
+            state.seeding = Boolean(enabled);
+        },
+        setReset(enabled) {
+            state.reset = Boolean(enabled);
+        },
+        setAuthUserId(userId) {
+            state.authUserId = userId;
+        },
+        withSeeding(fn) {
+            return _withFlag(state, "seeding", fn);
+        },
+        withReset(fn) {
+            return _withFlag(state, "reset", fn);
+        },
+        withAuthUserId(userId, fn) {
+            const previous = state.authUserId;
+            state.authUserId = userId;
+            try {
+                const result = fn();
+                if (result && typeof result.then === "function") {
+                    return result.finally(() => {
+                        state.authUserId = previous;
+                    });
+                }
+                state.authUserId = previous;
+                return result;
+            }
+            catch (error) {
+                state.authUserId = previous;
+                throw error;
+            }
+        },
+    };
+    const wrappedGetAuthHeaders = () => {
+        const headers = _normalizeHeaders(getAuthHeaders ? getAuthHeaders() : {});
+        const extraAuthHeaders = typeof testAuthHeaders === "function"
+            ? testAuthHeaders()
+            : testAuthHeaders;
+        if (extraAuthHeaders && typeof extraAuthHeaders === "object") {
+            Object.assign(headers, extraAuthHeaders);
+        }
+        const activeUserId = state.authUserId ?? testAuthUserId;
+        if (activeUserId !== undefined && activeUserId !== null) {
+            headers[testAuthHeaderName] = String(activeUserId);
+        }
+        if (state.seeding) {
+            headers["X-TEST-SEEDING"] = "1";
+        }
+        if (state.reset) {
+            headers["X-TEST-RESET"] = "1";
+        }
+        return headers;
+    };
+    const backendConfig = {
+        API_URL: apiUrl,
+        GENERATED_TYPES_DIR: generatedTypesDir,
+        getAuthHeaders: wrappedGetAuthHeaders,
+        events: { type: eventsType },
+    };
+    if (generatedActionsDir) {
+        backendConfig.GENERATED_ACTIONS_DIR = generatedActionsDir;
+    }
+    if (fileRootURL) {
+        backendConfig.fileRootURL = fileRootURL;
+    }
+    if (fileUploadMode) {
+        backendConfig.fileUploadMode = fileUploadMode;
+    }
+    const config = {
+        backendConfigs: {
+            [backendKey]: backendConfig,
+        },
+    };
+    return { config, testHeaders };
+}
+export function setupTestStateZero({ apiUrl, backendKey = "default", generatedTypesDir = "./src/models/", generatedActionsDir, getAuthHeaders, testAuthUserId, testAuthHeaders, testAuthHeaderName, eventsType = "none", fileRootURL, fileUploadMode, getModelClass, adapters, }) {
+    const { config, testHeaders } = createTestConfig({
+        apiUrl,
+        backendKey,
+        generatedTypesDir,
+        generatedActionsDir,
+        getAuthHeaders,
+        testAuthUserId,
+        testAuthHeaders,
+        testAuthHeaderName,
+        eventsType,
+        fileRootURL,
+        fileUploadMode,
+    });
+    setupStateZero(config, getModelClass, adapters);
+    return testHeaders;
+}
+export function createActionMocker(actionRegistry) {
+    const original = new Map();
+    function resolveRegistry(backendKey) {
+        if (!actionRegistry) {
+            throw new Error("actionRegistry is required");
+        }
+        return actionRegistry[backendKey] || actionRegistry;
+    }
+    return {
+        mock(actionName, handler, backendKey = "default") {
+            const registry = resolveRegistry(backendKey);
+            if (!registry || !registry[actionName]) {
+                throw new Error(`Action '${actionName}' not found in registry`);
+            }
+            const key = `${backendKey}:${actionName}`;
+            if (!original.has(key)) {
+                original.set(key, registry[actionName]);
+            }
+            registry[actionName] = handler;
+        },
+        restore(actionName, backendKey = "default") {
+            const registry = resolveRegistry(backendKey);
+            const key = `${backendKey}:${actionName}`;
+            if (!original.has(key)) {
+                return;
+            }
+            registry[actionName] = original.get(key);
+            original.delete(key);
+        },
+        restoreAll() {
+            for (const [key, fn] of original.entries()) {
+                const [backendKey, actionName] = key.split(":");
+                const registry = resolveRegistry(backendKey);
+                if (registry && actionName in registry) {
+                    registry[actionName] = fn;
+                }
+            }
+            original.clear();
+        },
+    };
+}
+export async function seedRemote(testHeaders, seedFn) {
+    if (!testHeaders || typeof testHeaders.withSeeding !== "function") {
+        throw new Error("seedRemote requires testHeaders from createTestConfig/setupTestStateZero");
+    }
+    return testHeaders.withSeeding(seedFn);
+}
+export async function resetRemote(testHeaders, resetFn) {
+    if (!testHeaders || typeof testHeaders.withReset !== "function") {
+        throw new Error("resetRemote requires testHeaders from createTestConfig/setupTestStateZero");
+    }
+    return testHeaders.withReset(resetFn);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statezero/core",
-  "version": "0.2.32",
+  "version": "0.2.34",
   "type": "module",
   "module": "ESNext",
   "description": "The type-safe frontend client for StateZero - connect directly to your backend models with zero boilerplate",
@@ -26,6 +26,10 @@
       "import": "./dist/vue-entry.js",
       "require": "./dist/vue-entry.js"
     },
+    "./testing": {
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.js"
+    },
     "./dist/*": "./dist/*"
   },
   "scripts": {

package/readme.md

@@ -174,6 +174,101 @@ const workTodos = Todo.objects.filter({
 });
 ```
 
+## Testing (Backend-Mode)
+
+StateZero supports frontend tests that run against a real Django test server (no test-only views).
+You opt-in via a test-only middleware that temporarily relaxes permissions and silences events
+when a request includes special headers.
+
+### Backend Setup (Django Test Settings)
+
+Add the test middleware and enable test mode in your **test settings**:
+
+```python
+# tests/settings.py
+STATEZERO_TEST_MODE = True
+STATEZERO_TEST_SEEDING_SILENT = True  # default behavior, silences events during seeding
+
+MIDDLEWARE = [
+    # ...
+    "statezero.adaptors.django.testing.TestSeedingMiddleware",
+    # ...
+]
+```
+
+Behavior:
+- `X-TEST-SEEDING: 1` → temporarily allows all permissions for the request
+- `X-TEST-RESET: 1` → deletes all registered StateZero models for the request
+
+Auth note:
+- Test mode does **not** bypass authentication. If you use DRF TokenAuth, you must either
+  create a real token for tests, or add a test-only auth class/middleware that accepts
+  a header like `X-TEST-USER-ID` and returns a test user.
+
+Start the test server:
+
+```bash
+python manage.py statezero_testserver --addrport 8000
+```
+
+Optional request hook:
+
+```python
+# tests/settings.py
+STATEZERO_TEST_REQUEST_CONTEXT = "myapp.test_utils.statezero_test_context"
+```
+
+Your factory should accept the request and return a context manager. This allows
+libraries like django-ai-first to wrap each test request (e.g., time control).
+
+### Frontend Setup (Vue / JS)
+
+Use the testing helpers and the `remote` manager to call the backend directly without local updates.
+
+```javascript
+import {
+  setupTestStateZero,
+  seedRemote,
+  resetRemote,
+  createActionMocker,
+} from "@statezero/core/testing";
+import { getModelClass } from "../model-registry";
+import { ACTION_REGISTRY } from "../action-registry";
+import { Todo } from "../models/default/django_app/todo";
+import { vueAdapters } from "./statezero-adapters";
+
+const testHeaders = setupTestStateZero({
+  apiUrl: "http://localhost:8000/statezero",
+  getModelClass,
+  adapters: vueAdapters,
+  // Optional: test-only force-auth header support (backend must opt in)
+  // testAuthUserId: 1,
+  // testAuthHeaderName: "X-TEST-USER-ID",
+});
+
+// Reset: deletes all registered StateZero models on the backend
+await resetRemote(testHeaders, () => Todo.remote.delete());
+
+// Seed: run standard ORM writes with X-TEST-SEEDING enabled
+await seedRemote(testHeaders, () =>
+  Todo.remote.create({ title: "Seeded todo" })
+);
+
+// Optional: temporarily force-auth as a test user for a block
+// await testHeaders.withAuthUserId(1, () =>
+//   Todo.remote.create({ title: "Seeded as user 1" })
+// );
+
+// Action mocking for frontend tests
+const actionMocker = createActionMocker(ACTION_REGISTRY);
+actionMocker.mock("send_notification", async () => ({ ok: true }));
+```
+
+Notes:
+- `Model.remote` (or `Model.objects.remote()`) uses the normal ORM AST/serializers,
+  but **skips local store updates** and **returns raw backend responses**.
+- These helpers are intended for tests that run against a live Django test server.
+
 ## Installation
 
 ### Backend