Implement IDataEngine interface for ObjectQL

- Created data-engine.zod.ts in spec/system with Zod schemas
- Updated ObjectQL class to implement IDataEngine interface
- Modified method signatures to match IDataEngine contract
- Updated ObjectQLPlugin to register as both 'objectql' and 'data-engine'
- Re-exported IDataEngine from runtime for backward compatibility

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/objectql/src/index.ts

@@ -1,6 +1,7 @@
 import { QueryAST, HookContext } from '@objectstack/spec/data';
 import { ObjectStackManifest } from '@objectstack/spec/system';
 import { DriverInterface, DriverOptions } from '@objectstack/spec/system';
+import { IDataEngine, QueryOptions } from '@objectstack/spec/system';
 import { SchemaRegistry } from './registry';
 
 // Export Registry for consumers
@@ -20,8 +21,10 @@ export interface PluginContext {
 
 /**
  * ObjectQL Engine
+ * 
+ * Implements the IDataEngine interface for data persistence.
  */
-export class ObjectQL {
+export class ObjectQL implements IDataEngine {
   private drivers = new Map<string, DriverInterface>();
   private defaultDriver: string | null = null;
 
@@ -211,27 +214,52 @@ export class ObjectQL {
   }
 
   // ============================================
-  // Data Access Methods
+  // Data Access Methods (IDataEngine Interface)
   // ============================================
 
-  async find(object: string, query: any = {}, options?: DriverOptions) {
+  /**
+   * Find records matching a query (IDataEngine interface)
+   * 
+   * @param object - Object name
+   * @param query - Query options (IDataEngine format)
+   * @returns Promise resolving to array of records
+   */
+  async find(object: string, query?: QueryOptions): Promise<any[]> {
     const driver = this.getDriver(object);
 
-    // Normalize QueryAST
-    let ast: QueryAST;
-    if (query.where || query.fields || query.orderBy || query.limit) {
-      ast = { object, ...query } as QueryAST;
-    } else {
-      ast = { object, where: query } as QueryAST;
+    // Convert QueryOptions to QueryAST
+    let ast: QueryAST = { object };
+    
+    if (query) {
+      // Map QueryOptions to QueryAST
+      if (query.filter) {
+        ast.where = query.filter;
+      }
+      if (query.select) {
+        ast.fields = query.select;
+      }
+      if (query.sort) {
+        ast.orderBy = query.sort;
+      }
+      // Handle both limit and top (top takes precedence)
+      if (query.top !== undefined) {
+        ast.limit = query.top;
+      } else if (query.limit !== undefined) {
+        ast.limit = query.limit;
+      }
+      if (query.skip !== undefined) {
+        ast.offset = query.skip;
+      }
     }
 
+    // Set default limit if not specified
     if (ast.limit === undefined) ast.limit = 100;
 
     // Trigger Before Hook
     const hookContext: HookContext = {
         object,
         event: 'beforeFind',
-        input: { ast, options }, // Hooks can modify AST here
+        input: { ast, options: undefined },
         ql: this
     };
     await this.triggerHooks('beforeFind', hookContext);
@@ -275,7 +303,14 @@ export class ObjectQL {
     return driver.findOne(object, ast, options);
   }
 
-  async insert(object: string, data: Record<string, any>, options?: DriverOptions) {
+  /**
+   * Insert a new record (IDataEngine interface)
+   * 
+   * @param object - Object name
+   * @param data - Data to insert
+   * @returns Promise resolving to the created record
+   */
+  async insert(object: string, data: any): Promise<any> {
     const driver = this.getDriver(object);
 
     // 1. Get Schema
@@ -290,7 +325,7 @@ export class ObjectQL {
     const hookContext: HookContext = {
         object,
         event: 'beforeInsert',
-        input: { data, options },
+        input: { data, options: undefined },
         ql: this
     };
     await this.triggerHooks('beforeInsert', hookContext);
@@ -306,13 +341,21 @@ export class ObjectQL {
     return hookContext.result;
   }
 
-  async update(object: string, id: string | number, data: Record<string, any>, options?: DriverOptions) {
+  /**
+   * Update a record by ID (IDataEngine interface)
+   * 
+   * @param object - Object name
+   * @param id - Record ID
+   * @param data - Updated data
+   * @returns Promise resolving to the updated record
+   */
+  async update(object: string, id: any, data: any): Promise<any> {
     const driver = this.getDriver(object);
 
     const hookContext: HookContext = {
         object,
         event: 'beforeUpdate',
-        input: { id, data, options },
+        input: { id, data, options: undefined },
         ql: this
     };
     await this.triggerHooks('beforeUpdate', hookContext);
@@ -326,13 +369,20 @@ export class ObjectQL {
     return hookContext.result;
   }
 
-  async delete(object: string, id: string | number, options?: DriverOptions) {
+  /**
+   * Delete a record by ID (IDataEngine interface)
+   * 
+   * @param object - Object name
+   * @param id - Record ID
+   * @returns Promise resolving to true if deleted, false otherwise
+   */
+  async delete(object: string, id: any): Promise<boolean> {
     const driver = this.getDriver(object);
 
     const hookContext: HookContext = {
         object,
         event: 'beforeDelete',
-        input: { id, options },
+        input: { id, options: undefined },
         ql: this
     };
     await this.triggerHooks('beforeDelete', hookContext);
@@ -343,6 +393,8 @@ export class ObjectQL {
     hookContext.result = result;
     await this.triggerHooks('afterDelete', hookContext);
 
-    return hookContext.result;
+    // Return boolean - true if deletion was successful
+    // The driver.delete should return the deleted record or null
+    return hookContext.result !== null && hookContext.result !== undefined;
   }
 }

packages/runtime/src/interfaces/data-engine.ts

@@ -1,122 +1,8 @@
 /**
  * IDataEngine - Standard Data Engine Interface
  * 
- * Abstract interface for data persistence capabilities.
- * This allows plugins to interact with data engines without knowing
- * the underlying implementation (SQL, MongoDB, Memory, etc.).
- * 
- * Follows Dependency Inversion Principle - plugins depend on this interface,
- * not on concrete database implementations.
- */
-
-/**
- * Query filter conditions
- */
-export interface QueryFilter {
-    [field: string]: any;
-}
-
-/**
- * Query options for find operations
+ * Re-exports the data engine interface from the spec package.
+ * This provides backward compatibility for imports from @objectstack/runtime.
  */
-export interface QueryOptions {
-    /** Filter conditions */
-    filter?: QueryFilter;
-    /** Fields to select */
-    select?: string[];
-    /** Sort order */
-    sort?: Record<string, 1 | -1 | 'asc' | 'desc'>;
-    /** Limit number of results (alternative name for top, used by some drivers) */
-    limit?: number;
-    /** Skip number of results (for pagination) */
-    skip?: number;
-    /** Maximum number of results (OData-style, takes precedence over limit if both specified) */
-    top?: number;
-}
 
-/**
- * IDataEngine - Data persistence capability interface
- * 
- * Defines the contract for data engine implementations.
- * Concrete implementations (ObjectQL, Prisma, TypeORM) should implement this interface.
- */
-export interface IDataEngine {
-    /**
-     * Insert a new record
-     * 
-     * @param objectName - Name of the object/table (e.g., 'user', 'order')
-     * @param data - Data to insert
-     * @returns Promise resolving to the created record (including generated ID)
-     * 
-     * @example
-     * ```ts
-     * const user = await engine.insert('user', {
-     *   name: 'John Doe',
-     *   email: 'john@example.com'
-     * });
-     * console.log(user.id); // Auto-generated ID
-     * ```
-     */
-    insert(objectName: string, data: any): Promise<any>;
-    
-    /**
-     * Find records matching a query
-     * 
-     * @param objectName - Name of the object/table
-     * @param query - Query conditions (optional)
-     * @returns Promise resolving to an array of matching records
-     * 
-     * @example
-     * ```ts
-     * // Find all users
-     * const allUsers = await engine.find('user');
-     * 
-     * // Find with filter
-     * const activeUsers = await engine.find('user', {
-     *   filter: { status: 'active' }
-     * });
-     * 
-     * // Find with limit and sort
-     * const recentUsers = await engine.find('user', {
-     *   sort: { createdAt: -1 },
-     *   limit: 10
-     * });
-     * ```
-     */
-    find(objectName: string, query?: QueryOptions): Promise<any[]>;
-    
-    /**
-     * Update a record by ID
-     * 
-     * @param objectName - Name of the object/table
-     * @param id - Record ID
-     * @param data - Updated data (partial update)
-     * @returns Promise resolving to the updated record
-     * 
-     * @example
-     * ```ts
-     * const updatedUser = await engine.update('user', '123', {
-     *   name: 'Jane Doe',
-     *   email: 'jane@example.com'
-     * });
-     * ```
-     */
-    update(objectName: string, id: any, data: any): Promise<any>;
-    
-    /**
-     * Delete a record by ID
-     * 
-     * @param objectName - Name of the object/table
-     * @param id - Record ID
-     * @returns Promise resolving to true if deleted, false otherwise
-     * 
-     * @example
-     * ```ts
-     * const deleted = await engine.delete('user', '123');
-     * if (deleted) {
-     *   console.log('User deleted successfully');
-     * }
-     * ```
-     */
-    delete(objectName: string, id: any): Promise<boolean>;
-}
+export type { IDataEngine, QueryOptions, QueryFilter } from '@objectstack/spec/system';

packages/runtime/src/objectql-plugin.ts

@@ -44,9 +44,13 @@ export class ObjectQLPlugin implements Plugin {
    * Init phase - Register ObjectQL as a service
    */
   async init(ctx: PluginContext) {
-    // Register ObjectQL engine as a service
+    // Register ObjectQL engine as 'objectql' service (legacy name)
     ctx.registerService('objectql', this.ql);
-    ctx.logger.log('[ObjectQLPlugin] ObjectQL engine registered as service');
+    
+    // Register ObjectQL engine as 'data-engine' service (IDataEngine interface)
+    ctx.registerService('data-engine', this.ql);
+    
+    ctx.logger.log('[ObjectQLPlugin] ObjectQL engine registered as services: objectql, data-engine');
   }
 
   /**