@squidcloud/client/dist/internal-common/src/public-types-backend/query.public-context.d.ts

A typescript implementation of the Squid client

import { AiQueryOptions } from '../public-types/ai-query.public-types';
import { IntegrationId } from '../public-types/communication.public-types';
import { CollectionName, DocumentData, FieldName } from '../public-types/document.public-types';
import { FieldSort, Operator, Query, SimpleCondition } from '../public-types/query.public-types';
import { DeepRecord, FieldOf, PartialBy, Paths } from '../public-types/typescript.public-types';
/**
 * The information provided to the secureAiQuery function about the AI query being executed.
 * @category AI
 */
export interface AiQueryContext {
    /** The prompt provided for the AI query. */
    prompt: string;
    /** The options used for executing the AI query. */
    options: AiQueryOptions;
}
/**
 * Represents the Squid query context.
 * Passed to methods that require query details, such as those annotated with the `@secureCollection` annotation.
 * @category Database
 */
export declare class QueryContext<T extends DocumentData = any> {
    readonly query: Query<T>;
    /**
     * The ID of the integration being queried.
     */
    get integrationId(): IntegrationId;
    /**
     * The name of the collection being queried.
     */
    get collectionName(): CollectionName;
    /**
     * The query limit if one exists, -1 otherwise.
     */
    get limit(): number;
    /**
     * The fields to project (include) in query results, or undefined if all fields should be returned.
     */
    get projectFields(): Array<FieldName> | undefined;
    /**
     * Verifies that the query's sort order aligns with the provided field sorts. The fields specified in the `sorts`
     * parameter must appear in the exact order at the beginning of the query's sort sequence. The query can include
     * additional fields in its sort order, but only after the specified sorts.
     *
     * @param sorts An array of field sorts.
     * @returns Whether the query's sorts matches the provided field sorts.
     */
    sortedBy(sorts: Array<PartialBy<FieldSort<T>, 'asc'>>): boolean;
    /**
     * Verifies that the query's sort order exactly matches the provided field sorts. The fields specified in the
     * `sorts` parameter must appear in the exact order in the query's sort sequence. No additional sorts may be present
     * in the query.
     *
     * @param sorts An array of field sorts.
     * @returns Whether the query's sorts exactly match the provided field sorts.
     */
    sortedByExact(sorts: Array<PartialBy<FieldSort<T>, 'asc'>>): boolean;
    /**
     * Verifies that the query is a subquery of the specified condition. A subquery is defined as a query that evaluates
     * to a subset of the results that would be obtained by applying the parent condition. The subquery may also include
     * additional conditions, as these only narrow the result set.
     *
     * @param fieldName The name of the field for the condition.
     * @param operator The operator of the condition.
     * @param value The value of the condition.
     * @returns Whether the query is a subquery of the parent condition.
     */
    isSubqueryOf<F extends Paths<T>, O extends AllOperators>(fieldName: F, operator: O, value: GenericValue<T, F, O> | null): boolean;
    /**
     * Verifies that the query is a subquery of the specified condition. A subquery is defined as a query that evaluates
     * to a subset of the results that would be obtained by applying the parent condition. The subquery may also include
     * additional conditions, as these only narrow the result set.
     *
     * @param condition The condition to validate.
     * @returns Whether the query is a subquery of the parent condition.
     */
    isSubqueryOfCondition(condition: GeneralCondition<T>): boolean;
    /**
     * Verifies that the query is a subquery of the specified conditions. A subquery is defined as a query that evaluates
     * to a subset of the results that would be obtained by applying the parent conditions. The subquery may also include
     * additional conditions, as these only narrow the result set.
     *
     * @param conditions The conditions to validate.
     * @returns Whether the query includes subquery of the parent conditions.
     */
    isSubqueryOfConditions(conditions: GeneralConditions<T>): boolean;
    /**
     * Verifies that the query is a subquery of the specified query. A subquery is defined as a query that evaluates
     * to a subset of the results that obtained for the parent query, including sorts and limits.
     *
     * @param query The query to validate.
     * @returns Whether the query is a subquery of the parent query.
     */
    isSubqueryOfQuery(query: Query<T>): boolean;
    /**
     * Checks if this query's projectFields are a subset of the parent query's projectFields.
     * A query can only be a child of another if the parent provides all fields the child needs.
     *
     * @param childFields - The projectFields of this query (the potential child)
     * @param parentFields - The projectFields of the candidate parent query
     * @returns Whether the child's fields are available from the parent
     */
    private isProjectFieldsSubset;
    /**
     * Returns all conditions that apply to any of the specified field names. This method
     * provides a convenient way to retrieve all conditions that involve a specific set of fields.
     *
     * @param fieldNames The field names for which to retrieve conditions.
     * @returns An array of conditions that involve any of the specified field names.
     */
    getConditionsFor<K extends Paths<T>>(...fieldNames: Array<K>): ContextConditions<T, K>;
    /**
     * Returns all conditions that apply to the specified field name. This method provides
     * a convenient way to retrieve all conditions that involve a specific field.
     *
     * @param fieldName The field name for which to retrieve conditions.
     * @returns An array of conditions that involve the specified field name.
     */
    getConditionsForField<K extends Paths<T>>(fieldName: K): ContextConditions<T>;
    /**
     * Returns true if the given document can be a result of the query.
     * The method does not account for limit and sort order.
     */
    documentMatchesQuery(doc: DocumentData): boolean;
}
/**
 * A list of context conditions.
 * @category Database
 */
