@objectql/core 4.2.0 → 4.2.1

package/src/query/filter-translator.ts

@@ -1,41 +0,0 @@
-/**
- * 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 { Data } from '@objectstack/spec';
-import { z } from 'zod';
-import { ObjectQLError } from '@objectql/types';
-
-/**
- * Filter Translator
- * 
- * Translates ObjectQL Filter to ObjectStack FilterCondition format.
- * Since both now use the same format, this is mostly a pass-through.
- * 
- * @example
- * Input:  { age: { $gte: 18 }, $or: [{ status: "active" }, { role: "admin" }] }
- * Output: { age: { $gte: 18 }, $or: [{ status: "active" }, { role: "admin" }] }
- */
-export class FilterTranslator {
-    /**
-     * Translate filters from ObjectQL format to ObjectStack FilterCondition format
-     */
-    translate(filters?: Filter): Filter | undefined {
-        if (!filters) {
-            return undefined;
-        }
-
-        // If it's an empty object, return undefined
-        if (typeof filters === 'object' && Object.keys(filters).length === 0) {
-            return undefined;
-        }
-
-        // Both ObjectQL Filter and ObjectStack FilterCondition use the same format now
-        return filters;
-    }
-}

package/src/query/index.ts

@@ -1,24 +0,0 @@
-/**
- * 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
- * - QueryService: Executes queries via drivers with profiling support
- * - QueryAnalyzer: Provides query performance analysis and optimization suggestions
- * 
- * These are the core components that differentiate ObjectQL from generic runtime systems.
- */
-
-export * from './filter-translator';
-export * from './query-builder';
-export * from './query-service';
-export * from './query-analyzer';

package/src/query/query-analyzer.ts

