@statezero/core 0.1.0

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

@@ -0,0 +1,412 @@
+/**
+ * @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.
+ *
+ * @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?: SerializerOptions | undefined;
+        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: SerializerOptions;
+    _materialized: boolean;
+    __uuid: string;
+    __parent: any;
+    __reactivityId: any;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+}
+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>>;
+};