@objectql/core 3.0.0 → 4.0.0

package/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;
+    }
+}

package/src/query/query-service.ts

@@ -0,0 +1,392 @@
+/**
+ * ObjectQL Query Service
+ * 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 { 
+    Driver, 
+    ObjectConfig, 
+    UnifiedQuery, 
+    Filter,
+    MetadataRegistry
+} from '@objectql/types';
+import type { QueryAST } from '@objectstack/spec';
+import { QueryBuilder } from './query-builder';
+
+/**
+ * Options for query execution
+ */
+export interface QueryOptions {
+    /**
+     * Transaction handle for transactional queries
+     */
+    transaction?: any;
+    
+    /**
+     * Skip validation (for system operations)
+     */
+    skipValidation?: boolean;
+    
+    /**
+     * Include profiling information
+     */
+    profile?: boolean;
+    
+    /**
+     * Custom driver options
+     */
+    driverOptions?: Record<string, unknown>;
+}
+
+/**
+ * Result of a query execution with optional profiling data
+ */
+export interface QueryResult<T = any> {
+    /**
+     * The query results
+     */
+    value: T;
+    
+    /**
+     * Total count (for paginated queries)
+     */
+    count?: number;
+    
+    /**
+     * Profiling information (if profile option was enabled)
+     */
+    profile?: QueryProfile;
+}
+
+/**
+ * Profiling information for a query
+ */
+export interface QueryProfile {
+    /**
+     * Execution time in milliseconds
+     */
+    executionTime: number;
+    
+    /**
+     * Number of rows scanned
+     */
+    rowsScanned?: number;
+    
+    /**
+     * Whether an index was used
+     */
+    indexUsed?: boolean;
+    
+    /**
+     * The generated QueryAST
+     */
+    ast?: QueryAST;
+}
+
+/**
+ * Query Service
+ * 
+ * Handles all query execution logic, separating query concerns from
+ * the repository pattern. This service is responsible for:
+ * - Building QueryAST from UnifiedQuery
+ * - Executing queries via drivers
+ * - Optional query profiling and analysis
+ * 
+ * The QueryService is registered as a service in the ObjectQLPlugin
+ * and can be used by Repository for all read operations.
+ */
+export class QueryService {
+    private queryBuilder: QueryBuilder;
+    
+    constructor(
+        private datasources: Record<string, Driver>,
+        private metadata: MetadataRegistry
+    ) {
+        this.queryBuilder = new QueryBuilder();
+    }
+    
+    /**
+     * Get the driver for a specific object
+     * @private
+     */
+    private getDriver(objectName: string): Driver {
+        const obj = this.getSchema(objectName);
+        const datasourceName = obj.datasource || 'default';
+        const driver = this.datasources[datasourceName];
+        
+        if (!driver) {
+            throw new Error(`Datasource '${datasourceName}' not found for object '${objectName}'`);
+        }
+        
+        return driver;
+    }
+    
+    /**
+     * Get the schema for an object
+     * @private
+     */
+    private getSchema(objectName: string): ObjectConfig {
+        const obj = this.metadata.get<ObjectConfig>('object', objectName);
+        if (!obj) {
+            throw new Error(`Object '${objectName}' not found in metadata`);
+        }
+        return obj;
+    }
+    
+    /**
+     * Build QueryAST from UnifiedQuery
+     * @private
+     */
+    private buildQueryAST(objectName: string, query: UnifiedQuery): QueryAST {
+        return this.queryBuilder.build(objectName, query);
+    }
+    
+    /**
+     * Execute a find query
+     * 
+     * @param objectName - The object to query
+     * @param query - The unified query
+     * @param options - Query execution options
+     * @returns Array of matching records
+     */
+    async find(
+        objectName: string, 
+        query: UnifiedQuery = {}, 
+        options: QueryOptions = {}
+    ): Promise<QueryResult<any[]>> {
+        const driver = this.getDriver(objectName);
+        const startTime = options.profile ? Date.now() : 0;
+        
+        // Build QueryAST
+        const ast = this.buildQueryAST(objectName, query);
+        
+        // Execute query via driver
+        const driverOptions = {
+            transaction: options.transaction,
+            ...options.driverOptions
+        };
+        
+        let results: any[];
+        let count: number | undefined;
+        
+        if (driver.find) {
+            // Legacy driver interface
+            const result: any = await driver.find(objectName, query, driverOptions);
+            results = Array.isArray(result) ? result : (result?.value || []);
+            count = (typeof result === 'object' && !Array.isArray(result) && result?.count !== undefined) ? result.count : undefined;
+        } else if (driver.executeQuery) {
+            // New DriverInterface
+            const result = await driver.executeQuery(ast, driverOptions);
+            results = result.value || [];
+            count = result.count;
+        } else {
+            throw new Error(`Driver does not support query execution`);
+        }
+        
+        const executionTime = options.profile ? Date.now() - startTime : 0;
+        
+        return {
+            value: results,
+            count,
+            profile: options.profile ? {
+                executionTime,
+                ast,
+                rowsScanned: results.length,
+            } : undefined
+        };
+    }
+    
+    /**
+     * Execute a findOne query by ID
+     * 
+     * @param objectName - The object to query
+     * @param id - The record ID
+     * @param options - Query execution options
+     * @returns The matching record or undefined
+     */
+    async findOne(
+        objectName: string, 
+        id: string | number, 
+        options: QueryOptions = {}
+    ): Promise<QueryResult<any>> {
+        const driver = this.getDriver(objectName);
+        const startTime = options.profile ? Date.now() : 0;
+        
+        const driverOptions = {
+            transaction: options.transaction,
+            ...options.driverOptions
+        };
+        
+        let result: any;
+        
+        if (driver.findOne) {
+            // Legacy driver interface
+            result = await driver.findOne(objectName, id, driverOptions);
+        } else if (driver.get) {
+            // Alternative method name
+            result = await driver.get(objectName, String(id), driverOptions);
+        } else if (driver.executeQuery) {
+            // Fallback to query with ID filter
+            const query: UnifiedQuery = {
+                filters: [['_id', '=', id]]
+            };
+            const ast = this.buildQueryAST(objectName, query);
+            const queryResult = await driver.executeQuery(ast, driverOptions);
+            result = queryResult.value?.[0];
+        } else {
+            throw new Error(`Driver does not support findOne operation`);
+        }
+        
+        const executionTime = options.profile ? Date.now() - startTime : 0;
+        
+        return {
+            value: result,
+            profile: options.profile ? {
+                executionTime,
+                rowsScanned: result ? 1 : 0,
+            } : undefined
+        };
+    }
+    
+    /**
+     * Execute a count query
+     * 
+     * @param objectName - The object to query
+     * @param filters - Optional filters
+     * @param options - Query execution options
+     * @returns Count of matching records
+     */
+    async count(
+        objectName: string, 
+        filters?: Filter[], 
+        options: QueryOptions = {}
+    ): Promise<QueryResult<number>> {
+        const driver = this.getDriver(objectName);
+        const startTime = options.profile ? Date.now() : 0;
+        
+        const query: UnifiedQuery = filters ? { filters } : {};
+        const ast = this.buildQueryAST(objectName, query);
+        
+        const driverOptions = {
+            transaction: options.transaction,
+            ...options.driverOptions
+        };
+        
+        let count: number;
+        
+        if (driver.count) {
+            // Legacy driver interface
+            count = await driver.count(objectName, filters || [], driverOptions);
+        } else if (driver.executeQuery) {
+            // Use executeQuery and count results
+            // Note: This is inefficient for large datasets
+            // Ideally, driver should support count-specific optimization
+            const result = await driver.executeQuery(ast, driverOptions);
+            count = result.count ?? result.value?.length ?? 0;
+        } else {
+            throw new Error(`Driver does not support count operation`);
+        }
+        
+        const executionTime = options.profile ? Date.now() - startTime : 0;
+        
+        return {
+            value: count,
+            profile: options.profile ? {
+                executionTime,
+                ast,
+            } : undefined
+        };
+    }
+    
+    /**
+     * Execute an aggregate query
+     * 
+     * @param objectName - The object to query
+     * @param query - The aggregation query using UnifiedQuery format
+     * @param options - Query execution options
+     * @returns Aggregation results
+     */
+    async aggregate(
+        objectName: string, 
+        query: UnifiedQuery, 
+        options: QueryOptions = {}
+    ): Promise<QueryResult<any[]>> {
+        const driver = this.getDriver(objectName);
+        const startTime = options.profile ? Date.now() : 0;
+        
+        const driverOptions = {
+            transaction: options.transaction,
+            ...options.driverOptions
+        };
+        
+        let results: any[];
+        
+        if (driver.aggregate) {
+            // Driver supports aggregation
+            results = await driver.aggregate(objectName, query, driverOptions);
+        } else {
+            // Driver doesn't support aggregation
+            throw new Error(`Driver does not support aggregate operations. Consider using a driver that supports aggregation.`);
+        }
+        
+        const executionTime = options.profile ? Date.now() - startTime : 0;
+        
+        return {
+            value: results,
+            profile: options.profile ? {
+                executionTime,
+                rowsScanned: results.length,
+            } : undefined
+        };
+    }
+    
+    /**
+     * Execute a direct SQL/query passthrough
+     * 
+     * This bypasses ObjectQL's query builder and executes raw queries.
+     * Use with caution as it bypasses security and validation.
+     * 
+     * @param objectName - The object (determines which datasource to use)
+     * @param queryString - Raw query string (SQL, MongoDB query, etc.)
+     * @param params - Query parameters (for parameterized queries)
+     * @param options - Query execution options
+     * @returns Query results
+     */
+    async directQuery(
+        objectName: string,
+        queryString: string,
+        params?: any[],
+        options: QueryOptions = {}
+    ): Promise<QueryResult<any>> {
+        const driver = this.getDriver(objectName);
+        const startTime = options.profile ? Date.now() : 0;
+        
+        const driverOptions = {
+            transaction: options.transaction,
+            ...options.driverOptions
+        };
+        
+        let results: any;
+        
+        if (driver.directQuery) {
+            results = await driver.directQuery(queryString, params);
+        } else if (driver.query) {
+            // Alternative method name
+            results = await driver.query(queryString, params);
+        } else {
+            throw new Error(`Driver does not support direct query execution`);
+        }
+        
+        const executionTime = options.profile ? Date.now() - startTime : 0;
+        
+        return {
+            value: results,
+            profile: options.profile ? {
+                executionTime,
+            } : undefined
+        };
+    }
+}

