Merge pull request #959 from objectstack-ai/copilot/fix-driverinterface-iadatadriver-split

Author: hotlong

CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- **Unified Data Driver Contract (`IDataDriver`)** — Resolved the split between `DriverInterface`
+  (core, minimal ~13 methods) and `IDataDriver` (spec, comprehensive 28 methods). `IDataDriver`
+  from `@objectstack/spec/contracts` is now the **single authoritative** contract for all database
+  driver implementations. `DriverInterface` is retained as a deprecated type alias for backward
+  compatibility. Both `@objectstack/driver-sql` and `@objectstack/driver-memory` now implement
+  `IDataDriver` directly with full `DriverCapabilities` support.
+- **`@objectstack/driver-sql`** — Added missing `IDataDriver` methods: `findStream`, `upsert`,
+  `bulkUpdate`, `bulkDelete`, `commit`, `rollback`, `dropTable`, `explain`. Aligned `supports`
+  with full `DriverCapabilities` schema. `updateMany`/`deleteMany` now return `number` (count)
+  instead of `{ modifiedCount }` / `{ deletedCount }` objects. `delete` returns `boolean`.
+- **`@objectstack/driver-memory`** — Aligned `supports` property with full `DriverCapabilities`
+  schema (added `create`, `read`, `update`, `delete`, `bulkCreate`, `bulkUpdate`, `bulkDelete`,
+  `savepoints`, `queryCTE`, `jsonQuery`, `geospatialQuery`, `streaming`, `schemaSync`, etc.).
+
+### Deprecated
+- **`DriverInterface`** — Use `IDataDriver` from `@objectstack/spec/contracts` instead.
+  `DriverInterface` remains as a type alias in both `@objectstack/spec/contracts` and
+  `@objectstack/core` for backward compatibility.
+
 ### Added
 - **`@objectstack/driver-sql` plugin** — Migrated the Knex-based SQL driver from `@objectql/driver-sql`
   into `packages/plugins/driver-sql/`. The driver implements the standard `DriverInterface` from

packages/core/src/contracts/data-engine.ts

@@ -7,9 +7,7 @@ import {
   DataEngineDeleteOptions,
   DataEngineAggregateOptions, 
   DataEngineCountOptions,
-  DataEngineRequest, // Added Request type for batch
-  QueryAST,
-  DriverOptions
+  DataEngineRequest,
 } from '@objectstack/spec/data';
 
 /**
@@ -47,30 +45,9 @@ export interface IDataEngine {
   execute?(command: any, options?: Record<string, any>): Promise<any>;
 }
 
-export interface DriverInterface {
-  name: string;
-  version: string;
-  connect(): Promise<void>;
-  disconnect(): Promise<void>;
-  
-  find(object: string, query: QueryAST, options?: DriverOptions): Promise<any[]>;
-  findOne(object: string, query: QueryAST, options?: DriverOptions): Promise<any>;
-  create(object: string, data: any, options?: DriverOptions): Promise<any>;
-  update(object: string, id: any, data: any, options?: DriverOptions): Promise<any>;
-  delete(object: string, id: any, options?: DriverOptions): Promise<any>;
-  
-  /**
-   * Bulk & Batch Operations
-   */
-  bulkCreate?(object: string, data: any[], options?: DriverOptions): Promise<any>;
-  updateMany?(object: string, query: QueryAST, data: any, options?: DriverOptions): Promise<any>;
-  deleteMany?(object: string, query: QueryAST, options?: DriverOptions): Promise<any>;
-
-  count?(object: string, query: QueryAST, options?: DriverOptions): Promise<number>;
-  
-  /**
-   * Raw Execution
-   */
-  execute?(command: any, params?: any, options?: DriverOptions): Promise<any>;
-}
+/**
+ * @deprecated Use `IDataDriver` from `@objectstack/spec/contracts` instead.
+ * This type is re-exported from `@objectstack/spec/contracts` for backward compatibility only.
+ */
+export type { DriverInterface } from '@objectstack/spec/contracts';
 

packages/core/src/index.ts

@@ -44,5 +44,7 @@ export type {
     RouteHandler,
     Middleware,
     IDataEngine,
+    IDataDriver,
+    /** @deprecated Use `IDataDriver` instead */
     DriverInterface
 } from '@objectstack/spec/contracts';

packages/objectql/src/engine.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { ObjectQL } from './engine';
 import { SchemaRegistry } from './registry';
