@objectql/core 3.0.1 → 4.0.1

package/dist/query/filter-translator.js

@@ -0,0 +1,135 @@
+"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.FilterTranslator = void 0;
+const types_1 = require("@objectql/types");
+/**
+ * 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"]]]
+ */
+class FilterTranslator {
+    /**
+     * Translate filters from ObjectQL format to ObjectStack FilterNode format
+     */
+    translate(filters) {
+        if (!filters) {
+            return undefined;
+        }
+        // Backward compatibility: if it's already an array (old format), pass through
+        if (Array.isArray(filters)) {
+            return filters;
+        }
+        // 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
+     */
+    convertToNode(filter) {
+        const nodes = [];
+        // 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 types_1.ObjectQLError({
+                code: 'UNSUPPORTED_OPERATOR',
+                message: '$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);
+    }
+    /**
+     * Interleaves filter nodes with a logical operator
+     */
+    interleaveWithOperator(nodes, operator) {
+        if (nodes.length === 0)
+            return [];
+        if (nodes.length === 1)
+            return [nodes[0]];
+        const result = [nodes[0]];
+        for (let i = 1; i < nodes.length; i++) {
+            result.push(operator, nodes[i]);
+        }
+        return result;
+    }
+    /**
+     * Maps modern $-prefixed operators to legacy format
+     */
+    mapOperatorToLegacy(operator) {
+        const mapping = {
+            '$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('$', '');
+    }
+}
+exports.FilterTranslator = FilterTranslator;
+//# sourceMappingURL=filter-translator.js.map

package/dist/query/filter-translator.js.map

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

package/dist/query/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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/dist/query/index.js

@@ -0,0 +1,39 @@
+"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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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.
+ */
+__exportStar(require("./filter-translator"), exports);
+__exportStar(require("./query-builder"), exports);
+__exportStar(require("./query-service"), exports);
+__exportStar(require("./query-analyzer"), exports);
+//# sourceMappingURL=index.js.map

package/dist/query/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;AAEH;;;;;;;;;;GAUG;AAEH,sDAAoC;AACpC,kDAAgC;AAChC,kDAAgC;AAChC,mDAAiC"}

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

@@ -0,0 +1,188 @@
+/**
+ * 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, MetadataRegistry } from '@objectql/types';
+import { Data } from '@objectstack/spec';
+type QueryAST = Data.QueryAST;
+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 declare class QueryAnalyzer {
+    private queryService;
+    private metadata;
+    private stats;
+    private executionTimes;
+    private readonly MAX_SLOW_QUERIES;
+    constructor(queryService: QueryService, 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
+     */
+    explain(objectName: string, query: UnifiedQuery): Promise<QueryPlan>;
+    /**
+     * 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
+     */
+    profile(objectName: string, query: UnifiedQuery, options?: QueryOptions): Promise<ProfileResult>;
+    /**
+     * Get aggregated query statistics
+     *
+     * @returns Current query statistics
+     */
+    getStatistics(): QueryStats;
+    /**
+     * Reset statistics
+     */
+    resetStatistics(): void;
+    /**
+     * Get schema for an object
+     * @private
+     */
+    private getSchema;
+    /**
+     * Find indexes that could be used for the query
+     * @private
+     */
+    private findApplicableIndexes;
+    /**
+     * Analyze query for potential issues
+     * @private
+     */
+    private analyzeWarnings;
+    /**
+     * Generate optimization suggestions
+     * @private
+     */
+    private generateSuggestions;
+    /**
+     * Calculate query complexity score (0-100)
+     * @private
+     */
+    private calculateComplexity;
+    /**
+     * Estimate number of rows (very rough heuristic)
+     * @private
+     */
+    private estimateRows;
+    /**
+     * Record a query execution for statistics
+     * @private
+     */
+    private recordExecution;
+}
+export {};