@onchaindb/sdk 0.4.0 → 0.4.2

package/src/query-sdk/QueryBuilder.ts

@@ -0,0 +1,1191 @@
+import {QueryRequest, QueryResponse, QueryValue, SelectionMap, Val, PaymentRequiredError} from '../index';
+import {FieldConditionBuilder, LogicalOperator} from './operators';
+import {SelectionBuilder} from './SelectionBuilder';
+import {ConditionBuilder} from './ConditionBuilder';
+import {FieldMap, HttpClient} from "./index";
+import {AxiosError} from "axios";
+import {
+    X402PaymentRequirement,
+    X402PaymentRequiredResponse,
+    encodePaymentHeader,
+    requirementToQuote,
+} from '../x402';
+
+// Interface for server-side join configuration (Scepter format)
+export interface ServerJoinConfig {
+    alias: string;              // Field name for joined data
+    model: string;              // Target collection to join with
+    many?: boolean;             // Explicit control over result type: true=array, false=single object, undefined=default (array)
+    resolve: {                  // Sub-query to resolve joined data
+        find?: any;             // Filter conditions for join
+        select?: SelectionMap;  // Fields to select from joined collection
+    };
+}
+
+// DEPRECATED: Client-side join configuration (kept for backward compatibility)
+export interface JoinConfig {
+    parentCollection: string;
+    parentField: string;
+    childField: string;
+    alias: string;
+}
+
+// Main query builder providing fluent API for building queries
+export class QueryBuilder {
+    private findConditions?: LogicalOperator;
+    private selections?: SelectionMap;
+    private fieldMap?: FieldMap;
+    private limitValue?: number;
+    private offsetValue?: number;
+    private sortBy?: string;
+    private sortDirection?: string;
+    private includeHistoryValue?: boolean;
+    private httpClient?: HttpClient;
+    private serverUrl?: string;
+    private collectionName: string | undefined;
+    private app: string | undefined;
+    private serverJoinConfigs: ServerJoinConfig[] = [];  // Server-side JOINs (Scepter)
+    private joinConfigs: JoinConfig[] = [];  // DEPRECATED: Client-side JOINs
+
+    constructor(httpClient?: HttpClient, serverUrl?: string, app?: string) {
+        this.httpClient = httpClient;
+        this.serverUrl = serverUrl;
+        this.app = app;
+    }
+
+    static new(httpClient?: HttpClient, serverUrl?: string, app?: string): QueryBuilder {
+        return new QueryBuilder(httpClient, serverUrl, app);
+    }
+
+    // Set HTTP client and server URL (for method chaining)
+    withHttpClient(httpClient: HttpClient): QueryBuilder {
+        this.httpClient = httpClient;
+        return this;
+    }
+
+    withServerUrl(serverUrl: string): QueryBuilder {
+        this.serverUrl = serverUrl;
+        return this;
+    }
+
+    // Build find conditions using a builder function
+    find(builderFn: (builder: ConditionBuilder) => LogicalOperator): QueryBuilder {
+        const conditionBuilder = new ConditionBuilder();
+        this.findConditions = builderFn(conditionBuilder);
+        return this;
+    }
+
+    collection(s: string): QueryBuilder {
+        this.collectionName = s;
+        return this;
+    }
+
+    // Simple field condition (equivalent to Rust's where_field)
+    whereField(fieldName: string): WhereClause {
+        return new WhereClause(this, fieldName);
+    }
+
+    // Server-side JOIN with Scepter query engine (RECOMMENDED)
+    // This generates a JOIN query that the backend executes recursively
+    serverJoin(alias: string, model: string, resolve: { find?: any; select?: SelectionMap }): QueryBuilder {
+        this.serverJoinConfigs.push({
+            alias,
+            model,
+            resolve
+        });
+        return this;
+    }
+
+    // Fluent JOIN builder for constructing server-side JOINs (default behavior - returns array)
+    joinWith(alias: string, model: string): JoinBuilder {
+        return new JoinBuilder(this, alias, model);
+    }
+
+    // One-to-one JOIN: Returns a single object (or null if no match)
+    // Use this when you expect at most one related record (e.g., user has one profile)
+    joinOne(alias: string, model: string): JoinBuilder {
+        return new JoinBuilder(this, alias, model, false);  // many = false
+    }
+
+    // One-to-many JOIN: Returns an array of objects (or empty array if no matches)
+    // Use this when you expect multiple related records (e.g., user has many tweets)
+    joinMany(alias: string, model: string): JoinBuilder {
+        return new JoinBuilder(this, alias, model, true);  // many = true
+    }
+
+    // DEPRECATED: Client-side join (uses Promise.all to fetch related data)
+    // Use serverJoin(), joinWith(), joinOne(), or joinMany() instead for better performance
+    join(parentCollection: string, parentField: string, childField: string, alias: string): QueryBuilder {
+        console.warn('QueryBuilder.join() is deprecated. Use serverJoin(), joinOne(), or joinMany() for server-side JOINs.');
+        this.joinConfigs.push({
+            parentCollection,
+            parentField,
+            childField,
+            alias
+        });
+        return this;
+    }
+
+    // Build selections using a builder function
+    select(builderFn: (builder: SelectionBuilder) => SelectionBuilder): QueryBuilder {
+        const selectionBuilder = new SelectionBuilder();
+        builderFn(selectionBuilder);
+        this.selections = selectionBuilder.build();
+        return this;
+    }
+
+    // Select specific fields by name
+    selectFields(fields: string[]): QueryBuilder {
+        const selectionBuilder = new SelectionBuilder();
+        selectionBuilder.fields(fields);
+        this.selections = selectionBuilder.build();
+        return this;
+    }
+
+    // Select all fields (no field filtering)
+    selectAll(): QueryBuilder {
+        this.selections = SelectionBuilder.all();
+        return this;
+    }
+
+    // Set field mapping for the query
+    withFieldMap(fieldMap: FieldMap): QueryBuilder {
+        this.fieldMap = fieldMap;
+        return this;
+    }
+
+    // Set limit for results
+    limit(limit: number): QueryBuilder {
+        this.limitValue = limit;
+        return this;
+    }
+
+    // Set offset for results
+    offset(offset: number): QueryBuilder {
+        this.offsetValue = offset;
+        return this;
+    }
+
+    // Set sorting fields
+    orderBy(fields: string, direction?: "ASC" | "DESC"): QueryBuilder {
+        this.sortBy = fields;
+        switch (direction) {
+            case "ASC":
+                this.sortDirection = "ascending";
+                break;
+                case "DESC":
+                    this.sortDirection = "descending";
+                    break;
+            default:
+                this.sortDirection = "ascending";
+        }
+
+        return this;
+    }
+
+    // Include all versions of records in query results (default: false, returns only latest versions)
+    // When true, returns all historical versions of each record
+    // When false or not called (default), returns only the most recent version of each record
+    includeHistory(include: boolean = true): QueryBuilder {
+        this.includeHistoryValue = include;
+        return this;
+    }
+
+    // Execute the query via HTTP with join support
+    async execute<T extends Record<string, any>>(): Promise<QueryResponse<T>> {
+        if (!this.httpClient) {
+            throw new Error('HTTP client is required for query execution');
+        }
+        if (!this.serverUrl) {
+            throw new Error('Server URL is required for query execution');
+        }
+
+        // Server-side JOINs are embedded in the query structure and handled by the backend
+        if (this.serverJoinConfigs.length > 0) {
+            return this.executeSimpleQuery<T>();
+        }
+
+        // DEPRECATED: Client-side joins using Promise.all
+        if (this.joinConfigs.length > 0) {
+            console.warn('Using deprecated client-side JOINs. Consider migrating to serverJoin() for better performance.');
+            return this.executeWithJoins<T>();
+        }
+
+        // No joins, execute as a normal query
+        return this.executeSimpleQuery<T>();
+    }
+
+    /**
+     * Execute the query and return only the latest record by metadata (updatedAt or createdAt).
+     * This is the server-side implementation - it runs the find query, sorts by metadata
+     * timestamp descending, and returns only the first (latest) record.
+     *
+     * @returns Promise resolving to the latest matching record or null if none found
+     *
+     * @example
+     * ```typescript
+     * const latestUser = await db.queryBuilder()
+     *   .collection('users')
+     *   .whereField('email').equals('alice@example.com')
+     *   .executeUnique<User>();
+     * ```
+     */
+    async executeUnique<T extends Record<string, any>>(): Promise<T | null> {
+        const response = await this.execute<T>();
+
+        if (!response.records || response.records.length === 0) {
+            return null;
+        }
+
+        // Sort by metadata timestamp (updatedAt first, then createdAt) descending
+        const sortedRecords = [...response.records].sort((a: any, b: any) => {
+            const getTimestamp = (record: any): string | null => {
+                return record.updatedAt || record.updated_at ||
+                       record.createdAt || record.created_at || null;
+            };
+
+            const tsA = getTimestamp(a);
+            const tsB = getTimestamp(b);
+
+            // Sort descending (latest first)
+            if (tsB && tsA) return tsB.localeCompare(tsA);
+            if (tsB && !tsA) return -1;
+            if (!tsB && tsA) return 1;
+            return 0;
+        });
+
+        return sortedRecords[0] as T;
+    }
+
+    // ===== AGGREGATION METHODS =====
+    // These methods execute server-side aggregations via the query builder
+
+    /**
+     * Count the number of records matching the query conditions.
+     * Executes server-side for efficiency.
+     *
+     * @returns Promise resolving to the count of matching records
+     *
+     * @example
+     * ```typescript
+     * const activeUsers = await db.queryBuilder()
+     *   .collection('users')
+     *   .whereField('active').equals(true)
+     *   .count();
+     * ```
+     */
+    async count(): Promise<number> {
+        const response = await this.execute();
+        return response.records?.length || 0;
+    }
+
+    /**
+     * Sum values of a numeric field for records matching the query.
+     *
+     * @param field - The field name to sum
+     * @returns Promise resolving to the sum
+     *
+     * @example
+     * ```typescript
+     * const totalRevenue = await db.queryBuilder()
+     *   .collection('orders')
+     *   .whereField('status').equals('completed')
+     *   .sumBy('amount');
+     * ```
+     */
+    async sumBy(field: string): Promise<number> {
+        const response = await this.execute();
+        if (!response.records) return 0;
+
+        return response.records.reduce((sum: number, record: any) => {
+            const value = record[field];
+            return sum + (typeof value === 'number' ? value : 0);
+        }, 0);
+    }
+
+    /**
+     * Calculate average of a numeric field for records matching the query.
+     *
+     * @param field - The field name to average
+     * @returns Promise resolving to the average (or 0 if no records)
+     *
+     * @example
+     * ```typescript
+     * const avgPrice = await db.queryBuilder()
+     *   .collection('products')
+     *   .whereField('category').equals('electronics')
+     *   .avgBy('price');
+     * ```
+     */
+    async avgBy(field: string): Promise<number> {
+        const response = await this.execute();
+        if (!response.records || response.records.length === 0) return 0;
+
+        const sum = response.records.reduce((total: number, record: any) => {
+            const value = record[field];
+            return total + (typeof value === 'number' ? value : 0);
+        }, 0);
+
+        return sum / response.records.length;
+    }
+
+    /**
+     * Find maximum value of a field for records matching the query.
+     *
+     * @param field - The field name to find maximum
+     * @returns Promise resolving to the maximum value or null if no records
+     *
+     * @example
+     * ```typescript
+     * const highestPrice = await db.queryBuilder()
+     *   .collection('products')
+     *   .maxBy('price');
+     * ```
+     */
+    async maxBy<T = any>(field: string): Promise<T | null> {
+        const response = await this.execute();
+        if (!response.records || response.records.length === 0) return null;
+
+        return response.records.reduce((max: any, record: any) => {
+            const value = record[field];
+            if (max === null) return value;
+            return value > max ? value : max;
+        }, null);
+    }
+
+    /**
+     * Find minimum value of a field for records matching the query.
+     *
+     * @param field - The field name to find minimum
+     * @returns Promise resolving to the minimum value or null if no records
+     *
+     * @example
+     * ```typescript
+     * const lowestPrice = await db.queryBuilder()
+     *   .collection('products')
+     *   .minBy('price');
+     * ```
+     */
+    async minBy<T = any>(field: string): Promise<T | null> {
+        const response = await this.execute();
+        if (!response.records || response.records.length === 0) return null;
+
+        return response.records.reduce((min: any, record: any) => {
+            const value = record[field];
+            if (min === null) return value;
+            return value < min ? value : min;
+        }, null);
+    }
+
+    /**
+     * Get distinct values of a field for records matching the query.
+     *
+     * @param field - The field name to get distinct values
+     * @returns Promise resolving to array of distinct values
+     *
+     * @example
+     * ```typescript
+     * const categories = await db.queryBuilder()
+     *   .collection('products')
+     *   .distinctBy('category');
+     * ```
+     */
+    async distinctBy<T = any>(field: string): Promise<T[]> {
+        const response = await this.execute();
+        if (!response.records) return [];
+
+        const uniqueValues = new Set<T>();
+        for (const record of response.records) {
+            const value = (record as any)[field];
+            if (value !== undefined && value !== null) {
+                uniqueValues.add(value);
+            }
+        }
+
+        return Array.from(uniqueValues);
+    }
+
+    /**
+     * Count distinct values of a field for records matching the query.
+     *
+     * @param field - The field name to count distinct values
+     * @returns Promise resolving to the count of distinct values
+     *
+     * @example
+     * ```typescript
+     * const uniqueCategories = await db.queryBuilder()
+     *   .collection('products')
+     *   .countDistinct('category');
+     * ```
+     */
+    async countDistinct(field: string): Promise<number> {
+        const distinctValues = await this.distinctBy(field);
+        return distinctValues.length;
+    }
+
+    /**
+     * Start a grouped aggregation query.
+     * Returns a GroupByBuilder for specifying the aggregation operation.
+     *
+     * @param field - The field name to group by
+     * @returns GroupByQueryBuilder for chaining aggregation methods
+     *
+     * @example
+     * ```typescript
+     * const salesByCategory = await db.queryBuilder()
+     *   .collection('orders')
+     *   .groupBy('category')
+     *   .sumBy('amount');
+     *
+     * // Returns: { "electronics": 5000, "clothing": 3000, ... }
+     * ```
+     */
+    groupBy(field: string): GroupByQueryBuilder {
+        return new GroupByQueryBuilder(this, field);
+    }
+
+    // Execute query with payment proof (for paid queries)
+    async executeWithPayment<T extends Record<string, any>>(
+        quoteId: string,
+        paymentProof: string,
+        network?: string  // Optional network selection
+    ): Promise<QueryResponse<T>> {
+        if (!this.httpClient) {
+            throw new Error('HTTP client is required for query execution');
+        }
+        if (!this.serverUrl) {
+            throw new Error('Server URL is required for query execution');
+        }
+
+        // Create x402 payment payload using proper types
+        const x402Payload = {
+            x402Version: 1 as const,
+            scheme: 'exact' as const,
+            network: network || 'mocha-4',
+            quoteId: quoteId,
+            payload: {
+                txHash: paymentProof.toLowerCase(),
+                sender: 'unknown', // Will be extracted from tx by backend
+                timestamp: Math.floor(Date.now() / 1000)
+            }
+        };
+
+        // Encode using x402 utility
+        const encodedPayment = encodePaymentHeader(x402Payload);
+
+        const request = this.getQueryRequest();
+
+        try {
+            const response = await this.httpClient.post(
+                `${this.serverUrl}/list`,
+                request,
+                {
+                    'Content-Type': 'application/json',
+                    'X-PAYMENT': encodedPayment  // NEW: x402 header
+                }
+            );
+
+            // Log X-PAYMENT-RESPONSE header if present
+            if (response?.headers && response.headers['x-payment-response']) {
+                console.log('✅ Payment confirmed:', JSON.parse(response.headers['x-payment-response']));
+            }
+
+            return response?.data as QueryResponse<T> || {
+                records: [],
+                total: 0,
+                page: 0,
+                limit: 0
+            } as QueryResponse<T>;
+        } catch (error) {
+            throw new Error(`Paid query execution failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+
+    getQueryRequest(): QueryRequest {
+        const queryValue = this.buildQueryValue();
+
+        return {
+            ...queryValue,
+            limit: this.limitValue,
+            offset: this.offsetValue,
+            sortBy: this.sortBy,
+            root: `${this.app}::${this.collectionName}`
+        };
+    }
+
+    // Check if the query is valid (has required components)
+    isValid(): boolean {
+        // A query is valid if it has either find conditions or selections
+        return this.findConditions !== undefined || this.selections !== undefined;
+    }
+
+    // Build raw query JSON (useful for debugging)
+    buildRawQuery(): QueryRequest {
+        return {
+            ...this.buildQueryValue(),
+            limit: this.limitValue,
+            offset: this.offsetValue,
+            sortBy: this.sortBy
+        };
+    }
+
+    // Clone the query builder
+    clone(): QueryBuilder {
+        const cloned = new QueryBuilder(this.httpClient, this.serverUrl, this.app);
+        cloned.findConditions = this.findConditions;
+        cloned.selections = this.selections ? {...this.selections} : undefined;
+        cloned.fieldMap = this.fieldMap ? {...this.fieldMap} : undefined;
+        cloned.limitValue = this.limitValue;
+        cloned.offsetValue = this.offsetValue;
+        cloned.sortBy = this.sortBy;
+        cloned.includeHistoryValue = this.includeHistoryValue;
+        cloned.collectionName = this.collectionName;
+        cloned.serverJoinConfigs = [...this.serverJoinConfigs]; // Deep copy server join configs
+        cloned.joinConfigs = [...this.joinConfigs]; // Deep copy client join configs (deprecated)
+        return cloned;
+    }
+
+    // Internal method to add a server join config (used by JoinBuilder)
+    _addServerJoin(config: ServerJoinConfig): void {
+        this.serverJoinConfigs.push(config);
+    }
+
+    // Execute a simple query without joins
+    private async executeSimpleQuery<T extends Record<string, any>>(): Promise<QueryResponse<T>> {
+        const request = this.getQueryRequest();
+
+        try {
+            const response = await this.httpClient!.post(
+                `${this.serverUrl}/list`,
+                request,
+                {'Content-Type': 'application/json'}
+            );
+
+            // x402: Check for 402 Payment Required
+            if (response?.status === 402 && response?.data) {
+                const x402Response = response.data as X402PaymentRequiredResponse;
+                const requirement = x402Response.accepts?.[0];
+                if (requirement) {
+                    const quote = requirementToQuote(requirement, x402Response.accepts);
+                    throw new PaymentRequiredError('Payment required for this query', quote);
+                }
+            }
+
+            // Normal response with records
+            return response?.data as QueryResponse<T> || {
+                records: [],
+                limit: 0,
+                page: 0,
+                total: 0,
+            } as QueryResponse<T>;
+        } catch (error: any) {
+            // Re-throw PaymentRequiredError as-is
+            if (error instanceof PaymentRequiredError) {
+                throw error;
+            }
+            const response = (error as AxiosError)?.response;
+            if (response?.status === 402 && response?.data) {
+                const x402Response = response.data as X402PaymentRequiredResponse;
+                const requirement = x402Response.accepts?.[0];
+                if (requirement) {
+                    const quote = requirementToQuote(requirement, x402Response.accepts);
+                    throw new PaymentRequiredError('Payment required for this query', quote);
+                }
+            }
+            throw new Error(`Query execution failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+
+    // Execute query with joins using parallel queries
+    private async executeWithJoins<T extends Record<string, any>>(): Promise<QueryResponse<T>> {
+        // First, get the main collection records
+        const mainQuery = this.clone();
+        mainQuery.joinConfigs = []; // Remove joins for main query
+        const mainResults = await mainQuery.executeSimpleQuery();
+
+        if (mainResults.records.length === 0) {
+            return mainResults as QueryResponse<T>;
+        }
+
+        // For each join, execute parallel queries and merge results
+        const joinResults: Record<string, any[]> = {};
+
+        for (const joinConfig of this.joinConfigs) {
+            // Get all unique values from the main results for the join key
+            const joinKeys = [...new Set(
+                mainResults.records
+                    .map(record => record[joinConfig.childField])
+                    .filter(key => key !== null && key !== undefined)
+            )];
+
+            if (joinKeys.length > 0) {
+                // Query the joined collection
+                const joinQuery = new QueryBuilder(this.httpClient, this.serverUrl, this.app);
+                const joinResponse = await joinQuery
+                    .collection(joinConfig.parentCollection)
+                    .whereField(joinConfig.parentField).in(joinKeys)
+                    .selectAll()
+                    .executeSimpleQuery();
+
+                joinResults[joinConfig.alias] = joinResponse.records;
+            } else {
+                joinResults[joinConfig.alias] = [];
+            }
+        }
+
+        // Merge join results with main results
+        const mergedRecords = mainResults.records.map(mainRecord => {
+            const merged: any = {...mainRecord};
+
+            for (const joinConfig of this.joinConfigs) {
+                const joinKey = mainRecord[joinConfig.childField];
+                const relatedRecords = joinResults[joinConfig.alias].filter(
+                    joinRecord => joinRecord[joinConfig.parentField] === joinKey
+                );
+
+                // For one-to-many relationships, return array; for many-to-one, return single object
+                if (joinConfig.parentCollection === this.collectionName) {
+                    // Self-referential join (like replies to tweets)
+                    merged[joinConfig.alias] = relatedRecords;
+                } else {
+                    // Cross-collection join
+                    merged[joinConfig.alias] = relatedRecords.length > 0 ? relatedRecords[0] : null;
+                }
+            }
+
+            return merged;
+        });
+
+        return {
+            records: mergedRecords,
+            limit: mainResults.limit,
+            page: mainResults.page,
+            total: mainResults.total
+        } as QueryResponse<T>;
+    }
+
+    // Build the query value object for HTTP requests
+    private buildQueryValue(): QueryValue {
+        let find = this.findConditions ? this.findConditions.toComposable() : {};
+        const select = this.selections || SelectionBuilder.all();
+
+        // Add server-side JOINs to the find conditions
+        // JOINs are just additional fields in the find map, they should NOT be wrapped in "and"
+        if (this.serverJoinConfigs.length > 0) {
+            for (const join of this.serverJoinConfigs) {
+                // Scepter JOIN format (untagged enum): { "alias": { "resolve": {...}, "model": "collection", "many": true/false } }
+                // The "join" key is NOT needed because QueryInner::Join uses #[serde(untagged)]
+                const joinConfig: any = {
+                    resolve: join.resolve,
+                    model: join.model
+                };
+
+                // Only include 'many' field if explicitly set
+                if (join.many !== undefined) {
+                    joinConfig.many = join.many;
+                }
+
+                find[join.alias] = joinConfig;
+            }
+        }
+
+        const queryValue: QueryValue = {
+            find,
+            select
+        };
+
+        // Add include_history if explicitly set
+        if (this.includeHistoryValue !== undefined) {
+            queryValue.include_history = this.includeHistoryValue;
+        }
+
+        return queryValue;
+    }
+}
+
+// Helper class for building where clauses with method chaining
+export class WhereClause {
+    constructor(
+        private queryBuilder: QueryBuilder,
+        private fieldName: string
+    ) {
+    }
+
+    equals(value: Val): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).equals(value);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    notEquals(value: Val): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).notEquals(value);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    greaterThan(value: Val): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).greaterThan(value);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    greaterThanOrEqual(value: Val): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).greaterThanOrEqual(value);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    lessThan(value: Val): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).lessThan(value);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    lessThanOrEqual(value: Val): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).lessThanOrEqual(value);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    contains(value: string): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).contains(value);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    startsWith(value: string): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).startsWith(value);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    endsWith(value: string): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).endsWith(value);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    in(values: Val[]): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).in(values);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    notIn(values: Val[]): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).notIn(values);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    exists(): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).exists();
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    notExists(): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).notExists();
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    isNull(): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).isNull();
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    isNotNull(): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).isNotNull();
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    regExpMatches(pattern: string): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).regExpMatches(pattern);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    includesCaseInsensitive(value: string): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).includesCaseInsensitive(value);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    startsWithCaseInsensitive(value: string): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).startsWithCaseInsensitive(value);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    endsWithCaseInsensitive(value: string): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).endsWithCaseInsensitive(value);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    // ===== IP OPERATORS =====
+
+    isLocalIp(): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).isLocalIp();
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    isExternalIp(): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).isExternalIp();
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    // ===== MISC OPERATORS =====
+
+    b64(value: string): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).b64(value);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    inDataset(dataset: string): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).inDataset(dataset);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    inCountry(countryCode: string): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).inCountry(countryCode);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    cidr(cidr: string): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).cidr(cidr);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    // ===== BETWEEN OPERATOR =====
+
+    between(min: any, max: any): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).between(min, max);
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    // ===== CONVENIENCE METHODS =====
+
+    isTrue(): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).isTrue();
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+
+    isFalse(): QueryBuilder {
+        const condition = new FieldConditionBuilder(this.fieldName).isFalse();
+        (this.queryBuilder as any).findConditions = LogicalOperator.Condition(condition);
+        return this.queryBuilder;
+    }
+}
+
+// Fluent builder for constructing server-side JOINs
+export class JoinBuilder<TParent extends QueryBuilder | JoinBuilder<any> = QueryBuilder> {
+    private alias: string;
+    private model: string;
+    private findConditions: any = {};
+    private selections?: SelectionMap;
+    private parentBuilder: TParent;
+    private many?: boolean;  // Explicit control over result type
+    private nestedJoins: ServerJoinConfig[] = [];  // Support nested JOINs
+
+    constructor(parentBuilder: TParent, alias: string, model: string, many?: boolean) {
+        this.parentBuilder = parentBuilder;
+        this.alias = alias;
+        this.model = model;
+        this.many = many;
+    }
+
+    // Add filter conditions for the joined collection
+    on(builderFn: (builder: ConditionBuilder) => LogicalOperator): this {
+        const conditionBuilder = new ConditionBuilder();
+        this.findConditions = builderFn(conditionBuilder).toComposable();
+        return this;
+    }
+
+    // Add a simple equality condition (most common case)
+    onField(fieldName: string): JoinWhereClause<TParent> {
+        return new JoinWhereClause(this, fieldName);
+    }
+
+    // Select specific fields from the joined collection
+    selecting(builderFn: (builder: SelectionBuilder) => SelectionBuilder): this {
+        const selectionBuilder = new SelectionBuilder();
+        builderFn(selectionBuilder);
+        this.selections = selectionBuilder.build();
+        return this;
+    }
+
+    // Select specific fields by name
+    selectFields(fields: string[]): this {
+        const selectionBuilder = new SelectionBuilder();
+        selectionBuilder.fields(fields);
+        this.selections = selectionBuilder.build();
+        return this;
+    }
+
+    // Select all fields from joined collection
+    selectAll(): this {
+        this.selections = SelectionBuilder.all();
+        return this;
+    }
+
+    // Nested JOIN: one-to-one relationship within this JOIN
+    joinOne(alias: string, model: string): JoinBuilder<this> {
+        return new JoinBuilder(this, alias, model, false);
+    }
+
+    // Nested JOIN: one-to-many relationship within this JOIN
+    joinMany(alias: string, model: string): JoinBuilder<this> {
+        return new JoinBuilder(this, alias, model, true);
+    }
+
+    // Complete the JOIN and return to the parent builder
+    // Returns the parent builder's type (JoinBuilder for nested JOINs, QueryBuilder for top-level)
+    build(): TParent {
+        const joinConfig: ServerJoinConfig = {
+            alias: this.alias,
+            model: this.model,
+            many: this.many,
+            resolve: {
+                find: this.buildFindWithNestedJoins(),
+                select: this.selections || SelectionBuilder.all()
+            }
+        };
+
+        this.parentBuilder._addServerJoin(joinConfig);
+        return this.parentBuilder;
+    }
+
+    // Build find conditions with nested JOINs embedded
+    private buildFindWithNestedJoins(): any {
+        // Start with existing find conditions
+        const find = Object.keys(this.findConditions).length > 0 ? {...this.findConditions} : {};
+
+        // Add nested JOINs to the find map
+        if (this.nestedJoins.length > 0) {
+            for (const nestedJoin of this.nestedJoins) {
+                const joinConfig: any = {
+                    resolve: nestedJoin.resolve,
+                    model: nestedJoin.model
+                };
+
+                if (nestedJoin.many !== undefined) {
+                    joinConfig.many = nestedJoin.many;
+                }
+
+                find[nestedJoin.alias] = joinConfig;
+            }
+        }
+
+        return Object.keys(find).length > 0 ? find : undefined;
+    }
+
+    // Internal method to set find conditions (used by JoinWhereClause)
+    _setFindConditions(conditions: any): void {
+        this.findConditions = conditions;
+    }
+
+    // Internal method to add nested joins (used by nested JoinBuilder)
+    _addServerJoin(config: ServerJoinConfig): void {
+        this.nestedJoins.push(config);
+    }
+}
+
+// Helper class for building WHERE clauses in JOINs
+export class JoinWhereClause<TParent extends QueryBuilder | JoinBuilder<any> = QueryBuilder> {
+    constructor(
+        private joinBuilder: JoinBuilder<TParent>,
+        private fieldName: string
+    ) {
+    }
+
+    equals(value: Val): JoinBuilder<TParent> {
+        const condition = new FieldConditionBuilder(this.fieldName).equals(value);
+        this.joinBuilder._setFindConditions(LogicalOperator.Condition(condition).toComposable());
+        return this.joinBuilder;
+    }
+
+    in(values: Val[]): JoinBuilder<TParent> {
+        const condition = new FieldConditionBuilder(this.fieldName).in(values);
+        this.joinBuilder._setFindConditions(LogicalOperator.Condition(condition).toComposable());
+        return this.joinBuilder;
+    }
+
+    greaterThan(value: Val): JoinBuilder<TParent> {
+        const condition = new FieldConditionBuilder(this.fieldName).greaterThan(value);
+        this.joinBuilder._setFindConditions(LogicalOperator.Condition(condition).toComposable());
+        return this.joinBuilder;
+    }
+
+    lessThan(value: Val): JoinBuilder<TParent> {
+        const condition = new FieldConditionBuilder(this.fieldName).lessThan(value);
+        this.joinBuilder._setFindConditions(LogicalOperator.Condition(condition).toComposable());
+        return this.joinBuilder;
+    }
+
+    isNull(): JoinBuilder<TParent> {
+        const condition = new FieldConditionBuilder(this.fieldName).isNull();
+        this.joinBuilder._setFindConditions(LogicalOperator.Condition(condition).toComposable());
+        return this.joinBuilder;
+    }
+
+    isNotNull(): JoinBuilder<TParent> {
+        const condition = new FieldConditionBuilder(this.fieldName).isNotNull();
+        this.joinBuilder._setFindConditions(LogicalOperator.Condition(condition).toComposable());
+        return this.joinBuilder;
+    }
+}
+
+/**
+ * Builder for grouped aggregation queries.
+ * Allows aggregation operations to be performed on groups of records.
+ *
+ * @example
+ * ```typescript
+ * // Count users by country
+ * const usersByCountry = await db.queryBuilder()
+ *   .collection('users')
+ *   .groupBy('country')
+ *   .count();
+ *
+ * // Sum order amounts by category
+ * const salesByCategory = await db.queryBuilder()
+ *   .collection('orders')
+ *   .whereField('status').equals('completed')
+ *   .groupBy('category')
+ *   .sumBy('amount');
+ * ```
+ */
+export class GroupByQueryBuilder {
+    constructor(
+        private queryBuilder: QueryBuilder,
+        private groupByField: string
+    ) {}
+
+    /**
+     * Count records in each group
+     * @returns Promise resolving to map of group key -> count
+     */
+    async count(): Promise<Record<string, number>> {
+        const response = await this.queryBuilder.execute();
+        if (!response.records) return {};
+
+        const groups: Record<string, number> = {};
+        for (const record of response.records) {
+            const key = this.getGroupKey(record);
+            groups[key] = (groups[key] || 0) + 1;
+        }
+        return groups;
+    }
+
+    /**
+     * Sum a numeric field within each group
+     * @param field - The field name to sum
+     * @returns Promise resolving to map of group key -> sum
+     */
+    async sumBy(field: string): Promise<Record<string, number>> {
+        const response = await this.queryBuilder.execute();
+        if (!response.records) return {};
+
+        const groups: Record<string, number> = {};
+        for (const record of response.records) {
+            const key = this.getGroupKey(record);
+            const value = (record as any)[field];
+            groups[key] = (groups[key] || 0) + (typeof value === 'number' ? value : 0);
+        }
+        return groups;
+    }
+
+    /**
+     * Calculate average of a numeric field within each group
+     * @param field - The field name to average
+     * @returns Promise resolving to map of group key -> average
+     */
+    async avgBy(field: string): Promise<Record<string, number>> {
+        const response = await this.queryBuilder.execute();
+        if (!response.records) return {};
+
+        const groups: Record<string, { sum: number; count: number }> = {};
+        for (const record of response.records) {
+            const key = this.getGroupKey(record);
+            const value = (record as any)[field];
+            if (!groups[key]) {
+                groups[key] = { sum: 0, count: 0 };
+            }
+            groups[key].sum += typeof value === 'number' ? value : 0;
+            groups[key].count += 1;
+        }
+
+        const result: Record<string, number> = {};
+        for (const [key, { sum, count }] of Object.entries(groups)) {
+            result[key] = count > 0 ? sum / count : 0;
+        }
+        return result;
+    }
+
+    /**
+     * Find maximum value of a field within each group
+     * @param field - The field name to find maximum
+     * @returns Promise resolving to map of group key -> max value
+     */
+    async maxBy<T = any>(field: string): Promise<Record<string, T>> {
+        const response = await this.queryBuilder.execute();
+        if (!response.records) return {};
+
+        const groups: Record<string, T> = {};
+        for (const record of response.records) {
+            const key = this.getGroupKey(record);
+            const value = (record as any)[field] as T;
+            if (!(key in groups) || value > (groups[key] as T)) {
+                groups[key] = value;
+            }
+        }
+        return groups;
+    }
+
+    /**
+     * Find minimum value of a field within each group
+     * @param field - The field name to find minimum
+     * @returns Promise resolving to map of group key -> min value
+     */
+    async minBy<T = any>(field: string): Promise<Record<string, T>> {
+        const response = await this.queryBuilder.execute();
+        if (!response.records) return {};
+
+        const groups: Record<string, T> = {};
+        for (const record of response.records) {
+            const key = this.getGroupKey(record);
+            const value = (record as any)[field] as T;
+            if (!(key in groups) || value < (groups[key] as T)) {
+                groups[key] = value;
+            }
+        }
+        return groups;
+    }
+
+    /**
+     * Get the group key from a record, supporting nested field paths
+     */
+    private getGroupKey(record: any): string {
+        // Support nested field paths (e.g., "user.country")
+        if (this.groupByField.includes('.')) {
+            const parts = this.groupByField.split('.');
+            let current = record;
+            for (const part of parts) {
+                current = current?.[part];
+            }
+            return String(current ?? 'null');
+        }
+        return String(record[this.groupByField] ?? 'null');
+    }
+}