package/src/repository.ts

@@ -1,18 +1,62 @@
-import { ObjectQLContext, IObjectQL, ObjectConfig, Driver, UnifiedQuery, ActionContext, HookAPI, RetrievalHookContext, MutationHookContext, UpdateHookContext, ValidationContext, ValidationError, ValidationRuleResult, FormulaContext } from '@objectql/types';
+/**
+ * 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 { ObjectQLContext, IObjectQL, ObjectConfig, Driver, UnifiedQuery, ActionContext, HookAPI, RetrievalHookContext, MutationHookContext, UpdateHookContext, ValidationContext, ValidationError, ValidationRuleResult, FormulaContext, Filter } from '@objectql/types';
+import type { ObjectStackKernel } from '@objectstack/runtime';
+import type { QueryAST, FilterNode, SortNode } from '@objectstack/spec';
 import { Validator } from './validator';
 import { FormulaEngine } from './formula-engine';
+import { QueryBuilder } from './query';
+
+/**
+ * Extended ObjectStack Kernel with optional ObjectQL plugin capabilities.
+ * These properties are attached by ValidatorPlugin and FormulaPlugin during installation.
+ */
+interface ExtendedKernel extends ObjectStackKernel {
+    validator?: Validator;
+    formulaEngine?: FormulaEngine;
+}
 
 export class ObjectRepository {
-    private validator: Validator;
-    private formulaEngine: FormulaEngine;
+    private queryBuilder: QueryBuilder;
 
     constructor(
         private objectName: string,
         private context: ObjectQLContext,
         private app: IObjectQL
     ) {
-        this.validator = new Validator();
-        this.formulaEngine = new FormulaEngine();
+        this.queryBuilder = new QueryBuilder();
+    }
+    
+    /**
+     * Get validator instance from kernel (via plugin)
+     * Falls back to creating a new instance if not available
+     */
+    private getValidator(): Validator {
+        const kernel = this.getKernel() as ExtendedKernel;
+        if (kernel.validator) {
+            return kernel.validator;
+        }
+        // Fallback for backward compatibility
+        return new Validator();
+    }
+    
+    /**
+     * Get formula engine instance from kernel (via plugin)
+     * Falls back to creating a new instance if not available
+     */
+    private getFormulaEngine(): FormulaEngine {
+        const kernel = this.getKernel() as ExtendedKernel;
+        if (kernel.formulaEngine) {
+            return kernel.formulaEngine;
+        }
+        // Fallback for backward compatibility
+        return new FormulaEngine();
     }
 
     private getDriver(): Driver {
@@ -21,13 +65,24 @@ export class ObjectRepository {
         return this.app.datasource(datasourceName);
     }
     
-    private getOptions(extra: any = {}) {
+    private getKernel(): ObjectStackKernel {
+        return this.app.getKernel();
+    }
+
+    private getOptions(extra: Record<string, unknown> = {}) {
         return {
             transaction: this.context.transactionHandle,
             ...extra
         };
     }
 
+    /**
+     * Translates ObjectQL UnifiedQuery to ObjectStack QueryAST format
+     */
+    private buildQueryAST(query: UnifiedQuery): QueryAST {
+        return this.queryBuilder.build(this.objectName, query);
+    }
+
     getSchema(): ObjectConfig {
         const obj = this.app.getObject(this.objectName);
         if (!obj) {
@@ -82,7 +137,7 @@ export class ObjectRepository {
             }
             
             const value = record[fieldName];
-            const fieldResults = await this.validator.validateField(
+            const fieldResults = await this.getValidator().validateField(
                 fieldName,
                 fieldConfig,
                 value,
@@ -121,7 +176,7 @@ export class ObjectRepository {
                 changedFields,
             };
 
-            const result = await this.validator.validate(schema.validation.rules, validationContext);
+            const result = await this.getValidator().validate(schema.validation.rules, validationContext);
             allResults.push(...result.results);
         }
 
@@ -168,7 +223,7 @@ export class ObjectRepository {
         // Evaluate each formula field
         for (const [fieldName, fieldConfig] of Object.entries(schema.fields)) {
             if (fieldConfig.type === 'formula' && fieldConfig.formula) {
-                const result = this.formulaEngine.evaluate(
+                const result = this.getFormulaEngine().evaluate(
                     fieldConfig.formula,
                     formulaContext,
                     fieldConfig.data_type || 'text',
@@ -213,11 +268,13 @@ export class ObjectRepository {
         };
         await this.app.triggerHook('beforeFind', this.objectName, hookCtx);
 
-        // TODO: Apply basic filters like spaceId
-        const results = await this.getDriver().find(this.objectName, hookCtx.query || {}, this.getOptions());
+        // Build QueryAST and execute via kernel
+        const ast = this.buildQueryAST(hookCtx.query || {});
+        const kernelResult = await this.getKernel().find(this.objectName, ast);
+        const results = kernelResult.value;
         
         // Evaluate formulas for each result
-        const resultsWithFormulas = results.map(record => this.evaluateFormulas(record));
+        const resultsWithFormulas = results.map((record: any) => this.evaluateFormulas(record));
         
         hookCtx.result = resultsWithFormulas;
         await this.app.triggerHook('afterFind', this.objectName, hookCtx);
@@ -238,7 +295,8 @@ export class ObjectRepository {
             };
             await this.app.triggerHook('beforeFind', this.objectName, hookCtx);
             
-            const result = await this.getDriver().findOne(this.objectName, idOrQuery, hookCtx.query, this.getOptions());
+            // Use kernel.get() for direct ID lookup
+            const result = await this.getKernel().get(this.objectName, String(idOrQuery));
 
             // Evaluate formulas if result exists
             const resultWithFormulas = result ? this.evaluateFormulas(result) : result;
@@ -264,7 +322,10 @@ export class ObjectRepository {
         };
         await this.app.triggerHook('beforeCount', this.objectName, hookCtx);
 
-        const result = await this.getDriver().count(this.objectName, hookCtx.query, this.getOptions());
+        // Build QueryAST and execute via kernel to get count
+        const ast = this.buildQueryAST(hookCtx.query || {});
+        const kernelResult = await this.getKernel().find(this.objectName, ast);
+        const result = kernelResult.count;
 
         hookCtx.result = result;
         await this.app.triggerHook('afterCount', this.objectName, hookCtx);
@@ -290,7 +351,8 @@ export class ObjectRepository {
         // Validate the record before creating
         await this.validateRecord('create', finalDoc);
         
-        const result = await this.getDriver().create(this.objectName, finalDoc, this.getOptions());
+        // Execute via kernel
+        const result = await this.getKernel().create(this.objectName, finalDoc);
         
         hookCtx.result = result;
         await this.app.triggerHook('afterCreate', this.objectName, hookCtx);
@@ -316,7 +378,8 @@ export class ObjectRepository {
         // Validate the update
         await this.validateRecord('update', hookCtx.data, previousData);
 
-        const result = await this.getDriver().update(this.objectName, id, hookCtx.data, this.getOptions(options));
+        // Execute via kernel
+        const result = await this.getKernel().update(this.objectName, String(id), hookCtx.data);
 
         hookCtx.result = result;
         await this.app.triggerHook('afterUpdate', this.objectName, hookCtx);
@@ -337,7 +400,8 @@ export class ObjectRepository {
         };
         await this.app.triggerHook('beforeDelete', this.objectName, hookCtx);
 
-        const result = await this.getDriver().delete(this.objectName, id, this.getOptions());
+        // Execute via kernel
+        const result = await this.getKernel().delete(this.objectName, String(id));
 
         hookCtx.result = result;
         await this.app.triggerHook('afterDelete', this.objectName, hookCtx);