@statezero/core 0.2.38 → 0.2.40

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

@@ -0,0 +1,301 @@
+/**
+ * A QuerySet provides a fluent API for constructing and executing queries.
+ *
+ * @template T
+ */
+export class QuerySet<T> {
+    /**
+     * 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: ModelConstructor, config?: {
+        nodes?: QueryNode[] | undefined;
+        orderBy?: {
+            field: string;
+            direction: "asc" | "desc";
+        }[] | undefined;
+        fields?: Set<string> | undefined;
+        aggregations?: Aggregation[] | undefined;
+        initialQueryset?: string | undefined;
+        serializerOptions?: any;
+        materialized?: boolean | undefined;
+    }, parent?: null);
+    ModelClass: ModelConstructor;
+    nodes: QueryNode[];
+    _orderBy: {
+        field: string;
+        direction: "asc" | "desc";
+    }[] | undefined;
+    _fields: Set<string>;
+    _aggregations: Aggregation[];
+    _initialQueryset: string | undefined;
+    _serializerOptions: any;
+    _materialized: boolean;
+    _optimisticOnly: any;
+    _remoteOnly: any;
+    __uuid: string;
+    __parent: any;
+    __reactivityId: any;
+    _serializer: ModelSerializer;
+    /**
+     * Clones this QuerySet, creating a new instance with the same configuration.
+     *
+     * @returns {QuerySet} A new QuerySet instance.
+     */
+    clone(): QuerySet<any>;
+    get semanticKey(): string;
+    get key(): string;
+    /**
+     * Ensures the QuerySet is still lazy (not materialized).
+     *
+     * @private
+     * @throws {Error} If the QuerySet is already materialized.
+     */
+    private ensureNotMaterialized;
+    /**
+     * Returns the model constructor for this QuerySet.
+     *
+     * @returns {ModelConstructor} The model constructor.
+     */
+    get modelClass(): ModelConstructor;
+    /**
+     * Sets serializer options for the QuerySet.
+     *
+     * @param {SerializerOptions} options - The serializer options to set.
+     * @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;
+    /**
+     * Serializes a value based on its type (handles arrays, Model instances, Dates, primitives)
+     *
+     * @private
+     * @param {any} value - The value to serialize
+     * @returns {any} The serialized value
+     */
+    private _serializeValue;
+    /**
+     * Filters the QuerySet with the provided conditions.
+     *
+     * @param {Object} conditions - The filter conditions.
+     * @returns {QuerySet} A new QuerySet with the filter applied.
+     */
+    filter(conditions: Object): QuerySet<any>;
+    /**
+     * 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: Object): QuerySet<any>;
+    /**
+     * Orders the QuerySet by the specified fields.
+     *
+     * @param {...string} fields - Fields to order by.
+     * @returns {QuerySet} A new QuerySet with ordering applied.
+     */
+    orderBy(...fields: string[]): QuerySet<any>;
+    /**
+     * 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: string, searchFields?: string[]): QuerySet<any>;
+    /**
+     * Processes a Q object or condition into a QueryNode.
+     *
+     * @private
+     * @param {QObject|QCondition} q - The query object or condition.
+     * @returns {QueryNode} The processed QueryNode.
+     */
+    private processQObject;
+    /**
+     * 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: AggregateFunction, field: string, alias?: string): QuerySet<any>;
+    /**
+     * 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?: string): Promise<number>;
+    /**
+     * 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: string): Promise<number>;
+    /**
+     * 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: string): Promise<number>;
+    /**
+     * 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: string): Promise<any>;
+    /**
+     * 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: string): Promise<any>;
+    /**
+     * 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?: SerializerOptions): Promise<T | null>;
+    /**
+     * 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?: SerializerOptions): Promise<T | null>;
+    /**
+     * Checks if any records exist in the QuerySet.
+     *
+     * @returns {Promise<boolean>} A promise that resolves to true if records exist, otherwise false.
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Applies serializer options to the QuerySet.
+     *
+     * @param {SerializerOptions} [serializerOptions] - Optional serializer options.
+     * @returns {QuerySet} A new QuerySet with the serializer options applied.
+     */
+    all(serializerOptions?: SerializerOptions): QuerySet<any>;
+    /**
+     * Internal method to create an optimistic-only QuerySet.
+     * @private
+     * @returns {QuerySet} A new QuerySet with optimistic-only mode enabled.
+     */
+    private _optimistic;
+    /**
+     * Returns a QuerySet marked as optimistic-only, meaning operations will only
+     * update local state without making backend API calls.
+     *
+     * @returns {QuerySet} A new QuerySet with optimistic-only mode enabled.
+     */
+    get optimistic(): QuerySet<any>;
+    /**
+     * Returns a QuerySet marked as remote-only, meaning operations will
+     * hit the backend but skip local store updates and live thenables.
+     *
+     * @returns {QuerySet} A new QuerySet with remote-only mode enabled.
+     */
+    remote(): QuerySet<any>;
+    /**
+     * Creates a new record in the QuerySet.
+     * @param {Object} data - The fields and values for the new record.
+     * @returns {Promise<any>} The created model instance.
+     */
+    create(data: Object): Promise<any>;
+    /**
+     * Creates multiple model instances using the provided model instances.
+     *
+     * @param {Array<Model>} modelInstances - Array of unsaved model instances to create.
+     * @returns {Promise<Array<any>>} A promise that resolves to an array of newly created model instances.
+     */
+    bulkCreate(modelInstances: Array<Model>): Promise<Array<any>>;
+    /**
+     * 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: Object, ...args: any[]): Promise<[number, Object]>;
+    /**
+     * 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(...args: any[]): Promise<[number, Object]>;
+    /**
+     * 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?: 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).
+     *
+     * @returns {Object} The final query object.
+     */
+    build(): Object;
+    /**
+     * Returns the current configuration of the QuerySet.
+     *
+     * @private
+     * @returns {Object} The current QuerySet configuration.
+     */
+    private _getConfig;
+    /**
+     * 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?: SerializerOptions): Promise<T[]>;
+    /**
+     * Implements the async iterator protocol so that you can iterate over the QuerySet.
+     *
+     * @returns {AsyncIterator<T>} An async iterator over the model instances.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+import { ModelSerializer } from "./serializers.js";
+import { Model } from "./model.js";