@statezero/core 0.1.58 → 0.1.59

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

@@ -47,6 +47,7 @@ export class Model {
     _data: {};
     _pk: any;
     __version: number;
+    serializer: ModelSerializer;
     touch(): void;
     /**
      * Sets the primary key of the model instance.
@@ -74,13 +75,6 @@ export class Model {
      * @param {any} value - The field value to set
      */
     setField(field: string, value: any): void;
-    /**
-     * Serializes a field value for API transmission
-     *
-     * @param {string} field - The field name
-     * @returns {any} The serialized field value
-     */
-    serializeField(field: string): any;
     /**
      * Serializes the model instance.
      *
@@ -125,3 +119,4 @@ export class Model {
  * A constructor for a Model.
  */
 export type ModelConstructor = Function;
+import { ModelSerializer } from "./serializers.js";

package/dist/flavours/django/model.js

@@ -1,7 +1,3 @@
-var __setFunctionName = (this && this.__setFunctionName) || function (f, name, prefix) {
-    if (typeof name === "symbol") name = name.description ? "[".concat(name.description, "]") : "";
-    return Object.defineProperty(f, "name", { configurable: true, value: prefix ? "".concat(prefix, " ", name) : name });
-};
 import { Manager } from "./manager.js";
 import { ValidationError } from "./errors.js";
 import { modelStoreRegistry } from "../../syncEngine/registries/modelStoreRegistry.js";
@@ -11,6 +7,7 @@ import { wrapReactiveModel } from "../../reactiveAdaptor.js";
 import { DateParsingHelpers } from "./dates.js";
 import { FileObject } from './files.js';
 import { configInstance } from "../../config.js";
+import { ModelSerializer } from "./serializers.js";
 import { parseStateZeroError, MultipleObjectsReturned, DoesNotExist, } from "./errors.js";
 import axios from "axios";
 /**
@@ -36,6 +33,7 @@ export class Model {
         this._data = data;
         this._pk = data[this.constructor.primaryKeyField] || undefined;
         this.__version = 0;
+        this.serializer = new ModelSerializer(this.constructor);
         return wrapReactiveModel(this);
     }
     touch() {
@@ -78,7 +76,6 @@ export class Model {
      * @returns {any} The field value
      */
     getField(field) {
-        var _a;
         // Access the reactive __version property to establish dependency for vue integration
         const trackVersion = this.__version;
         const ModelClass = this.constructor;
@@ -92,57 +89,8 @@ export class Model {
             if (storedValue)
                 value = storedValue[field]; // if stops null -> undefined
         }
-        // Date/DateTime fields need special handling - convert to Date objects
-        const dateFormats = ["date", "datetime", "date-time"];
-        if (ModelClass.schema &&
-            dateFormats.includes(ModelClass.schema.properties[field]?.format) &&
-            value) {
-            // Let DateParsingHelpers.parseDate throw if it fails
-            return DateParsingHelpers.parseDate(value, field, ModelClass.schema);
-        }
-        // File/Image fields need special handling - wrap as FileObject
-        const fileFormats = ["file-path", "image-path"];
-        if (ModelClass.schema &&
-            fileFormats.includes(ModelClass.schema.properties[field]?.format) &&
-            value) {
-            // Check if it's already a FileObject
-            if (value instanceof FileObject) {
-                return value;
-            }
-            // If it's stored file data from API, wrap it as FileObject
-            if (typeof value === "object" && value.file_path) {
-                // Create anonymous subclass with correct configKey
-                const BackendFileObject = (_a = class extends FileObject {
-                    },
-                    __setFunctionName(_a, "BackendFileObject"),
-                    _a.configKey = ModelClass.configKey,
-                    _a);
-                return new BackendFileObject(value);
-            }
-        }
-        // relationship fields need special handling
-        if (ModelClass.relationshipFields.has(field) && value) {
-            // fetch the stored value
-            let fieldInfo = ModelClass.relationshipFields.get(field);
-            // footgun - fieldInfo.ModelClass() calls the arrow function that lazily gets the model class
-            let relPkField = fieldInfo.ModelClass().primaryKeyField;
-            switch (fieldInfo.relationshipType) {
-                case "many-to-many":
-                    // value is an array
-                    if (!Array.isArray(value) && value)
-                        throw new Error(`Data corruption: m2m field for ${ModelClass.modelName} stored as ${value}`);
-                    // set each pk to the full model object for that pk
-                    value = value.map((pk) => fieldInfo.ModelClass().fromPk(pk));
-                    break;
-                case "one-to-one":
-                case "foreign-key":
-                    // footgun - fieldInfo.ModelClass() calls the arrow function that lazily gets the model class
-                    if (!isNil(value))
-                        value = fieldInfo.ModelClass().fromPk(value);
-                    break;
-            }
-        }
-        return value;
+        // Use serializer to convert internal format to live format
+        return this.serializer.toLiveField(field, value);
     }
     /**
      * Sets a field value in the internal data store
@@ -152,11 +100,13 @@ export class Model {
      */
     setField(field, value) {
         const ModelClass = this.constructor;
+        // Use serializer to convert live format to internal format
+        const internalValue = this.serializer.toInternalField(field, value);
         if (ModelClass.primaryKeyField === field) {
-            this._pk = value;
+            this._pk = internalValue;
         }
         else {
-            this._data[field] = value;
+            this._data[field] = internalValue;
         }
     }
     /**
@@ -184,40 +134,6 @@ export class Model {
             }
         }
     }
-    /**
-     * Serializes a field value for API transmission
-     *
-     * @param {string} field - The field name
-     * @returns {any} The serialized field value
-     */
-    serializeField(field) {
-        const ModelClass = this.constructor;
-        if (ModelClass.primaryKeyField === field)
-            return this._pk;
-        // check local overrides
-        let value = this._data[field];
-        // if it's not been overridden, get it from the store
-        if (value === undefined && !isNil(this._pk)) {
-            let storedValue = modelStoreRegistry.getEntity(ModelClass, this._pk);
-            if (storedValue)
-                value = storedValue[field];
-        }
-        // Date/DateTime fields need special handling - convert Date objects to strings for API
-        const dateFormats = ["date", "date-time"];
-        if (ModelClass.schema &&
-            dateFormats.includes(ModelClass.schema.properties[field]?.format) &&
-            value instanceof Date) {
-            // Let DateParsingHelpers.serializeDate throw if it fails
-            return DateParsingHelpers.serializeDate(value, field, ModelClass.schema);
-        }
-        const fileFormats = ["file-path", "image-path"];
-        if (ModelClass.schema &&
-            fileFormats.includes(ModelClass.schema.properties[field]?.format) &&
-            value) {
-            return value.filePath || value.file_path || value;
-        }
-        return value;
-    }
     /**
      * Serializes the model instance.
      *
@@ -227,13 +143,27 @@ export class Model {
      * @returns {Object} The serialized model data.
      */
     serialize() {
-        const serialized = {};
         const ModelClass = this.constructor;
-        // Include all fields defined in the model
+        const data = {};
+        // Collect all field values (already in internal format)
         for (const field of ModelClass.fields) {
-            serialized[field] = this.serializeField(field);
+            if (field === ModelClass.primaryKeyField) {
+                data[field] = this._pk;
+            }
+            else {
+                let value = this._data[field];
+                // Get from store if not in local data
+                if (value === undefined && !isNil(this._pk)) {
+                    const storedData = modelStoreRegistry.getEntity(ModelClass, this._pk);
+                    if (storedData) {
+                        value = storedData[field];
+                    }
+                }
+                data[field] = value;
+            }
         }
-        return serialized;
+        // Data is already in internal format, so return as-is for API transmission
+        return data;
     }
     /**
      * Saves the model instance by either creating a new record or updating an existing one.

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

@@ -1,70 +1,3 @@
-/**
- * @typedef {'count'|'sum'|'avg'|'min'|'max'} AggregateFunction
- */
-/**
- * @typedef {Object} Aggregation
- * @property {AggregateFunction} function - The aggregation function.
- * @property {string} field - The field to aggregate.
- * @property {string} [alias] - Optional alias for the aggregated field.
- */
-/**
- * @typedef {'filter'|'or'|'and'|'not'|'exclude'|'get'|'create'|'update'|'delete'|'get_or_create'|'update_or_create'|'first'|'last'|'exists'|'search'} QueryOperationType
- */
-/**
- * @typedef {Object} QueryNode
- * @property {QueryOperationType} type - The operation type.
- * @property {Object.<string, any>} [conditions] - Filter conditions.
- * @property {QueryNode[]} [children] - Child query nodes.
- * @property {any} [lookup] - Extra parameter for operations that need it.
- * @property {Partial<any>} [defaults] - Default values for create operations.
- * @property {number} [pk] - Primary key value.
- * @property {any} [data] - Data payload.
- * @property {string} [searchQuery] - Search term for search operations.
- * @property {string[]} [searchFields] - Optional array of field names for search.
- */
-/**
- * @typedef {Object} SerializerOptions
- * @property {number} [depth] - How deep to serialize nested objects.
- * @property {string[]} [fields] - Fields to include.
- * @property {number} [limit] - Limit for pagination.
- * @property {number} [offset] - Offset for pagination.
- * @property {number} [overfetch] - Overfetch additional items, for smooth optimistic delete replacement.
- * @property {string} [namespace] - Custom namespace for real-time updates.
- */
-/**
- * @template T
- * @typedef {Object.<string, any>} FieldLookup
- */
-/**
- * @template T
- * @typedef {Object.<string, any>} ObjectLookup
- */
-/**
- * Django-specific Q helper type.
- *
- * A QCondition is either a partial object of type T or a combination
- * of partial field and object lookups.
- *
- * @template T
- * @typedef {Partial<T> | (Partial<FieldLookup<T>> & Partial<ObjectLookup<T>>)} QCondition
- */
-/**
- * Django-specific Q helper type representing a logical grouping of conditions.
- *
- * @template T
- * @typedef {Object} QObject
- * @property {'AND'|'OR'} operator - The logical operator.
- * @property {Array<QCondition<T>|QObject<T>>} conditions - An array of conditions or nested Q objects.
- */
-/**
- * Creates a Q object for combining conditions.
- *
- * @template T
- * @param {'AND'|'OR'} operator - The operator to combine conditions.
- * @param {...(QCondition<T>|QObject<T>)} conditions - The conditions to combine.
- * @returns {QObject<T>} The combined Q object.
- */
-export function Q<T>(operator: "AND" | "OR", ...conditions: (QCondition<T> | QObject<T>)[]): QObject<T>;
 /**
  * A QuerySet provides a fluent API for constructing and executing queries.
  *
@@ -93,7 +26,7 @@ export class QuerySet<T> {
         fields?: Set<string> | undefined;
         aggregations?: Aggregation[] | undefined;
         initialQueryset?: string | undefined;
-        serializerOptions?: SerializerOptions | undefined;
+        serializerOptions?: any;
         materialized?: boolean | undefined;
     }, parent?: null);
     ModelClass: ModelConstructor;
@@ -105,11 +38,12 @@ export class QuerySet<T> {
     _fields: Set<string>;
     _aggregations: Aggregation[];
     _initialQueryset: string | undefined;
-    _serializerOptions: SerializerOptions;
+    _serializerOptions: any;
     _materialized: boolean;
     __uuid: string;
     __parent: any;
     __reactivityId: any;
+    _serializer: ModelSerializer;
     /**
      * Clones this QuerySet, creating a new instance with the same configuration.
      *
@@ -138,6 +72,14 @@ export class QuerySet<T> {
      * @returns {QuerySet} This QuerySet instance for chaining.
      */
     setSerializerOptions(options: SerializerOptions): QuerySet<any>;
+    /**
+     * Serializes filter conditions using the model serializer.
+     *
+     * @private
+     * @param {Object} conditions - The filter conditions to serialize.
+     * @returns {Object} The serialized conditions.
+     */
+    private _serializeConditions;
     /**
      * Filters the QuerySet with the provided conditions.
      *
@@ -275,6 +217,22 @@ export class QuerySet<T> {
      * @throws {DoesNotExist} If no records are found.
      */
     get(filters?: Object, serializerOptions?: SerializerOptions): Promise<T>;
+    /**
+     * Gets or creates a record based on the provided lookup parameters.
+     *
+     * @param {Object} lookupParams - The lookup parameters to find the record.
+     * @param {Object} [defaults={}] - Default values to use when creating a new record.
+     * @returns {Promise<[T, boolean]>} A promise that resolves to a tuple of [instance, created].
+     */
+    getOrCreate(lookupParams: Object, defaults?: Object): Promise<[T, boolean]>;
+    /**
+     * Updates or creates a record based on the provided lookup parameters.
+     *
+     * @param {Object} lookupParams - The lookup parameters to find the record.
+     * @param {Object} [defaults={}] - Default values to use when creating or updating.
+     * @returns {Promise<[T, boolean]>} A promise that resolves to a tuple of [instance, created].
+     */
+    updateOrCreate(lookupParams: Object, defaults?: Object): Promise<[T, boolean]>;
     /**
      * Builds the final query object to be sent to the backend (simple jsonable object format).
      *
@@ -302,111 +260,4 @@ export class QuerySet<T> {
      */
     [Symbol.asyncIterator](): AsyncIterator<T>;
 }
