@objectql/core 4.2.0 → 4.2.1

package/src/optimizations/SQLQueryOptimizer.ts

@@ -1,329 +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.
- */
-
-/**
- * Index metadata
- */
-export interface IndexMetadata {
-    name: string;
-    fields: string[];
-    unique: boolean;
-    type?: 'btree' | 'hash' | 'fulltext';
-}
-
-/**
- * Schema with index information
- */
-export interface SchemaWithIndexes {
-    name: string;
-    fields: Record<string, any>;
-    indexes?: IndexMetadata[];
-}
-
-/**
- * Query AST for optimization
- */
-export interface OptimizableQueryAST {
-    object: string;
-    fields?: string[];
-    filters?: any;
-    sort?: Array<{ field: string; order: 'asc' | 'desc' }>;
-    joins?: Array<{ type: 'left' | 'inner'; table: string; on: any }>;
-    limit?: number;
-    offset?: number;
-}
-
-/**
- * SQL Query Optimizer
- * 
- * Improvement: SQL-aware optimization with index hints and join reordering.
- * Analyzes query patterns and schema to generate optimal SQL.
- * 
- * Expected: 2-5x faster queries on large datasets
- */
-export class SQLQueryOptimizer {
-    private schemas = new Map<string, SchemaWithIndexes>();
-
-    /**
-     * Register a schema with index information
-     */
-    registerSchema(schema: SchemaWithIndexes): void {
-        this.schemas.set(schema.name, schema);
-    }
-
-    /**
-     * Check if a field has an index
-     */
-    private hasIndex(objectName: string, fieldName: string): boolean {
-        const schema = this.schemas.get(objectName);
-        if (!schema || !schema.indexes) return false;
-
-        return schema.indexes.some(index => 
-            index.fields.includes(fieldName)
-        );
-    }
-
-    /**
-     * Get the best index for given filter fields
-     */
-    private getBestIndex(objectName: string, filterFields: string[]): IndexMetadata | null {
-        const schema = this.schemas.get(objectName);
-        if (!schema || !schema.indexes) return null;
-
-        // Find indexes that cover the filter fields
-        const candidateIndexes = schema.indexes.filter(index => {
-            // Check if index covers any of the filter fields
-            return filterFields.some(field => index.fields.includes(field));
-        });
-
-        if (candidateIndexes.length === 0) return null;
-
-        // Prefer indexes that match more filter fields
-        candidateIndexes.sort((a, b) => {
-            const aMatches = a.fields.filter(f => filterFields.includes(f)).length;
-            const bMatches = b.fields.filter(f => filterFields.includes(f)).length;
-            return bMatches - aMatches;
-        });
-
-        return candidateIndexes[0];
-    }
-
-    /**
-     * Extract filter fields from filter conditions
-     */
-    private extractFilterFields(filters: any): string[] {
-        const fields: string[] = [];
-
-        const extract = (obj: any) => {
-            if (!obj || typeof obj !== 'object') return;
-
-            for (const key of Object.keys(obj)) {
-                if (!key.startsWith('$')) {
-                    fields.push(key);
-                }
-                if (typeof obj[key] === 'object') {
-                    extract(obj[key]);
-                }
-            }
-        };
-
-        extract(filters);
-        return [...new Set(fields)]; // Remove duplicates
-    }
-
-    /**
-     * Optimize join type based on query characteristics
-     * 
-     * Note: This method expects filter fields in one of two formats:
-     * 1. Table-prefixed: "tableName.fieldName" (e.g., "accounts.type")
-     * 2. Simple field name: "fieldName" (checked against joined table schema)
-     * 
-     * Multi-level qualification (e.g., "schema.table.field") is not currently supported.
-     */
-    private optimizeJoinType(
-        join: { type: 'left' | 'inner'; table: string; on: any },
-        ast: OptimizableQueryAST
-    ): 'left' | 'inner' {
-        // If we're filtering on the joined table, we can use INNER JOIN
-        if (ast.filters) {
-            const filterFields = this.extractFilterFields(ast.filters);
-            
-            // Check if any filter field references the joined table
-            const hasFilterOnJoinTable = filterFields.some(field => {
-                // Handle table-prefixed fields like "accounts.type"
-                if (field.includes('.')) {
-                    const parts = field.split('.');
-                    // Only consider the first part as table name for simplicity
-                    // This assumes format: "table.field" not "schema.table.field"
-                    if (parts.length === 2 && parts[0] === join.table) {
-                        return true;
-                    }
-                    // If more than 2 parts or table doesn't match, skip this field
-                    return false;
-                }
-                
-                // Also check if the field exists in the joined table schema (non-prefixed)
-                const schema = this.schemas.get(join.table);
-                if (schema) {
-                    return schema.fields[field] !== undefined;
-                }
-                
-                return false;
-            });
-            
-            if (hasFilterOnJoinTable) {
-                return 'inner'; // Convert LEFT to INNER for better performance
-            }
-        }
-
-        return join.type;
-    }
-
-    /**
-     * Optimize a query AST to SQL
-     */
-    optimize(ast: OptimizableQueryAST): string {
-        const schema = this.schemas.get(ast.object);
-        if (!schema) {
-            // Fallback to basic SQL generation
-            return this.generateBasicSQL(ast);
-        }
-
-        let sql = 'SELECT ';
-
-        // Fields
-        if (ast.fields && ast.fields.length > 0) {
-            sql += ast.fields.join(', ');
-        } else {
-            sql += '*';
-        }
-
-        sql += ` FROM ${ast.object}`;
-
-        // Index hints
-        if (ast.filters) {
-            const filterFields = this.extractFilterFields(ast.filters);
-            const bestIndex = this.getBestIndex(ast.object, filterFields);
-            
-            if (bestIndex) {
-                // Add index hint for MySQL/MariaDB
-                sql += ` USE INDEX (${bestIndex.name})`;
-            }
-        }
-
-        // Optimized joins
-        if (ast.joins && ast.joins.length > 0) {
-            for (const join of ast.joins) {
-                const optimizedType = this.optimizeJoinType(join, ast);
-                sql += ` ${optimizedType.toUpperCase()} JOIN ${join.table}`;
-                
-                // Simplified join condition
-                if (typeof join.on === 'string') {
-                    sql += ` ON ${join.on}`;
-                }
-            }
-        }
-
-        // WHERE clause
-        if (ast.filters) {
-            sql += ' WHERE ' + this.filtersToSQL(ast.filters);
-        }
-
-        // ORDER BY
-        if (ast.sort && ast.sort.length > 0) {
-            sql += ' ORDER BY ';
-            sql += ast.sort.map(s => `${s.field} ${s.order.toUpperCase()}`).join(', ');
-        }
-
-        // LIMIT and OFFSET
-        if (ast.limit !== undefined) {
-            sql += ` LIMIT ${ast.limit}`;
-        }
-        if (ast.offset !== undefined) {
-            sql += ` OFFSET ${ast.offset}`;
-        }
-
-        return sql;
-    }
-
-    /**
-     * Convert filter object to SQL WHERE clause
-     */
-    private filtersToSQL(filters: any): string {
-        if (typeof filters === 'string') {
-            return filters;
-        }
-
-        // Simplified filter conversion
-        const conditions: string[] = [];
-        
-        for (const [key, value] of Object.entries(filters)) {
-            if (key === '$and') {
-                const subconditions = (value as any[]).map(f => this.filtersToSQL(f));
-                conditions.push(`(${subconditions.join(' AND ')})`);
-            } else if (key === '$or') {
-                const subconditions = (value as any[]).map(f => this.filtersToSQL(f));
-                conditions.push(`(${subconditions.join(' OR ')})`);
-            } else if (!key.startsWith('$')) {
-                // Field condition
-                if (typeof value === 'object' && value !== null) {
-                    for (const [op, val] of Object.entries(value)) {
-                        switch (op) {
-                            case '$eq':
-                                conditions.push(`${key} = '${val}'`);
-                                break;
-                            case '$ne':
-                                conditions.push(`${key} != '${val}'`);
-                                break;
-                            case '$gt':
-                                conditions.push(`${key} > '${val}'`);
-                                break;
-                            case '$gte':
-                                conditions.push(`${key} >= '${val}'`);
-                                break;
-                            case '$lt':
-                                conditions.push(`${key} < '${val}'`);
-                                break;
-                            case '$lte':
-                                conditions.push(`${key} <= '${val}'`);
-                                break;
-                            case '$in':
-                                const inValues = (val as any[]).map(v => `'${v}'`).join(', ');
-                                conditions.push(`${key} IN (${inValues})`);
-                                break;
-                        }
-                    }
-                } else {
-                    conditions.push(`${key} = '${value}'`);
-                }
-            }
-        }
-
-        return conditions.join(' AND ');
-    }
-
-    /**
-     * Fallback: generate basic SQL without optimizations
-     */
-    private generateBasicSQL(ast: OptimizableQueryAST): string {
-        let sql = 'SELECT ';
-        
-        if (ast.fields && ast.fields.length > 0) {
-            sql += ast.fields.join(', ');
-        } else {
-            sql += '*';
-        }
-        
-        sql += ` FROM ${ast.object}`;
-        
-        if (ast.filters) {
-            sql += ' WHERE ' + this.filtersToSQL(ast.filters);
-        }
-        
-        if (ast.sort && ast.sort.length > 0) {
-            sql += ' ORDER BY ';
-            sql += ast.sort.map(s => `${s.field} ${s.order.toUpperCase()}`).join(', ');
-        }
-        
-        if (ast.limit !== undefined) {
-            sql += ` LIMIT ${ast.limit}`;
-        }
-        if (ast.offset !== undefined) {
-            sql += ` OFFSET ${ast.offset}`;
-        }
-        
-        return sql;
-    }
-
-    /**
-     * Clear all registered schemas
-     */
-    clearSchemas(): void {
-        this.schemas.clear();
-    }
-}

