@objectql/core 3.0.0 → 4.0.0

package/src/app.ts

@@ -1,12 +1,20 @@
+/**
+ * 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 { 
-    MetadataRegistry, 
+    MetadataRegistry,
+    MetadataItem,
     Driver, 
     ObjectConfig, 
     ObjectQLContext, 
     ObjectQLContextOptions, 
     IObjectQL, 
     ObjectQLConfig,
-    ObjectQLPlugin,
     HookName,
     HookHandler,
     HookContext,
@@ -14,37 +22,47 @@ import {
     ActionContext,
     LoaderPlugin
 } from '@objectql/types';
+import { ObjectStackKernel, type RuntimePlugin } from '@objectstack/runtime';
 import { ObjectRepository } from './repository';
-// import { createDriverFromConnection } from './driver'; // REMOVE THIS
-
-// import { loadRemoteFromUrl } from './remote';
-import { executeActionHelper, registerActionHelper, ActionEntry } from './action';
-import { registerHookHelper, triggerHookHelper, HookEntry } from './hook';
-import { registerObjectHelper, getConfigsHelper } from './object';
+import { ObjectQLPlugin } from './plugin';
 import { convertIntrospectedSchemaToObjects } from './util';
 
+/**
+ * ObjectQL
+ * 
+ * ObjectQL implementation that wraps ObjectStackKernel
+ * to provide the plugin architecture.
+ */
 export class ObjectQL implements IObjectQL {
-    public metadata: MetadataRegistry;
+    // Delegate to kernel for metadata, hooks, and actions
+    public get metadata(): MetadataRegistry {
+        return this.kernel.metadata;
+    }
+    
     private datasources: Record<string, Driver> = {};
     private remotes: string[] = [];
-    private hooks: Record<string, HookEntry[]> = {};
-    private actions: Record<string, ActionEntry> = {};
-    private pluginsList: ObjectQLPlugin[] = [];
+    
+    // ObjectStack Kernel Integration
+    private kernel!: ObjectStackKernel;
+    private kernelPlugins: RuntimePlugin[] = [];
     
     // Store config for lazy loading in init()
     private config: ObjectQLConfig;
 
     constructor(config: ObjectQLConfig) {
         this.config = config;
-        this.metadata = config.registry || new MetadataRegistry();
         this.datasources = config.datasources || {};
-        // this.remotes = config.remotes || [];
         
         if (config.connection) {
              throw new Error("Connection strings are not supported in core directly. Use @objectql/platform-node's createDriverFromConnection or pass a driver instance to 'datasources'.");
         }
 
-        // Initialize Plugin List (but don't setup yet)
+        // Add the ObjectQL plugin to provide enhanced features
+        this.kernelPlugins.push(new ObjectQLPlugin({
+            datasources: this.datasources
+        }));
+        
+        // Add runtime plugins from config
         if (config.plugins) {
             for (const plugin of config.plugins) {
                 if (typeof plugin === 'string') {
@@ -54,41 +72,68 @@ export class ObjectQL implements IObjectQL {
                 }
             }
         }
-    }
-    use(plugin: ObjectQLPlugin) {
-        this.pluginsList.push(plugin);
-    }
-
-    removePackage(name: string) {
-        this.metadata.unregisterPackage(name);
         
-        // Remove hooks
-        for (const event of Object.keys(this.hooks)) {
-            this.hooks[event] = this.hooks[event].filter(h => h.packageName !== name);
-        }
+        // Create the kernel
+        this.kernel = new ObjectStackKernel(this.kernelPlugins);
         
-        // Remove actions
-        for (const key of Object.keys(this.actions)) {
-            if (this.actions[key].packageName === name) {
-                delete this.actions[key];
+        // Register initial metadata if provided
+        if (config.registry) {
+            // Copy metadata from provided registry to kernel's registry
+            for (const type of config.registry.getTypes()) {
+                const items = config.registry.list(type);
+                for (const item of items) {
+                    // Safely extract the item's id/name
+                    const itemId = typeof item === 'object' && item !== null 
+                        ? (item as { name?: string; id?: string }).name || (item as { name?: string; id?: string }).id || 'unknown'
+                        : 'unknown';
+                    
+                    this.kernel.metadata.register(type, {
+                        type,
+                        id: itemId,
+                        content: item
+                    });
+                }
             }
         }
     }
+    
+    use(plugin: RuntimePlugin) {
+        this.kernelPlugins.push(plugin);
+    }
+
+    removePackage(name: string) {
+        // Delegate to kernel managers
+        this.kernel.metadata.unregisterPackage(name);
+        this.kernel.hooks.removePackage(name);
+        this.kernel.actions.removePackage(name);
+    }
 
     on(event: HookName, objectName: string, handler: HookHandler, packageName?: string) {
-        registerHookHelper(this.hooks, event, objectName, handler, packageName);
+        // Delegate to kernel hook manager
+        // We wrap the handler to bridge ObjectQL's rich context types with runtime's base types
+        // The runtime HookContext supports all fields via index signature, so this is safe
+        const wrappedHandler = handler as unknown as import('@objectstack/runtime').HookHandler;
+        this.kernel.hooks.register(event, objectName, wrappedHandler, packageName);
     }
 
     async triggerHook(event: HookName, objectName: string, ctx: HookContext) {
-        await triggerHookHelper(this.metadata, this.hooks, event, objectName, ctx);
+        // Delegate to kernel hook manager
+        // Runtime HookContext supports ObjectQL-specific fields via index signature
+        await this.kernel.hooks.trigger(event, objectName, ctx);
     }
 
     registerAction(objectName: string, actionName: string, handler: ActionHandler, packageName?: string) {
-        registerActionHelper(this.actions, objectName, actionName, handler, packageName);
+        // Delegate to kernel action manager
+        // We wrap the handler to bridge ObjectQL's rich context types with runtime's base types
+        // The runtime ActionContext supports all fields via index signature, so this is safe
+        const wrappedHandler = handler as unknown as import('@objectstack/runtime').ActionHandler;
+        this.kernel.actions.register(objectName, actionName, wrappedHandler, packageName);
     }
 
     async executeAction(objectName: string, actionName: string, ctx: ActionContext) {
-        return await executeActionHelper(this.metadata, this.actions, objectName, actionName, ctx);
+        // Delegate to kernel action manager
+        // Runtime ActionContext supports ObjectQL-specific fields via index signature
+        return await this.kernel.actions.execute(objectName, actionName, ctx);
     }
 
     createContext(options: ObjectQLContextOptions): ObjectQLContext {
@@ -100,7 +145,7 @@ export class ObjectQL implements IObjectQL {
             object: (name: string) => {
                 return new ObjectRepository(name, ctx, this);
             },
-            transaction: async (callback) => {
+            transaction: async (callback: (ctx: ObjectQLContext) => Promise<any>) => {
                  const driver = this.datasources['default'];
                  if (!driver || !driver.beginTransaction) {
                       return callback(ctx);
@@ -116,7 +161,7 @@ export class ObjectQL implements IObjectQL {
                  const trxCtx: ObjectQLContext = {
                      ...ctx,
                      transactionHandle: trx,
-                     transaction: async (cb) => cb(trxCtx)
+                     transaction: async (cb: (ctx: ObjectQLContext) => Promise<any>) => cb(trxCtx)
                  };
 
                  try {
@@ -135,20 +180,53 @@ export class ObjectQL implements IObjectQL {
         return ctx;
     }
 
+    /**
+     * Get the underlying ObjectStackKernel instance
+     * 
+     * This provides access to the kernel for advanced usage scenarios
+     * where you need direct access to the plugin architecture.
+     * 
+     * @returns The ObjectStackKernel instance
+     * @throws Error if called before init()
+     */
+    getKernel(): ObjectStackKernel {
+        if (!this.kernel) {
+            throw new Error('Kernel not initialized. Call init() first.');
+        }
+        return this.kernel;
+    }
+
     registerObject(object: ObjectConfig) {
-        registerObjectHelper(this.metadata, object);
+        // Normalize fields
+        if (object.fields) {
+            for (const [key, field] of Object.entries(object.fields)) {
+                if (field && !field.name) {
+                    field.name = key;
+                }
+            }
+        }
+        this.kernel.metadata.register('object', {
+            type: 'object',
+            id: object.name,
+            content: object
+        });
     }
 
     unregisterObject(name: string) {
-        this.metadata.unregister('object', name);
+        this.kernel.metadata.unregister('object', name);
     }
 
     getObject(name: string): ObjectConfig | undefined {
-        return this.metadata.get<ObjectConfig>('object', name);
+        return this.kernel.metadata.get<ObjectConfig>('object', name);
     }
 
     getConfigs(): Record<string, ObjectConfig> {
-        return getConfigsHelper(this.metadata);
+        const result: Record<string, ObjectConfig> = {};
+        const items = this.kernel.metadata.list<ObjectConfig>('object');
+        for (const item of items) {
+            result[item.name] = item;
+        }
+        return result;
     }
 
     datasource(name: string): Driver {
@@ -207,46 +285,30 @@ export class ObjectQL implements IObjectQL {
     }
 
     async init() {
-        // 0. Init Plugins (This allows plugins to register custom loaders)
-        for (const plugin of this.pluginsList) {
-            console.log(`Initializing plugin '${plugin.name}'...`);
-            
-            let app: IObjectQL = this;
-            const pkgName = (plugin as any)._packageName;
-
-            if (pkgName) {
-                app = new Proxy(this, {
-                    get(target, prop) {
-                        if (prop === 'on') {
-                            return (event: HookName, obj: string, handler: HookHandler) => 
-                                target.on(event, obj, handler, pkgName);
-                        }
-                        if (prop === 'registerAction') {
-                            return (obj: string, act: string, handler: ActionHandler) => 
-                                target.registerAction(obj, act, handler, pkgName);
-                        }
-                        const value = (target as any)[prop];
-                        return typeof value === 'function' ? value.bind(target) : value;
-                    }
-                });
+        console.log('[ObjectQL] Initializing with ObjectStackKernel...');
+        
+        // Start the kernel - this will install and start all plugins
+        await this.kernel.start();
+        
+        // TEMPORARY: Set driver for backward compatibility during migration
+        // This allows the kernel mock to delegate to the driver
+        if (typeof (this.kernel as any).setDriver === 'function') {
+            const defaultDriver = this.datasources['default'];
+            if (defaultDriver) {
+                (this.kernel as any).setDriver(defaultDriver);
             }
-
-            await plugin.setup(app);
         }
 
-        // Packages, Presets, Source, Objects loading logic removed from Core.
-        // Use @objectql/platform-node's ObjectLoader or platform-specific loaders.
-        
-        // 3. Load In-Memory Objects (Dynamic Layer)
+        // Load In-Memory Objects (Dynamic Layer)
         if (this.config.objects) {
             for (const [key, obj] of Object.entries(this.config.objects)) {
                 this.registerObject(obj);
             }
         }
 
-        const objects = this.metadata.list<ObjectConfig>('object');
+        const objects = this.kernel.metadata.list<ObjectConfig>('object');
         
-        // 5. Init Datasources
+        // Init Datasources
         // Let's pass all objects to all configured drivers.
         for (const [name, driver] of Object.entries(this.datasources)) {
             if (driver.init) {
@@ -255,12 +317,14 @@ export class ObjectQL implements IObjectQL {
             }
         }
 
-        // 6. Process Initial Data
+        // Process Initial Data
         await this.processInitialData();
+        
+        console.log('[ObjectQL] Initialization complete');
     }
 
     private async processInitialData() {
-        const dataEntries = this.metadata.list<any>('data');
+        const dataEntries = this.kernel.metadata.list<any>('data');
         if (dataEntries.length === 0) return;
 
         console.log(`Processing ${dataEntries.length} initial data files...`);

package/src/formula-engine.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.
+ */
+
 /**
  * Formula Engine Implementation
  * 

package/src/formula-plugin.ts

@@ -0,0 +1,141 @@
+/**
+ * ObjectQL Formula Plugin
+ * 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 { RuntimePlugin, RuntimeContext, ObjectStackKernel } from '@objectstack/runtime';
+import { FormulaEngine } from './formula-engine';
+import type { FormulaEngineConfig } from '@objectql/types';
+
+/**
+ * Extended ObjectStack Kernel with formula engine capability
+ */
+interface KernelWithFormulas extends ObjectStackKernel {
+    formulaEngine?: FormulaEngine;
+}
+
+/**
+ * Configuration for the Formula Plugin
+ */
+export interface FormulaPluginConfig extends FormulaEngineConfig {
+  /**
+   * Enable automatic formula evaluation on queries
+   * @default true
+   */
+  autoEvaluateOnQuery?: boolean;
+}
+
+/**
+ * Formula Plugin
+ * 
+ * Wraps the ObjectQL Formula Engine as an ObjectStack plugin.
+ * Registers formula evaluation capabilities into the kernel.
+ */
+export class FormulaPlugin implements RuntimePlugin {
+  name = '@objectql/formulas';
+  version = '4.0.0';
+  
+  private engine: FormulaEngine;
+  private config: FormulaPluginConfig;
+  
+  constructor(config: FormulaPluginConfig = {}) {
+    this.config = {
+      autoEvaluateOnQuery: true,
+      ...config
+    };
+    
+    // Initialize the formula engine with configuration
+    this.engine = new FormulaEngine(config);
+  }
+  
+  /**
+   * Install the plugin into the kernel
+   * Registers formula evaluation capabilities
+   */
+  async install(ctx: RuntimeContext): Promise<void> {
+    const kernel = ctx.engine as KernelWithFormulas;
+    
+    console.log(`[${this.name}] Installing formula plugin...`);
+    
+    // Make formula engine accessible from the kernel for direct usage
+    kernel.formulaEngine = this.engine;
+    
+    // Register formula provider if the kernel supports it
+    this.registerFormulaProvider(kernel);
+    
+    // Register formula evaluation middleware if auto-evaluation is enabled
+    if (this.config.autoEvaluateOnQuery !== false) {
+      this.registerFormulaMiddleware(kernel);
+    }
+    
+    console.log(`[${this.name}] Formula plugin installed`);
+  }
+  
+  /**
+   * Register the formula provider with the kernel
+   * @private
+   */
+  private registerFormulaProvider(kernel: KernelWithFormulas): void {
+    // Check if kernel supports formula provider registration
+    if (typeof (kernel as any).registerFormulaProvider === 'function') {
+      (kernel as any).registerFormulaProvider({
+        evaluate: (formula: string, context: any) => {
+          // Delegate to the formula engine
+          // Note: In a real implementation, we would need to properly construct
+          // the FormulaContext from the provided context
+          return this.engine.evaluate(
+            formula,
+            context,
+            'text', // default data type
+            {}
+          );
+        },
+        validate: (expression: string) => {
+          return this.engine.validate(expression);
+        },
+        extractMetadata: (fieldName: string, expression: string, dataType: any) => {
+          return this.engine.extractMetadata(fieldName, expression, dataType);
+        }
+      });
+    }
+    // Note: formulaEngine is already registered in install() method above
+  }
+  
+  /**
+   * Register formula evaluation middleware
+   * @private
+   */
+  private registerFormulaMiddleware(kernel: KernelWithFormulas): void {
+    // Check if kernel supports middleware hooks
+    if (typeof (kernel as any).use === 'function') {
+      // Register middleware to evaluate formulas after queries
+      (kernel as any).use('afterQuery', async (context: any) => {
+        // Formula evaluation logic would go here
+        // This would automatically compute formula fields after data is retrieved
+        if (context.results && context.metadata?.fields) {
+          // Iterate through fields and evaluate formulas
+          // const formulaFields = Object.entries(context.metadata.fields)
+          //   .filter(([_, fieldConfig]) => (fieldConfig as any).formula);
+          // 
+          // for (const record of context.results) {
+          //   for (const [fieldName, fieldConfig] of formulaFields) {
+          //     const formula = (fieldConfig as any).formula;
+          //     const result = this.engine.evaluate(formula, /* context */, /* dataType */);
+          //     record[fieldName] = result.value;
+          //   }
+          // }
+        }
+      });
+    }
+  }
+  
+  /**
+   * Get the formula engine instance for direct access
+   */
+  getEngine(): FormulaEngine {
+    return this.engine;
+  }
+}

package/src/index.ts

@@ -1,9 +1,31 @@
+/**
+ * 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.
+ */
+
+// Re-export types from @objectstack packages for API compatibility
+export type { ObjectStackKernel, ObjectStackRuntimeProtocol } from '@objectstack/runtime';
+// Note: @objectstack/objectql types temporarily commented out due to type incompatibilities
+// in the published package. Will be re-enabled when package is updated.
+// export type { ObjectQL as ObjectQLEngine, SchemaRegistry } from '@objectstack/objectql';
+
+// Export ObjectStack spec types for driver development
+export type { DriverInterface, DriverOptions, QueryAST } from '@objectstack/spec';
+
+// Export our enhanced runtime components (actual implementations)
 export * from './repository';
 export * from './app';
+export * from './plugin';
+export * from './validator-plugin';
+export * from './formula-plugin';
+
+// Export query-specific modules (ObjectQL core competency)
+export * from './query';
 
-export * from './action';
-export * from './hook';
-export * from './object';
+// Export utilities
 export * from './validator';
 export * from './util';
 export * from './ai-agent';

package/src/plugin.ts

@@ -0,0 +1,179 @@
+/**
+ * ObjectQL Plugin
+ * 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 { RuntimePlugin, RuntimeContext } from '@objectstack/runtime';
+import type { ObjectStackKernel } from '@objectstack/runtime';
+import { ValidatorPlugin, ValidatorPluginConfig } from './validator-plugin';
+import { FormulaPlugin, FormulaPluginConfig } from './formula-plugin';
+import { QueryService } from './query/query-service';
+import { QueryAnalyzer } from './query/query-analyzer';
+import type { Driver } from '@objectql/types';
+
+/**
+ * Extended ObjectStack Kernel with ObjectQL services
+ */
+interface ExtendedKernel extends ObjectStackKernel {
+    queryService?: QueryService;
+    queryAnalyzer?: QueryAnalyzer;
+}
+
+/**
+ * Configuration for the ObjectQL Plugin
+ */
+export interface ObjectQLPluginConfig {
+  /**
+   * Enable repository pattern for data access
+   * @default true
+   */
+  enableRepository?: boolean;
+  
+  /**
+   * Enable validation engine
+   * @default true
+   */
+  enableValidator?: boolean;
+  
+  /**
+   * Validator plugin configuration
+   * Only used if enableValidator is not false
+   */
+  validatorConfig?: ValidatorPluginConfig;
+  
+  /**
+   * Enable formula engine
+   * @default true
+   */
+  enableFormulas?: boolean;
+  
+  /**
+   * Formula plugin configuration
+   * Only used if enableFormulas is not false
+   */
+  formulaConfig?: FormulaPluginConfig;
+  
+  /**
+   * Enable AI integration
+   * @default true
+   */
+  enableAI?: boolean;
+  
+  /**
+   * Enable query service and analyzer
+   * @default true
+   */
+  enableQueryService?: boolean;
+  
+  /**
+   * Datasources for query service
+   * Required if enableQueryService is true
+   */
+  datasources?: Record<string, Driver>;
+}
+
+/**
+ * ObjectQL Plugin
+ * 
+ * Implements the RuntimePlugin interface from @objectstack/runtime
+ * to provide ObjectQL's enhanced features (Repository, Validator, Formula, AI)
+ * on top of the ObjectStack kernel.
+ */
+export class ObjectQLPlugin implements RuntimePlugin {
+  name = '@objectql/core';
+  version = '4.0.0';
+  
+  constructor(private config: ObjectQLPluginConfig = {}) {
+    // Set defaults
+    this.config = {
+      enableRepository: true,
+      enableValidator: true,
+      enableFormulas: true,
+      enableAI: true,
+      enableQueryService: true,
+      ...config
+    };
+  }
+  
+  /**
+   * Install the plugin into the kernel
+   * This is called during kernel initialization
+   */
+  async install(ctx: RuntimeContext): Promise<void> {
+    console.log(`[${this.name}] Installing plugin...`);
+    
+    const kernel = ctx.engine as ExtendedKernel;
+    
+    // Register QueryService and QueryAnalyzer if enabled
+    if (this.config.enableQueryService !== false && this.config.datasources) {
+      const queryService = new QueryService(
+        this.config.datasources,
+        kernel.metadata
+      );
+      kernel.queryService = queryService;
+      
+      const queryAnalyzer = new QueryAnalyzer(
+        queryService,
+        kernel.metadata
+      );
+      kernel.queryAnalyzer = queryAnalyzer;
+      
+      console.log(`[${this.name}] QueryService and QueryAnalyzer registered`);
+    }
+    
+    // Register components based on configuration
+    if (this.config.enableRepository !== false) {
+      await this.registerRepository(ctx.engine);
+    }
+    
+    // Install validator plugin if enabled
+    if (this.config.enableValidator !== false) {
+      const validatorPlugin = new ValidatorPlugin(this.config.validatorConfig || {});
+      await validatorPlugin.install(ctx);
+    }
+    
+    // Install formula plugin if enabled
+    if (this.config.enableFormulas !== false) {
+      const formulaPlugin = new FormulaPlugin(this.config.formulaConfig || {});
+      await formulaPlugin.install(ctx);
+    }
+    
+    if (this.config.enableAI !== false) {
+      await this.registerAI(ctx.engine);
+    }
+    
+    console.log(`[${this.name}] Plugin installed successfully`);
+  }
+  
+  /**
+   * Called when the kernel starts
+   * This is the initialization phase
+   */
+  async onStart(ctx: RuntimeContext): Promise<void> {
+    console.log(`[${this.name}] Starting plugin...`);
+    // Additional startup logic can be added here
+  }
+  
+  /**
+   * Register the Repository pattern
+   * @private
+   */
+  private async registerRepository(kernel: ObjectStackKernel): Promise<void> {
+    // TODO: Implement repository registration
+    // For now, this is a placeholder to establish the structure
+    console.log(`[${this.name}] Repository pattern registered`);
+  }
+  
+  /**
+   * Register AI integration
+   * @private
+   */
+  private async registerAI(kernel: ObjectStackKernel): Promise<void> {
+    // TODO: Implement AI registration
+    // For now, this is a placeholder to establish the structure
+    console.log(`[${this.name}] AI integration registered`);
+  }
+}