-export type AggregateFunction = "count" | "sum" | "avg" | "min" | "max";
-export type Aggregation = {
-    /**
-     * - The aggregation function.
-     */
-    function: AggregateFunction;
-    /**
-     * - The field to aggregate.
-     */
-    field: string;
-    /**
-     * - Optional alias for the aggregated field.
-     */
-    alias?: string | undefined;
-};
-export type QueryOperationType = "filter" | "or" | "and" | "not" | "exclude" | "get" | "create" | "update" | "delete" | "get_or_create" | "update_or_create" | "first" | "last" | "exists" | "search";
-export type QueryNode = {
-    /**
-     * - The operation type.
-     */
-    type: QueryOperationType;
-    /**
-     * - Filter conditions.
-     */
-    conditions?: {
-        [x: string]: any;
-    } | undefined;
-    /**
-     * - Child query nodes.
-     */
-    children?: QueryNode[] | undefined;
-    /**
-     * - Extra parameter for operations that need it.
-     */
-    lookup?: any;
-    /**
-     * - Default values for create operations.
-     */
-    defaults?: Partial<any> | undefined;
-    /**
-     * - Primary key value.
-     */
-    pk?: number | undefined;
-    /**
-     * - Data payload.
-     */
-    data?: any;
-    /**
-     * - Search term for search operations.
-     */
-    searchQuery?: string | undefined;
-    /**
-     * - Optional array of field names for search.
-     */
-    searchFields?: string[] | undefined;
-};
-export type SerializerOptions = {
-    /**
-     * - How deep to serialize nested objects.
-     */
-    depth?: number | undefined;
-    /**
-     * - Fields to include.
-     */
-    fields?: string[] | undefined;
-    /**
-     * - Limit for pagination.
-     */
-    limit?: number | undefined;
-    /**
-     * - Offset for pagination.
-     */
-    offset?: number | undefined;
-    /**
-     * - Overfetch additional items, for smooth optimistic delete replacement.
-     */
-    overfetch?: number | undefined;
-    /**
-     * - Custom namespace for real-time updates.
-     */
-    namespace?: string | undefined;
-};
-export type FieldLookup<T> = {
-    [x: string]: any;
-};
-export type ObjectLookup<T> = {
-    [x: string]: any;
-};
-/**
- * Django-specific Q helper type.
- *
- * A QCondition is either a partial object of type T or a combination
- * of partial field and object lookups.
- */
-export type QCondition<T> = Partial<T> | (Partial<FieldLookup<T>> & Partial<ObjectLookup<T>>);
-/**
- * Django-specific Q helper type representing a logical grouping of conditions.
- */
-export type QObject<T> = {
-    /**
-     * - The logical operator.
-     */
-    operator: "AND" | "OR";
-    /**
-     * - An array of conditions or nested Q objects.
-     */
-    conditions: Array<QCondition<T> | QObject<T>>;
-};
+import { ModelSerializer } from "./serializers.js";

