@objectql/core 3.0.1 → 4.0.0

package/dist/query/query-analyzer.js

@@ -0,0 +1,349 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryAnalyzer = void 0;
+/**
+ * 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
+ */
+class QueryAnalyzer {
+    constructor(queryService, metadata) {
+        this.queryService = queryService;
+        this.metadata = metadata;
+        this.stats = {
+            totalQueries: 0,
+            avgExecutionTime: 0,
+            slowestQuery: 0,
+            fastestQuery: Number.MAX_VALUE,
+            byObject: {},
+            slowQueries: []
+        };
+        this.executionTimes = [];
+        this.MAX_SLOW_QUERIES = 10;
+    }
+    /**
+     * 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, query) {
+        const schema = this.getSchema(objectName);
+        // Build the QueryAST (without executing)
+        const ast = {
+            object: objectName,
+            filters: query.filters, // FilterCondition is compatible with FilterNode
+            sort: query.sort, // Will be converted to SortNode[] format
+            top: query.limit, // Changed from limit to top (QueryAST uses 'top')
+            skip: query.skip,
+            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, query, options = {}) {
+        var _a, _b;
+        // 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 = ((_a = result.profile) === null || _a === void 0 ? void 0 : _a.executionTime) || 0;
+        const rowsReturned = result.value.length;
+        const rowsScanned = ((_b = result.profile) === null || _b === void 0 ? void 0 : _b.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() {
+        return { ...this.stats };
+    }
+    /**
+     * Reset statistics
+     */
+    resetStatistics() {
+        this.stats = {
+            totalQueries: 0,
+            avgExecutionTime: 0,
+            slowestQuery: 0,
+            fastestQuery: Number.MAX_VALUE,
+            byObject: {},
+            slowQueries: []
+        };
+        this.executionTimes = [];
+    }
+    /**
+     * Get schema for an object
+     * @private
+     */
+    getSchema(objectName) {
+        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
+     */
+    findApplicableIndexes(schema, query) {
+        const indexes = [];
+        if (!schema.indexes || !query.filters) {
+            return indexes;
+        }
+        // Extract fields used in filters
+        const filterFields = new Set();
+        // 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) => {
+            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.filters);
+        // 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
+     */
+    analyzeWarnings(schema, query) {
+        const warnings = [];
+        // Warning: No filters (full table scan)
+        if (!query.filters || query.filters.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.filters && query.filters.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
+     */
+    generateSuggestions(schema, query, indexes) {
+        const suggestions = [];
+        // Suggest adding limit
+        if (!query.limit) {
+            suggestions.push('Add a limit clause to restrict result set size');
+        }
+        // Suggest adding indexes
+        if (query.filters && query.filters.length > 0 && indexes.length === 0) {
+            const filterFields = query.filters
+                .filter((f) => Array.isArray(f) && f.length >= 1)
+                .map((f) => String(f[0]));
+            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.filters && query.filters.length > 1 && indexes.length < 2) {
+            const filterFields = query.filters
+                .filter((f) => Array.isArray(f) && f.length >= 1)
+                .map((f) => String(f[0]))
+                .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
+     */
+    calculateComplexity(query) {
+        let complexity = 0;
+        // Base complexity
+        complexity += 10;
+        // Filters add complexity
+        if (query.filters) {
+            complexity += query.filters.length * 5;
+            // Nested filters (OR conditions) add more
+            const hasNestedFilters = query.filters.some((f) => Array.isArray(f) && Array.isArray(f[0]));
+            if (hasNestedFilters) {
+                complexity += 15;
+            }
+        }
+        // Sorting adds complexity
+        if (query.sort && query.sort.length > 0) {
+            complexity += query.sort.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
+     */
+    estimateRows(schema, query) {
+        // This is a placeholder - real implementation would need statistics
+        // from the database (row count, index selectivity, etc.)
+        // Default to unknown
+        if (!query.filters || query.filters.length === 0) {
+            return -1; // Unknown, full scan
+        }
+        // Very rough estimate based on filter count
+        const baseEstimate = 1000;
+        const filterReduction = Math.pow(0.5, query.filters.length);
+        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
+     */
+    recordExecution(objectName, executionTime, query) {
+        // 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);
+        }
+    }
+}
+exports.QueryAnalyzer = QueryAnalyzer;
+//# sourceMappingURL=query-analyzer.js.map

package/dist/query/query-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-analyzer.js","sourceRoot":"","sources":["../../src/query/query-analyzer.ts"],"names":[],"mappings":"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"}

package/dist/query/query-builder.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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';
+/**
+ * Query Builder
+ *
+ * Builds ObjectStack QueryAST from ObjectQL UnifiedQuery.
+ * This is the central query construction module for ObjectQL.
+ */
+export declare class QueryBuilder {
+    private filterTranslator;
+    constructor();
+    /**
+     * Build a QueryAST from a UnifiedQuery
+     *
+     * @param objectName - Target object name
+     * @param query - ObjectQL UnifiedQuery
+     * @returns ObjectStack QueryAST
+     */
+    build(objectName: string, query: UnifiedQuery): QueryAST;
+}

package/dist/query/query-builder.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryBuilder = void 0;
+const filter_translator_1 = require("./filter-translator");
+/**
+ * Query Builder
+ *
+ * Builds ObjectStack QueryAST from ObjectQL UnifiedQuery.
+ * This is the central query construction module for ObjectQL.
+ */
+class QueryBuilder {
+    constructor() {
+        this.filterTranslator = new filter_translator_1.FilterTranslator();
+    }
+    /**
+     * Build a QueryAST from a UnifiedQuery
+     *
+     * @param objectName - Target object name
+     * @param query - ObjectQL UnifiedQuery
+     * @returns ObjectStack QueryAST
+     */
+    build(objectName, query) {
+        const ast = {
+            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
+            }));
+        }
+        // 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,
+                field: agg.field,
+                alias: agg.alias || `${agg.func}_${agg.field}`
+            }));
+        }
+        return ast;
+    }
+}
+exports.QueryBuilder = QueryBuilder;
+//# sourceMappingURL=query-builder.js.map

