feat(spec)!: remove deprecated DriverInterface alias — use IDataDriver (11.0, #2378) (#2384)

Scope correction: `IDataEngine` is NOT deprecated (live engine-layer contract,
`ObjectQL implements IDataEngine`). The actual `@deprecated` alias was
`DriverInterface` (= `IDataDriver`) in spec/contracts + core.

- spec/contracts/data-engine.ts: drop the `DriverInterface` alias (+ now-unused
  IDataDriver import)
- core: drop the `DriverInterface` re-export (contracts/data-engine.ts + index.ts)
- objectql/engine.ts: type drivers as `IDataDriver` (type-identical rename, 11 refs)
- driver-memory config / sql-driver comment / data-engine.test.ts: IDataDriver
- regen spec api-surface snapshot (only `DriverInterface (type)` removed)

Untouched (not deprecated): `IDataEngine`, and the separate zod
`DriverInterface`/`DriverInterfaceSchema` in spec/data (runtime driver schema).

Verified: spec contracts/data tests (32) + objectql (718) green; 8 build tasks
green; api-surface check will pass (snapshot regenerated).

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.changeset/v11-remove-driverinterface-alias.md

@@ -0,0 +1,19 @@
+---
+"@objectstack/spec": major
+"@objectstack/core": major
+"@objectstack/objectql": major
+---
+
+Remove the deprecated `DriverInterface` type alias — use `IDataDriver` (11.0).
+
+`DriverInterface` was a `@deprecated` alias of `IDataDriver` (the authoritative
+driver contract). It is removed from `@objectstack/spec/contracts` and
+`@objectstack/core`; `objectql`'s engine now types drivers as `IDataDriver`
+directly (a type-identical change, since the alias *was* `IDataDriver`).
+
+Driver authors: replace `DriverInterface` with `IDataDriver` (same shape).
+
+Note: this is unrelated to the live `IDataEngine` interface (engine-layer
+contract, not deprecated) and to the separate zod-derived `DriverInterface` /
+`DriverInterfaceSchema` in `@objectstack/spec/data` (the runtime driver schema),
+both of which are unchanged.

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

@@ -49,9 +49,4 @@ export interface IDataEngine {
   execute?(command: any, options?: Record<string, any>): 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

@@ -47,6 +47,4 @@ export type {
     Middleware,
     IDataEngine,
     IDataDriver,
-    /** @deprecated Use `IDataDriver` instead */
-    DriverInterface
 } from '@objectstack/spec/contracts';

packages/objectql/src/engine.ts

@@ -12,7 +12,7 @@ import {
 } from '@objectstack/spec/data';
 import { parseAutonumberFormat, renderAutonumber, missingFieldValues } from '@objectstack/spec/data';
 import { ExecutionContext, ExecutionContextSchema } from '@objectstack/spec/kernel';
-import { DriverInterface, IDataEngine, Logger, createLogger } from '@objectstack/core';
+import { IDataDriver, IDataEngine, Logger, createLogger } from '@objectstack/core';
 import { CoreServiceName, StorageNameMapping } from '@objectstack/spec/system';
 import { IRealtimeService, RealtimeEventPayload } from '@objectstack/spec/contracts';
 import type { ICryptoProvider, CryptoHandle } from '@objectstack/spec/contracts';
@@ -268,7 +268,7 @@ export class ObjectQL implements IDataEngine {
    */
   private readonly txStore = new AsyncLocalStorage<{ transaction: unknown }>();
 
-  private drivers = new Map<string, DriverInterface>();
+  private drivers = new Map<string, IDataDriver>();
   private defaultDriver: string | null = null;
   private logger: Logger;
 
@@ -399,7 +399,7 @@ export class ObjectQL implements IDataEngine {
             logger: this.logger,
             // Expose the driver registry helper explicitly if needed
             drivers: {
-                register: (driver: DriverInterface) => this.registerDriver(driver)
+                register: (driver: IDataDriver) => this.registerDriver(driver)
             },
             ...this.hostContext
           };
@@ -1206,7 +1206,7 @@ export class ObjectQL implements IDataEngine {
   /**
    * Register a new storage driver
    */
-  registerDriver(driver: DriverInterface, isDefault: boolean = false) {
+  registerDriver(driver: IDataDriver, isDefault: boolean = false) {
     if (this.drivers.has(driver.name)) {
       this.logger.warn('Driver already registered, skipping', { driverName: driver.name });
       return;
@@ -1465,7 +1465,7 @@ export class ObjectQL implements IDataEngine {
    * 3. Package's `defaultDatasource` from manifest
    * 4. Global default driver
    */
-  private getDriver(objectName: string): DriverInterface {
+  private getDriver(objectName: string): IDataDriver {
     const object = this._registry.getObject(objectName);
 
     // 1. Object's explicit datasource field (highest priority)
@@ -2632,7 +2632,7 @@ export class ObjectQL implements IDataEngine {
       // This lets system services (e.g. PackageService, AuditService) issue raw
       // SQL against the control-plane / default DB without having to know the
       // object name behind every CREATE TABLE / SELECT statement.
-      let driver: DriverInterface | undefined;
+      let driver: IDataDriver | undefined;
       if (options?.object) {
           driver = this.getDriver(options.object);
       } else if (options?.datasource && this.drivers.has(options.datasource)) {
@@ -2787,7 +2787,7 @@ export class ObjectQL implements IDataEngine {
    * Unlike the private getDriver() (which resolves by object name),
    * this method directly looks up a driver by its registered name.
    */
-  getDriverByName(name: string): DriverInterface | undefined {
+  getDriverByName(name: string): IDataDriver | undefined {
     return this.drivers.get(name);
   }
 
@@ -2820,9 +2820,9 @@ export class ObjectQL implements IDataEngine {
    * the internal getDriver() used by CRUD operations.
    *
    * @param objectName - FQN or short name of the registered object.
-   * @returns The resolved DriverInterface, or undefined if no driver is available.
+   * @returns The resolved IDataDriver, or undefined if no driver is available.
    */
-  getDriverForObject(objectName: string): DriverInterface | undefined {
+  getDriverForObject(objectName: string): IDataDriver | undefined {
     try {
       return this.getDriver(objectName);
     } catch {
@@ -2907,7 +2907,7 @@ export class ObjectQL implements IDataEngine {
    *
    * @throws Error if the datasource is not found
    */
-  datasource(name: string): DriverInterface {
+  datasource(name: string): IDataDriver {
     const driver = this.drivers.get(name);
     if (!driver) {
       throw new Error(`[ObjectQL] Datasource '${name}' not found`);
@@ -2984,7 +2984,7 @@ export class ObjectQL implements IDataEngine {
    *   });
    */
   static async create(config: {
-    datasources?: Record<string, DriverInterface>;
+    datasources?: Record<string, IDataDriver>;
     objects?: Record<string, ServiceObject>;
     hooks?: Array<{ event: string; object: string; handler: (ctx: HookContext) => Promise<void> | void }>;
   }): Promise<ObjectQL> {

packages/plugins/driver-memory/objectstack.config.ts

@@ -14,7 +14,7 @@ const MemoryDriverPlugin: ObjectStackManifest = {
   version: '1.0.0',
   type: 'driver',
   scope: 'project',
-  description: 'A reference specification implementation of the DriverInterface using in-memory arrays. Suitable for testing and development.',
+  description: 'A reference specification implementation of the IDataDriver interface using in-memory arrays. Suitable for testing and development.',
 
   configuration: {
     title: 'Memory Driver Settings',
@@ -88,7 +88,7 @@ const MemoryDriverPlugin: ObjectStackManifest = {
     provides: [
       {
         id: 'com.objectstack.driver.memory.interface.driver',
-        name: 'DriverInterface',
+        name: 'IDataDriver',
         description: 'Standard ObjectStack driver interface for data operations',
         version: { major: 1, minor: 0, patch: 0 },
         stability: 'stable',

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

@@ -586,7 +586,7 @@ export class SqlDriver implements IDataDriver {
   }
 
   // ===================================
-  // CRUD — DriverInterface core
+  // CRUD — IDataDriver core
   // ===================================
 
   async find(object: string, query: QueryAST, options?: DriverOptions): Promise<any[]> {

packages/spec/api-surface.json

@@ -3423,7 +3423,6 @@
     "DefineSharingRuleInput (interface)",
     "DeployExecutionResult (interface)",
     "DriverCapabilities (interface)",
-    "DriverInterface (type)",
     "EMBEDDER_SERVICE (const)",
     "EmailAddress (type)",
     "EmailAttachment (interface)",

packages/spec/src/contracts/data-engine.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import type { IDataEngine, DriverInterface } from './data-engine';
+import type { IDataEngine } from './data-engine';
 import type { IDataDriver } from './data-driver';
 
 /**
@@ -158,7 +158,7 @@ describe('Data Engine Contract', () => {
     });
   });
 
-  describe('DriverInterface (deprecated alias for IDataDriver)', () => {
+  describe('IDataDriver (driver contract)', () => {
     it('should be assignable from IDataDriver (type alias check)', () => {
       const driver: IDataDriver = {
         name: 'postgres',
@@ -186,8 +186,7 @@ describe('Data Engine Contract', () => {
         dropTable: async () => {},
       };
 
-      // DriverInterface is now a type alias for IDataDriver
-      const driverAsInterface: DriverInterface = driver;
+      const driverAsInterface: IDataDriver = driver;
 
       expect(driverAsInterface.name).toBe('postgres');
       expect(driverAsInterface.version).toBe('1.0.0');
@@ -200,7 +199,7 @@ describe('Data Engine Contract', () => {
     it('should support full IDataDriver lifecycle and CRUD', async () => {
       let connected = false;
 
-      const driver: DriverInterface = {
+      const driver: IDataDriver = {
         name: 'mongo',
         version: '2.0.0',
         supports: minimalCapabilities,
@@ -234,7 +233,7 @@ describe('Data Engine Contract', () => {
     });
 
     it('should support bulk, transaction, and schema operations', async () => {
-      const driver: DriverInterface = {
+      const driver: IDataDriver = {
         name: 'postgres',
         version: '1.0.0',
         supports: { ...minimalCapabilities, transactions: true, bulkCreate: true },
@@ -276,7 +275,7 @@ describe('Data Engine Contract', () => {
 
     it('should support findStream with yielded values', async () => {
       const records = [{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }];
-      const driver: DriverInterface = {
+      const driver: IDataDriver = {
         name: 'streamer',
         version: '1.0.0',
         supports: { ...minimalCapabilities, streaming: true },

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

@@ -10,7 +10,6 @@ import {
   DataEngineRequest,
 } from '../data/index.js';
 
-import type { IDataDriver } from './data-driver.js';
 
 /**
  * IDataEngine - Standard Data Engine Interface
@@ -51,11 +50,3 @@ export interface IDataEngine {
   execute?(command: any, options?: Record<string, any>): Promise<any>;
 }
 
-/**
- * @deprecated Use `IDataDriver` from `@objectstack/spec/contracts` instead.
- * `DriverInterface` is now a type alias for `IDataDriver` — the single authoritative
- * driver contract. All new driver implementations should use `IDataDriver` directly.
- *
- * @see IDataDriver in data-driver.ts for the full contract specification.
- */
-export type DriverInterface = IDataDriver;