package/src/optimizations/index.ts

@@ -1,34 +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.
- */
-
-/**
- * Kernel Optimizations Module
- * 
- * This module contains 10 key optimizations for the ObjectQL kernel:
- * 
- * 1. OptimizedMetadataRegistry - O(k) package uninstall with secondary indexes
- * 2. QueryCompiler - LRU cache for compiled query plans
- * 3. CompiledHookManager - Pre-compiled hook pipelines
- * 4. GlobalConnectionPool - Kernel-level connection pooling
- * 5. OptimizedValidationEngine - Compiled validation rules
- * 6. LazyMetadataLoader - On-demand metadata loading with predictive preload
- * 7. DependencyGraph - DAG-based dependency resolution
- * 8. SQLQueryOptimizer - SQL-aware query optimization with index hints
- * 
- * Note: TypeScript type generation optimization (#7) and memory-mapped storage (#10)
- * are not included in this release for compatibility and complexity reasons.
- */
-
-export { OptimizedMetadataRegistry } from './OptimizedMetadataRegistry';
-export { QueryCompiler, type CompiledQuery } from './QueryCompiler';
-export { CompiledHookManager, type Hook } from './CompiledHookManager';
-export { GlobalConnectionPool, type Connection, type PoolLimits } from './GlobalConnectionPool';
-export { OptimizedValidationEngine, type ValidatorFunction, type ValidationSchema } from './OptimizedValidationEngine';
-export { LazyMetadataLoader, type ObjectMetadata, type MetadataLoader } from './LazyMetadataLoader';
-export { DependencyGraph, type DependencyEdge, type DependencyType } from './DependencyGraph';
-export { SQLQueryOptimizer, type IndexMetadata, type SchemaWithIndexes, type OptimizableQueryAST } from './SQLQueryOptimizer';

