@statezero/core/dist/flavours/django/querySet.d.ts

The type-safe frontend client for StateZero - connect directly to your backend models with zero boilerplate

/**
 * 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;
    __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>;
    /**
     * 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";