@objectql/core 3.0.1 → 4.0.1

package/src/query/query-service.ts

@@ -0,0 +1,393 @@
+/**
+ * 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 { Data } from '@objectstack/spec';
+type QueryAST = Data.QueryAST;
+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,65 @@
-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 '@objectql/runtime';
+import { Data } from '@objectstack/spec';
+type QueryAST = Data.QueryAST;
+type FilterNode = Data.FilterNode;
+type SortNode = Data.SortNode;
 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 +68,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 +140,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 +179,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 +226,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 +271,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 +298,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;
@@ -253,6 +314,22 @@ export class ObjectRepository {
     }
 
     async count(filters: any): Promise<number> {
+        // Normalize filters to UnifiedQuery format
+        // If filters is an array, wrap it in a query object
+        // If filters is already a UnifiedQuery (has UnifiedQuery-specific properties), use it as-is
+        let query: UnifiedQuery;
+        if (Array.isArray(filters)) {
+            query = { filters };
+        } else if (filters && typeof filters === 'object' && (filters.fields || filters.sort || filters.limit !== undefined || filters.skip !== undefined)) {
+            // It's already a UnifiedQuery object
+            query = filters;
+        } else if (filters) {
+            // It's a raw filter object, wrap it
+            query = { filters };
+        } else {
+            query = {};
+        }
+
         const hookCtx: RetrievalHookContext = {
             ...this.context,
             objectName: this.objectName,
@@ -260,11 +337,14 @@ export class ObjectRepository {
             api: this.getHookAPI(),
             user: this.getUserFromContext(),
             state: {},
-            query: filters
+            query
         };
         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 +370,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 +397,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 +419,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);

package/src/util.ts

@@ -1,3 +1,11 @@
+/**
+ * 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 { ObjectConfig, FieldConfig, FieldType, IntrospectedSchema, IntrospectedColumn, IntrospectedTable } from '@objectql/types';
 
 export function toTitleCase(str: string): string {
@@ -102,20 +110,28 @@ export function convertIntrospectedSchemaToObjects(
             
             if (foreignKey) {
                 // This is a lookup field
+                // Note: name must be set explicitly here since we're creating the config programmatically.
+                // When defined in YAML (ObjectConfig.fields Record), the name is auto-populated from the key.
                 fieldConfig = {
+                    name: column.name,
                     type: 'lookup',
                     reference_to: foreignKey.referencedTable,
                     label: toTitleCase(column.name),
-                    required: !column.nullable
+                    required: !column.nullable,
+                    searchable: false
                 };
             } else {
                 // Regular field
                 const fieldType = mapDatabaseTypeToFieldType(column.type);
                 
+                // Note: name must be set explicitly here since we're creating the config programmatically.
+                // When defined in YAML (ObjectConfig.fields Record), the name is auto-populated from the key.
                 fieldConfig = {
+                    name: column.name,
                     type: fieldType,
                     label: toTitleCase(column.name),
-                    required: !column.nullable
+                    required: !column.nullable,
+                    searchable: false
                 };
                 
                 // Add unique constraint
@@ -125,7 +141,7 @@ export function convertIntrospectedSchemaToObjects(
                 
                 // Add max length for text fields
                 if (column.maxLength && (fieldType === 'text' || fieldType === 'textarea')) {
-                    fieldConfig.max_length = column.maxLength;
+                    fieldConfig.maxLength = column.maxLength;
                 }
                 
                 // Add default value