package/src/protocol.ts

@@ -1,304 +0,0 @@
-/**
- * ObjectStack Protocol Implementation
- * 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 { ObjectStackProtocol } from '@objectstack/spec/api';
-import { IObjectQL } from '@objectql/types';
-
-/**
- * Bridges the ObjectStack Protocol (Specification) to the ObjectQL Engine (Implementation)
- */
-export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
-    constructor(private engine: IObjectQL) {}
-
-    /**
-     * Get API Discovery Document
-     */
-    async getDiscovery(args: any): Promise<any> {
-        return {
-            name: 'ObjectQL Engine',
-            version: '4.0.0',
-            protocols: ['rest', 'graphql', 'json-rpc', 'odata'],
-            auth: {
-                type: 'bearer',
-                url: '/auth/token'
-            }
-        };
-    }
-
-    /**
-     * Get Metadata Types (e.g., ['object', 'action'])
-     */
-    async getMetaTypes(args: any): Promise<{ types: string[] }> {
-        let types = ['object'];
-        if (this.engine.metadata && typeof this.engine.metadata.getTypes === 'function') {
-            types = this.engine.metadata.getTypes();
-        }
-        return { types };
-    }
-
-    /**
-     * Get Metadata Items for a Type
-     */
-    async getMetaItems(args: { type: string }): Promise<{ type: string; items: any[] }> {
-        const { type } = args;
-        let items: any[] = [];
-        if (this.engine.metadata && typeof this.engine.metadata.list === 'function') {
-            items = this.engine.metadata.list(type);
-        }
-        return { type, items };
-    }
-
-    /**
-     * Get Metadata Item
-     */
-    async getMetaItem(args: { type: string; name: string }): Promise<any> {
-        const { type, name } = args;
-        if (this.engine.metadata && typeof this.engine.metadata.get === 'function') {
-            return this.engine.metadata.get(type, name);
-        }
-        return null;
-    }
-
-    /**
-     * Get Cached Metadata Item
-     */
-    async getMetaItemCached(args: { type: string; name: string }): Promise<any> {
-        // Fallback to non-cached version for now
-        return this.getMetaItem(args);
-    }
-
-    /**
-     * Save Metadata Item
-     */
-    async saveMetaItem(args: { type: string; name: string; item?: any }): Promise<{ success: boolean; message?: string }> {
-        const { type, name, item } = args;
-        if (this.engine.metadata && typeof this.engine.metadata.register === 'function') {
-            const data = { ...(item || {}), name }; // Ensure name is in data
-            this.engine.metadata.register(type, data);
-            return { success: true };
-        }
-        throw new Error('Engine does not support saving metadata');
-    }
-
-    /**
-     * Get UI View
-     */
-    async getUiView(args: { object: string; type: 'list' | 'form' }): Promise<any> {
-        return null;
-    }
-
-    /**
-     * Find Data Records
-     */
-    async findData(args: { object: string; query?: any }): Promise<any> {
-        const { object, query } = args;
-        
-        // Use direct kernel method if available (preferred)
-        if (typeof (this.engine as any).find === 'function') {
-            const result = await (this.engine as any).find(object, query || {});
-            return result;
-        }
-
-        // Fallback to createContext (if engine is IObjectQL)
-        if (typeof (this.engine as any).createContext === 'function') {
-            const ctx = (this.engine as any).createContext({ isSystem: true });
-            try {
-                const repo = ctx.object(object);
-                return await repo.find(query || {});
-            } catch (error: any) {
-                throw new Error(`Data access failed: ${error.message}`);
-            }
-        }
-
-        throw new Error('Engine does not support find operation');
-    }
-
-    /**
-     * Count Data Records
-     */
-    async countData(args: { object: string; query?: any }): Promise<number> {
-        const { object, query } = args;
-        // Basic fallback
-        const result = await this.findData(args);
-        return Array.isArray(result) ? result.length : (result.value ? result.value.length : 0);
-    }
-
-
-    /**
-     * Get Single Data Record
-     */
-    async getData(args: { object: string; id: string }): Promise<any> {
-        const { object, id } = args;
-        
-        if (typeof (this.engine as any).get === 'function') {
-            return await (this.engine as any).get(object, id);
-        }
-        
-        if (typeof (this.engine as any).createContext === 'function') {
-            const ctx = (this.engine as any).createContext({ isSystem: true });
-            try {
-                const repo = ctx.object(object);
-                return await repo.findOne(id);
-            } catch (error: any) {
-                throw new Error(`Data retrieval failed: ${error.message}`);
-            }
-        }
-        
-        throw new Error('Engine does not support get operation');
-    }
-
-    /**
-     * Create Data Record
-     */
-    async createData(args: { object: string; data: any }): Promise<any> {
-        const { object, data } = args;
-
-        if (typeof (this.engine as any).create === 'function') {
-            return await (this.engine as any).create(object, data);
-        }
-        
-        if (typeof (this.engine as any).createContext === 'function') {
-            const ctx = (this.engine as any).createContext({ isSystem: true });
-            try {
-                const repo = ctx.object(object);
-                // Protocol expects returned data
-                return await repo.create(data);
-            } catch (error: any) {
-                throw new Error(`Data creation failed: ${error.message}`);
-            }
-        }
-        
-        throw new Error('Engine does not support create operation');
-    }
-
-    /**
-     * Update Data Record
-     */
-    async updateData(args: { object: string; id: string; data: any }): Promise<any> {
-        const { object, id, data } = args;
-
-        if (typeof (this.engine as any).update === 'function') {
-            return await (this.engine as any).update(object, id, data);
-        }
-
-        if (typeof (this.engine as any).createContext === 'function') {
-            const ctx = (this.engine as any).createContext({ isSystem: true });
-            try {
-                const repo = ctx.object(object);
-                return await repo.update(id, data);
-            } catch (error: any) {
-                 throw new Error(`Data update failed: ${error.message}`);
-            }
-        }
-
-        throw new Error('Engine does not support update operation');
-    }
-
-    /**
-     * Delete Data Record
-     */
-    async deleteData(args: { object: string; id: string }): Promise<{ object: string; id: string; success: boolean }> {
-        const { object, id } = args;
-
-        if (typeof (this.engine as any).delete === 'function') {
-            const success = await (this.engine as any).delete(object, id);
-            return { object, id, success: !!success };
-        }
-
-        if (typeof (this.engine as any).createContext === 'function') {
-            const ctx = (this.engine as any).createContext({ isSystem: true });
-            try {
-                const repo = ctx.object(object);
-                await repo.delete(id);
-                return { object, id, success: true };
-            } catch (error: any) {
-                throw new Error(`Data deletion failed: ${error.message}`);
-            }
-        }
-
-        throw new Error('Engine does not support delete operation');
-    }
-
-    /**
-     * Create Many Data Records
-     */
-    async createManyData(args: { object: string; records: any[]; options?: any }): Promise<any> {
-        throw new Error('createManyData not implemented');
-    }
-
-    /**
-     * Update Many Data Records
-     */
-    async updateManyData(args: { object: string; records: { id: string; data: any }[]; options?: any }): Promise<any> {
-        throw new Error('updateManyData not implemented');
-    }
-
-    /**
-     * Delete Many Data Records
-     */
-    async deleteManyData(args: { object: string; ids: string[]; options?: any }): Promise<any> {
-         throw new Error('deleteManyData not implemented');
-    }
-
-    /**
-     * Batch Operations
-     */
-    async batchData(args: { object: string; request: { operation: 'create' | 'update' | 'delete' | 'upsert'; records: any[] } }): Promise<any> {
-        throw new Error('batchData not implemented');
-    }
-
-    /**
-     * Execute Action/Operation
-     */
-    async performAction(args: { object: string; id?: string; action: string; args?: any }): Promise<any> {
-        // Not implemented in this shim yet
-        throw new Error('Action execution not implemented in protocol shim');
-    }
-
-    /**
-     * Analytics Query - Execute analytics query
-     */
-    async analyticsQuery(args: any): Promise<any> {
-        throw new Error('analyticsQuery not implemented');
-    }
-
-    /**
-     * Get Analytics Metadata
-     */
-    async getAnalyticsMeta(args: any): Promise<any> {
-        throw new Error('getAnalyticsMeta not implemented');
-    }
-
-    /**
-     * Trigger Automation
-     */
-    async triggerAutomation(args: { trigger: string; payload: Record<string, any> }): Promise<{ success: boolean; jobId?: string; result?: any }> {
-        throw new Error('triggerAutomation not implemented');
-    }
-
-    /**
-     * List Spaces (Hub/Workspace Management)
-     */
-    async listSpaces(args: any): Promise<any> {
-        throw new Error('listSpaces not implemented');
-    }
-
-    /**
-     * Create Space (Hub/Workspace Management)
-     */
-    async createSpace(args: any): Promise<any> {
-        throw new Error('createSpace not implemented');
-    }
-
-    /**
-     * Install Plugin (Hub/Extension Management)
-     */
-    async installPlugin(args: any): Promise<any> {
-        throw new Error('installPlugin not implemented');
-    }
-}