@statezero/core 0.2.56 → 0.2.59

package/dist/adaptors/vue/components/StateZeroDebugPanel.js

@@ -2,11 +2,11 @@ import { ref as J, computed as I, onMounted as hs, onBeforeUnmount as fs, watch
 import { v7 as B } from "uuid";
 import { isNil as b, isEmpty as Te, trim as dt, isEqual as He } from "lodash-es";
 import Oe from "mitt";
-import Ft from "handlebars";
-import Pt from "superjson";
+import Pt from "handlebars";
+import Ft from "superjson";
 import ps from "p-queue";
 import ms from "axios";
-import { z as $ } from "zod";
+import { z as O } from "zod";
 import ys from "pusher-js";
 import Wt, { createEqualsOperation as ee } from "sift";
 import { DateTime as _e } from "luxon";
@@ -47,9 +47,9 @@ function Je(n) {
   const e = Object.fromEntries(se);
   try {
     if (typeof n == "string")
-      return Ft.compile(n, { noEscape: !0 })(e);
-    const t = Pt.stringify(n), r = Ft.compile(t, { noEscape: !0 })(e);
-    return Pt.parse(r);
+      return Pt.compile(n, { noEscape: !0 })(e);
+    const t = Ft.stringify(n), r = Pt.compile(t, { noEscape: !0 })(e);
+    return Ft.parse(r);
   } catch {
     return n;
   }
@@ -363,7 +363,7 @@ class Ss {
    */
   _loadOperations(e) {
     e.forEach((t) => {
-      const s = Fe.get(t.operationId);
+      const s = Pe.get(t.operationId);
       s ? this.operationsMap.set(s.operationId, s) : this.operationsMap.set(t.operationId, new q(t, !0));
     });
   }
@@ -480,7 +480,7 @@ class Ss {
     if (r.push(...Array.from(s.values())), this.groundTruthArray = r, i.length > 0) {
       const l = /* @__PURE__ */ new Set();
       for (const c of this.operations)
-        if ((c.type === P.UPDATE || c.type === P.UPDATE_INSTANCE) && c.status !== C.CONFIRMED && c.status !== C.REJECTED)
+        if ((c.type === F.UPDATE || c.type === F.UPDATE_INSTANCE) && c.status !== C.CONFIRMED && c.status !== C.REJECTED)
           for (const h of c.instances)
             h && h[t] != null && l.add(h[t]);
       const a = i.filter(
@@ -489,7 +489,7 @@ class Ss {
       if (a.length > 0) {
         const c = new q({
           operationId: `checkpoint_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
-          type: P.CHECKPOINT,
+          type: F.CHECKPOINT,
           instances: a,
           status: C.CONFIRMED,
           timestamp: Date.now(),
@@ -553,21 +553,21 @@ class Ss {
       }
       let o = r[s];
       switch (e.type) {
-        case P.CREATE:
-        case P.BULK_CREATE:
+        case F.CREATE:
+        case F.BULK_CREATE:
           t.has(o) || t.set(o, r);
           break;
-        case P.CHECKPOINT:
-        case P.UPDATE_INSTANCE:
-        case P.UPDATE: {
+        case F.CHECKPOINT:
+        case F.UPDATE_INSTANCE:
+        case F.UPDATE: {
           const i = t.get(o);
           i ? t.set(o, { ...i, ...r }) : this.operations.some(
-            (a) => a.type === P.DELETE && a.status !== C.REJECTED && a.instances.some((c) => c && c[s] === o)
+            (a) => a.type === F.DELETE && a.status !== C.REJECTED && a.instances.some((c) => c && c[s] === o)
           ) || t.set(o, r);
           break;
         }
-        case P.DELETE_INSTANCE:
-        case P.DELETE:
+        case F.DELETE_INSTANCE:
+        case F.DELETE:
           t.delete(o);
           break;
         default:
@@ -726,7 +726,7 @@ const j = new Ve(), ie = Oe(), C = {
   REJECTED: "operation:rejected",
   CLEAR: "clear:all",
   MUTATED: "operation:mutated"
-}, P = {
+}, F = {
   CREATE: "create",
   BULK_CREATE: "bulk_create",
   UPDATE: "update",
@@ -763,7 +763,7 @@ class q {
       throw new Error(`All operation instances must be objects with the '${o}' field`);
     this.#e = r;
     const i = r.map((a) => a[o]);
-    j.getStore(s).render(i, !0, !1), this.#t = r.map((a) => s.fromPk(a[o]).serialize()), this.timestamp = e.timestamp || Date.now(), !t && (Fe.register(this), ie.emit(C.CREATED, this));
+    j.getStore(s).render(i, !0, !1), this.#t = r.map((a) => s.fromPk(a[o]).serialize()), this.timestamp = e.timestamp || Date.now(), !t && (Pe.register(this), ie.emit(C.CREATED, this));
   }
   /**
    * Getter for instances that replaces any temporary PKs with real PKs
@@ -915,7 +915,7 @@ class Ts {
     return t.length > 0 ? t[t.length - 1] : void 0;
   }
 }
-const Fe = new Ts(), Ms = Oe();
+const Pe = new Ts(), Ms = Oe();
 function As(n) {
   Ms.emit("error", n);
 }
@@ -927,9 +927,10 @@ class fe extends Error {
    * @param {string} code - The error code.
    * @param {IErrorDetail|Object|string} detail - The error details.
    * @param {number} status - The HTTP status code.
+   * @param {Object} [data={}] - Additional structured data from the server.
    */
-  constructor(e, t, s, r) {
-    super(e), this.name = "StateZeroError", this.code = t, this.detail = s, this.status = r, Object.setPrototypeOf(this, new.target.prototype), As(this);
+  constructor(e, t, s, r, o = {}) {
+    super(e), this.name = "StateZeroError", this.code = t, this.detail = s, this.status = r, this.data = o, Object.setPrototypeOf(this, new.target.prototype), As(this);
   }
   /**
    * Returns a full error message including the detail.
@@ -1028,8 +1029,8 @@ class U extends fe {
     super("Configuration error", "config_error", e, t), this.name = "ConfigError";
   }
 }
-function Fs(n) {
-  const { status: e, type: t, detail: s } = n;
+function Ps(n) {
+  const { status: e, type: t, detail: s, data: r } = n;
   if (t === void 0 && s === "Invalid token.")
     return new lt(s, 403);
   switch (t) {
@@ -1054,7 +1055,13 @@ function Fs(n) {
     case "ValueError":
       return new $e(s, e);
     default:
-      return e === 400 ? new $e(s, e) : e === 403 ? new lt(s, e) : e === 404 ? new It(s, e) : e === 409 ? new Nt(s, e) : new fe("Unknown error", "unknown", s, e);
+      return e === 400 ? new $e(s, e) : e === 403 ? new lt(s, e) : e === 404 ? new It(s, e) : e === 409 ? new Nt(s, e) : new fe(
+        s || "Unknown error",
+        t || "unknown",
+        s,
+        e,
+        r || {}
+      );
   }
 }
 const xt = {
@@ -1065,7 +1072,7 @@ const xt = {
   BULK_UPDATE: "bulk_update",
   BULK_DELETE: "bulk_delete"
 };
-class Ps {
+class Fs {
   /**
   * @param {PusherReceiverOptions} options
   * @param {string} configKey - The backend configuration key
@@ -1075,12 +1082,13 @@ class Ps {
     this.configKey = t, this.connectionTimeoutId = null, s.appKey && /^\d+$/.test(s.appKey) && s.appKey.length < 15 && console.warn(
       `%c[Pusher Warning] The provided appKey ("${s.appKey}") looks like a numeric app_id. Pusher requires the alphanumeric key, not the ID. Please verify your configuration for backend: "${this.configKey}".`,
       "color: orange; font-weight: bold; font-size: 14px;"
-    ), this.pusherClient = new ys(s.appKey, {
-      cluster: s.cluster,
+    );
+    const l = {
       forceTLS: s.forceTLS ?? !0,
       authEndpoint: s.authEndpoint,
       auth: { headers: s.getAuthHeaders?.() || {} }
-    }), this.pusherClient.connection.bind("connected", () => {
+    };
+    s.wsHost ? (l.wsHost = s.wsHost, l.wsPort = s.wsPort ?? 443, l.wssPort = s.wssPort ?? 443, l.enabledTransports = s.enabledTransports ?? ["ws", "wss"]) : l.cluster = s.cluster, this.pusherClient = new ys(s.appKey, l), this.pusherClient.connection.bind("connected", () => {
       console.log(
         `Pusher client connected successfully for backend: ${this.configKey}.`
       ), this.connectionTimeoutId && (clearTimeout(this.connectionTimeoutId), this.connectionTimeoutId = null);
@@ -1090,7 +1098,7 @@ class Ps {
       this.pusherClient.connection.state !== "connected" && this._logConnectionError(
         `Pusher connection timed out after ${i / 1e3} seconds.`
       );
-    }, i), this.formatChannelName = r ?? ((l) => `private-${l}`), this.namespaceResolver = o ?? ((l) => l), this.channels = /* @__PURE__ */ new Map(), this.eventHandlers = /* @__PURE__ */ new Set();
+    }, i), this.formatChannelName = r ?? ((a) => `private-${a}`), this.namespaceResolver = o ?? ((a) => a), this.channels = /* @__PURE__ */ new Map(), this.eventHandlers = /* @__PURE__ */ new Set();
   }
   /**
    * @private
@@ -1226,53 +1234,60 @@ function zs() {
 let Ut = {
   backendConfigs: {}
 };
-const Rs = $.object({
-  clientOptions: $.object({
-    appKey: $.string({ required_error: "Pusher appKey is required" }),
-    cluster: $.string({ required_error: "Pusher cluster is required" }),
-    forceTLS: $.boolean().optional(),
-    authEndpoint: $.string().url("Pusher authentication endpoint URL is required"),
-    getAuthHeaders: $.function().optional().refine(
+const Rs = O.object({
+  clientOptions: O.object({
+    appKey: O.string({ required_error: "Pusher appKey is required" }),
+    cluster: O.string().optional(),
+    wsHost: O.string().optional(),
+    wsPort: O.number().optional(),
+    wssPort: O.number().optional(),
+    enabledTransports: O.array(O.string()).optional(),
+    forceTLS: O.boolean().optional(),
+    authEndpoint: O.string().url("Pusher authentication endpoint URL is required"),
+    getAuthHeaders: O.function().optional().refine(
       (n) => n === void 0 || typeof n == "function",
       "getAuthHeaders must be a function if provided"
     )
-  })
-}), Ks = $.object({
-  type: $.enum(["websocket", "pusher", "none"]),
-  websocketUrl: $.string().url().optional(),
+  }).refine(
+    (n) => n.cluster || n.wsHost,
+    "Either cluster or wsHost must be provided"
+  )
+}), Ks = O.object({
+  type: O.enum(["websocket", "pusher", "none"]),
+  websocketUrl: O.string().url().optional(),
   pusher: Rs.optional(),
-  hotpaths: $.array($.string()).default(["default"])
+  hotpaths: O.array(O.string()).default(["default"])
 }).superRefine((n, e) => {
   n.type === "websocket" && (n.websocketUrl || e.addIssue({
-    code: $.ZodIssueCode.custom,
+    code: O.ZodIssueCode.custom,
     path: ["websocketUrl"],
     message: "WebSocket URL is required for WebSocket event receiver"
   })), n.type === "pusher" && (n.pusher || e.addIssue({
-    code: $.ZodIssueCode.custom,
+    code: O.ZodIssueCode.custom,
     path: ["pusher"],
     message: "Pusher configuration is required for Pusher event receiver"
   }));
-}), Be = $.object({
-  API_URL: $.string().url("API_URL must be a valid URL"),
-  GENERATED_TYPES_DIR: $.string({
+}), Be = O.object({
+  API_URL: O.string().url("API_URL must be a valid URL"),
+  GENERATED_TYPES_DIR: O.string({
     required_error: "GENERATED_TYPES_DIR is required"
   }),
-  GENERATED_ACTIONS_DIR: $.string().optional(),
-  BACKEND_TZ: $.string().optional(),
-  SYNC_TOKEN: $.string().optional(),
-  fileRootURL: $.string().url("fileRootURL must be a valid URL").optional(),
-  fileUploadMode: $.enum(["server", "s3"]).default("server"),
-  getAuthHeaders: $.function().optional().refine(
+  GENERATED_ACTIONS_DIR: O.string().optional(),
+  BACKEND_TZ: O.string().optional(),
+  SYNC_TOKEN: O.string().optional(),
+  fileRootURL: O.string().url("fileRootURL must be a valid URL").optional(),
+  fileUploadMode: O.enum(["server", "s3"]).default("server"),
+  getAuthHeaders: O.function().optional().refine(
     (n) => n === void 0 || typeof n == "function",
     "getAuthHeaders must be a function if provided"
   ),
-  eventInterceptor: $.function().optional().refine(
+  eventInterceptor: O.function().optional().refine(
     (n) => n === void 0 || typeof n == "function",
     "eventInterceptor must be a function if provided"
   ),
-  events: $.lazy(() => Ks.optional())
-}), Is = $.object({
-  backendConfigs: $.record($.string(), Be).refine(
+  events: O.lazy(() => Ks.optional())
+}), Is = O.object({
+  backendConfigs: O.record(O.string(), Be).refine(
     (n) => {
       for (const [e, t] of Object.entries(n))
         if (!Be.safeParse(t).success)
@@ -1291,7 +1306,7 @@ const Rs = $.object({
       return { message: e.join("; ") };
     }
   ),
-  periodicSyncIntervalSeconds: $.number().min(5).nullable().optional().default(null)
+  periodicSyncIntervalSeconds: O.number().min(5).nullable().optional().default(null)
 });
 let ht = null;
 function Ns(n) {
@@ -1345,7 +1360,7 @@ function Yt(n = "default") {
           ...t.events.pusher.clientOptions,
           getAuthHeaders: i
         };
-        s = new Ps({ clientOptions: l }, n);
+        s = new Fs({ clientOptions: l }, n);
         break;
       case "none":
         return null;
@@ -1549,8 +1564,8 @@ async function V(n, e, t = {}, s, r = null, o = null, i = {}) {
       query: _,
       serializerOptions: y
     }
-  }, v = w?.ast?.serializerOptions?.limit, O = w?.ast?.serializerOptions?.overfetch || 10;
-  v && O && (w.ast.serializerOptions.limit = v + O);
+  }, v = w?.ast?.serializerOptions?.limit, $ = w?.ast?.serializerOptions?.overfetch || 10;
+  v && $ && (w.ast.serializerOptions.limit = v + $);
   const k = [
     "create",
     "bulk_create",
@@ -1560,7 +1575,7 @@ async function V(n, e, t = {}, s, r = null, o = null, i = {}) {
     "delete_instance",
     "get_or_create",
     "update_or_create"
-  ].includes(e), Q = `${p.API_URL.replace(/\/+$/, "")}/${c.modelName}/`, N = p.getAuthHeaders ? p.getAuthHeaders() : {}, F = n.semanticKey;
+  ].includes(e), Q = `${p.API_URL.replace(/\/+$/, "")}/${c.modelName}/`, N = p.getAuthHeaders ? p.getAuthHeaders() : {}, P = n.semanticKey;
   s && (N["X-Operation-ID"] = s), o && (N["X-Canonical-ID"] = o);
   const re = async () => {
     try {
@@ -1568,7 +1583,7 @@ async function V(n, e, t = {}, s, r = null, o = null, i = {}) {
         type: "request",
         modelName: c.modelName,
         configKey: c.configKey,
-        semanticKey: F,
+        semanticKey: P,
         operationType: e,
         operationId: s,
         canonicalId: o,
@@ -1594,7 +1609,7 @@ async function V(n, e, t = {}, s, r = null, o = null, i = {}) {
         type: "response",
         modelName: c.modelName,
         configKey: c.configKey,
-        semanticKey: F,
+        semanticKey: P,
         operationType: e,
         operationId: s,
         canonicalId: o,
@@ -1612,7 +1627,7 @@ async function V(n, e, t = {}, s, r = null, o = null, i = {}) {
         type: "error",
         modelName: c.modelName,
         configKey: c.configKey,
-        semanticKey: F,
+        semanticKey: P,
         operationType: e,
         operationId: s,
         canonicalId: o,
@@ -1624,7 +1639,7 @@ async function V(n, e, t = {}, s, r = null, o = null, i = {}) {
         throw new Error(`${D} (${Q})`);
       }
       if (z.response && z.response.data) {
-        const D = Fs(z.response.data);
+        const D = Ps(z.response.data);
         throw Error.captureStackTrace && Error.captureStackTrace(D, V), D;
       }
       throw new Error(`API call failed: ${z.message}`);
@@ -1959,11 +1974,11 @@ function ze(n, e, t, s = {}) {
     E === "pk" && p && (E = p.primaryKeyField);
     const Q = k === c.length - 1;
     if (p && p.relationshipFields && p.relationshipFields instanceof Map && p.relationshipFields.has(E)) {
-      const N = p.relationshipFields.get(E), F = N.ModelClass(), re = N.relationshipType;
+      const N = p.relationshipFields.get(E), P = N.ModelClass(), re = N.relationshipType;
       if (!Q && re === "many-to-many") {
         let ae = c.slice(k + 1).join("__");
         a.length > 0 ? ae += "__" + a.join("__") : h && (ae += "__" + h);
-        const z = ze(ae, e, F, s), D = m.length > 0 ? m.join(".") + "." + E : E, K = z.requiredPath || z.field, me = `${D}.${K}`;
+        const z = ze(ae, e, P, s), D = m.length > 0 ? m.join(".") + "." + E : E, K = z.requiredPath || z.field, me = `${D}.${K}`;
         return {
           field: D,
           operator: { $elemMatch: { [z.field]: z.operator } },
@@ -1973,23 +1988,23 @@ function ze(n, e, t, s = {}) {
         };
       }
       if (m.push(E), !Q)
-        p = F;
+        p = P;
       else {
         if (y = !0, re === "many-to-many")
           _ = !0, w = E;
         else {
-          const pe = F.primaryKeyField || "id";
+          const pe = P.primaryKeyField || "id";
           m.push(pe), w = pe;
         }
-        p = F;
+        p = P;
       }
     } else if (p && p.fields && p.fields.includes(E)) {
       if (m.push(E), w = E, Q)
         break;
       const N = p.schema?.properties?.[E];
       if (N && N.format === "json") {
-        const F = c.slice(k + 1);
-        m.push(...F);
+        const P = c.slice(k + 1);
+        m.push(...P);
         break;
       }
       throw new Error(`Field '${E}' in '${n}' is not a relationship field and cannot be traversed.`);
@@ -2186,17 +2201,17 @@ function tr(n = "UTC", e = null) {
           if (!y || !(y instanceof Date) || isNaN(y.getTime()))
             return !1;
           const _ = _e.fromJSDate(y).setZone(n);
-          let w, v, O;
+          let w, v, $;
           if (typeof a == "string") {
             const T = a.split(":");
-            w = parseInt(T[0], 10), v = parseInt(T[1], 10), O = parseInt(T[2], 10);
+            w = parseInt(T[0], 10), v = parseInt(T[1], 10), $ = parseInt(T[2], 10);
           } else {
             const T = s(a, m);
             if (!T) return !1;
             const k = _e.fromJSDate(T).setZone(n);
-            w = k.hour, v = k.minute, O = k.second;
+            w = k.hour, v = k.minute, $ = k.second;
           }
-          return _.hour === w && _.minute === v && _.second === O;
+          return _.hour === w && _.minute === v && _.second === $;
         },
         c,
         h
@@ -2223,7 +2238,7 @@ function tr(n = "UTC", e = null) {
           const v = s(_, w);
           if (!v || !(v instanceof Date) || isNaN(v.getTime()))
             return !1;
-          const O = _e.fromJSDate(v).setZone(n), T = c(O), k = a === "date" ? p : typeof p == "string" ? Number(p) : p;
+          const $ = _e.fromJSDate(v).setZone(n), T = c($), k = a === "date" ? p : typeof p == "string" ? Number(p) : p;
           switch (h) {
             case "gt":
               return T > k;
@@ -2466,7 +2481,7 @@ class ar {
   constructor(e, t, s, r = null, o = null, i = {}) {
     if (this.modelClass = e, this.fetchFn = t, this.queryset = s, this.isSyncing = !1, this.lastSync = null, this.lastHydrated = null, this._createdAt = Date.now(), this.isTemp = i.isTemp || !1, this.pruneThreshold = i.pruneThreshold || 10, this.groundTruthPks = r || [], this.operationsMap = /* @__PURE__ */ new Map(), this.includedPks = /* @__PURE__ */ new Map(), Array.isArray(o))
       for (const l of o) {
-        const c = Fe.get(l.operationId) || new q(l, !0);
+        const c = Pe.get(l.operationId) || new q(l, !0);
         this.operationsMap.set(c.operationId, c);
       }
     if (this.qsCache = new Ct("queryset-cache", {}, this.onHydrated.bind(this)), this._lastRenderedPks = null, this.renderCallbacks = /* @__PURE__ */ new Set(), !this.isTemp) {
@@ -2599,7 +2614,7 @@ class ar {
     if (a == null) return null;
     const c = this.pkField, h = new Set(e), p = new Set(e);
     for (const m of s.operations)
-      if (m.status !== C.REJECTED && !(!t && m.status !== C.CONFIRMED) && !(m.type !== P.CREATE && m.type !== P.BULK_CREATE && m.type !== P.GET_OR_CREATE && m.type !== P.UPDATE_OR_CREATE))
+      if (m.status !== C.REJECTED && !(!t && m.status !== C.CONFIRMED) && !(m.type !== F.CREATE && m.type !== F.BULK_CREATE && m.type !== F.GET_OR_CREATE && m.type !== F.UPDATE_OR_CREATE))
         for (const y of m.instances) {
           if (!y || y[c] == null || h.has(y[c])) continue;
           const _ = y[o];
@@ -3060,7 +3075,7 @@ class Ce {
         });
         return;
       }
-      const v = p.pks.map((k) => i.fromPk(k, e)), O = e.build(), T = ss(v, O, i, !1);
+      const v = p.pks.map((k) => i.fromPk(k, e)), $ = e.build(), T = ss(v, $, i, !1);
       m.setGroundTruth(T), m.setOperations(m.getInflightOperations()), m.lastSync = Date.now(), G({
         type: "groupSync",
         phase: "filteredFromRoot",
@@ -3229,7 +3244,7 @@ class de {
     const o = e.ModelClass.primaryKeyField, i = s || `${B()}`, l = zt(i);
     return new q({
       operationId: i,
-      type: P.CREATE,
+      type: F.CREATE,
       instances: [{ ...t, [o]: l }],
       queryset: e,
       args: { data: t },
@@ -3250,7 +3265,7 @@ class de {
     });
     return new q({
       operationId: i,
-      type: P.BULK_CREATE,
+      type: F.BULK_CREATE,
       instances: l,
       queryset: e,
       args: { data: t },
@@ -3279,7 +3294,7 @@ class de {
     });
     return new q({
       operationId: c,
-      type: P.UPDATE,
+      type: F.UPDATE,
       instances: h,
       queryset: e,
       args: { filter: s, data: t },
@@ -3296,7 +3311,7 @@ class de {
     const r = e.ModelClass.primaryKeyField, i = x.getStore(e).render(), l = t || `${B()}`, a = i.map((c) => ({ [r]: c }));
     return new q({
       operationId: l,
-      type: P.DELETE,
+      type: F.DELETE,
       instances: a,
       queryset: e,
       args: {},
@@ -3314,7 +3329,7 @@ class de {
     const o = e.ModelClass.primaryKeyField, l = x.getStore(e).render(), a = s || `${B()}`, c = l.map((h) => ({ ...t, [o]: h }));
     return new q({
       operationId: a,
-      type: P.UPDATE_INSTANCE,
+      type: F.UPDATE_INSTANCE,
       instances: c,
       queryset: e,
       args: { data: t },
@@ -3332,7 +3347,7 @@ class de {
     const r = s || `${B()}`;
     return new q({
       operationId: r,
-      type: P.DELETE_INSTANCE,
+      type: F.DELETE_INSTANCE,
       instances: [t],
       queryset: e,
       args: t,
@@ -3352,7 +3367,7 @@ class de {
       (E) => _t(y, o.fromPk(E[i], e))
     ), w = mt(_, m, o), v = c.filter(
       (E) => w.includes(E[i])
-    ), O = v.length === 0, T = O ? P.CREATE : P.UPDATE, k = O ? { ...t, ...s, [i]: l } : v[0];
+    ), $ = v.length === 0, T = $ ? F.CREATE : F.UPDATE, k = $ ? { ...t, ...s, [i]: l } : v[0];
     return new q({
       operationId: l,
       type: T,
@@ -3375,7 +3390,7 @@ class de {
       (E) => _t(y, o.fromPk(E[i], e))
     ), w = mt(_, m, o), v = c.filter(
       (E) => w.includes(E[i])
-    ), O = v.length === 0, T = O ? P.CREATE : P.UPDATE, k = O ? { ...t, ...s, [i]: l } : { ...v[0], ...s };
+    ), $ = v.length === 0, T = $ ? F.CREATE : F.UPDATE, k = $ ? { ...t, ...s, [i]: l } : { ...v[0], ...s };
     return new q({
       operationId: l,
       type: T,
@@ -3467,9 +3482,9 @@ class hr {
     ).then((m) => {
       const { data: y, included: _, model_name: w } = m.data, v = m.metadata.created;
       we(j, _, r, e);
-      const O = Array.isArray(y) ? y[0] : y;
-      a && (c.pk = O);
-      const k = (_[w] || {})[O];
+      const $ = Array.isArray(y) ? y[0] : y;
+      a && (c.pk = $);
+      const k = (_[w] || {})[$];
       return k && l.mutate({
         instances: [k],
         status: C.CONFIRMED
@@ -3493,7 +3508,7 @@ class hr {
       throw new Error(
         `Field parameter is required for ${t} operation`
       );
-    const i = Pe.getEntity(t, e, o), l = {};
+    const i = Fe.getEntity(t, e, o), l = {};
     t !== "exists" && (l.field = o);
     const a = V(
       e,
@@ -3501,7 +3516,7 @@ class hr {
       l
     ).then((c) => {
       const h = c.data, p = x.getEntity(e);
-      return Pe.setEntity(t, e, o, h, p), Z(i), h;
+      return Fe.setEntity(t, e, o, h, p), Z(i), h;
     });
     return te(i, a);
   }
@@ -3545,7 +3560,7 @@ class hr {
       i,
       l.operationId
     ).then((p) => {
-      const { data: m, included: y } = p.data || {}, _ = y[o] || {}, w = Array.isArray(m) ? m.map((O) => _[`${O}`]) : [];
+      const { data: m, included: y } = p.data || {}, _ = y[o] || {}, w = Array.isArray(m) ? m.map(($) => _[`${$}`]) : [];
       l.updateStatus(C.CONFIRMED, w);
       const v = p.metadata?.updated_count ?? 0;
       return c = [v, { [o]: v }, w], Z(c), c;
@@ -3610,13 +3625,13 @@ class hr {
       we(j, y, r, e);
       const w = Array.isArray(m) ? m[0] : m;
       c.pk = w;
-      const O = (y[_] || {})[w];
-      if (!O)
+      const $ = (y[_] || {})[w];
+      if (!$)
         throw new Error(
           `Entity data not found for ${_} with pk ${w}`
         );
       return l.mutate({
-        instances: [O],
+        instances: [$],
         status: C.CONFIRMED
       }), Z(c), c;
     }).catch((p) => {
@@ -3663,9 +3678,9 @@ class hr {
       w.forEach((T, k) => {
         c[k] && (c[k].pk = T);
       });
-      const v = y[_] || {}, O = w.map((T) => v[T]).filter(Boolean);
+      const v = y[_] || {}, $ = w.map((T) => v[T]).filter(Boolean);
       return a.mutate({
-        instances: O,
+        instances: $,
         status: C.CONFIRMED
       }), c.forEach((T) => Z(T)), Z(c), c;
     }).catch((p) => {
@@ -3807,7 +3822,7 @@ class fr {
    * Delegates to the underlying store's sync method
    */
   refreshFromDb() {
-    return Pe.getStore(
+    return Fe.getStore(
       this.metricType,
       this.queryset,
       this.field
@@ -3818,7 +3833,7 @@ class fr {
    * Called implicitly by JS when coercing to a primitive (arithmetic, template literals, etc.)
    */
   valueOf() {
-    const e = Pe.getStore(
+    const e = Fe.getStore(
       this.metricType,
       this.queryset,
       this.field
@@ -3934,7 +3949,7 @@ class wt {
     return this._stores.has(e) ? this._stores.get(e).queryset : null;
   }
 }
-const Pe = new wt();
+const Fe = new wt();
 class pr {
   constructor(e) {
     this.event = e.event, this.model = e.model, this.operation_id = e.operation_id, this.pk_field_name = e.pk_field_name, this.configKey = e.configKey, this.canonical_id = e.canonical_id || null, this.server_ts_ms = e.server_ts_ms || null, this.instances = e.instances?.map((t) => t && this.pk_field_name && t[this.pk_field_name] != null ? {
@@ -4059,7 +4074,7 @@ class mr {
    * Checks the `verify` flag on membership state to determine which querysets need syncing.
    */
   syncQuerysetsNeedingVerification(e) {
-    const t = Fe.getQuerysetStates(e);
+    const t = Pe.getQuerysetStates(e);
     if (!t) return;
     const s = this.registries.get(Ce);
     if (!s) return;
@@ -4090,7 +4105,7 @@ class mr {
       operationId: e.operation_id,
       socketId: e.socket_id
     });
-    let t = new pr(e), s = Fe.has(t.operation_id);
+    let t = new pr(e), s = Pe.has(t.operation_id);
     if (this.registries.has(wt) && this.processMetrics(t), s) {
       this.syncQuerysetsNeedingVerification(t.operation_id);
       return;
@@ -4190,7 +4205,7 @@ class mr {
 const Ae = new mr();
 Ae.manageRegistry(x);
 Ae.manageRegistry(j);
-Ae.manageRegistry(Pe);
+Ae.manageRegistry(Fe);
 const yr = /* @__PURE__ */ new Set();
 function gr(n) {
   typeof n == "function" && yr.add(n);
@@ -4217,7 +4232,7 @@ const _r = (n, e) => {
 }, Mr = {
   key: 1,
   class: "szd-header__badge"
-}, Ar = { class: "szd-header__badge" }, Or = { class: "szd-tabs" }, $r = ["onClick"], Fr = { class: "szd-content" }, Pr = {
+}, Ar = { class: "szd-header__badge" }, Or = { class: "szd-tabs" }, $r = ["onClick"], Pr = { class: "szd-content" }, Fr = {
   key: 0,
   class: "szd-panel"
 }, Dr = { class: "szd-panel__section" }, zr = { class: "szd-kv" }, Rr = { class: "szd-kv__row" }, Kr = { class: "szd-kv__value" }, Ir = { class: "szd-kv__row" }, Nr = { class: "szd-kv__value" }, xr = { class: "szd-kv__row" }, jr = { class: "szd-kv__value" }, Ur = { class: "szd-kv__row" }, Qr = { class: "szd-kv__value" }, Lr = { class: "szd-panel__section" }, Vr = { class: "szd-stats" }, Br = { class: "szd-stat" }, Gr = { class: "szd-stat__value" }, Hr = { class: "szd-stat" }, qr = { class: "szd-stat__value" }, Jr = { class: "szd-stat" }, Wr = { class: "szd-stat__value" }, Zr = { class: "szd-stat" }, Yr = { class: "szd-stat__value" }, Xr = {
@@ -4259,7 +4274,7 @@ const _r = (n, e) => {
 }, $n = {
   class: "szd-kv",
   style: { "margin-bottom": "16px" }
-}, Fn = { class: "szd-kv__row" }, Pn = { class: "szd-kv__value szd-kv__value--mono" }, Dn = { class: "szd-ast" }, zn = {
+}, Pn = { class: "szd-kv__row" }, Fn = { class: "szd-kv__value szd-kv__value--mono" }, Dn = { class: "szd-ast" }, zn = {
   key: 0,
   class: "szd-detail"
 }, Rn = { class: "szd-detail__panel szd-detail__panel--sm" }, Kn = { class: "szd-detail__header" }, In = { class: "szd-detail__body" }, Nn = { class: "szd-settings-section" }, xn = ["value"], jn = {
@@ -4320,7 +4335,7 @@ const _r = (n, e) => {
           queryset: d
         });
       }), u;
-    }), O = I(() => (a.value, Array.from(x._stores.entries()).map(
+    }), $ = I(() => (a.value, Array.from(x._stores.entries()).map(
       ([u, d]) => ({
         semanticKey: u,
         modelName: d?.modelClass?.modelName,
@@ -4336,7 +4351,7 @@ const _r = (n, e) => {
       const u = /* @__PURE__ */ new Map();
       return v.value.forEach((d) => {
         u.set(d.semanticKey, d);
-      }), O.value.forEach((d) => {
+      }), $.value.forEach((d) => {
         u.has(d.semanticKey) || u.set(d.semanticKey, d);
       }), Array.from(u.values());
     }), E = I(() => w.value?.semanticKey ? w.value.semanticKey : r.value ? r.value : ""), Q = I(() => w.value ? w.value : r.value && T.value.get(r.value) || null), N = I(() => {
@@ -4347,7 +4362,7 @@ const _r = (n, e) => {
           return null;
         }
       return E.value && x._stores.get(E.value) || null;
-    }), F = I(() => {
+    }), P = I(() => {
       a.value;
       const u = N.value, d = Q.value, g = u?.modelClass?.modelName || d?.ModelClass?.modelName, R = u?.modelClass?.configKey || d?.ModelClass?.configKey, H = u?.groundTruthPks?.length ?? 0, oe = u?.operationsMap?.size ?? 0, le = u?.getInflightOperations?.() || [], ke = u?.isSyncing ?? !1, je = u?.lastSync ? new Date(u.lastSync).toLocaleString() : "—", nt = u && Array.isArray(u._lastRenderedPks) ? u._lastRenderedPks.length : null, cs = u?.groundTruthPks?.length ?? 0, ds = u ? u.lastSync === null ? "model store" : "ground truth" : "—", us = ke ? "Sync in progress — results may change." : oe > 0 ? "Optimistic operations are applied to results." : u?.lastSync === null ? "No ground truth yet — rendering from model store." : "Using ground truth + local filters.";
       return {
@@ -4622,11 +4637,11 @@ const _r = (n, e) => {
         f("div", vr, [
           f("div", kr, [
             d[9] || (d[9] = f("div", { class: "szd-header__title" }, "StateZero", -1)),
-            E.value ? (A(), M("span", br, S(F.value.modelName || "?"), 1)) : (A(), M("span", Er, "No queryset"))
+            E.value ? (A(), M("span", br, S(P.value.modelName || "?"), 1)) : (A(), M("span", Er, "No queryset"))
           ]),
           f("div", Sr, [
-            F.value.isSyncing ? (A(), M("span", Tr, "Syncing")) : L("", !0),
-            F.value.opsCount > 0 ? (A(), M("span", Mr, S(F.value.opsCount) + " ops", 1)) : L("", !0),
+            P.value.isSyncing ? (A(), M("span", Tr, "Syncing")) : L("", !0),
+            P.value.opsCount > 0 ? (A(), M("span", Mr, S(P.value.opsCount) + " ops", 1)) : L("", !0),
             f("span", Ar, S(Ie.value) + " events", 1),
             f("button", {
               class: "szd-btn szd-btn--icon",
@@ -4659,8 +4674,8 @@ const _r = (n, e) => {
           }, S(g.label), 11, $r)), 64))
         ])
       ]),
-      f("main", Fr, [
-        t.value === "overview" ? (A(), M("div", Pr, [
+      f("main", Pr, [
+        t.value === "overview" ? (A(), M("div", Fr, [
           f("div", Dr, [
             d[15] || (d[15] = f("h3", { class: "szd-panel__heading" }, "Why This View?", -1)),
             f("div", zr, [
@@ -4678,7 +4693,7 @@ const _r = (n, e) => {
               ]),
               f("div", Ur, [
                 d[14] || (d[14] = f("span", { class: "szd-kv__key" }, "Reason:", -1)),
-                f("span", Qr, S(F.value.reason), 1)
+                f("span", Qr, S(P.value.reason), 1)
               ])
             ])
           ]),
@@ -4686,26 +4701,26 @@ const _r = (n, e) => {
             d[21] || (d[21] = f("h3", { class: "szd-panel__heading" }, "Current State", -1)),
             f("div", Vr, [
               f("div", Br, [
-                f("div", Gr, S(F.value.optimisticCount ?? "—"), 1),
+                f("div", Gr, S(P.value.optimisticCount ?? "—"), 1),
                 d[16] || (d[16] = f("div", { class: "szd-stat__label" }, "Optimistic", -1))
               ]),
               f("div", Hr, [
-                f("div", qr, S(F.value.confirmedCount), 1),
+                f("div", qr, S(P.value.confirmedCount), 1),
                 d[17] || (d[17] = f("div", { class: "szd-stat__label" }, "Confirmed", -1))
               ]),
               f("div", Jr, [
-                f("div", Wr, S(F.value.groundTruthCount), 1),
+                f("div", Wr, S(P.value.groundTruthCount), 1),
                 d[18] || (d[18] = f("div", { class: "szd-stat__label" }, "Ground Truth", -1))
               ]),
               f("div", Zr, [
-                f("div", Yr, S(F.value.inFlightCount), 1),
+                f("div", Yr, S(P.value.inFlightCount), 1),
                 d[19] || (d[19] = f("div", { class: "szd-stat__label" }, "In-Flight", -1))
               ])
             ]),
             f("div", Xr, [
               f("div", en, [
                 d[20] || (d[20] = f("span", { class: "szd-kv__key" }, "Last Sync:", -1)),
-                f("span", tn, S(F.value.lastSync), 1)
+                f("span", tn, S(P.value.lastSync), 1)
               ])
             ])
           ]),
@@ -4814,9 +4829,9 @@ const _r = (n, e) => {
         t.value === "ast" ? (A(), M("div", On, [
           d[27] || (d[27] = f("h3", { class: "szd-panel__heading" }, "Query AST", -1)),
           f("div", $n, [
-            f("div", Fn, [
+            f("div", Pn, [
               d[26] || (d[26] = f("span", { class: "szd-kv__key" }, "Semantic Key:", -1)),
-              f("code", Pn, S(E.value || "—"), 1)
+              f("code", Fn, S(E.value || "—"), 1)
             ])
           ]),
           f("pre", Dn, S(re.value ? JSON.stringify(re.value, null, 2) : "Select a queryset to view AST"), 1)
@@ -4894,23 +4909,23 @@ const _r = (n, e) => {
                   f("div", Jn, [
                     f("div", Wn, [
                       d[35] || (d[35] = f("span", { class: "szd-kv__key" }, "Model:", -1)),
-                      f("span", Zn, S(F.value.modelName || "—"), 1)
+                      f("span", Zn, S(P.value.modelName || "—"), 1)
                     ]),
                     f("div", Yn, [
                       d[36] || (d[36] = f("span", { class: "szd-kv__key" }, "Source:", -1)),
-                      f("span", Xn, S(F.value.source), 1)
+                      f("span", Xn, S(P.value.source), 1)
                     ]),
                     f("div", eo, [
                       d[37] || (d[37] = f("span", { class: "szd-kv__key" }, "Syncing:", -1)),
-                      f("span", to, S(F.value.isSyncing ? "Yes" : "No"), 1)
+                      f("span", to, S(P.value.isSyncing ? "Yes" : "No"), 1)
                     ]),
                     f("div", so, [
                       d[38] || (d[38] = f("span", { class: "szd-kv__key" }, "Operations:", -1)),
-                      f("span", ro, S(F.value.opsCount), 1)
+                      f("span", ro, S(P.value.opsCount), 1)
                     ]),
                     f("div", no, [
                       d[39] || (d[39] = f("span", { class: "szd-kv__key" }, "Last Sync:", -1)),
-                      f("span", oo, S(F.value.lastSync), 1)
+                      f("span", oo, S(P.value.lastSync), 1)
                     ])
                   ])
                 ])) : L("", !0)

package/dist/cli/commands/syncModels.js

@@ -248,7 +248,7 @@ const TS_DECLARATION_TEMPLATE = `/**
 
 import { Model, Manager } from '{{modulePath}}';
 import { StringOperators, NumberOperators, BooleanOperators, DateOperators } from '{{modulePath}}';
-import { QuerySet, LiveQuerySet, LiveQuerySetOptions, MetricResult, ResultTuple, SerializerOptions, NestedPaths } from '{{modulePath}}';
+import { QuerySet, LiveQuerySet, LiveQuerySetOptions, MetricResult, ResultTuple, SerializerOptions, NestedPaths, CompiledAST } from '{{modulePath}}';
 
 // Re-export the real Manager for runtime use
 import { Manager as RuntimeManager } from '{{modulePath}}';
@@ -387,6 +387,26 @@ export declare class {{className}}QuerySet extends QuerySet<any> {
   delete(): Promise<[number, Record<string, number>]>;
   exists(): Promise<boolean>;
   fetch(serializerOptions?: SerializerOptions): Promise<{{className}}[]>;
+
+  // Compile
+  get compile(): {
+    fetch(args?: Record<string, any>): CompiledAST;
+    get(args?: Record<string, any>): CompiledAST;
+    first(args?: Record<string, any>): CompiledAST;
+    last(args?: Record<string, any>): CompiledAST;
+    count(args?: Record<string, any>): CompiledAST;
+    sum(args?: Record<string, any>): CompiledAST;
+    avg(args?: Record<string, any>): CompiledAST;
+    min(args?: Record<string, any>): CompiledAST;
+    max(args?: Record<string, any>): CompiledAST;
+    exists(args?: Record<string, any>): CompiledAST;
+    create(args?: Record<string, any>): CompiledAST;
+    bulkCreate(args?: Record<string, any>): CompiledAST;
+    update(args?: Record<string, any>): CompiledAST;
+    delete(args?: Record<string, any>): CompiledAST;
+    getOrCreate(args?: Record<string, any>): CompiledAST;
+    updateOrCreate(args?: Record<string, any>): CompiledAST;
+  };
 }
 
 /**
@@ -400,6 +420,7 @@ export declare class {{className}}Manager extends Manager {
   get(filters?: {{className}}FilterData, serializerOptions?: SerializerOptions): Promise<{{className}}>;
   create(data: {{className}}CreateData): Promise<{{className}}>;
   delete(): Promise<[number, Record<string, number>]>;
+  execute(ast: CompiledAST): Promise<any>;
 }
 
 /**
@@ -471,6 +492,7 @@ export declare class {{className}} extends Model implements {{interfaceName}} {
 
   constructor(data: Partial<{{interfaceName}}>);
   serialize(): Partial<{{interfaceName}}>;
+  static execute(ast: CompiledAST): Promise<any>;
 }
 
 /**

package/dist/config.js

@@ -9,13 +9,17 @@ export let liveConfig = {
 const pusherSchema = z.object({
     clientOptions: z.object({
         appKey: z.string({ required_error: 'Pusher appKey is required' }),
-        cluster: z.string({ required_error: 'Pusher cluster is required' }),
+        cluster: z.string().optional(),
+        wsHost: z.string().optional(),
+        wsPort: z.number().optional(),
+        wssPort: z.number().optional(),
+        enabledTransports: z.array(z.string()).optional(),
         forceTLS: z.boolean().optional(),
         authEndpoint: z.string()
             .url('Pusher authentication endpoint URL is required'),
         getAuthHeaders: z.function().optional()
             .refine((fn) => fn === undefined || typeof fn === 'function', 'getAuthHeaders must be a function if provided')
-    })
+    }).refine((opts) => opts.cluster || opts.wsHost, 'Either cluster or wsHost must be provided')
 });
 const eventConfigSchema = z.object({
     type: z.enum(['websocket', 'pusher', 'none']),

package/dist/core/eventReceivers.d.ts

@@ -48,7 +48,11 @@ export namespace EventType {
  * Options for instantiating a Pusher client.
  * @typedef {Object} PusherClientOptions
  * @property {string} appKey
- * @property {string} cluster
+ * @property {string} [cluster] - Pusher cluster (use this OR wsHost)
+ * @property {string} [wsHost] - Custom WebSocket host (e.g. for Soketi)
+ * @property {number} [wsPort] - Custom WebSocket port (default 443)
+ * @property {number} [wssPort] - Custom secure WebSocket port (default 443)
+ * @property {string[]} [enabledTransports] - Transports to use (default ['ws', 'wss'])
  * @property {boolean} [forceTLS]
  * @property {string} authEndpoint
  * @property {function(): Object<string, string>} [getAuthHeaders]
@@ -162,7 +166,26 @@ export type NamespaceResolver = (modelName: string) => string;
  */
 export type PusherClientOptions = {
     appKey: string;
-    cluster: string;
+    /**
+     * - Pusher cluster (use this OR wsHost)
+     */
+    cluster?: string | undefined;
+    /**
+     * - Custom WebSocket host (e.g. for Soketi)
+     */
+    wsHost?: string | undefined;
+    /**
+     * - Custom WebSocket port (default 443)
+     */
+    wsPort?: number | undefined;
+    /**
+     * - Custom secure WebSocket port (default 443)
+     */
+    wssPort?: number | undefined;
+    /**
+     * - Transports to use (default ['ws', 'wss'])
+     */
+    enabledTransports?: string[] | undefined;
     forceTLS?: boolean | undefined;
     authEndpoint: string;
     getAuthHeaders?: (() => {

package/dist/core/eventReceivers.js

@@ -41,7 +41,11 @@ export const EventType = {
  * Options for instantiating a Pusher client.
  * @typedef {Object} PusherClientOptions
  * @property {string} appKey
- * @property {string} cluster
+ * @property {string} [cluster] - Pusher cluster (use this OR wsHost)
+ * @property {string} [wsHost] - Custom WebSocket host (e.g. for Soketi)
+ * @property {number} [wsPort] - Custom WebSocket port (default 443)
+ * @property {number} [wssPort] - Custom secure WebSocket port (default 443)
+ * @property {string[]} [enabledTransports] - Transports to use (default ['ws', 'wss'])
  * @property {boolean} [forceTLS]
  * @property {string} authEndpoint
  * @property {function(): Object<string, string>} [getAuthHeaders]
@@ -71,12 +75,21 @@ export class PusherEventReceiver {
             clientOptions.appKey.length < 15) {
             console.warn(`%c[Pusher Warning] The provided appKey ("${clientOptions.appKey}") looks like a numeric app_id. Pusher requires the alphanumeric key, not the ID. Please verify your configuration for backend: "${this.configKey}".`, "color: orange; font-weight: bold; font-size: 14px;");
         }
-        this.pusherClient = new Pusher(clientOptions.appKey, {
-            cluster: clientOptions.cluster,
+        const pusherOpts = {
             forceTLS: clientOptions.forceTLS ?? true,
             authEndpoint: clientOptions.authEndpoint,
             auth: { headers: clientOptions.getAuthHeaders?.() || {} },
-        });
+        };
+        if (clientOptions.wsHost) {
+            pusherOpts.wsHost = clientOptions.wsHost;
+            pusherOpts.wsPort = clientOptions.wsPort ?? 443;
+            pusherOpts.wssPort = clientOptions.wssPort ?? 443;
+            pusherOpts.enabledTransports = clientOptions.enabledTransports ?? ['ws', 'wss'];
+        }
+        else {
+            pusherOpts.cluster = clientOptions.cluster;
+        }
+        this.pusherClient = new Pusher(clientOptions.appKey, pusherOpts);
         this.pusherClient.connection.bind("connected", () => {
             console.log(`Pusher client connected successfully for backend: ${this.configKey}.`);
             if (this.connectionTimeoutId) {

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

@@ -28,11 +28,13 @@ export class StateZeroError extends Error {
      * @param {string} code - The error code.
      * @param {IErrorDetail|Object|string} detail - The error details.
      * @param {number} status - The HTTP status code.
+     * @param {Object} [data={}] - Additional structured data from the server.
      */
-    constructor(message: string, code: string, detail: IErrorDetail | Object | string, status: number);
+    constructor(message: string, code: string, detail: IErrorDetail | Object | string, status: number, data?: Object);
     code: string;
     detail: string | Object | IErrorDetail;
     status: number;
+    data: Object;
     /**
      * Returns a full error message including the detail.
      *

package/dist/flavours/django/errors.js

@@ -21,13 +21,15 @@ export class StateZeroError extends Error {
      * @param {string} code - The error code.
      * @param {IErrorDetail|Object|string} detail - The error details.
      * @param {number} status - The HTTP status code.
+     * @param {Object} [data={}] - Additional structured data from the server.
      */
-    constructor(message, code, detail, status) {
+    constructor(message, code, detail, status, data = {}) {
         super(message);
         this.name = "StateZeroError";
         this.code = code;
         this.detail = detail;
         this.status = status;
+        this.data = data;
         Object.setPrototypeOf(this, new.target.prototype);
         emitError(this);
     }
@@ -169,7 +171,7 @@ export class ConfigError extends StateZeroError {
  * @returns {StateZeroError} An instance of a StateZeroError subclass.
  */
 export function parseStateZeroError(errorResponse) {
-    const { status, type, detail } = errorResponse;
+    const { status, type, detail, data } = errorResponse;
     // Handle undefined type/status case (like in permission denied)
     if (type === undefined && detail === 'Invalid token.') {
         return new PermissionDenied(detail, 403);
@@ -209,6 +211,6 @@ export function parseStateZeroError(errorResponse) {
             else if (status === 409) {
                 return new ConflictError(detail, status);
             }
-            return new StateZeroError("Unknown error", "unknown", detail, status);
+            return new StateZeroError(detail || "Unknown error", type || "unknown", detail, status, data || {});
     }
 }

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

@@ -157,6 +157,13 @@ export class Manager {
      * and a boolean indicating whether it was created.
      */
     updateOrCreate(lookupFields: any, defaults?: Object): Promise<ResultTuple>;
+    /**
+     * Executes a pre-compiled AST through the standard QueryExecutor path.
+     *
+     * @param {import('./querySet.js').CompiledAST} ast - A compiled AST from QuerySet.compile()
+     * @returns {Promise<any>} The query result.
+     */
+    execute(ast: import("./querySet.js").CompiledAST): Promise<any>;
     /**
      * Applies a search to the QuerySet using the specified search query and fields.
      *

package/dist/flavours/django/manager.js

@@ -200,6 +200,18 @@ export class Manager {
     async updateOrCreate(lookupFields, defaults = {}) {
         return this.newQuerySet().updateOrCreate(lookupFields, defaults);
     }
+    /**
+     * Executes a pre-compiled AST through the standard QueryExecutor path.
+     *
+     * @param {import('./querySet.js').CompiledAST} ast - A compiled AST from QuerySet.compile()
+     * @returns {Promise<any>} The query result.
+     */
+    execute(ast) {
+        const { op, args, ...buildOutput } = ast;
+        const qs = new this.QuerySetClass(this.ModelClass, { serializerOptions: buildOutput.serializerOptions || {} });
+        qs._prebuiltAST = { ...buildOutput, serializerOptions: buildOutput.serializerOptions || {} };
+        return QueryExecutor.execute(qs, op, args || {});
+    }
     /**
      * Applies a search to the QuerySet using the specified search query and fields.
      *

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

@@ -47,6 +47,13 @@ export class Model {
      * @returns {Promise<boolean>} Promise that resolves to true if valid, throws error if invalid
      */
     static validate(data: Object, validateType?: string, partial?: boolean): Promise<boolean>;
+    /**
+     * Executes a pre-compiled AST through the standard QueryExecutor path.
+     *
+     * @param {import('./querySet.js').CompiledAST} ast - A compiled AST from QuerySet.compile()
+     * @returns {Promise<any>} The query result.
+     */
+    static execute(ast: import("./querySet.js").CompiledAST): Promise<any>;
     /**
      * Get field permissions for the current user (cached on the class)
      * @param {boolean} refresh - Force refresh the cached permissions

package/dist/flavours/django/model.js

@@ -313,6 +313,15 @@ export class Model {
             throw new Error(`Validation failed: ${error.message}`);
         }
     }
+    /**
+     * Executes a pre-compiled AST through the standard QueryExecutor path.
+     *
+     * @param {import('./querySet.js').CompiledAST} ast - A compiled AST from QuerySet.compile()
+     * @returns {Promise<any>} The query result.
+     */
+    static execute(ast) {
+        return this.objects.execute(ast);
+    }
     /**
      * Get field permissions for the current user (cached on the class)
      * @param {boolean} refresh - Force refresh the cached permissions

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

@@ -1,3 +1,15 @@
+/**
+ * A compiled AST that can be serialized and later executed via Model.execute().
+ *
+ * @typedef {Object} CompiledAST
+ * @property {string} op - The operation type (e.g. 'list', 'get', 'create').
+ * @property {Object} args - Operation-specific arguments.
+ * @property {Object|null} filter - The filter AST node.
+ * @property {Object|null} search - The search configuration.
+ * @property {Array} aggregations - Aggregation operations.
+ * @property {Array<string>} [orderBy] - Ordering fields.
+ * @property {Object} serializerOptions - Serializer options.
+ */
 /**
  * A QuerySet provides a fluent API for constructing and executing queries.
  *
@@ -273,9 +285,30 @@ export class QuerySet<T> {
     /**
      * Builds the final query object to be sent to the backend (simple jsonable object format).
      *
-     * @returns {Object} The final query object.
-     */
-    build(): Object;
+     * @param {string} op - The operation type.
+     * @param {Object} [args={}] - Operation-specific arguments.
+     * @returns {CompiledAST} The compiled AST.
+     */
+    _compile(op: string, args?: Object): CompiledAST;
+    get compile(): {
+        fetch: (args: any) => CompiledAST;
+        get: (args: any) => CompiledAST;
+        first: (args: any) => CompiledAST;
+        last: (args: any) => CompiledAST;
+        count: (args: any) => CompiledAST;
+        sum: (args: any) => CompiledAST;
+        avg: (args: any) => CompiledAST;
+        min: (args: any) => CompiledAST;
+        max: (args: any) => CompiledAST;
+        exists: (args: any) => CompiledAST;
+        create: (args: any) => CompiledAST;
+        bulkCreate: (args: any) => CompiledAST;
+        update: (args: any) => CompiledAST;
+        delete: (args: any) => CompiledAST;
+        getOrCreate: (args: any) => CompiledAST;
+        updateOrCreate: (args: any) => CompiledAST;
+    };
+    build(): any;
     /**
      * Returns the current configuration of the QuerySet.
      *
@@ -297,5 +330,38 @@ export class QuerySet<T> {
      */
     [Symbol.asyncIterator](): AsyncIterator<T>;
 }
+/**
+ * A compiled AST that can be serialized and later executed via Model.execute().
+ */
+export type CompiledAST = {
+    /**
+     * - The operation type (e.g. 'list', 'get', 'create').
+     */
+    op: string;
+    /**
+     * - Operation-specific arguments.
+     */
+    args: Object;
+    /**
+     * - The filter AST node.
+     */
+    filter: Object | null;
+    /**
+     * - The search configuration.
+     */
+    search: Object | null;
+    /**
+     * - Aggregation operations.
+     */
+    aggregations: any[];
+    /**
+     * - Ordering fields.
+     */
+    orderBy?: string[] | undefined;
+    /**
+     * - Serializer options.
+     */
+    serializerOptions: Object;
+};
 import { ModelSerializer } from "./serializers.js";
 import { Model } from "./model.js";

package/dist/flavours/django/querySet.js

@@ -7,6 +7,18 @@ import { v7 } from "uuid";
 import hash from "object-hash";
 import rfdc from "rfdc";
 const clone = rfdc();
+/**
+ * A compiled AST that can be serialized and later executed via Model.execute().
+ *
+ * @typedef {Object} CompiledAST
+ * @property {string} op - The operation type (e.g. 'list', 'get', 'create').
+ * @property {Object} args - Operation-specific arguments.
+ * @property {Object|null} filter - The filter AST node.
+ * @property {Object|null} search - The search configuration.
+ * @property {Array} aggregations - Aggregation operations.
+ * @property {Array<string>} [orderBy] - Ordering fields.
+ * @property {Object} serializerOptions - Serializer options.
+ */
 /**
  * A QuerySet provides a fluent API for constructing and executing queries.
  *
@@ -649,9 +661,36 @@ export class QuerySet {
     /**
      * Builds the final query object to be sent to the backend (simple jsonable object format).
      *
-     * @returns {Object} The final query object.
+     * @param {string} op - The operation type.
+     * @param {Object} [args={}] - Operation-specific arguments.
+     * @returns {CompiledAST} The compiled AST.
      */
+    _compile(op, args = {}) {
+        return { op, args, ...this.build() };
+    }
+    get compile() {
+        return {
+            fetch: (args) => this._compile('list', args),
+            get: (args) => this._compile('get', args),
+            first: (args) => this._compile('first', args),
+            last: (args) => this._compile('last', args),
+            count: (args) => this._compile('count', args),
+            sum: (args) => this._compile('sum', args),
+            avg: (args) => this._compile('avg', args),
+            min: (args) => this._compile('min', args),
+            max: (args) => this._compile('max', args),
+            exists: (args) => this._compile('exists', args),
+            create: (args) => this._compile('create', args),
+            bulkCreate: (args) => this._compile('bulk_create', args),
+            update: (args) => this._compile('update', args),
+            delete: (args) => this._compile('delete', args),
+            getOrCreate: (args) => this._compile('get_or_create', args),
+            updateOrCreate: (args) => this._compile('update_or_create', args),
+        };
+    }
     build() {
+        if (this._prebuiltAST)
+            return clone(this._prebuiltAST);
         let searchData = null;
         const nonSearchNodes = [];
         for (const node of this.nodes) {

package/package.json

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