export type ContextConditions<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> = Array<ContextCondition<Doc, F>>;
/**
 * A Context condition - a condition that replaces multiple '==' or '!=' conditions with 'in' and 'not in'.
 * @category Database
 */
export type ContextCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> = InContextCondition<Doc, F> | NotInContextCondition<Doc, F> | OtherContextCondition<Doc, F>;
/**
 * A condition using the 'in' operator to match values within a set.
 * @category Database
 */
export interface InContextCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> extends SimpleCondition<Doc, F, 'in'> {
    /** Specifies the 'in' operator to check if a value exists within an array. */
    operator: 'in';
    /** An array of values to match against the field. */
    value: Array<FieldOf<DeepRecord<Doc>, Paths<Doc>> | any>;
}
/**
 * A condition using the 'not in' operator to exclude values within a set.
 * @category Database
 */
export interface NotInContextCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> extends SimpleCondition<Doc, F, 'not in'> {
    /** Specifies the 'not in' operator to check if a value does not exist within an array. */
    operator: 'not in';
    /** An array of values to exclude from the field. */
    value: Array<FieldOf<DeepRecord<Doc>, Paths<Doc>> | any>;
}
/**
 * A condition using operators other than 'in' or 'not in' for field comparisons.
 * @category Database
 */
export interface OtherContextCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> extends SimpleCondition<Doc, F, Exclude<ContextOperator, 'in' | 'not in'>> {
    /** The operator to use for the comparison, excluding 'in' and 'not in'. */
    operator: Exclude<ContextOperator, 'in' | 'not in'>;
    /** The value to compare against the field. */
    value: FieldOf<DeepRecord<Doc>, Paths<Doc>> | any;
}
/**
 * A condition that includes all operators, including 'in' and 'not in', for general use.
 * @category Database
 */
export interface GeneralCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> extends SimpleCondition<Doc, F, AllOperators> {
    /** The operator to apply to the condition, including all possible operators. */
    operator: AllOperators;
    /** The value to use in the condition comparison. */
    value: any;
}
/**
 * A list of general conditions.
 * @category Database
 */
export type GeneralConditions<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> = Array<GeneralCondition<Doc, F>>;
/**
 * @category Database
 */
export type ContextOperator = Exclude<Operator, '==' | '!='> | 'in' | 'not in';
type AllOperators = Operator | 'in' | 'not in';
/**
 * A generic value that can exist in a query.
 * @category Database
 */
export type GenericValue<Doc = any, F extends Paths<Doc> = Paths<Doc>, O extends AllOperators = any> = O extends 'in' ? Array<DeepRecord<Doc>[F]> | null : O extends 'not in' ? Array<DeepRecord<Doc>[F]> | null : DeepRecord<Doc>[F] | null;
export {};