package/dist/query/query-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-builder.js","sourceRoot":"","sources":["../../src/query/query-builder.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAIH,2DAAuD;AAEvD;;;;;GAKG;AACH,MAAa,YAAY;IAGrB;QACI,IAAI,CAAC,gBAAgB,GAAG,IAAI,oCAAgB,EAAE,CAAC;IACnD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAkB,EAAE,KAAmB;QACzC,MAAM,GAAG,GAAa;YAClB,MAAM,EAAE,UAAU;SACrB,CAAC;QAEF,aAAa;QACb,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACf,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC9B,CAAC;QAED,qCAAqC;QACrC,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAChB,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjE,CAAC;QAED,WAAW;QACX,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACb,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC3C,KAAK;gBACL,KAAK,EAAE,KAAuB;aACjC,CAAC,CAAC,CAAC;QACR,CAAC;QAED,iBAAiB;QACjB,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC5B,GAAG,CAAC,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC3B,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QAC1B,CAAC;QAED,cAAc;QACd,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAChB,GAAG,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAChC,CAAC;QAED,mBAAmB;QACnB,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YAClB,GAAG,CAAC,YAAY,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC3C,QAAQ,EAAE,GAAG,CAAC,IAAW;gBACzB,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,KAAK,EAAE;aACjD,CAAC,CAAC,CAAC;QACR,CAAC;QAED,OAAO,GAAG,CAAC;IACf,CAAC;CACJ;AA7DD,oCA6DC"}

package/dist/query/query-service.d.ts

@@ -0,0 +1,150 @@
+/**
+ * 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, UnifiedQuery, Filter, MetadataRegistry } from '@objectql/types';
+import type { QueryAST } from '@objectstack/spec';
+/**
+ * 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 declare class QueryService {
+    private datasources;
+    private metadata;
+    private queryBuilder;
+    constructor(datasources: Record<string, Driver>, metadata: MetadataRegistry);
+    /**
+     * Get the driver for a specific object
+     * @private
+     */
+    private getDriver;
+    /**
+     * Get the schema for an object
+     * @private
+     */
+    private getSchema;
+    /**
+     * Build QueryAST from UnifiedQuery
+     * @private
+     */
+    private buildQueryAST;
+    /**
+     * 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
+     */
+    find(objectName: string, query?: UnifiedQuery, options?: QueryOptions): Promise<QueryResult<any[]>>;
+    /**
+     * 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
+     */
+    findOne(objectName: string, id: string | number, options?: QueryOptions): Promise<QueryResult<any>>;
+    /**
+     * Execute a count query
+     *
+     * @param objectName - The object to query
+     * @param filters - Optional filters
+     * @param options - Query execution options
+     * @returns Count of matching records
+     */
+    count(objectName: string, filters?: Filter[], options?: QueryOptions): Promise<QueryResult<number>>;
+    /**
+     * 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
+     */
+    aggregate(objectName: string, query: UnifiedQuery, options?: QueryOptions): Promise<QueryResult<any[]>>;
+    /**
+     * 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
+     */
+    directQuery(objectName: string, queryString: string, params?: any[], options?: QueryOptions): Promise<QueryResult<any>>;
+}