@statezero/core 0.2.38 → 0.2.40

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

@@ -0,0 +1,70 @@
+/**
+ * Minimal type definitions for field lookups.
+ *
+ * @template T
+ * @typedef {Object.<string, any>} FieldLookup
+ */
+/**
+ * Minimal type definitions for object lookups.
+ *
+ * @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>;
+/**
+ * Minimal type definitions for field lookups.
+ */
+export type FieldLookup<T> = {
+    [x: string]: any;
+};
+/**
+ * Minimal type definitions for object lookups.
+ */
+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>>;
+};

package/dist/flavours/django/q.js

@@ -0,0 +1,43 @@
+/**
+ * Minimal type definitions for field lookups.
+ *
+ * @template T
+ * @typedef {Object.<string, any>} FieldLookup
+ */
+/**
+ * Minimal type definitions for object lookups.
+ *
+ * @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,
+    };
+}

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

@@ -0,0 +1,149 @@
+/**
+ * A custom data structure that behaves as an augmented array.
+ * It stores [instance, created] and also provides named properties for clarity.
+ *
+ * @class ResultTuple
+ * @extends {Array}
+ */
+export class ResultTuple extends Array<any> {
+    /**
+     * Creates a new ResultTuple.
+     *
+     * @param {*} instance - The model instance.
+     * @param {boolean} created - Whether the instance was created.
+     */
+    constructor(instance: any, created: boolean);
+    0: any;
+    1: boolean;
+    instance: any;
+    created: boolean;
+}
+/**
+ * Handles query execution against the backend, and parsing the response into the correct format.
+ */
+export class QueryExecutor {
+    /**
+     * Executes a get operation (get, first, last) with the QuerySet.
+     *
+     * @param {QuerySet} querySet - The QuerySet to execute.
+     * @param {string} operationType - The specific get operation type.
+     * @param {Object} args - Additional arguments for the operation.
+     * @returns {Promise<Object>} The model instance.
+     */
+    static executeGet(querySet: QuerySet, operationType: string, args?: Object): Promise<Object>;
+    /**
+     * Execute a list-style API call for the given QuerySet, update the in‑memory store with the returned primary keys,
+     * process any included entities, and return a live‑thenable that keeps the local "live" collection in sync.
+     *
+     * @template T  The model type of the QuerySet
+     * @param {QuerySet<T>} qs
+     *   The QuerySet to execute.
+     * @param {string} [op="list"]
+     *   The operation to perform. Defaults to `"list"`, but could be overridden for other list‑style endpoints.
+     * @param {Object} [args={}]
+     *   Additional arguments to pass through to the underlying API call (e.g. filters, pagination).
+     * @returns {LiveThenable<import('./makeLiveThenable').Result<T[]>>}
+     *   A live‑thenable wrapping an array of primary‑key values for the fetched models. The live part remains
+     *   synchronized with the in‑memory store.
+     */
+    static executeList<T>(qs: QuerySet<T>, op?: string, args?: Object): LiveThenable<any>;
+    /**
+     * Executes a get_or_create or update_or_create operation with the QuerySet.
+     *
+     * @param {QuerySet} querySet - The QuerySet to execute.
+     * @param {string} operationType - The specific operation type ('get_or_create' or 'update_or_create').
+     * @param {Object} args - Additional arguments for the operation.
+     * @returns {Promise<ResultTuple>} Tuple with instance and created flag.
+     */
+    static executeOrCreate(querySet: QuerySet, operationType: string, args?: Object): Promise<ResultTuple>;
+    /**
+     * Executes an aggregation operation with the QuerySet.
+     *
+     * @param {QuerySet} querySet - The QuerySet to execute.
+     * @param {string} operationType - The specific aggregation operation type.
+     * @param {Object} args - Additional arguments for the operation.
+     * @returns {LiveMetric} The LiveMetric instance that updates optimistically.
+     */
+    static executeAgg(querySet: QuerySet, operationType: string, args?: Object): LiveMetric;
+    /**
+     * Executes an exists operation with the QuerySet.
+     *
+     * @param {QuerySet} querySet - The QuerySet to execute.
+     * @param {string} operationType - The operation type (always 'exists' for this method).
+     * @param {Object} args - Additional arguments for the operation.
+     * @returns {Promise<boolean>} Whether records exist.
+     */
+    static executeExists(querySet: QuerySet, operationType?: string, args?: Object): Promise<boolean>;
+    /**
+     * Executes an update operation with the QuerySet.
+     *
+     * @param {QuerySet} querySet - The QuerySet to execute.
+     * @param {string} operationType - The operation type (always 'update' for this method).
+     * @param {Object} args - Additional arguments for the operation.
+     * @returns {Promise<Array>} Tuple with count and model counts map.
+     */
+    static executeUpdate(querySet: QuerySet, operationType?: string, args?: Object): Promise<any[]>;
+    /**
+     * Executes a delete operation with the QuerySet.
+     *
+     * @param {QuerySet} querySet - The QuerySet to execute.
+     * @param {string} operationType - The operation type (always 'delete' for this method).
+     * @param {Object} args - Additional arguments for the operation.
+     * @returns {Promise<Array>} Tuple with count and model counts map.
+     */
+    static executeDelete(querySet: QuerySet, operationType?: string, args?: Object): Promise<any[]>;
+    /**
+     * Executes a create operation with the QuerySet.
+     *
+     * @param {QuerySet} querySet - The QuerySet to execute.
+     * @param {string} operationType - The operation type (always 'create' for this method).
+     * @param {Object} args - Additional arguments for the operation.
+     * @returns {LiveThenable<Object>} The live Model instance which resolves to the created model.
+     */
+    static executeCreate(querySet: QuerySet, operationType?: string, args?: Object): LiveThenable<Object>;
+    /**
+     * Executes a bulk_create operation with the QuerySet.
+     *
+     * @param {QuerySet} querySet - The QuerySet to execute.
+     * @param {string} operationType - The operation type (always 'bulk_create' for this method).
+     * @param {Object} args - Additional arguments for the operation.
+     * @returns {LiveThenable<Array>} Array of live Model instances.
+     */
+    static executeBulkCreate(querySet: QuerySet, operationType?: string, args?: Object): LiveThenable<any[]>;
+    /**
+     * Executes an update_instance operation with the QuerySet.
+     *
+     * @param {QuerySet} querySet - The QuerySet to execute.
+     * @param {string} operationType - The operation type (always 'update_instance' for this method).
+     * @param {Object} args - Additional arguments for the operation.
+     * @returns {LiveThenable<Object>} The live Model instance which resolves to the updated model.
+     */
+    static executeUpdateInstance(querySet: QuerySet, operationType?: string, args?: Object): LiveThenable<Object>;
+    /**
+     * Executes a delete_instance operation with the QuerySet.
+     *
+     * @param {QuerySet} querySet - The QuerySet to execute.
+     * @param {string} operationType - The operation type (always 'delete_instance' for this method).
+     * @param {Object} args - Additional arguments for the operation, including the primary key.
+     * @returns {LiveThenable<Array>} A live‑thenable resolving to [deletedCount, { modelName: deletedCount }].
+     */
+    static executeDeleteInstance(querySet: QuerySet, operationType?: string, args?: Object): LiveThenable<any[]>;
+    /**
+     * Executes a query operation with the QuerySet.
+     *
+     * @param {QuerySet} querySet - The QuerySet to execute.
+     * @param {string} operationType - The operation type to perform.
+     * @param {Object} args - Additional arguments for the operation.
+     * @returns {Promise<any>} The operation result.
+     */
+    static execute(querySet: QuerySet, operationType?: string, args?: Object): Promise<any>;
+    /**
+     * Executes a query operation remotely without updating local stores.
+     *
+     * @param {QuerySet} querySet - The QuerySet to execute.
+     * @param {string} operationType - The operation type to perform.
+     * @param {Object} args - Additional arguments for the operation.
+     * @returns {Promise<any>} The raw API response data.
+     */
+    static executeRemote(querySet: QuerySet, operationType?: string, args?: Object): Promise<any>;
+}