From 2c6a91dc3054e3de79a0fb564d483a1783bb83b0 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Sat, 27 Jun 2026 23:14:23 +0800 Subject: [PATCH] =?UTF-8?q?feat(spec)!:=20remove=20deprecated=20DriverInte?= =?UTF-8?q?rface=20alias=20=E2=80=94=20use=20IDataDriver=20(11.0,=20#2378)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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: Claude Opus 4.8 --- .../v11-remove-driverinterface-alias.md | 19 ++++++++++++++++ packages/core/src/contracts/data-engine.ts | 5 ----- packages/core/src/index.ts | 2 -- packages/objectql/src/engine.ts | 22 +++++++++---------- .../driver-memory/objectstack.config.ts | 4 ++-- packages/plugins/driver-sql/src/sql-driver.ts | 2 +- packages/spec/api-surface.json | 1 - .../spec/src/contracts/data-engine.test.ts | 13 +++++------ packages/spec/src/contracts/data-engine.ts | 9 -------- 9 files changed, 39 insertions(+), 38 deletions(-) create mode 100644 .changeset/v11-remove-driverinterface-alias.md diff --git a/.changeset/v11-remove-driverinterface-alias.md b/.changeset/v11-remove-driverinterface-alias.md new file mode 100644 index 0000000000..6a68b0701b --- /dev/null +++ b/.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. diff --git a/packages/core/src/contracts/data-engine.ts b/packages/core/src/contracts/data-engine.ts index 4e80f63997..19a1e2e6e3 100644 --- a/packages/core/src/contracts/data-engine.ts +++ b/packages/core/src/contracts/data-engine.ts @@ -49,9 +49,4 @@ export interface IDataEngine { execute?(command: any, options?: Record): Promise; } -/** - * @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'; diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index e717c8b89b..ff3ce5392a 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -47,6 +47,4 @@ export type { Middleware, IDataEngine, IDataDriver, - /** @deprecated Use `IDataDriver` instead */ - DriverInterface } from '@objectstack/spec/contracts'; diff --git a/packages/objectql/src/engine.ts b/packages/objectql/src/engine.ts index e584da41ab..922b00e266 100644 --- a/packages/objectql/src/engine.ts +++ b/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(); + private drivers = new Map(); 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; + datasources?: Record; objects?: Record; hooks?: Array<{ event: string; object: string; handler: (ctx: HookContext) => Promise | void }>; }): Promise { diff --git a/packages/plugins/driver-memory/objectstack.config.ts b/packages/plugins/driver-memory/objectstack.config.ts index c4af9224be..fffe69126e 100644 --- a/packages/plugins/driver-memory/objectstack.config.ts +++ b/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', diff --git a/packages/plugins/driver-sql/src/sql-driver.ts b/packages/plugins/driver-sql/src/sql-driver.ts index d3029a113c..ea70802966 100644 --- a/packages/plugins/driver-sql/src/sql-driver.ts +++ b/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 { diff --git a/packages/spec/api-surface.json b/packages/spec/api-surface.json index 55b80a2615..8f905ef7c8 100644 --- a/packages/spec/api-surface.json +++ b/packages/spec/api-surface.json @@ -3423,7 +3423,6 @@ "DefineSharingRuleInput (interface)", "DeployExecutionResult (interface)", "DriverCapabilities (interface)", - "DriverInterface (type)", "EMBEDDER_SERVICE (const)", "EmailAddress (type)", "EmailAttachment (interface)", diff --git a/packages/spec/src/contracts/data-engine.test.ts b/packages/spec/src/contracts/data-engine.test.ts index 71774f859a..301dd3475f 100644 --- a/packages/spec/src/contracts/data-engine.test.ts +++ b/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 }, diff --git a/packages/spec/src/contracts/data-engine.ts b/packages/spec/src/contracts/data-engine.ts index 91eae01b44..d48cc1e22a 100644 --- a/packages/spec/src/contracts/data-engine.ts +++ b/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): Promise; } -/** - * @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;