package/dist/flavours/django/querySet.js

@@ -1,83 +1,12 @@
-/**
- * @typedef {'count'|'sum'|'avg'|'min'|'max'} AggregateFunction
- */
-/**
- * @typedef {Object} Aggregation
- * @property {AggregateFunction} function - The aggregation function.
- * @property {string} field - The field to aggregate.
- * @property {string} [alias] - Optional alias for the aggregated field.
- */
-/**
- * @typedef {'filter'|'or'|'and'|'not'|'exclude'|'get'|'create'|'update'|'delete'|'get_or_create'|'update_or_create'|'first'|'last'|'exists'|'search'} QueryOperationType
- */
-/**
- * @typedef {Object} QueryNode
- * @property {QueryOperationType} type - The operation type.
- * @property {Object.<string, any>} [conditions] - Filter conditions.
- * @property {QueryNode[]} [children] - Child query nodes.
- * @property {any} [lookup] - Extra parameter for operations that need it.
- * @property {Partial<any>} [defaults] - Default values for create operations.
- * @property {number} [pk] - Primary key value.
- * @property {any} [data] - Data payload.
- * @property {string} [searchQuery] - Search term for search operations.
- * @property {string[]} [searchFields] - Optional array of field names for search.
- */
-/**
- * @typedef {Object} SerializerOptions
- * @property {number} [depth] - How deep to serialize nested objects.
- * @property {string[]} [fields] - Fields to include.
- * @property {number} [limit] - Limit for pagination.
- * @property {number} [offset] - Offset for pagination.
- * @property {number} [overfetch] - Overfetch additional items, for smooth optimistic delete replacement.
- * @property {string} [namespace] - Custom namespace for real-time updates.
- */
-/**
- * @template T
- * @typedef {Object.<string, any>} FieldLookup
- */
-/**
- * @template T
- * @typedef {Object.<string, any>} ObjectLookup
- */
-/**
- * Django-specific Q helper type.
- *
- * A QCondition is either a partial object of type T or a combination
- * of partial field and object lookups.
- *
- * @template T
- * @typedef {Partial<T> | (Partial<FieldLookup<T>> & Partial<ObjectLookup<T>>)} QCondition
- */
-/**
- * Django-specific Q helper type representing a logical grouping of conditions.
- *
- * @template T
- * @typedef {Object} QObject
- * @property {'AND'|'OR'} operator - The logical operator.
- * @property {Array<QCondition<T>|QObject<T>>} conditions - An array of conditions or nested Q objects.
- */
-/**
- * Creates a Q object for combining conditions.
- *
- * @template T
- * @param {'AND'|'OR'} operator - The operator to combine conditions.
- * @param {...(QCondition<T>|QObject<T>)} conditions - The conditions to combine.
- * @returns {QObject<T>} The combined Q object.
- */
-export function Q(operator, ...conditions) {
-    return {
-        operator,
-        conditions,
-    };
-}
-import { MultipleObjectsReturned, DoesNotExist, parseStateZeroError } from './errors.js';
-import { Model } from './model.js';
-import axios from 'axios';
-import { QueryExecutor } from './queryExecutor.js';
-import { json } from 'stream/consumers';
-import { v7 } from 'uuid';
-import hash from 'object-hash';
-import rfdc from 'rfdc';
+import { MultipleObjectsReturned, DoesNotExist, parseStateZeroError, } from "./errors.js";
+import { Model } from "./model.js";
+import { ModelSerializer } from "./serializers.js"; // Import the ModelSerializer
+import axios from "axios";
+import { QueryExecutor } from "./queryExecutor.js";
+import { json } from "stream/consumers";
+import { v7 } from "uuid";
+import hash from "object-hash";
+import rfdc from "rfdc";
 const clone = rfdc();
 /**
  * A QuerySet provides a fluent API for constructing and executing queries.
@@ -110,6 +39,8 @@ export class QuerySet {
         this.__uuid = v7();
         this.__parent = parent;
         this.__reactivityId = parent?.__reactivityId;
+        // Initialize the serializer for this model
+        this._serializer = new ModelSerializer(this.ModelClass);
     }
     /**
      * Clones this QuerySet, creating a new instance with the same configuration.
@@ -168,6 +99,20 @@ export class QuerySet {
         this._serializerOptions = { ...this._serializerOptions, ...options };
         return this;
     }
+    /**
+     * Serializes filter conditions using the model serializer.
+     *
+     * @private
+     * @param {Object} conditions - The filter conditions to serialize.
+     * @returns {Object} The serialized conditions.
+     */
+    _serializeConditions(conditions) {
+        if (!conditions || typeof conditions !== "object") {
+            return conditions;
+        }
+        // Use the model serializer to convert conditions to internal format
+        return this._serializer.toInternal(conditions);
+    }
     /**
      * Filters the QuerySet with the provided conditions.
      *
@@ -179,20 +124,22 @@ export class QuerySet {
         const { Q: qConditions, ...filters } = conditions;
         const newNodes = [...this.nodes];
         if (Object.keys(filters).length > 0) {
+            // Serialize the filter conditions before adding to the node
+            const serializedFilters = this._serializeConditions(filters);
             newNodes.push({
-                type: 'filter',
-                conditions: filters
+                type: "filter",
+                conditions: serializedFilters,
             });
         }
         if (qConditions && qConditions.length) {
             newNodes.push({
-                type: 'and',
-                children: qConditions.map(q => this.processQObject(q))
+                type: "and",
+                children: qConditions.map((q) => this.processQObject(q)),
             });
         }
         return new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            nodes: newNodes
+            nodes: newNodes,
         }, this);
     }
     /**
@@ -207,34 +154,41 @@ export class QuerySet {
         const newNodes = [...this.nodes];
         let childNode = null;
         if (Object.keys(filters).length > 0 && qConditions && qConditions.length) {
+            // Serialize the filter conditions
+            const serializedFilters = this._serializeConditions(filters);
             childNode = {
-                type: 'and',
+                type: "and",
                 children: [
-                    { type: 'filter', conditions: filters },
-                    { type: 'and', children: qConditions.map(q => this.processQObject(q)) }
-                ]
+                    { type: "filter", conditions: serializedFilters },
+                    {
+                        type: "and",
+                        children: qConditions.map((q) => this.processQObject(q)),
+                    },
+                ],
             };
         }
         else if (Object.keys(filters).length > 0) {
+            // Serialize the filter conditions
+            const serializedFilters = this._serializeConditions(filters);
             childNode = {
-                type: 'filter',
-                conditions: filters
+                type: "filter",
+                conditions: serializedFilters,
             };
         }
         else if (qConditions && qConditions.length) {
             childNode = {
-                type: 'and',
-                children: qConditions.map(q => this.processQObject(q))
+                type: "and",
+                children: qConditions.map((q) => this.processQObject(q)),
             };
         }
         const excludeNode = {
-            type: 'exclude',
-            child: childNode
+            type: "exclude",
+            child: childNode,
         };
         newNodes.push(excludeNode);
         return new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            nodes: newNodes
+            nodes: newNodes,
         }, this);
     }
     /**
@@ -247,7 +201,7 @@ export class QuerySet {
         this.ensureNotMaterialized();
         return new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            orderBy: fields
+            orderBy: fields,
         }, this);
     }
     /**
@@ -261,13 +215,13 @@ export class QuerySet {
         this.ensureNotMaterialized();
         const newNodes = [...this.nodes];
         newNodes.push({
-            type: 'search',
+            type: "search",
             searchQuery,
-            searchFields: searchFields
+            searchFields: searchFields,
         });
         return new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            nodes: newNodes
+            nodes: newNodes,
         }, this);
     }
     /**
@@ -278,18 +232,20 @@ export class QuerySet {
      * @returns {QueryNode} The processed QueryNode.
      */
     processQObject(q) {
-        if ('operator' in q && 'conditions' in q) {
+        if ("operator" in q && "conditions" in q) {
             return {
-                type: q.operator === 'AND' ? 'and' : 'or',
+                type: q.operator === "AND" ? "and" : "or",
                 children: Array.isArray(q.conditions)
-                    ? q.conditions.map(c => this.processQObject(c))
-                    : []
+                    ? q.conditions.map((c) => this.processQObject(c))
+                    : [],
             };
         }
         else {
+            // Serialize the conditions in Q objects as well
+            const serializedConditions = this._serializeConditions(q);
             return {
-                type: 'filter',
-                conditions: q
+                type: "filter",
+                conditions: serializedConditions,
             };
         }
     }
@@ -305,11 +261,14 @@ export class QuerySet {
         this.ensureNotMaterialized();
         return new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            aggregations: [...this._aggregations, {
+            aggregations: [
+                ...this._aggregations,
+                {
                     function: fn,
                     field: field,
-                    alias
-                }]
+                    alias,
+                },
+            ],
         }, this);
     }
     /**
@@ -322,9 +281,11 @@ export class QuerySet {
         this.ensureNotMaterialized();
         const newQs = new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            materialized: true
+            materialized: true,
         }, this);
-        return QueryExecutor.execute(newQs, 'count', { field: field || this.ModelClass.primaryKeyField });
+        return QueryExecutor.execute(newQs, "count", {
+            field: field || this.ModelClass.primaryKeyField,
+        });
     }
     /**
      * Executes a sum aggregation on the QuerySet.
@@ -336,9 +297,9 @@ export class QuerySet {
         this.ensureNotMaterialized();
         const newQs = new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            materialized: true
+            materialized: true,
         }, this);
-        return QueryExecutor.execute(newQs, 'sum', { field });
+        return QueryExecutor.execute(newQs, "sum", { field });
     }
     /**
      * Executes an average aggregation on the QuerySet.
@@ -350,9 +311,9 @@ export class QuerySet {
         this.ensureNotMaterialized();
         const newQs = new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            materialized: true
+            materialized: true,
         }, this);
-        return QueryExecutor.execute(newQs, 'avg', { field });
+        return QueryExecutor.execute(newQs, "avg", { field });
     }
     /**
      * Executes a min aggregation on the QuerySet.
@@ -364,9 +325,9 @@ export class QuerySet {
         this.ensureNotMaterialized();
         const newQs = new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            materialized: true
+            materialized: true,
         }, this);
-        return QueryExecutor.execute(newQs, 'min', { field });
+        return QueryExecutor.execute(newQs, "min", { field });
     }
     /**
      * Executes a max aggregation on the QuerySet.
@@ -378,9 +339,9 @@ export class QuerySet {
         this.ensureNotMaterialized();
         const newQs = new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            materialized: true
+            materialized: true,
         }, this);
-        return QueryExecutor.execute(newQs, 'max', { field });
+        return QueryExecutor.execute(newQs, "max", { field });
     }
     /**
      * Retrieves the first record of the QuerySet.
@@ -392,10 +353,12 @@ export class QuerySet {
         this.ensureNotMaterialized();
         const newQs = new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            serializerOptions: serializerOptions ? { ...this._serializerOptions, ...serializerOptions } : this._serializerOptions,
-            materialized: true
+            serializerOptions: serializerOptions
+                ? { ...this._serializerOptions, ...serializerOptions }
+                : this._serializerOptions,
+            materialized: true,
         }, this);
-        return QueryExecutor.execute(newQs, 'first');
+        return QueryExecutor.execute(newQs, "first");
     }
     /**
      * Retrieves the last record of the QuerySet.
@@ -407,10 +370,12 @@ export class QuerySet {
         this.ensureNotMaterialized();
         const newQs = new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            serializerOptions: serializerOptions ? { ...this._serializerOptions, ...serializerOptions } : this._serializerOptions,
-            materialized: true
+            serializerOptions: serializerOptions
+                ? { ...this._serializerOptions, ...serializerOptions }
+                : this._serializerOptions,
+            materialized: true,
         }, this);
-        return QueryExecutor.execute(newQs, 'last');
+        return QueryExecutor.execute(newQs, "last");
     }
     /**
      * Checks if any records exist in the QuerySet.
@@ -421,9 +386,9 @@ export class QuerySet {
         this.ensureNotMaterialized();
         const newQs = new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            materialized: true
+            materialized: true,
         }, this);
-        return QueryExecutor.execute(newQs, 'exists');
+        return QueryExecutor.execute(newQs, "exists");
     }
     /**
      * Applies serializer options to the QuerySet.
@@ -436,7 +401,10 @@ export class QuerySet {
         if (serializerOptions) {
             return new QuerySet(this.ModelClass, {
                 ...this._getConfig(),
-                serializerOptions: { ...this._serializerOptions, ...serializerOptions }
+                serializerOptions: {
+                    ...this._serializerOptions,
+                    ...serializerOptions,
+                },
             }, this);
         }
         return this;
@@ -448,12 +416,14 @@ export class QuerySet {
      */
     async create(data) {
         this.ensureNotMaterialized();
+        // Serialize the data before sending to backend
+        const serializedData = this._serializer.toInternal(data);
         // Materialize for create
         const newQs = new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            materialized: true
+            materialized: true,
         }, this);