@@ -1,532 +0,0 @@
-/**
- * ObjectQL Query Analyzer
- * 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, ObjectConfig, MetadataRegistry } from '@objectql/types';
-import { QueryAST } from '@objectql/types';
-import { QueryService, QueryOptions } from './query-service';
-
-/**
- * Query execution plan
- */
-export interface QueryPlan {
-    /**
-     * The compiled QueryAST
-     */
-    ast: QueryAST;
-    
-    /**
-     * Estimated number of rows to be scanned
-     */
-    estimatedRows?: number;
-    
-    /**
-     * Indexes that could be used for this query
-     */
-    indexes: string[];
-    
-    /**
-     * Warnings about potential performance issues
-     */
-    warnings: string[];
-    
-    /**
-     * Suggestions for optimization
-     */
-    suggestions: string[];
-    
-    /**
-     * Complexity score (0-100, higher is more complex)
-     */
-    complexity: number;
-}
-
-/**
- * Query profile result with execution statistics
- */
-export interface ProfileResult {
-    /**
-     * Execution time in milliseconds
-     */
-    executionTime: number;
-    
-    /**
-     * Number of rows scanned by the database
-     */
-    rowsScanned: number;
-    
-    /**
-     * Number of rows returned
-     */
-    rowsReturned: number;
-    
-    /**
-     * Whether an index was used
-     */
-    indexUsed: boolean;
-    
-    /**
-     * The query plan
-     */
-    plan: QueryPlan;
-    
-    /**
-     * Efficiency ratio (rowsReturned / rowsScanned)
-     * Higher is better (1.0 is perfect, 0.0 is worst)
-     */
-    efficiency: number;
-}
-
-/**
- * Aggregated query statistics
- */
-export interface QueryStats {
-    /**
-     * Total number of queries executed
-     */
-    totalQueries: number;
-    
-    /**
-     * Average execution time in milliseconds
-     */
-    avgExecutionTime: number;
-    
-    /**
-     * Slowest query execution time
-     */
-    slowestQuery: number;
-    
-    /**
-     * Fastest query execution time
-     */
-    fastestQuery: number;
-    
-    /**
-     * Queries by object
-     */
-    byObject: Record<string, {
-        count: number;
-        avgTime: number;
-    }>;
-    
-    /**
-     * Top slow queries
-     */
-    slowQueries: Array<{
-        objectName: string;
-        executionTime: number;
-        query: UnifiedQuery;
-        timestamp: Date;
-    }>;
-}
-
-/**
- * Query Analyzer
- * 
- * Provides query performance analysis and profiling capabilities.
- * This class helps developers optimize queries by:
- * - Analyzing query plans
- * - Profiling execution performance
- * - Tracking statistics
- * - Providing optimization suggestions
- */
-export class QueryAnalyzer {
-    private stats: QueryStats = {
-        totalQueries: 0,
-        avgExecutionTime: 0,
-        slowestQuery: 0,
-        fastestQuery: Number.MAX_VALUE,
-        byObject: {},
-        slowQueries: []
-    };
-    
-    private executionTimes: number[] = [];
-    private readonly MAX_SLOW_QUERIES = 10;
-    
-    constructor(
-        private queryService: QueryService,
-        private metadata: MetadataRegistry
-    ) {}
-    
-    /**
-     * Analyze a query and generate an execution plan
-     * 
-     * @param objectName - The object to query
-     * @param query - The unified query
-     * @returns Query plan with optimization suggestions
-     */
-    async explain(objectName: string, query: UnifiedQuery): Promise<QueryPlan> {
-        const schema = this.getSchema(objectName);
-        
-        // Build the QueryAST (without executing)
-        const ast: QueryAST = {
-            object: objectName,
-            where: query.where as any, // FilterCondition format
-            orderBy: query.orderBy as any, // Will be converted to SortNode[] format
-            limit: query.limit,
-            offset: query.offset,
-            fields: query.fields
-        };
-        
-        // Analyze filters for index usage
-        const indexes = this.findApplicableIndexes(schema, query);
-        
-        // Detect potential issues
-        const warnings = this.analyzeWarnings(schema, query);
-        
-        // Generate suggestions
-        const suggestions = this.generateSuggestions(schema, query, indexes);
-        
-        // Calculate complexity
-        const complexity = this.calculateComplexity(query);
-        
-        // Try to estimate rows (basic heuristic)
-        const estimatedRows = this.estimateRows(schema, query);
-        
-        return {
-            ast,
-            estimatedRows,
-            indexes,
-            warnings,
-            suggestions,
-            complexity
-        };
-    }
-    
-    /**
-     * Profile a query execution
-     * 
-     * @param objectName - The object to query
-     * @param query - The unified query
-     * @param options - Query execution options
-     * @returns Profile result with execution statistics
-     */
-    async profile(
-        objectName: string, 
-        query: UnifiedQuery,
-        options: QueryOptions = {}
-    ): Promise<ProfileResult> {
-        // Get the query plan first
-        const plan = await this.explain(objectName, query);
-        
-        // Execute with profiling enabled
-        const result = await this.queryService.find(objectName, query, {
-            ...options,
-            profile: true
-        });
-        
-        const executionTime = result.profile?.executionTime || 0;
-        const rowsReturned = result.value.length;
-        const rowsScanned = result.profile?.rowsScanned || rowsReturned;
-        
-        // Calculate efficiency
-        const efficiency = rowsScanned > 0 ? rowsReturned / rowsScanned : 0;
-        
-        // Determine if index was used (heuristic)
-        const indexUsed = plan.indexes.length > 0 && efficiency > 0.5;
-        
-        // Update statistics
-        this.recordExecution(objectName, executionTime, query);
-        
-        return {
-            executionTime,
-            rowsScanned,
-            rowsReturned,
-            indexUsed,
-            plan,
-            efficiency
-        };
-    }
-    
-    /**
-     * Get aggregated query statistics
-     * 
-     * @returns Current query statistics
-     */
-    getStatistics(): QueryStats {
-        return { ...this.stats };
-    }
-    
-    /**
-     * Reset statistics
-     */
-    resetStatistics(): void {
-        this.stats = {
-            totalQueries: 0,
-            avgExecutionTime: 0,
-            slowestQuery: 0,
-            fastestQuery: Number.MAX_VALUE,
-            byObject: {},
-            slowQueries: []
-        };
-        this.executionTimes = [];
-    }
-    
-    /**
-     * Get schema for an object
-     * @private
-     */
-    private getSchema(objectName: string): ObjectConfig {
-        const obj = this.metadata.get('object', objectName);
-        if (!obj) {
-            throw new Error(`Object '${objectName}' not found`);
-        }
-        return obj;
-    }
-    
-    /**
-     * Find indexes that could be used for the query
-     * @private
-     */
-    private findApplicableIndexes(schema: ObjectConfig, query: UnifiedQuery): string[] {
-        const indexes: string[] = [];
-        
-        if (!schema.indexes || !query.where) {
-            return indexes;
-        }
-        
-        // Extract fields used in filters
-        const filterFields = new Set<string>();
-        
-        // FilterCondition is an object-based filter (e.g., { field: value } or { field: { $eq: value } })
-        // We need to extract field names from the filter object
-        const extractFieldsFromFilter = (filter: any): void => {
-            if (!filter || typeof filter !== 'object') return;
-            
-            for (const key of Object.keys(filter)) {
-                // Skip logical operators
-                if (key.startsWith('$')) {
-                    // Logical operators contain nested filters
-                    if (key === '$and' || key === '$or') {
-                        const nested = filter[key];
-                        if (Array.isArray(nested)) {
-                            nested.forEach(extractFieldsFromFilter);
-                        }
-                    }
-                    continue;
-                }
-                // This is a field name
-                filterFields.add(key);
-            }
-        };
-        
-        extractFieldsFromFilter(query.where);
-        
-        // Check which indexes could be used
-        const indexesArray = Array.isArray(schema.indexes) ? schema.indexes : Object.values(schema.indexes || {});
-        for (const index of indexesArray) {
-            const indexFields = Array.isArray(index.fields) 
-                ? index.fields 
-                : [index.fields];
-            
-            // Simple heuristic: index is applicable if first field is in filter
-            if (indexFields.length > 0 && filterFields.has(indexFields[0])) {
-                const indexName = index.name || indexFields.join('_');
-                indexes.push(indexName);
-            }
-        }
-        
-        return indexes;
-    }
-    
-    /**
-     * Analyze query for potential issues
-     * @private
-     */
-    private analyzeWarnings(schema: ObjectConfig, query: UnifiedQuery): string[] {
-        const warnings: string[] = [];
-        
-        // Warning: No filters (full table scan)
-        if (!query.where || Object.keys(query.where).length === 0) {
-            warnings.push('No filters specified - this will scan all records');
-        }
-        
-        // Warning: No limit on potentially large dataset
-        if (!query.limit) {
-            warnings.push('No limit specified - consider adding pagination');
-        }
-        
-        // Warning: Selecting all fields
-        if (!query.fields || query.fields.length === 0) {
-            const fieldCount = Object.keys(schema.fields || {}).length;
-            if (fieldCount > 10) {
-                warnings.push(`Selecting all ${fieldCount} fields - consider selecting only needed fields`);
-            }
-        }
-        
-        // Warning: Complex filters without indexes
-        if (query.where && Object.keys(query.where).length > 5) {
-            const indexes = this.findApplicableIndexes(schema, query);
-            if (indexes.length === 0) {
-                warnings.push('Complex filters without matching indexes - consider adding indexes');
-            }
-        }
-        
-        return warnings;
-    }
-    
-    /**
-     * Generate optimization suggestions
-     * @private
-     */
-    private generateSuggestions(
-        schema: ObjectConfig, 
-        query: UnifiedQuery,
-        indexes: string[]
-    ): string[] {
-        const suggestions: string[] = [];
-        
-        // Suggest adding limit
-        if (!query.limit) {
-            suggestions.push('Add a limit clause to restrict result set size');
-        }
-        
-        // Suggest adding indexes
-        if (query.where && Object.keys(query.where).length > 0 && indexes.length === 0) {
-            const filterFields = Object.keys(query.where).filter(k => !k.startsWith('$'));
-            
-            if (filterFields.length > 0) {
-                suggestions.push(`Consider adding an index on: ${filterFields.join(', ')}`);
-            }
-        }
-        
-        // Suggest field selection
-        if (!query.fields || query.fields.length === 0) {
-            suggestions.push('Select only required fields to reduce data transfer');
-        }
-        
-        // Suggest composite index for multiple filters
-        if (query.where && Object.keys(query.where).length > 1 && indexes.length < 2) {
-            const filterFields = Object.keys(query.where)
-                .filter(k => !k.startsWith('$'))
-                .slice(0, 3); // Top 3 fields
-            
-            if (filterFields.length > 1) {
-                suggestions.push(`Consider a composite index on: (${filterFields.join(', ')})`);
-            }
-        }
-        
-        return suggestions;
-    }
-    
-    /**
-     * Calculate query complexity score (0-100)
-     * @private
-     */
-    private calculateComplexity(query: UnifiedQuery): number {
-        let complexity = 0;
-        
-        // Base complexity
-        complexity += 10;
-        
-        // Filters add complexity
-        if (query.where) {
-            const filterCount = Object.keys(query.where).length;
-            complexity += filterCount * 5;
-            
-            // Nested filters (OR/AND conditions) add more
-            const hasLogicalOps = query.where.$and || query.where.$or;
-            if (hasLogicalOps) {
-                complexity += 15;
-            }
-        }
-        
-        // Sorting adds complexity
-        if (query.orderBy && query.orderBy.length > 0) {
-            complexity += query.orderBy.length * 3;
-        }
-        
-        // Field selection reduces complexity slightly
-        if (query.fields && query.fields.length > 0 && query.fields.length < 10) {
-            complexity -= 5;
-        }
-        
-        // Pagination reduces complexity
-        if (query.limit) {
-            complexity -= 5;
-        }
-        
-        // Cap at 100
-        return Math.min(Math.max(complexity, 0), 100);
-    }
-    
-    /**
-     * Estimate number of rows (very rough heuristic)
-     * @private
-     */
-    private estimateRows(schema: ObjectConfig, query: UnifiedQuery): number {
-        // This is a placeholder - real implementation would need statistics
-        // from the database (row count, index selectivity, etc.)
-        
-        // Default to unknown
-        if (!query.where || Object.keys(query.where).length === 0) {
-            return -1; // Unknown, full scan
-        }
-        
-        // Very rough estimate based on filter count
-        const baseEstimate = 1000;
-        const filterCount = Object.keys(query.where).length;
-        const filterReduction = Math.pow(0.5, filterCount);
-        const estimated = Math.floor(baseEstimate * filterReduction);
-        
-        // Apply limit if present
-        if (query.limit) {
-            return Math.min(estimated, query.limit);
-        }
-        
-        return estimated;
-    }
-    
-    /**
-     * Record a query execution for statistics
-     * @private
-     */
-    private recordExecution(
-        objectName: string,
-        executionTime: number,
-        query: UnifiedQuery
-    ): void {
-        // Update totals
-        this.stats.totalQueries++;
-        this.executionTimes.push(executionTime);
-        
-        // Update average
-        this.stats.avgExecutionTime = 
-            this.executionTimes.reduce((sum, t) => sum + t, 0) / this.executionTimes.length;
-        
-        // Update min/max
-        this.stats.slowestQuery = Math.max(this.stats.slowestQuery, executionTime);
-        this.stats.fastestQuery = Math.min(this.stats.fastestQuery, executionTime);
-        
-        // Update per-object stats
-        if (!this.stats.byObject[objectName]) {
-            this.stats.byObject[objectName] = { count: 0, avgTime: 0 };
-        }
-        const objStats = this.stats.byObject[objectName];
-        objStats.count++;
-        objStats.avgTime = ((objStats.avgTime * (objStats.count - 1)) + executionTime) / objStats.count;
-        
-        // Track slow queries
-        if (this.stats.slowQueries.length < this.MAX_SLOW_QUERIES) {
-            this.stats.slowQueries.push({
-                objectName,
-                executionTime,
-                query,
-                timestamp: new Date()
-            });
-            this.stats.slowQueries.sort((a, b) => b.executionTime - a.executionTime);
-        } else if (executionTime > this.stats.slowQueries[this.MAX_SLOW_QUERIES - 1].executionTime) {
-            this.stats.slowQueries[this.MAX_SLOW_QUERIES - 1] = {
-                objectName,
-                executionTime,
-                query,
-                timestamp: new Date()
-            };
-            this.stats.slowQueries.sort((a, b) => b.executionTime - a.executionTime);
-        }
-    }
-}