-import { DriverInterface } from '@objectstack/spec/data';
+import type { IDataDriver } from '@objectstack/spec/contracts';
 
 // Mock the SchemaRegistry to avoid side effects between tests
 vi.mock('./registry', () => {
@@ -35,8 +35,8 @@ vi.mock('./registry', () => {
 
 describe('ObjectQL Engine', () => {
     let engine: ObjectQL;
-    let mockDriver: DriverInterface;
-    let mockDriver2: DriverInterface;
+    let mockDriver: IDataDriver;
+    let mockDriver2: IDataDriver;
 
     beforeEach(() => {
         // Clear Registry Mocks
@@ -54,7 +54,7 @@ describe('ObjectQL Engine', () => {
             delete: vi.fn(),
             count: vi.fn(),
             capabilities: {} as any // Simplified
-        } as unknown as DriverInterface;
+        } as unknown as IDataDriver;
 
         mockDriver2 = {
             name: 'mongo',
@@ -67,7 +67,7 @@ describe('ObjectQL Engine', () => {
             delete: vi.fn(),
             count: vi.fn(),
             capabilities: {} as any
-        } as unknown as DriverInterface;
+        } as unknown as IDataDriver;
 
         engine = new ObjectQL();
     });

packages/objectql/src/engine.ts

@@ -898,7 +898,7 @@ export class ObjectQL implements IDataEngine {
                result = await Promise.all((hookContext.input.data as any[]).map((item: any) => driver.create(object, item, hookContext.input.options as any)));
           }
         } else {
-          result = await driver.create(object, hookContext.input.data, hookContext.input.options as any);
+          result = await driver.create(object, hookContext.input.data as Record<string, unknown>, hookContext.input.options as any);
         }
 
         hookContext.event = 'afterInsert';
@@ -949,10 +949,10 @@ export class ObjectQL implements IDataEngine {
        try {
            let result;
            if (hookContext.input.id) {
-               result = await driver.update(object, hookContext.input.id as string, hookContext.input.data, hookContext.input.options as any);
+               result = await driver.update(object, hookContext.input.id as string, hookContext.input.data as Record<string, unknown>, hookContext.input.options as any);
            } else if (options?.multi && driver.updateMany) {
                const ast = this.toQueryAST(object, { filter: options.filter });
-               result = await driver.updateMany(object, ast, hookContext.input.data, hookContext.input.options as any);
+               result = await driver.updateMany(object, ast, hookContext.input.data as Record<string, unknown>, hookContext.input.options as any);
            } else {
                throw new Error('Update requires an ID or options.multi=true');
            }

packages/plugins/driver-memory/src/memory-driver.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import type { QueryAST, QueryInput, DriverOptions } from '@objectstack/spec/data';
-import type { DriverInterface } from '@objectstack/core';
+import type { IDataDriver } from '@objectstack/spec/contracts';
 import { Logger, createLogger } from '@objectstack/core';
 import { Query, Aggregator } from 'mingo';
 import { getValueByPath } from './memory-matcher.js';
@@ -79,10 +79,10 @@ interface MemoryTransaction {
  * 
  * Reference: objectql/packages/drivers/memory
  */
-export class InMemoryDriver implements DriverInterface {
-  name = 'com.objectstack.driver.memory';
+export class InMemoryDriver implements IDataDriver {
+  readonly name = 'com.objectstack.driver.memory';
   type = 'driver';
-  version = '1.0.0';
+  readonly version = '1.0.0';
   private config: InMemoryDriverConfig;
   private logger: Logger;
   private idCounters: Map<string, number> = new Map();
@@ -106,9 +106,21 @@ export class InMemoryDriver implements DriverInterface {
     }
   }
 
-  supports = {
+  readonly supports = {
+    // Basic CRUD Operations
+    create: true,
+    read: true,
+    update: true,
+    delete: true,
+
+    // Bulk Operations
+    bulkCreate: true,
+    bulkUpdate: true,
+    bulkDelete: true,
+
     // Transaction & Connection Management
     transactions: true,          // Snapshot-based transactions
+    savepoints: false,
 
     // Query Operations
     queryFilters: true,          // Implemented via memory-matcher
@@ -117,14 +129,27 @@ export class InMemoryDriver implements DriverInterface {
     queryPagination: true,       // Implemented
     queryWindowFunctions: false, // @planned: Window functions (ROW_NUMBER, RANK, etc.)
     querySubqueries: false,      // @planned: Subquery execution
+    queryCTE: false,
     joins: false,                // @planned: In-memory join operations
 
     // Advanced Features
     fullTextSearch: false,       // @planned: Text tokenization + matching
-    vectorSearch: false,         // @planned: Cosine similarity search
-    geoSpatial: false,           // @planned: Distance/within calculations
+    jsonQuery: false,
+    geospatialQuery: false,
+    streaming: true,             // Implemented via findStream()
     jsonFields: true,            // Native JS object support
     arrayFields: true,           // Native JS array support
+    vectorSearch: false,         // @planned: Cosine similarity search
+
+    // Schema Management
+    schemaSync: true,            // Implemented via syncSchema()
+    migrations: false,
+    indexes: false,
+
+    // Performance & Optimization
+    connectionPooling: false,
+    preparedStatements: false,
+    queryCache: false,
   };
 
   /**
@@ -230,7 +255,7 @@ export class InMemoryDriver implements DriverInterface {
   // CRUD
   // ===================================
 
-  async find(object: string, query: QueryInput, options?: DriverOptions) {
+  async find(object: string, query: QueryAST, options?: DriverOptions) {
     this.logger.debug('Find operation', { object, query });
 
     const table = this.getTable(object);
@@ -275,7 +300,7 @@ export class InMemoryDriver implements DriverInterface {
     return results;
   }
 
-  async *findStream(object: string, query: QueryInput, options?: DriverOptions) {
+  async *findStream(object: string, query: QueryAST, options?: DriverOptions) {
     this.logger.debug('FindStream operation', { object });
 
     const results = await this.find(object, query, options);
@@ -284,7 +309,7 @@ export class InMemoryDriver implements DriverInterface {
     }
   }
 
-  async findOne(object: string, query: QueryInput, options?: DriverOptions) {
+  async findOne(object: string, query: QueryAST, options?: DriverOptions) {
     this.logger.debug('FindOne operation', { object, query });
 
     const results = await this.find(object, { ...query, limit: 1 }, options);
@@ -381,7 +406,7 @@ export class InMemoryDriver implements DriverInterface {
     return true;
   }
 
-  async count(object: string, query?: QueryInput, options?: DriverOptions) {
+  async count(object: string, query?: QueryAST, options?: DriverOptions) {
     let records = this.getTable(object);
     if (query?.where) {
         const mongoQuery = this.convertToMongoQuery(query.where);
@@ -406,7 +431,7 @@ export class InMemoryDriver implements DriverInterface {
     return results;
   }
 
-  async updateMany(object: string, query: QueryInput, data: Record<string, any>, options?: DriverOptions) {
+  async updateMany(object: string, query: QueryAST, data: Record<string, any>, options?: DriverOptions): Promise<number> {
       this.logger.debug('UpdateMany operation', { object, query });
 
       const table = this.getTable(object);
@@ -436,10 +461,10 @@ export class InMemoryDriver implements DriverInterface {
 
       if (count > 0) this.markDirty();
       this.logger.debug('UpdateMany completed', { object, count });
-      return { count };
+      return count;
   }
 
-  async deleteMany(object: string, query: QueryInput, options?: DriverOptions) {
+  async deleteMany(object: string, query: QueryAST, options?: DriverOptions): Promise<number> {
       this.logger.debug('DeleteMany operation', { object, query });
 
       const table = this.getTable(object);
@@ -464,7 +489,7 @@ export class InMemoryDriver implements DriverInterface {
       const count = initialLength - this.db[object].length;
       if (count > 0) this.markDirty();
       this.logger.debug('DeleteMany completed', { object, count });
-      return { count };
+      return count;
   }
 
   // Compatibility aliases

packages/plugins/driver-sql/src/sql-driver-advanced.test.ts

@@ -146,7 +146,7 @@ describe('SqlDriver Advanced Operations (SQLite)', () => {
     it('should update many records', async () => {
       const result = await driver.updateMany('orders', { status: 'pending' } as any, { status: 'processing' });
 
-      expect(result.modifiedCount).toBeGreaterThan(0);
+      expect(result).toBeGreaterThan(0);
 
       const results = await driver.find('orders', { where: { status: 'processing' } });
       expect(results.length).toBe(1);
@@ -155,18 +155,18 @@ describe('SqlDriver Advanced Operations (SQLite)', () => {
     it('should delete many records', async () => {
       const result = await driver.deleteMany('orders', { status: 'cancelled' } as any);
 
-      expect(result.deletedCount).toBe(1);
+      expect(result).toBe(1);
 
       const remaining = await driver.count('orders', {});
       expect(remaining).toBe(4);
     });
 
     it('should handle empty bulk update and delete', async () => {
       const result = await driver.updateMany('orders', { status: 'nonexistent' } as any, { status: 'updated' });
-      expect(result.modifiedCount).toBe(0);
+      expect(result).toBe(0);
 
       const deleteResult = await driver.deleteMany('orders', { id: 'nonexistent' } as any);
-      expect(deleteResult.deletedCount).toBe(0);
+      expect(deleteResult).toBe(0);
     });
   });