-        return QueryExecutor.execute(newQs, 'create', { data });
+        return QueryExecutor.execute(newQs, "create", { data: serializedData });
     }
     /**
      * Updates records in the QuerySet.
@@ -463,14 +433,16 @@ export class QuerySet {
      */
     update(updates) {
         if (arguments.length > 1) {
-            throw new Error('Update accepts only accepts an object of the updates to apply. Use filter() before calling update() to select elements.');
+            throw new Error("Update accepts only accepts an object of the updates to apply. Use filter() before calling update() to select elements.");
         }
         this.ensureNotMaterialized();
+        // Serialize the updates before sending to backend
+        const serializedUpdates = this._serializer.toInternal(updates);
         const newQs = new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            materialized: true
+            materialized: true,
         });
-        return QueryExecutor.execute(newQs, 'update', { data: updates });
+        return QueryExecutor.execute(newQs, "update", { data: serializedUpdates });
     }
     /**
      * Deletes records in the QuerySet.
@@ -479,14 +451,14 @@ export class QuerySet {
      */
     delete() {
         if (arguments.length > 0) {
-            throw new Error('delete() does not accept arguments and will delete the entire queryset. Use filter() before calling delete() to select elements.');
+            throw new Error("delete() does not accept arguments and will delete the entire queryset. Use filter() before calling delete() to select elements.");
         }
         this.ensureNotMaterialized();
         const newQs = new QuerySet(this.ModelClass, {
             ...this._getConfig(),
-            materialized: true
+            materialized: true,
         }, this);
-        return QueryExecutor.execute(newQs, 'delete');
+        return QueryExecutor.execute(newQs, "delete");
     }
     /**
      * Retrieves a single record from the QuerySet.
@@ -506,19 +478,64 @@ export class QuerySet {
         if (serializerOptions) {
             newQs = new QuerySet(this.ModelClass, {
                 ...newQs._getConfig(),
-                serializerOptions: { ...newQs._serializerOptions, ...serializerOptions }
+                serializerOptions: {
+                    ...newQs._serializerOptions,
+                    ...serializerOptions,
+                },
             }, this);
         }
         const materializedQs = new QuerySet(this.ModelClass, {
             ...newQs._getConfig(),
-            materialized: true
+            materialized: true,
         }, this);
-        const result = QueryExecutor.execute(materializedQs, 'get');
+        const result = QueryExecutor.execute(materializedQs, "get");
         if (result === null) {
             throw new DoesNotExist();
         }
         return result;
     }
+    /**
+     * Gets or creates a record based on the provided lookup parameters.
+     *
+     * @param {Object} lookupParams - The lookup parameters to find the record.
+     * @param {Object} [defaults={}] - Default values to use when creating a new record.
+     * @returns {Promise<[T, boolean]>} A promise that resolves to a tuple of [instance, created].
+     */
+    async getOrCreate(lookupParams, defaults = {}) {
+        this.ensureNotMaterialized();
+        // Serialize both lookup params and defaults
+        const serializedLookup = this._serializer.toInternal(lookupParams);
+        const serializedDefaults = this._serializer.toInternal(defaults);
+        const newQs = new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            materialized: true,
+        }, this);
+        return QueryExecutor.execute(newQs, "get_or_create", {
+            lookup: serializedLookup,
+            defaults: serializedDefaults,
+        });
+    }
+    /**
+     * Updates or creates a record based on the provided lookup parameters.
+     *
+     * @param {Object} lookupParams - The lookup parameters to find the record.
+     * @param {Object} [defaults={}] - Default values to use when creating or updating.
+     * @returns {Promise<[T, boolean]>} A promise that resolves to a tuple of [instance, created].
+     */
+    async updateOrCreate(lookupParams, defaults = {}) {
+        this.ensureNotMaterialized();
+        // Serialize both lookup params and defaults
+        const serializedLookup = this._serializer.toInternal(lookupParams);
+        const serializedDefaults = this._serializer.toInternal(defaults);
+        const newQs = new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            materialized: true,
+        }, this);
+        return QueryExecutor.execute(newQs, "update_or_create", {
+            lookup: serializedLookup,
+            defaults: serializedDefaults,
+        });
+    }
     /**
      * Builds the final query object to be sent to the backend (simple jsonable object format).
      *
@@ -528,27 +545,30 @@ export class QuerySet {
         let searchData = null;
         const nonSearchNodes = [];
         for (const node of this.nodes) {
-            if (node.type === 'search') {
+            if (node.type === "search") {
                 searchData = {
-                    searchQuery: node.searchQuery || '',
-                    searchFields: node.searchFields
+                    searchQuery: node.searchQuery || "",
+                    searchFields: node.searchFields,
                 };
             }
             else {
                 nonSearchNodes.push(node);
             }
         }
-        const filterNode = nonSearchNodes.length === 0 ? null :
-            nonSearchNodes.length === 1 ? nonSearchNodes[0] : {
-                type: 'and',
-                children: nonSearchNodes
-            };
+        const filterNode = nonSearchNodes.length === 0
+            ? null
+            : nonSearchNodes.length === 1
+                ? nonSearchNodes[0]
+                : {
+                    type: "and",
+                    children: nonSearchNodes,
+                };
         return clone({
             filter: filterNode,
             search: searchData,
             aggregations: this._aggregations,
             orderBy: this._orderBy,
-            serializerOptions: this._serializerOptions
+            serializerOptions: this._serializerOptions,
         });
     }
     /**
@@ -564,7 +584,7 @@ export class QuerySet {
             fields: this._fields,
             aggregations: this._aggregations,
             initialQueryset: this._initialQueryset,
-            serializerOptions: this._serializerOptions
+            serializerOptions: this._serializerOptions,
         };
     }
     /**
@@ -578,14 +598,17 @@ export class QuerySet {
         if (serializerOptions) {
             querySet = new QuerySet(this.ModelClass, {
                 ...this._getConfig(),
-                serializerOptions: { ...this._serializerOptions, ...serializerOptions }
+                serializerOptions: {
+                    ...this._serializerOptions,
+                    ...serializerOptions,
+                },
             }, this);
         }
         const materializedQs = new QuerySet(this.ModelClass, {
             ...querySet._getConfig(),
-            materialized: true
+            materialized: true,
         }, this);
-        return QueryExecutor.execute(materializedQs, 'list');
+        return QueryExecutor.execute(materializedQs, "list");
     }
     /**
      * Implements the async iterator protocol so that you can iterate over the QuerySet.

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

@@ -0,0 +1,30 @@
+export namespace fileFieldSerializer {
+    function toInternal(value: any, context?: {}): any;
+    function toLive(value: any, context?: {}): any;
+}
+export namespace dateFieldSerializer {
+    export function toInternal_1(value: any, context?: {}): any;
+    export { toInternal_1 as toInternal };
+    export function toLive_1(value: any, context?: {}): any;
+    export { toLive_1 as toLive };
+}
+export namespace relationshipFieldSerializer {
+    export function toInternal_2(value: any, context?: {}): string | number | null | undefined;
+    export { toInternal_2 as toInternal };
+    export function toLive_2(value: any, context?: {}): any;
+    export { toLive_2 as toLive };
+}
+export namespace m2mFieldSerializer {
+    export function toInternal_3(value: any, context?: {}): any;
+    export { toInternal_3 as toInternal };
+    export function toLive_3(value: any, context?: {}): any;
+    export { toLive_3 as toLive };
+}
+export class ModelSerializer {
+    constructor(modelClass: any);
+    modelClass: any;
+    toInternalField(field: any, value: any, context?: {}): any;
+    toInternal(data: any): {};
+    toLiveField(field: any, value: any, context?: {}): any;
+    toLive(data: any): {};
+}

package/dist/flavours/django/serializers.js

@@ -0,0 +1,217 @@
+import { configInstance } from "../../config.js";
+import { isNil } from "lodash-es";
+import { DateParsingHelpers } from "./dates.js";
+/**
+ * File field serializer - handles both camelCase (frontend) and snake_case (backend) formats
+ */
+export const fileFieldSerializer = {
+    // Store backend snake_case format internally for consistency with API
+    toInternal: (value, context = {}) => {
+        // Handle plain strings - throw error
+        if (typeof value === "string") {
+            throw new Error("File field expects a file object, not a string path");
+        }
+        if (isNil(value)) {
+            return null;
+        }
+        value = {
+            file_path: value.filePath || value.file_path,
+            file_name: value.fileName || value.file_name,
+            file_url: value.fileUrl || value.file_url,
+            size: value.size,
+            mime_type: value.mimeType || value.mime_type,
+        };
+        return value;
+    },
+    // Return object with both formats for maximum compatibility
+    toLive: (value, context = {}) => {
+        if (!value || typeof value !== "object")
+            return value;
+        // Build the proper file URL using the same logic as FileObject
+        const backendKey = context.model?.constructor?.configKey || "default";
+        const fullFileUrl = value.file_url
+            ? configInstance.buildFileUrl(value.file_url, backendKey)
+            : null;
+        return {
+            // snake_case (backend format)
+            file_path: value.file_path,
+            file_name: value.file_name,
+            file_url: fullFileUrl, // Use the built URL here
+            size: value.size,
+            mime_type: value.mime_type,
+            // camelCase (frontend format) - for compatibility
+            filePath: value.file_path,
+            fileName: value.file_name,
+            fileUrl: fullFileUrl, // Use the built URL here too
+            mimeType: value.mime_type,
+        };
+    },
+};
+/**
+ * Date/DateTime field serializer - uses DateParsingHelpers like the model does
+ */
+export const dateFieldSerializer = {
+    toInternal: (value, context = {}) => {
+        if (isNil(value))
+            return value;
+        // If it's already a string, keep it (from API)
+        if (typeof value === "string")
+            return value;
+        // If it's a Date object, serialize it using DateParsingHelpers
+        if (value instanceof Date) {
+            const { model, field } = context;
+            if (model?.schema) {
+                return DateParsingHelpers.serializeDate(value, field, model.schema);
+            }
+            // Fallback if no schema context
+            return value.toISOString();
+        }
+        return value;
+    },
+    toLive: (value, context = {}) => {
+        if (isNil(value) || typeof value !== "string")
+            return value;
+        const { model, field } = context;
+        if (model?.schema) {
+            // Use DateParsingHelpers like the model does
+            return DateParsingHelpers.parseDate(value, field, model.schema);
+        }
+        // Fallback parsing if no schema context
+        try {
+            return new Date(value);
+        }
+        catch (e) {
+            console.warn(`Failed to parse date: ${value}`);
+            return value;
+        }
+    },
+};
+/**
+ * Foreign Key / One-to-One field serializer - follows existing relationship logic
+ */
+export const relationshipFieldSerializer = {
+    toInternal: (value, context = {}) => {
+        if (isNil(value))
+            return value;
+        // Extract PK or use value directly
+        const pk = value.pk || value;
+        // Assert it's a valid PK type
+        if (typeof pk !== "string" && typeof pk !== "number") {
+            throw new Error(`Invalid primary key type for relationship field: expected string or number, got ${typeof pk}`);
+        }
+        return pk;
+    },
+    toLive: (value, context = {}) => {
+        if (isNil(value))
+            return value;
+        // Follow the exact same pattern as the original getField code
+        const { model, field } = context;
+        if (model.relationshipFields.has(field) && value) {
+            const fieldInfo = model.relationshipFields.get(field);
+            // For foreign-key and one-to-one, value is guaranteed to be a plain PK
+            return fieldInfo.ModelClass().fromPk(value);
+        }
+        return value;
+    },
+};
+/**
+ * Many-to-Many field serializer - follows existing m2m logic
+ */
+export const m2mFieldSerializer = {
+    toInternal: (value, context = {}) => {
+        if (isNil(value) || !Array.isArray(value))
+            return value;
+        return value.map((item) => {
+            // Extract PK or use item directly
+            const pk = item.pk || item;
+            // Assert it's a valid PK type
+            if (typeof pk !== "string" && typeof pk !== "number") {
+                throw new Error(`Invalid primary key type for m2m field: expected string or number, got ${typeof pk}`);
+            }
+            return pk;
+        });
+    },
+    toLive: (value, context = {}) => {
+        if (isNil(value))
+            return value;
+        // Follow the exact same pattern as the original getField code
+        const { model, field } = context;
+        if (model.relationshipFields.has(field) && value) {
+            const fieldInfo = model.relationshipFields.get(field);
+            // Data corruption check like the original
+            if (!Array.isArray(value) && value) {
+                throw new Error(`Data corruption: m2m field for ${model.modelName} stored as ${value}`);
+            }
+            // Map each pk to the full model object - exactly like original
+            return value.map((pk) => fieldInfo.ModelClass().fromPk(pk));
+        }
+        return value;
+    },
+};
+const serializers = {
+    string: {
+        "file-path": fileFieldSerializer,
+        "image-path": fileFieldSerializer,
+        "date": dateFieldSerializer,
+        "date-time": dateFieldSerializer,
+        "foreign-key": relationshipFieldSerializer,
+        "one-to-one": relationshipFieldSerializer,
+    },
+    integer: {
+        "foreign-key": relationshipFieldSerializer,
+        "one-to-one": relationshipFieldSerializer,
+    },
+    // Add other PK types as needed
+    uuid: {
+        "foreign-key": relationshipFieldSerializer,
+        "one-to-one": relationshipFieldSerializer,
+    },
+    array: {
+        "many-to-many": m2mFieldSerializer,
+    },
+};
+export class ModelSerializer {
+    constructor(modelClass) {
+        this.modelClass = modelClass;
+    }
+    toInternalField(field, value, context = {}) {
+        const fieldType = this.modelClass.schema?.properties[field]?.type;
+        const fieldFormat = this.modelClass.schema?.properties[field]?.format;
+        if (serializers[fieldType] && serializers[fieldType][fieldFormat]) {
+            return serializers[fieldType][fieldFormat].toInternal(value, {
+                model: this.modelClass,
+                field,
+                ...context,
+            });
+        }
+        // Fallback to default serialization
+        return value;
+    }
+    toInternal(data) {
+        const serializedData = {};
+        for (const field in data) {
+            serializedData[field] = this.toInternalField(field, data[field]);
+        }
+        return serializedData;
+    }
+    toLiveField(field, value, context = {}) {
+        const fieldType = this.modelClass.schema?.properties[field]?.type;
+        const fieldFormat = this.modelClass.schema?.properties[field]?.format;
+        if (serializers[fieldType] && serializers[fieldType][fieldFormat]) {
+            return serializers[fieldType][fieldFormat].toLive(value, {
+                model: this.modelClass,
+                field,
+                ...context,
+            });
+        }
+        // Fallback to default serialization
+        return value;
+    }
+    toLive(data) {
+        const serializedData = {};
+        for (const field in data) {
+            serializedData[field] = this.toLiveField(field, data[field]);
+        }
+        return serializedData;
+    }
+}

package/package.json

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