@statezero/core 0.1.0

package/dist/flavours/django/querySet.js

@@ -0,0 +1,601 @@
+/**
+ * @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';
+const clone = rfdc();
+/**
+ * A QuerySet provides a fluent API for constructing and executing queries.
+ *
+ * @template T
+ */
+export class QuerySet {
+    /**
+     * Creates a new QuerySet.
+     *
+     * @param {ModelConstructor} ModelClass - The model constructor.
+     * @param {Object} [config={}] - The configuration for the QuerySet.
+     * @param {QueryNode[]} [config.nodes] - Array of query nodes.
+     * @param {Array<{ field: string, direction: 'asc'|'desc' }>} [config.orderBy] - Ordering configuration.
+     * @param {Set<string>} [config.fields] - Set of fields to retrieve.
+     * @param {Aggregation[]} [config.aggregations] - Aggregation operations.
+     * @param {string} [config.initialQueryset] - The initial queryset identifier.
+     * @param {SerializerOptions} [config.serializerOptions] - Serializer options.
+     * @param {boolean} [config.materialized] - Whether the queryset is materialized.
+     */
+    constructor(ModelClass, config = {}, parent = null) {
+        this.ModelClass = ModelClass;
+        this.nodes = config.nodes || [];
+        this._orderBy = config.orderBy;
+        this._fields = config.fields || new Set();
+        this._aggregations = config.aggregations || [];
+        this._initialQueryset = config.initialQueryset;
+        this._serializerOptions = config.serializerOptions || {};
+        this._materialized = config.materialized || false;
+        this.__uuid = v7();
+        this.__parent = parent;
+        this.__reactivityId = parent?.__reactivityId;
+    }
+    /**
+     * Clones this QuerySet, creating a new instance with the same configuration.
+     *
+     * @returns {QuerySet} A new QuerySet instance.
+     */
+    clone() {
+        return new QuerySet(this.ModelClass, {
+            nodes: [...this.nodes],
+            orderBy: this._orderBy ? [...this._orderBy] : undefined,
+            fields: new Set(this._fields),
+            aggregations: [...this._aggregations],
+            initialQueryset: this._initialQueryset,
+            serializerOptions: { ...this._serializerOptions },
+            materialized: this._materialized,
+        }, this);
+    }
+    get semanticKey() {
+        return JSON.stringify({
+            ModelClass: {
+                configKey: this.ModelClass.configKey,
+                modelName: this.ModelClass.modelName,
+            },
+            ast: this.build(),
+        });
+    }
+    get key() {
+        return this.__uuid;
+    }
+    /**
+     * Ensures the QuerySet is still lazy (not materialized).
+     *
+     * @private
+     * @throws {Error} If the QuerySet is already materialized.
+     */
+    ensureNotMaterialized() {
+        if (this._materialized) {
+            throw new Error("Cannot chain further operations on a materialized QuerySet.");
+        }
+    }
+    /**
+     * Returns the model constructor for this QuerySet.
+     *
+     * @returns {ModelConstructor} The model constructor.
+     */
+    get modelClass() {
+        return this.ModelClass;
+    }
+    /**
+     * Sets serializer options for the QuerySet.
+     *
+     * @param {SerializerOptions} options - The serializer options to set.
+     * @returns {QuerySet} This QuerySet instance for chaining.
+     */
+    setSerializerOptions(options) {
+        this._serializerOptions = { ...this._serializerOptions, ...options };
+        return this;
+    }
+    /**
+     * Filters the QuerySet with the provided conditions.
+     *
+     * @param {Object} conditions - The filter conditions.
+     * @returns {QuerySet} A new QuerySet with the filter applied.
+     */
+    filter(conditions) {
+        this.ensureNotMaterialized();
+        const { Q: qConditions, ...filters } = conditions;
+        const newNodes = [...this.nodes];
+        if (Object.keys(filters).length > 0) {
+            newNodes.push({
+                type: 'filter',
+                conditions: filters
+            });
+        }
+        if (qConditions && qConditions.length) {
+            newNodes.push({
+                type: 'and',
+                children: qConditions.map(q => this.processQObject(q))
+            });
+        }
+        return new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            nodes: newNodes
+        }, this);
+    }
+    /**
+     * Excludes the specified conditions from the QuerySet.
+     *
+     * @param {Object} conditions - The conditions to exclude.
+     * @returns {QuerySet} A new QuerySet with the exclusion applied.
+     */
+    exclude(conditions) {
+        this.ensureNotMaterialized();
+        const { Q: qConditions, ...filters } = conditions;
+        const newNodes = [...this.nodes];
+        let childNode = null;
+        if (Object.keys(filters).length > 0 && qConditions && qConditions.length) {
+            childNode = {
+                type: 'and',
+                children: [
+                    { type: 'filter', conditions: filters },
+                    { type: 'and', children: qConditions.map(q => this.processQObject(q)) }
+                ]
+            };
+        }
+        else if (Object.keys(filters).length > 0) {
+            childNode = {
+                type: 'filter',
+                conditions: filters
+            };
+        }
+        else if (qConditions && qConditions.length) {
+            childNode = {
+                type: 'and',
+                children: qConditions.map(q => this.processQObject(q))
+            };
+        }
+        const excludeNode = {
+            type: 'exclude',
+            child: childNode
+        };
+        newNodes.push(excludeNode);
+        return new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            nodes: newNodes
+        }, this);
+    }
+    /**
+     * Orders the QuerySet by the specified fields.
+     *
+     * @param {...string} fields - Fields to order by.
+     * @returns {QuerySet} A new QuerySet with ordering applied.
+     */
+    orderBy(...fields) {
+        this.ensureNotMaterialized();
+        return new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            orderBy: fields
+        }, this);
+    }
+    /**
+     * Applies a search to the QuerySet using the specified search query and fields.
+     *
+     * @param {string} searchQuery - The search query.
+     * @param {string[]} [searchFields] - The fields to search.
+     * @returns {QuerySet} A new QuerySet with the search applied.
+     */
+    search(searchQuery, searchFields) {
+        this.ensureNotMaterialized();
+        const newNodes = [...this.nodes];
+        newNodes.push({
+            type: 'search',
+            searchQuery,
+            searchFields: searchFields
+        });
+        return new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            nodes: newNodes
+        }, this);
+    }
+    /**
+     * Processes a Q object or condition into a QueryNode.
+     *
+     * @private
+     * @param {QObject|QCondition} q - The query object or condition.
+     * @returns {QueryNode} The processed QueryNode.
+     */
+    processQObject(q) {
+        if ('operator' in q && 'conditions' in q) {
+            return {
+                type: q.operator === 'AND' ? 'and' : 'or',
+                children: Array.isArray(q.conditions)
+                    ? q.conditions.map(c => this.processQObject(c))
+                    : []
+            };
+        }
+        else {
+            return {
+                type: 'filter',
+                conditions: q
+            };
+        }
+    }
+    /**
+     * Aggregates the QuerySet using the specified function.
+     *
+     * @param {AggregateFunction} fn - The aggregation function.
+     * @param {string} field - The field to aggregate.
+     * @param {string} [alias] - An optional alias for the aggregated field.
+     * @returns {QuerySet} A new QuerySet with the aggregation applied.
+     */
+    aggregate(fn, field, alias) {
+        this.ensureNotMaterialized();
+        return new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            aggregations: [...this._aggregations, {
+                    function: fn,
+                    field: field,
+                    alias
+                }]
+        }, this);
+    }
+    /**
+     * Executes a count query on the QuerySet.
+     *
+     * @param {string} [field] - The field to count.
+     * @returns {Promise<number>} A promise that resolves to the count.
+     */
+    count(field) {
+        this.ensureNotMaterialized();
+        const newQs = new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            materialized: true
+        }, this);
+        return QueryExecutor.execute(newQs, 'count', { field: field || this.ModelClass.primaryKeyField });
+    }
+    /**
+     * Executes a sum aggregation on the QuerySet.
+     *
+     * @param {string} field - The field to sum.
+     * @returns {Promise<number>} A promise that resolves to the sum.
+     */
+    sum(field) {
+        this.ensureNotMaterialized();
+        const newQs = new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            materialized: true
+        }, this);
+        return QueryExecutor.execute(newQs, 'sum', { field });
+    }
+    /**
+     * Executes an average aggregation on the QuerySet.
+     *
+     * @param {string} field - The field to average.
+     * @returns {Promise<number>} A promise that resolves to the average.
+     */
+    avg(field) {
+        this.ensureNotMaterialized();
+        const newQs = new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            materialized: true
+        }, this);
+        return QueryExecutor.execute(newQs, 'avg', { field });
+    }
+    /**
+     * Executes a min aggregation on the QuerySet.
+     *
+     * @param {string} field - The field to find the minimum value for.
+     * @returns {Promise<any>} A promise that resolves to the minimum value.
+     */
+    min(field) {
+        this.ensureNotMaterialized();
+        const newQs = new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            materialized: true
+        }, this);
+        return QueryExecutor.execute(newQs, 'min', { field });
+    }
+    /**
+     * Executes a max aggregation on the QuerySet.
+     *
+     * @param {string} field - The field to find the maximum value for.
+     * @returns {Promise<any>} A promise that resolves to the maximum value.
+     */
+    max(field) {
+        this.ensureNotMaterialized();
+        const newQs = new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            materialized: true
+        }, this);
+        return QueryExecutor.execute(newQs, 'max', { field });
+    }
+    /**
+     * Retrieves the first record of the QuerySet.
+     *
+     * @param {SerializerOptions} [serializerOptions] - Optional serializer options.
+     * @returns {Promise<T|null>} A promise that resolves to the first record or null.
+     */
+    first(serializerOptions) {
+        this.ensureNotMaterialized();
+        const newQs = new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            serializerOptions: serializerOptions ? { ...this._serializerOptions, ...serializerOptions } : this._serializerOptions,
+            materialized: true
+        }, this);
+        return QueryExecutor.execute(newQs, 'first');
+    }
+    /**
+     * Retrieves the last record of the QuerySet.
+     *
+     * @param {SerializerOptions} [serializerOptions] - Optional serializer options.
+     * @returns {Promise<T|null>} A promise that resolves to the last record or null.
+     */
+    last(serializerOptions) {
+        this.ensureNotMaterialized();
+        const newQs = new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            serializerOptions: serializerOptions ? { ...this._serializerOptions, ...serializerOptions } : this._serializerOptions,
+            materialized: true
+        }, this);
+        return QueryExecutor.execute(newQs, 'last');
+    }
+    /**
+     * Checks if any records exist in the QuerySet.
+     *
+     * @returns {Promise<boolean>} A promise that resolves to true if records exist, otherwise false.
+     */
+    exists() {
+        this.ensureNotMaterialized();
+        const newQs = new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            materialized: true
+        }, this);
+        return QueryExecutor.execute(newQs, 'exists');
+    }
+    /**
+     * Applies serializer options to the QuerySet.
+     *
+     * @param {SerializerOptions} [serializerOptions] - Optional serializer options.
+     * @returns {QuerySet} A new QuerySet with the serializer options applied.
+     */
+    all(serializerOptions) {
+        this.ensureNotMaterialized();
+        if (serializerOptions) {
+            return new QuerySet(this.ModelClass, {
+                ...this._getConfig(),
+                serializerOptions: { ...this._serializerOptions, ...serializerOptions }
+            }, this);
+        }
+        return this;
+    }
+    /**
+     * Creates a new record in the QuerySet.
+     * @param {Object} data - The fields and values for the new record.
+     * @returns {Promise<any>} The created model instance.
+     */
+    async create(data) {
+        this.ensureNotMaterialized();
+        // Materialize for create
+        const newQs = new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            materialized: true
+        }, this);
+        return QueryExecutor.execute(newQs, 'create', { data });
+    }
+    /**
+     * Updates records in the QuerySet.
+     *
+     * @param {Object} updates - The fields to update.
+     * @returns {Promise<[number, Object]>} A promise that resolves to a tuple with the number of updated records and a mapping of model names to counts.
+     */
+    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.');
+        }
+        this.ensureNotMaterialized();
+        const newQs = new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            materialized: true
+        });
+        return QueryExecutor.execute(newQs, 'update', { data: updates });
+    }
+    /**
+     * Deletes records in the QuerySet.
+     *
+     * @returns {Promise<[number, Object]>} A promise that resolves to a tuple with the number of deleted records and a mapping of model names to counts.
+     */
+    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.');
+        }
+        this.ensureNotMaterialized();
+        const newQs = new QuerySet(this.ModelClass, {
+            ...this._getConfig(),
+            materialized: true
+        }, this);
+        return QueryExecutor.execute(newQs, 'delete');
+    }
+    /**
+     * Retrieves a single record from the QuerySet.
+     *
+     * @param {Object} [filters] - Optional filters to apply.
+     * @param {SerializerOptions} [serializerOptions] - Optional serializer options.
+     * @returns {Promise<T>} A promise that resolves to the retrieved record.
+     * @throws {MultipleObjectsReturned} If more than one record is found.
+     * @throws {DoesNotExist} If no records are found.
+     */
+    get(filters, serializerOptions) {
+        this.ensureNotMaterialized();
+        let newQs = this;
+        if (filters) {
+            newQs = this.filter(filters);
+        }
+        if (serializerOptions) {
+            newQs = new QuerySet(this.ModelClass, {
+                ...newQs._getConfig(),
+                serializerOptions: { ...newQs._serializerOptions, ...serializerOptions }
+            }, this);
+        }
+        const materializedQs = new QuerySet(this.ModelClass, {
+            ...newQs._getConfig(),
+            materialized: true
+        }, this);
+        const result = QueryExecutor.execute(materializedQs, 'get');
+        if (result === null) {
+            throw new DoesNotExist();
+        }
+        return result;
+    }
+    /**
+     * Builds the final query object to be sent to the backend (simple jsonable object format).
+     *
+     * @returns {Object} The final query object.
+     */
+    build() {
+        let searchData = null;
+        const nonSearchNodes = [];
+        for (const node of this.nodes) {
+            if (node.type === 'search') {
+                searchData = {
+                    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
+            };
+        return clone({
+            filter: filterNode,
+            search: searchData,
+            aggregations: this._aggregations,
+            orderBy: this._orderBy,
+            serializerOptions: this._serializerOptions
+        });
+    }
+    /**
+     * Returns the current configuration of the QuerySet.
+     *
+     * @private
+     * @returns {Object} The current QuerySet configuration.
+     */
+    _getConfig() {
+        return {
+            nodes: this.nodes,
+            orderBy: this._orderBy,
+            fields: this._fields,
+            aggregations: this._aggregations,
+            initialQueryset: this._initialQueryset,
+            serializerOptions: this._serializerOptions
+        };
+    }
+    /**
+     * Materializes the QuerySet into an array of model instances.
+     *
+     * @param {SerializerOptions} [serializerOptions] - Optional serializer options.
+     * @returns {Promise<T[]>} A promise that resolves to an array of model instances.
+     */
+    fetch(serializerOptions) {
+        let querySet = this;
+        if (serializerOptions) {
+            querySet = new QuerySet(this.ModelClass, {
+                ...this._getConfig(),
+                serializerOptions: { ...this._serializerOptions, ...serializerOptions }
+            }, this);
+        }
+        const materializedQs = new QuerySet(this.ModelClass, {
+            ...querySet._getConfig(),
+            materialized: true
+        }, this);
+        return QueryExecutor.execute(materializedQs, 'list');
+    }
+    /**
+     * Implements the async iterator protocol so that you can iterate over the QuerySet.
+     *
+     * @returns {AsyncIterator<T>} An async iterator over the model instances.
+     */
+    async *[Symbol.asyncIterator]() {
+        const items = await this.fetch();
+        for (const item of items) {
+            yield item;
+        }
+    }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Check if a string contains a temporary PK template
+ * @param {string} str - The string to check
+ * @returns {boolean} - True if the string contains a TempPK tag
+ */
+export function containsTempPk(str: string): boolean;
+/**
+ * Create a temporary PK with handlebars syntax
+ */
+export function createTempPk(uuid: any): string;
+/**
+ * Register a real PK for a temporary PK
+ */
+export function setRealPk(uuid: any, realPk: any): void;
+/**
+ * Replace all temporary PKs in an object (or string) with their real values
+ */
+export function replaceTempPks(payload: any): any;
+export const tempPkMap: Map<any, any>;

package/dist/flavours/django/tempPk.js

@@ -0,0 +1,48 @@
+import Handlebars from 'handlebars';
+import superjson from 'superjson';
+// Simple map to store temporary PK to real PK mappings
+export const tempPkMap = new Map();
+/**
+ * Check if a string contains a temporary PK template
+ * @param {string} str - The string to check
+ * @returns {boolean} - True if the string contains a TempPK tag
+ */
+export function containsTempPk(str) {
+    return (typeof str === 'string' &&
+        /\{\{\s*TempPK_[^}\s]+\s*\}\}/.test(str));
+}
+/**
+ * Create a temporary PK with handlebars syntax
+ */
+export function createTempPk(uuid) {
+    const tempPk = `{{TempPK_${uuid}}}`;
+    return tempPk;
+}
+/**
+ * Register a real PK for a temporary PK
+ */
+export function setRealPk(uuid, realPk) {
+    const key = `TempPK_${uuid}`;
+    tempPkMap.set(key, realPk);
+}
+/**
+ * Replace all temporary PKs in an object (or string) with their real values
+ */
+export function replaceTempPks(payload) {
+    if (tempPkMap.size === 0)
+        return payload;
+    const context = Object.fromEntries(tempPkMap);
+    try {
+        if (typeof payload === 'string') {
+            const template = Handlebars.compile(payload, { noEscape: true });
+            return template(context);
+        }
+        const str = superjson.stringify(payload);
+        const template = Handlebars.compile(str, { noEscape: true });
+        const replaced = template(context);
+        return superjson.parse(replaced);
+    }
+    catch (error) {
+        return payload;
+    }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Given a live reactive handle and a Promise, wire them together so
+ * the handle is also thenable.
+ *
+ * @template T
+ * @param {LiveQueryset} live
+ * @param {Promise<T>} promise
+ * @returns {LiveQueryset & Promise<T>}
+ */
+export function makeLiveThenable<T>(live: LiveQueryset, promise: Promise<T>): LiveQueryset & Promise<T>;
+/**
+ * Remove the thenable hooks and clear the optimistic flag in-place, so the object
+ * can be returned without causing a recursive await loop.
+ *
+ * @template T
+ * @param {T} live
+ * @returns {T}
+ */
+export function breakThenable<T>(live: T): T;