Extract query-specific logic into query module (FilterTranslator, QueryBuilder)

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/foundation/core/src/index.ts

@@ -20,6 +20,9 @@ export * from './plugin';
 export * from './validator-plugin';
 export * from './formula-plugin';
 
+// Export query-specific modules (ObjectQL core competency)
+export * from './query';
+
 export * from './action';
 export * from './hook';
 export * from './object';

packages/foundation/core/src/query/filter-translator.ts

@@ -0,0 +1,143 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type { Filter } from '@objectql/types';
+import type { FilterNode } from '@objectstack/spec';
+
+/**
+ * Filter Translator
+ * 
+ * Translates ObjectQL Filter (FilterCondition) to ObjectStack FilterNode format.
+ * Converts modern object-based syntax to legacy array-based syntax for backward compatibility.
+ * 
+ * @example
+ * Input:  { age: { $gte: 18 }, $or: [{ status: "active" }, { role: "admin" }] }
+ * Output: [["age", ">=", 18], "or", [["status", "=", "active"], "or", ["role", "=", "admin"]]]
+ */
+export class FilterTranslator {
+    /**
+     * Translate filters from ObjectQL format to ObjectStack FilterNode format
+     */
+    translate(filters?: Filter): FilterNode | undefined {
+        if (!filters) {
+            return undefined;
+        }
+
+        // Backward compatibility: if it's already an array (old format), pass through
+        if (Array.isArray(filters)) {
+            return filters as unknown as FilterNode;
+        }
+
+        // If it's an empty object, return undefined
+        if (typeof filters === 'object' && Object.keys(filters).length === 0) {
+            return undefined;
+        }
+
+        return this.convertToNode(filters);
+    }
+
+    /**
+     * Recursively converts FilterCondition to FilterNode array format
+     */
+    private convertToNode(filter: Filter): FilterNode {
+        const nodes: any[] = [];
+        
+        // Process logical operators first
+        if (filter.$and) {
+            const andNodes = filter.$and.map(f => this.convertToNode(f));
+            nodes.push(...this.interleaveWithOperator(andNodes, 'and'));
+        }
+        
+        if (filter.$or) {
+            const orNodes = filter.$or.map(f => this.convertToNode(f));
+            if (nodes.length > 0) {
+                nodes.push('and');
+            }
+            nodes.push(...this.interleaveWithOperator(orNodes, 'or'));
+        }
+        
+        // Note: $not operator is not currently supported in the legacy FilterNode format
+        if (filter.$not) {
+            throw new Error('$not operator is not supported. Use $ne for field negation instead.');
+        }
+        
+        // Process field conditions
+        for (const [field, value] of Object.entries(filter)) {
+            if (field.startsWith('$')) {
+                continue; // Skip logical operators (already processed)
+            }
+            
+            if (nodes.length > 0) {
+                nodes.push('and');
+            }
+            
+            // Handle field value
+            if (value === null || value === undefined) {
+                nodes.push([field, '=', value]);
+            } else if (typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
+                // Explicit operators - multiple operators on same field are AND-ed together
+                const entries = Object.entries(value);
+                for (let i = 0; i < entries.length; i++) {
+                    const [op, opValue] = entries[i];
+                    
+                    // Add 'and' before each operator (except the very first node)
+                    if (nodes.length > 0 || i > 0) {
+                        nodes.push('and');
+                    }
+                    
+                    const legacyOp = this.mapOperatorToLegacy(op);
+                    nodes.push([field, legacyOp, opValue]);
+                }
+            } else {
+                // Implicit equality
+                nodes.push([field, '=', value]);
+            }
+        }
+        
+        // Return as FilterNode (type assertion for backward compatibility)
+        return (nodes.length === 1 ? nodes[0] : nodes) as unknown as FilterNode;
+    }
+    
+    /**
+     * Interleaves filter nodes with a logical operator
+     */
+    private interleaveWithOperator(nodes: FilterNode[], operator: string): any[] {
+        if (nodes.length === 0) return [];
+        if (nodes.length === 1) return [nodes[0]];
+        
+        const result: any[] = [nodes[0]];
+        for (let i = 1; i < nodes.length; i++) {
+            result.push(operator, nodes[i]);
+        }
+        return result;
+    }
+    
+    /**
+     * Maps modern $-prefixed operators to legacy format
+     */
+    private mapOperatorToLegacy(operator: string): string {
+        const mapping: Record<string, string> = {
+            '$eq': '=',
+            '$ne': '!=',
+            '$gt': '>',
+            '$gte': '>=',
+            '$lt': '<',
+            '$lte': '<=',
+            '$in': 'in',
+            '$nin': 'nin',
+            '$contains': 'contains',
+            '$startsWith': 'startswith',
+            '$endsWith': 'endswith',
+            '$null': 'is_null',
+            '$exist': 'is_not_null',
+            '$between': 'between',
+        };
+        
+        return mapping[operator] || operator.replace('$', '');
+    }
+}

packages/foundation/core/src/query/index.ts

@@ -0,0 +1,20 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Query Module
+ * 
+ * This module contains ObjectQL's query-specific functionality:
+ * - FilterTranslator: Converts ObjectQL filters to ObjectStack FilterNode
+ * - QueryBuilder: Builds ObjectStack QueryAST from ObjectQL UnifiedQuery
+ * 
+ * These are the core components that differentiate ObjectQL from generic runtime systems.
+ */
+
+export * from './filter-translator';
+export * from './query-builder';

packages/foundation/core/src/query/query-builder.ts

@@ -0,0 +1,80 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type { UnifiedQuery } from '@objectql/types';
+import type { QueryAST } from '@objectstack/spec';
+import { FilterTranslator } from './filter-translator';
+
+/**
+ * Query Builder
+ * 
+ * Builds ObjectStack QueryAST from ObjectQL UnifiedQuery.
+ * This is the central query construction module for ObjectQL.
+ */
+export class QueryBuilder {
+    private filterTranslator: FilterTranslator;
+
+    constructor() {
+        this.filterTranslator = new FilterTranslator();
+    }
+
+    /**
+     * Build a QueryAST from a UnifiedQuery
+     * 
+     * @param objectName - Target object name
+     * @param query - ObjectQL UnifiedQuery
+     * @returns ObjectStack QueryAST
+     */
+    build(objectName: string, query: UnifiedQuery): QueryAST {
+        const ast: QueryAST = {
+            object: objectName,
+        };
+
+        // Map fields
+        if (query.fields) {
+            ast.fields = query.fields;
+        }
+
+        // Map filters using FilterTranslator
+        if (query.filters) {
+            ast.filters = this.filterTranslator.translate(query.filters);
+        }
+
+        // Map sort
+        if (query.sort) {
+            ast.sort = query.sort.map(([field, order]) => ({
+                field,
+                order: order as 'asc' | 'desc'
+            }));
+        }
+
+        // Map pagination
+        if (query.limit !== undefined) {
+            ast.top = query.limit;
+        }
+        if (query.skip !== undefined) {
+            ast.skip = query.skip;
+        }
+
+        // Map groupBy
+        if (query.groupBy) {
+            ast.groupBy = query.groupBy;
+        }
+
+        // Map aggregations
+        if (query.aggregate) {
+            ast.aggregations = query.aggregate.map(agg => ({
+                function: agg.func as any,
+                field: agg.field,
+                alias: agg.alias || `${agg.func}_${agg.field}`
+            }));
+        }
+
+        return ast;
+    }
+}