package/src/query/query-builder.ts

@@ -1,64 +0,0 @@
-/**
- * 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, QueryAST } from '@objectql/types';
-// import { QueryAST } from './types'; (Removed)
-
-// Local QueryAST type extension to include all properties we need
-// interface QueryAST extends Data.QueryAST {
-//    top?: number;
-//    expand?: Record<string, any>;
-//    aggregations?: any[];
-//    having?: any;
-// }
-
-import { FilterTranslator } from './filter-translator';
-
-/**
- * Query Builder
- * 
- * Builds ObjectStack QueryAST from ObjectQL UnifiedQuery.
- * Since UnifiedQuery now uses the standard protocol format directly,
- * this is now a simple pass-through with object name injection.
- */
-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 (now in standard QueryAST format)
-     * @returns ObjectStack QueryAST
-     */
-    build(objectName: string, query: UnifiedQuery): QueryAST {
-        // UnifiedQuery now uses the same format as QueryAST
-        // Just add the object name and pass through
-        const ast: QueryAST = {
-            object: objectName
-        };
-
-        // Map UnifiedQuery properties to QueryAST
-        if (query.fields) ast.fields = query.fields;
-        if (query.where) ast.where = this.filterTranslator.translate(query.where);
-        if (query.orderBy) ast.orderBy = query.orderBy;
-        if (query.offset !== undefined) ast.offset = query.offset;
-        if (query.limit !== undefined) ast.top = query.limit; // UnifiedQuery uses 'limit', QueryAST uses 'top'
-        if (query.expand) ast.expand = query.expand;
-        if (query.groupBy) ast.groupBy = query.groupBy;
-        if (query.aggregations) ast.aggregations = query.aggregations;
-        if (query.having) ast.having = query.having;
-        if (query.distinct) ast.distinct = query.distinct;
-
-        return ast;
-    }
-}