@warlock.js/cascade 4.0.92 → 4.0.93

package/esm/drivers/postgres/postgres-query-builder.d.ts

@@ -0,0 +1,824 @@
+/**
+ * PostgreSQL Query Builder
+ *
+ * Implements the QueryBuilderContract for PostgreSQL databases.
+ * Provides a fluent API for building SQL queries with proper
+ * parameter handling and type safety.
+ *
+ * @module cascade/drivers/postgres
+ */
+import type { GenericObject } from "@mongez/reinforcements";
+import type { ChunkCallback, CursorPaginationOptions, CursorPaginationResult, GroupByInput, HavingInput, JoinOptions, OrderDirection, PaginationOptions, PaginationResult, QueryBuilderContract, RawExpression, WhereCallback, WhereObject, WhereOperator } from "../../contracts/query-builder.contract";
+import type { DataSource } from "../../data-source/data-source";
+import type { GlobalScopeDefinition, LocalScopeCallback } from "../../model/model";
+import { type PostgresParserOperation } from "./postgres-query-parser";
+/**
+ * PostgreSQL Query Builder.
+ *
+ * Implements the Cascade QueryBuilderContract for PostgreSQL.
+ * Collects query operations and delegates to PostgresQueryParser
+ * for SQL generation.
+ *
+ * @example
+ * ```typescript
+ * const users = await queryBuilder('users')
+ *   .select(['id', 'name', 'email'])
+ *   .where('status', 'active')
+ *   .where('age', '>', 18)
+ *   .orderBy('createdAt', 'desc')
+ *   .limit(10)
+ *   .get();
+ * ```
+ */
+export declare class PostgresQueryBuilder<T = unknown> implements QueryBuilderContract<T> {
+    readonly table: string;
+    /**
+     * Collected operations to be parsed into SQL.
+     */
+    operations: PostgresParserOperation[];
+    /**
+     * Data source instance.
+     */
+    readonly dataSource: DataSource;
+    /**
+     * Hydrate callback for transforming results.
+     */
+    hydrateCallback?: (data: unknown, index: number) => unknown;
+    /**
+     * Callback invoked before query execution.
+     */
+    private fetchingCallback?;
+    /**
+     * Callback invoked after records fetched but before hydration.
+     */
+    private hydratingCallback?;
+    /**
+     * Callback invoked after records fetched and hydrated.
+     */
+    private fetchedCallback?;
+    /**
+     * Pending global scopes.
+     */
+    pendingGlobalScopes?: Map<string, GlobalScopeDefinition>;
+    /**
+     * Available local scopes.
+     */
+    availableLocalScopes?: Map<string, LocalScopeCallback>;
+    /**
+     * Disabled global scope names.
+     */
+    disabledGlobalScopes: Set<string>;
+    /**
+     * Whether scopes have been applied.
+     */
+    scopesApplied: boolean;
+    /**
+     * Create a new query builder.
+     *
+     * @param table - Target table name
+     * @param dataSource - Optional data source (uses default if not provided)
+     */
+    constructor(table: string, dataSource?: DataSource);
+    /**
+     * Get the PostgreSQL driver instance.
+     */
+    private get driver();
+    /**
+     * Add an operation to the operations list.
+     *
+     * @param type - Operation type
+     * @param data - Operation data
+     */
+    private addOperation;
+    /**
+     * Clone this query builder with all current operations.
+     *
+     * @returns New query builder instance
+     */
+    clone(): this;
+    /**
+     * Set a hydration callback to transform each result row.
+     *
+     * @param callback - Transform function
+     * @returns This builder for chaining
+     */
+    hydrate(callback: (data: unknown, index: number) => unknown): this;
+    /**
+     * Register callback invoked before query execution.
+     *
+     * @param callback - Callback function
+     * @returns Unsubscribe function
+     */
+    onFetching(callback: (query: this) => void | Promise<void>): () => void;
+    /**
+     * Register callback invoked after fetch but before hydration.
+     *
+     * @param callback - Callback function
+     * @returns Unsubscribe function
+     */
+    onHydrating(callback: (records: unknown[], context: unknown) => void | Promise<void>): () => void;
+    /**
+     * Register callback invoked after fetch and hydration.
+     *
+     * @param callback - Callback function
+     * @returns Unsubscribe function
+     */
+    onFetched(callback: (records: unknown[], context: unknown) => void | Promise<void>): () => void;
+    /**
+     * Disable one or more global scopes for this query.
+     *
+     * @param scopeNames - Scope names to disable
+     * @returns This builder for chaining
+     */
+    withoutGlobalScope(...scopeNames: string[]): this;
+    /**
+     * Disable all global scopes for this query.
+     *
+     * @returns This builder for chaining
+     */
+    withoutGlobalScopes(): this;
+    /**
+     * Apply a local scope to this query.
+     *
+     * @param scopeName - Name of the local scope
+     * @returns This builder for chaining
+     */
+    scope(scopeName: string): this;
+    /**
+     * Apply pending global scopes before query execution.
+     */
+    private applyPendingScopes;
+    /**
+     * Add a WHERE clause to filter records.
+     */
+    where(field: string, value: unknown): this;
+    where(field: string, operator: WhereOperator, value: unknown): this;
+    where(conditions: WhereObject): this;
+    where(callback: WhereCallback<T>): this;
+    /**
+     * Add an OR WHERE clause.
+     */
+    orWhere(field: string, value: unknown): this;
+    orWhere(field: string, operator: WhereOperator, value: unknown): this;
+    orWhere(conditions: WhereObject): this;
+    orWhere(callback: WhereCallback<T>): this;
+    /**
+     * Add a raw WHERE clause.
+     */
+    whereRaw(expression: RawExpression, bindings?: unknown[]): this;
+    /**
+     * Add a raw OR WHERE clause.
+     */
+    orWhereRaw(expression: RawExpression, bindings?: unknown[]): this;
+    /**
+     * Compare two columns.
+     */
+    whereColumn(first: string, operator: WhereOperator, second: string): this;
+    /**
+     * Compare two columns with OR.
+     */
+    orWhereColumn(first: string, operator: WhereOperator, second: string): this;
+    /**
+     * Compare multiple column pairs.
+     */
+    whereColumns(comparisons: Array<[left: string, operator: WhereOperator, right: string]>): this;
+    /**
+     * Check if field is between two columns.
+     */
+    whereBetweenColumns(field: string, lowerColumn: string, upperColumn: string): this;
+    /**
+     * Filter by date (ignoring time).
+     */
+    whereDate(field: string, value: Date | string): this;
+    /**
+     * Alias for whereDate.
+     */
+    whereDateEquals(field: string, value: Date | string): this;
+    /**
+     * Filter for dates before a value.
+     */
+    whereDateBefore(field: string, value: Date | string): this;
+    /**
+     * Filter for dates after a value.
+     */
+    whereDateAfter(field: string, value: Date | string): this;
+    /**
+     * Filter by time.
+     */
+    whereTime(field: string, value: string): this;
+    /**
+     * Filter by day of month.
+     */
+    whereDay(field: string, value: number): this;
+    /**
+     * Filter by month.
+     */
+    whereMonth(field: string, value: number): this;
+    /**
+     * Filter by year.
+     */
+    whereYear(field: string, value: number): this;
+    /**
+     * Check if JSON contains value.
+     */
+    whereJsonContains(path: string, value: unknown): this;
+    /**
+     * Check if JSON doesn't contain value.
+     */
+    whereJsonDoesntContain(path: string, value: unknown): this;
+    /**
+     * Check if JSON contains key.
+     */
+    whereJsonContainsKey(path: string): this;
+    /**
+     * Check JSON array/string length.
+     */
+    whereJsonLength(path: string, operator: WhereOperator, value: number): this;
+    /**
+     * Check if JSON is array.
+     */
+    whereJsonIsArray(path: string): this;
+    /**
+     * Check if JSON is object.
+     */
+    whereJsonIsObject(path: string): this;
+    /**
+     * Check array length.
+     */
+    whereArrayLength(field: string, operator: WhereOperator, value: number): this;
+    /**
+     * Filter by ID.
+     */
+    whereId(value: string | number): this;
+    /**
+     * Filter by multiple IDs.
+     */
+    whereIds(values: Array<string | number>): this;
+    /**
+     * Filter by UUID.
+     */
+    whereUuid(value: string): this;
+    /**
+     * Filter by ULID.
+     */
+    whereUlid(value: string): this;
+    /**
+     * Full-text search.
+     */
+    whereFullText(fields: string | string[], query: string): this;
+    /**
+     * Full-text search with OR.
+     */
+    orWhereFullText(fields: string | string[], query: string): this;
+    /**
+     * Alias for whereFullText.
+     */
+    whereSearch(field: string, query: string): this;
+    /**
+     * Negate conditions.
+     */
+    whereNot(callback: WhereCallback<T>): this;
+    /**
+     * Negate conditions with OR.
+     */
+    orWhereNot(callback: WhereCallback<T>): this;
+    /**
+     * Filter by value in array.
+     */
+    whereIn(field: string, values: unknown[]): this;
+    /**
+     * Filter by value not in array.
+     */
+    whereNotIn(field: string, values: unknown[]): this;
+    /**
+     * Filter by NULL value.
+     */
+    whereNull(field: string): this;
+    /**
+     * Filter by NOT NULL value.
+     */
+    whereNotNull(field: string): this;
+    /**
+     * Filter by range (inclusive).
+     */
+    whereBetween(field: string, range: [unknown, unknown]): this;
+    /**
+     * Filter by not in range.
+     */
+    whereNotBetween(field: string, range: [unknown, unknown]): this;
+    /**
+     * Filter by LIKE pattern (case-insensitive).
+     */
+    whereLike(field: string, pattern: RegExp | string): this;
+    /**
+     * Filter by NOT LIKE pattern.
+     */
+    whereNotLike(field: string, pattern: RegExp | string): this;
+    /**
+     * Filter by prefix.
+     */
+    whereStartsWith(field: string, value: string | number): this;
+    /**
+     * Filter by not starting with prefix.
+     */
+    whereNotStartsWith(field: string, value: string | number): this;
+    /**
+     * Filter by suffix.
+     */
+    whereEndsWith(field: string, value: string | number): this;
+    /**
+     * Filter by not ending with suffix.
+     */
+    whereNotEndsWith(field: string, value: string | number): this;
+    /**
+     * Filter by date range.
+     */
+    whereDateBetween(field: string, range: [Date, Date]): this;
+    /**
+     * Filter by not in date range.
+     */
+    whereDateNotBetween(field: string, range: [Date, Date]): this;
+    /**
+     * Check if field/subquery exists.
+     */
+    whereExists(field: string): this;
+    whereExists(callback: WhereCallback<T>): this;
+    /**
+     * Check if field/subquery doesn't exist.
+     */
+    whereNotExists(field: string): this;
+    whereNotExists(callback: WhereCallback<T>): this;
+    /**
+     * Check array size.
+     */
+    whereSize(field: string, size: number): this;
+    whereSize(field: string, operator: WhereOperator, size: number): this;
+    /**
+     * Perform a full-text search.
+     */
+    textSearch(query: string, filters?: WhereObject): this;
+    /**
+     * Constrain an array field to contain the given value.
+     */
+    whereArrayContains(field: string, value: unknown, key?: string): this;
+    /**
+     * Constrain an array field to not contain the given value.
+     */
+    whereArrayNotContains(field: string, value: unknown, key?: string): this;
+    /**
+     * Constrain an array field to contain the value OR be empty.
+     */
+    whereArrayHasOrEmpty(field: string, value: unknown, key?: string): this;
+    /**
+     * Constrain an array field to not contain the value OR be empty.
+     */
+    whereArrayNotHaveOrEmpty(field: string, value: unknown, key?: string): this;
+    /**
+     * Add a JOIN clause.
+     */
+    join(table: string, localField: string, foreignField: string): this;
+    join(options: JoinOptions): this;
+    /**
+     * Add a LEFT JOIN clause.
+     */
+    leftJoin(table: string, localField: string, foreignField: string): this;
+    leftJoin(options: JoinOptions): this;
+    /**
+     * Add a RIGHT JOIN clause.
+     */
+    rightJoin(table: string, localField: string, foreignField: string): this;
+    rightJoin(options: JoinOptions): this;
+    /**
+     * Add an INNER JOIN clause.
+     */
+    innerJoin(table: string, localField: string, foreignField: string): this;
+    innerJoin(options: JoinOptions): this;
+    /**
+     * Add a FULL OUTER JOIN clause.
+     */
+    fullJoin(table: string, localField: string, foreignField: string): this;
+    fullJoin(options: JoinOptions): this;
+    /**
+     * Add a CROSS JOIN clause.
+     */
+    crossJoin(table: string): this;
+    /**
+     * Add a raw JOIN clause.
+     */
+    joinRaw(expression: RawExpression, bindings?: unknown[]): this;
+    /**
+     * Select specific columns.
+     */
+    select(fields: string[]): this;
+    select(fields: Record<string, 0 | 1 | boolean>): this;
+    select(...fields: Array<string | string[]>): this;
+    /**
+     * Select a field with alias.
+     */
+    selectAs(field: string, alias: string): this;
+    /**
+     * Select raw expression.
+     */
+    selectRaw(expression: RawExpression, bindings?: unknown[]): this;
+    /**
+     * Select multiple raw expressions.
+     */
+    selectRawMany(definitions: Array<{
+        alias: string;
+        expression: RawExpression;
+        bindings?: unknown[];
+    }>): this;
+    /**
+     * Select subquery.
+     */
+    selectSub(expression: RawExpression, alias: string): this;
+    /**
+     * Add subquery to existing selection.
+     */
+    addSelectSub(expression: RawExpression, alias: string): this;
+    /**
+     * Select aggregate value.
+     */
+    selectAggregate(field: string, aggregate: "sum" | "avg" | "min" | "max" | "count" | "first" | "last", alias: string): this;
+    /**
+     * Select existence check.
+     */
+    selectExists(field: string, alias: string): this;
+    /**
+     * Select count.
+     */
+    selectCount(field: string, alias: string): this;
+    /**
+     * Select CASE expression.
+     */
+    selectCase(cases: Array<{
+        when: RawExpression;
+        then: RawExpression | unknown;
+    }>, otherwise: RawExpression | unknown, alias: string): this;
+    /**
+     * Select conditional (IF/ELSE).
+     */
+    selectWhen(condition: RawExpression, thenValue: RawExpression | unknown, elseValue: RawExpression | unknown, alias: string): this;
+    /**
+     * Direct projection manipulation.
+     */
+    selectDriverProjection(callback: (projection: Record<string, unknown>) => void): this;
+    /**
+     * Select JSON path.
+     */
+    selectJson(path: string, alias?: string): this;
+    /**
+     * Select JSON path with raw expression.
+     */
+    selectJsonRaw(path: string, expression: RawExpression, alias: string): this;
+    /**
+     * Exclude JSON path.
+     */
+    deselectJson(path: string): this;
+    /**
+     * Concatenate fields.
+     */
+    selectConcat(fields: Array<string | RawExpression>, alias: string): this;
+    /**
+     * Coalesce values.
+     */
+    selectCoalesce(fields: Array<string | RawExpression>, alias: string): this;
+    /**
+     * Window function.
+     */
+    selectWindow(spec: RawExpression): this;
+    /**
+     * Exclude columns from projection.
+     */
+    deselect(fields: string[]): this;
+    /**
+     * Clear selection.
+     */
+    clearSelect(): this;
+    /**
+     * Select all columns.
+     */
+    selectAll(): this;
+    /**
+     * Restore default projection.
+     */
+    selectDefault(): this;
+    /**
+     * Select distinct values.
+     */
+    distinctValues(fields?: string | string[]): this;
+    /**
+     * Add additional select fields.
+     */
+    addSelect(fields: string[]): this;
+    /**
+     * Order results.
+     */
+    orderBy(field: string, direction?: OrderDirection): this;
+    orderBy(fields: Record<string, OrderDirection>): this;
+    /**
+     * Order descending.
+     */
+    orderByDesc(field: string): this;
+    /**
+     * Order with raw expression.
+     */
+    orderByRaw(expression: RawExpression, bindings?: unknown[]): this;
+    /**
+     * Order randomly.
+     */
+    orderByRandom(limit: number): this;
+    /**
+     * Get latest records.
+     */
+    latest(column?: string): Promise<T[]>;
+    /**
+     * Get oldest records.
+     */
+    oldest(column?: string): this;
+    /**
+     * Limit results.
+     */
+    limit(value: number): this;
+    /**
+     * Skip results.
+     */
+    skip(value: number): this;
+    /**
+     * Offset results.
+     */
+    offset(value: number): this;
+    /**
+     * Take first N results.
+     */
+    take(value: number): this;
+    /**
+     * Apply cursor pagination hints.
+     */
+    cursor(after?: unknown, before?: unknown): this;
+    /**
+     * Group results.
+     */
+    groupBy(input: GroupByInput): this;
+    /**
+     * Raw GROUP BY.
+     */
+    groupByRaw(expression: RawExpression, bindings?: unknown[]): this;
+    /**
+     * HAVING clause.
+     */
+    having(field: string, value: unknown): this;
+    having(field: string, operator: WhereOperator, value: unknown): this;
+    having(condition: HavingInput): this;
+    /**
+     * Raw HAVING clause.
+     */
+    havingRaw(expression: RawExpression, bindings?: unknown[]): this;
+    /**
+     * Execute query and get all results.
+     */
+    get<TResult = T>(): Promise<TResult[]>;
+    /**
+     * Apply JOIN operations for joinWith() relations.
+     */
+    private applyJoinRelations;
+    /**
+     * Extract joined relation data from raw records.
+     * Returns a map of record index to relation data.
+     */
+    private extractJoinedRelationData;
+    /**
+     * Attach joined relations to hydrated models.
+     */
+    private attachJoinedRelations;
+    /**
+     * Get first result.
+     */
+    first<TResult = T>(): Promise<TResult | null>;
+    /**
+     * Get last result.
+     */
+    last<TResult = T>(): Promise<TResult | null>;
+    /**
+     * Get random results.
+     */
+    random<TResult = T>(limit?: number): Promise<TResult[]>;
+    /**
+     * Get first or throw.
+     */
+    firstOrFail<TResult = T>(): Promise<TResult>;
+    /**
+     * Get first or call callback.
+     */
+    firstOr<TResult = T>(callback: () => TResult | Promise<TResult>): Promise<TResult>;
+    /**
+     * Get first or return default.
+     */
+    firstOrNull<TResult = T>(): Promise<TResult | null>;
+    /**
+     * Get first or create new.
+     */
+    firstOrNew<TResult = T>(defaults: GenericObject): Promise<TResult>;
+    /**
+     * Find by ID.
+     */
+    find<TResult = T>(id: number | string): Promise<TResult | null>;
+    /**
+     * Count results.
+     */
+    count(): Promise<number>;
+    /**
+     * Sum of field values.
+     */
+    sum(field: string): Promise<number>;
+    /**
+     * Average of field values.
+     */
+    avg(field: string): Promise<number>;
+    /**
+     * Minimum field value.
+     */
+    min(field: string): Promise<number>;
+    /**
+     * Maximum field value.
+     */
+    max(field: string): Promise<number>;
+    /**
+     * Get distinct values.
+     */
+    distinct<TResult = unknown>(field: string): Promise<TResult[]>;
+    /**
+     * Get array of values for field.
+     */
+    pluck(field: string): Promise<unknown[]>;
+    /**
+     * Get single scalar value.
+     */
+    value<TResult = unknown>(field: string): Promise<TResult | null>;
+    /**
+     * Check if records exist.
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Check if no records exist.
+     */
+    notExists(): Promise<boolean>;
+    /**
+     * Count distinct values.
+     */
+    countDistinct(field: string): Promise<number>;
+    /**
+     * Increment field value.
+     */
+    increment(field: string, amount?: number): Promise<number>;
+    /**
+     * Decrement field value.
+     */
+    decrement(field: string, amount?: number): Promise<number>;
+    /**
+     * Increment for all matching.
+     */
+    incrementMany(field: string, amount?: number): Promise<number>;
+    /**
+     * Decrement for all matching.
+     */
+    decrementMany(field: string, amount?: number): Promise<number>;
+    /**
+     * Process results in chunks.
+     */
+    chunk(size: number, callback: ChunkCallback<T>): Promise<void>;
+    /**
+     * Page-based pagination.
+     */
+    paginate(options: PaginationOptions): Promise<PaginationResult<T>>;
+    /**
+     * Cursor-based pagination.
+     */
+    cursorPaginate(options: CursorPaginationOptions): Promise<CursorPaginationResult<T>>;
+    /**
+     * Delete matching records.
+     */
+    delete(): Promise<number>;
+    /**
+     * Delete first matching record.
+     */
+    deleteOne(): Promise<number>;
+    /**
+     * Update matching records.
+     */
+    update(fields: Record<string, unknown>): Promise<number>;
+    /**
+     * Unset fields from matching records.
+     */
+    unset(...fields: string[]): Promise<number>;
+    /**
+     * Get the raw SQL query.
+     */
+    parse(): {
+        sql: string;
+        params: unknown[];
+    };
+    /**
+     * Get formatted SQL string.
+     */
+    pretty(): string;
+    /**
+     * Get query execution plan.
+     */
+    explain(): Promise<unknown>;
+    /**
+     * Add driver-specific raw modifications to the query.
+     */
+    raw(builder: (native: unknown) => unknown): this;
+    /**
+     * Extend the query builder with driver-specific extensions.
+     */
+    extend<R>(extension: string, ..._args: unknown[]): R;
+    /**
+     * Tap into the query builder for side-effects.
+     */
+    tap(callback: (builder: this) => void): this;
+    /**
+     * Conditionally apply query modifications.
+     */
+    when<V>(condition: V | boolean, callback: (builder: this, value: V) => void, otherwise?: (builder: this) => void): this;
+    /**
+     * Build WHERE clause from current operations.
+     */
+    private buildFilter;
+    /**
+     * Relations to eagerly load.
+     */
+    eagerLoadRelations: Map<string, boolean | ((query: QueryBuilderContract) => void)>;
+    /**
+     * Relations to count.
+     */
+    countRelations: string[];
+    /**
+     * Relations to load via JOIN (single query).
+     */
+    joinRelations: Map<string, {
+        alias: string;
+        type: "belongsTo" | "hasOne" | "hasMany";
+    }>;
+    /**
+     * Relation definitions from the model.
+     */
+    relationDefinitions?: Record<string, any>;
+    /**
+     * Model class reference.
+     */
+    modelClass?: any;
+    /**
+     * Load relations using database JOINs in a single query.
+     *
+     * Unlike `with()` which uses separate queries, `joinWith()` uses
+     * LEFT JOIN to fetch related data in a single query.
+     *
+     * @param relations - Relation names to load via JOIN
+     * @returns This builder for chaining
+     */
+    joinWith(...relations: string[]): this;
+    /**
+     * Eagerly load one or more relations.
+     *
+     * Supported patterns:
+     * - `with("posts")` - Load relation
+     * - `with("posts", "comments")` - Load multiple relations
+     * - `with("posts", callback)` - Load relation with constraint
+     * - `with({ posts: true, comments: callback })` - Object configuration
+     *
+     * @param args - Relation name(s), callbacks, or configuration object
+     */
+    with(...args: (string | Record<string, boolean | ((query: QueryBuilderContract) => void)> | ((query: QueryBuilderContract) => void))[]): this;
+    /**
+     * Add a count of related models as a virtual field.
+     * @param relations - Relation name(s) to count
+     */
+    withCount(...relations: string[]): this;
+    /**
+     * Filter results to only those that have related models.
+     * @param relation - Relation name
+     * @param operator - Optional comparison operator
+     * @param count - Optional count to compare against
+     */
+    has(relation: string, operator?: string, count?: number): this;
+    /**
+     * Filter results that have related models matching specific conditions.
+     * @param relation - Relation name
+     * @param callback - Callback to define conditions
+     */
+    whereHas(relation: string, callback: (query: QueryBuilderContract) => void): this;
+    /**
+     * Filter results that don't have any related models.
+     * @param relation - Relation name
+     */
+    doesntHave(relation: string): this;
+    /**
+     * Filter results that don't have related models matching specific conditions.
+     * @param relation - Relation name
+     * @param callback - Callback to define conditions
+     */
+    whereDoesntHave(relation: string, callback: (query: QueryBuilderContract) => void): this;
+}
+//# sourceMappingURL=postgres-query-builder.d.ts.map