@objectstack/driver-sql 3.2.9 → 3.3.0

package/src/sql-driver.test.ts

@@ -93,7 +93,7 @@ describe('SqlDriver (SQLite Integration)', () => {
   });
 
   it('should count objects', async () => {
-    const count = await driver.count('users', { age: 17 } as any);
+    const count = await driver.count('users', { where: { age: 17 } } as any);
     expect(count).toBe(2);
   });
 

package/src/sql-driver.ts

@@ -3,12 +3,12 @@
 /**
  * SQL Driver for ObjectStack
  *
- * Implements the standard DriverInterface from @objectstack/spec via Knex.js.
+ * Implements the standard IDataDriver from @objectstack/spec via Knex.js.
  * Supports PostgreSQL, MySQL, SQLite, and other SQL databases.
  */
 
-import type { QueryInput, DriverOptions } from '@objectstack/spec/data';
-import type { DriverInterface } from '@objectstack/core';
+import type { QueryAST, DriverOptions } from '@objectstack/spec/data';
+import type { IDataDriver } from '@objectstack/spec/contracts';
 import knex, { Knex } from 'knex';
 import { nanoid } from 'nanoid';
 
@@ -60,47 +60,79 @@ export type SqlDriverConfig = Knex.Config;
 /**
  * SQL Driver for ObjectStack.
  *
- * Implements the DriverInterface contract via Knex.js for optimal SQL
+ * Implements the IDataDriver contract via Knex.js for optimal SQL
  * generation against PostgreSQL, MySQL, SQLite and other SQL databases.
  */
-export class SqlDriver implements DriverInterface {
-  // DriverInterface metadata
-  public readonly name = 'com.objectstack.driver.sql';
-  public readonly version = '1.0.0';
+export class SqlDriver implements IDataDriver {
+  // IDataDriver metadata
+  public readonly name: string = 'com.objectstack.driver.sql';
+  public readonly version: string = '1.0.0';
   public 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,
-    joins: true,
-    fullTextSearch: false,
-    jsonFields: true,
-    arrayFields: true,
+    savepoints: false,
+
+    // Query Operations
     queryFilters: true,
     queryAggregations: true,
     querySorting: true,
     queryPagination: true,
     queryWindowFunctions: true,
     querySubqueries: true,
+    queryCTE: false,
+    joins: true,
+
+    // Advanced Features
+    fullTextSearch: false,
+    jsonQuery: false,
+    geospatialQuery: false,
+    streaming: false,
+    jsonFields: true,
+    arrayFields: true,
+    vectorSearch: false,
+
+    // Schema Management
+    schemaSync: true,
+    migrations: false,
+    indexes: false,
+
+    // Performance & Optimization
+    connectionPooling: true,
+    preparedStatements: true,
+    queryCache: false,
   };
 
-  private knex: Knex;
-  private config: Knex.Config;
-  private jsonFields: Record<string, string[]> = {};
-  private booleanFields: Record<string, string[]> = {};
-  private tablesWithTimestamps: Set<string> = new Set();
+  protected knex: Knex;
+  protected config: Knex.Config;
+  protected jsonFields: Record<string, string[]> = {};
+  protected booleanFields: Record<string, string[]> = {};
+  protected tablesWithTimestamps: Set<string> = new Set();
 
   /** Whether the underlying database is a SQLite variant (sqlite3 or better-sqlite3). */
-  private get isSqlite(): boolean {
+  protected get isSqlite(): boolean {
     const c = (this.config as any).client;
     return c === 'sqlite3' || c === 'better-sqlite3';
   }
 
   /** Whether the underlying database is PostgreSQL. */
-  private get isPostgres(): boolean {
+  protected get isPostgres(): boolean {
     const c = (this.config as any).client;
     return c === 'pg' || c === 'postgresql';
   }
 
   /** Whether the underlying database is MySQL. */
-  private get isMysql(): boolean {
+  protected get isMysql(): boolean {
     const c = (this.config as any).client;
     return c === 'mysql' || c === 'mysql2';
   }
@@ -135,7 +167,7 @@ export class SqlDriver implements DriverInterface {
   // CRUD — DriverInterface core
   // ===================================
 
-  async find(object: string, query: QueryInput, options?: DriverOptions): Promise<any[]> {
+  async find(object: string, query: QueryAST, options?: DriverOptions): Promise<any[]> {
     const builder = this.getBuilder(object, options);
 
     // SELECT
@@ -145,30 +177,23 @@ export class SqlDriver implements DriverInterface {
       builder.select('*');
     }
 
-    // WHERE — support both `where` (standard) and `filters` (legacy)
-    const filterCondition = query.where || (query as any).filters;
-    if (filterCondition) {
-      this.applyFilters(builder, filterCondition);
+    // WHERE
+    if (query.where) {
+      this.applyFilters(builder, query.where);
     }
 
-    // ORDER BY — support both `orderBy` (standard) and `sort` (legacy)
-    const sortArray = query.orderBy || (query as any).sort;
-    if (sortArray && Array.isArray(sortArray)) {
-      for (const item of sortArray) {
-        const field = item.field || item[0];
-        const dir = item.order || item[1] || 'asc';
-        if (field) {
-          builder.orderBy(this.mapSortField(field), dir);
+    // ORDER BY
+    if (query.orderBy && Array.isArray(query.orderBy)) {
+      for (const item of query.orderBy) {
+        if (item.field) {
+          builder.orderBy(this.mapSortField(item.field), item.order || 'asc');
         }
       }
     }
 
-    // PAGINATION — support both offset/limit (standard) and skip/top (legacy)
-    const offsetValue = query.offset ?? (query as any).skip;
-    const limitValue = query.limit ?? (query as any).top;
-
-    if (offsetValue !== undefined) builder.offset(offsetValue);
-    if (limitValue !== undefined) builder.limit(limitValue);
+    // PAGINATION
+    if (query.offset !== undefined) builder.offset(query.offset);
+    if (query.limit !== undefined) builder.limit(query.limit);
 
     let results: any[];
     try {
@@ -196,7 +221,7 @@ export class SqlDriver implements DriverInterface {
     return results;
   }
 
-  async findOne(object: string, query: QueryInput, options?: DriverOptions): Promise<any> {
+  async findOne(object: string, query: QueryAST, options?: DriverOptions): Promise<any> {
     // When called with a string/number id fall back gracefully
     if (typeof query === 'string' || typeof query === 'number') {
       const res = await this.getBuilder(object, options).where('id', query).first();
@@ -211,6 +236,18 @@ export class SqlDriver implements DriverInterface {
     return null;
   }
 
+  /**
+   * Stream records matching a structured query.
+   * NOTE: Current implementation fetches all results then yields them.
+   * TODO: Use Knex .stream() for true cursor-based streaming on large datasets.
+   */
+  async *findStream(object: string, query: QueryAST, options?: DriverOptions): AsyncGenerator<Record<string, any>> {
+    const results = await this.find(object, query, options);
+    for (const row of results) {
+      yield row;
+    }
+  }
+
   async create(object: string, data: Record<string, any>, options?: DriverOptions): Promise<any> {
     const { _id, ...rest } = data;
     const toInsert = { ...rest };
@@ -247,13 +284,34 @@ export class SqlDriver implements DriverInterface {
     return this.formatOutput(object, updated) || null;
   }
 
-  async delete(object: string, id: string | number, options?: DriverOptions): Promise<any> {
+  async upsert(object: string, data: Record<string, any>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, any>> {
+    const { _id, ...rest } = data;
+    const toUpsert = { ...rest };
+
+    if (_id !== undefined && toUpsert.id === undefined) {
+      toUpsert.id = _id;
+    } else if (toUpsert.id === undefined) {
+      toUpsert.id = nanoid(DEFAULT_ID_LENGTH);
+    }
+
+    const formatted = this.formatInput(object, toUpsert);
+    const mergeKeys = conflictKeys && conflictKeys.length > 0 ? conflictKeys : ['id'];
+
+    const builder = this.getBuilder(object, options);
+    await builder.insert(formatted).onConflict(mergeKeys).merge();
+
+    const result = await this.getBuilder(object, options).where('id', toUpsert.id).first();
+    return this.formatOutput(object, result) || toUpsert;
+  }
+
+  async delete(object: string, id: string | number, options?: DriverOptions): Promise<boolean> {
     const builder = this.getBuilder(object, options);
-    return await builder.where('id', id).delete();
+    const count = await builder.where('id', id).delete();
+    return count > 0;
   }
 
   // ===================================
-  // Optional — bulk & batch
+  // Bulk & Batch Operations
   // ===================================
 
   async bulkCreate(object: string, data: any[], options?: DriverOptions): Promise<any> {
@@ -261,38 +319,50 @@ export class SqlDriver implements DriverInterface {
     return await builder.insert(data).returning('*');
   }
 
-  async updateMany(object: string, query: QueryInput, data: any, options?: DriverOptions): Promise<any> {
+  /**
+   * Batch-update multiple records by ID.
+   * NOTE: Current implementation performs sequential updates for correctness.
+   * TODO: Optimize with SQL CASE statements or batched transactions for performance.
+   */
+  async bulkUpdate(object: string, updates: Array<{ id: string | number; data: Record<string, any> }>, options?: DriverOptions): Promise<Record<string, any>[]> {
+    const results: Record<string, any>[] = [];
+    for (const { id, data } of updates) {
+      const updated = await this.update(object, id, data, options);
+      if (updated) results.push(updated);
+    }
+    return results;
+  }
+
+  async bulkDelete(object: string, ids: Array<string | number>, options?: DriverOptions): Promise<void> {
     const builder = this.getBuilder(object, options);
-    const filters = query.where || (query as any).filters || query;
-    if (filters) this.applyFilters(builder, filters);
+    await builder.whereIn('id', ids).delete();
+  }
+
+  async updateMany(object: string, query: QueryAST, data: any, options?: DriverOptions): Promise<number> {
+    const builder = this.getBuilder(object, options);
+    if (query.where) this.applyFilters(builder, query.where);
     const count = await builder.update(data);
-    return { modifiedCount: count || 0 };
+    return count || 0;
   }
 
-  async deleteMany(object: string, query: QueryInput, options?: DriverOptions): Promise<any> {
+  async deleteMany(object: string, query: QueryAST, options?: DriverOptions): Promise<number> {
     const builder = this.getBuilder(object, options);
-    const filters = query.where || (query as any).filters || query;
-    if (filters) this.applyFilters(builder, filters);
+    if (query.where) this.applyFilters(builder, query.where);
     const count = await builder.delete();
-    return { deletedCount: count || 0 };
+    return count || 0;
   }
 
-  async count(object: string, query: QueryInput, options?: DriverOptions): Promise<number> {
+  async count(object: string, query?: QueryAST, options?: DriverOptions): Promise<number> {
     const builder = this.getBuilder(object, options);
 
-    let actualFilters = query as any;
-    if (query && (query.where || (query as any).filters)) {
-      actualFilters = query.where || (query as any).filters;
-    }
-
-    if (actualFilters) {
-      this.applyFilters(builder, actualFilters);
+    if (query?.where) {
+      this.applyFilters(builder, query.where);
     }
 
     const result = await builder.count<{ count: number }[]>('* as count');
     if (result && result.length > 0) {
       const row: any = result[0];
-      return Number(row.count || row['count(*)']);
+      return Number(row.count ?? row['count(*)'] ?? 0);
     }
     return 0;
   }
@@ -322,12 +392,24 @@ export class SqlDriver implements DriverInterface {
     return await this.knex.transaction();
   }
 
+  /** IDataDriver standard */
+  async commit(transaction: unknown): Promise<void> {
+    await (transaction as Knex.Transaction).commit();
+  }
+
+  /** IDataDriver standard */
+  async rollback(transaction: unknown): Promise<void> {
+    await (transaction as Knex.Transaction).rollback();
+  }
+
+  /** @deprecated Use commit() instead */
   async commitTransaction(trx: Knex.Transaction): Promise<void> {
-    await trx.commit();
+    await this.commit(trx);
   }
 
+  /** @deprecated Use rollback() instead */
   async rollbackTransaction(trx: Knex.Transaction): Promise<void> {
-    await trx.rollback();
+    await this.rollback(trx);
   }
 
   // ===================================
@@ -416,6 +498,11 @@ export class SqlDriver implements DriverInterface {
   // Query Plan Analysis
   // ===================================
 
+  /** IDataDriver standard: analyze query performance */
+  async explain(object: string, query: any, options?: DriverOptions): Promise<any> {
+    return this.analyzeQuery(object, query, options);
+  }
+
   async analyzeQuery(object: string, query: any, options?: DriverOptions): Promise<any> {
     const builder = this.getBuilder(object, options);
 
@@ -476,17 +563,25 @@ export class SqlDriver implements DriverInterface {
 
   async syncSchema(object: string, schema: unknown, _options?: DriverOptions): Promise<void> {
     const objectDef = schema as { name: string; fields?: Record<string, any> };
-    await this.initObjects([objectDef]);
+    // Use the physical table name (`object`) for DDL operations. The caller
+    // (e.g. syncRegisteredSchemas) passes the resolved tableName (e.g. 'sys_user')
+    // while objectDef.name may contain the FQN (e.g. 'sys__user').
+    await this.initObjects([{ ...objectDef, name: object }]);
+  }
+
+  async dropTable(object: string, _options?: DriverOptions): Promise<void> {
+    await this.knex.schema.dropTableIfExists(object);
   }
 
   /**
    * Batch-initialise tables from an array of object definitions.
    */
-  async initObjects(objects: Array<{ name: string; fields?: Record<string, any> }>): Promise<void> {
+  async initObjects(objects: Array<{ name: string; tableName?: string; fields?: Record<string, any> }>): Promise<void> {
     await this.ensureDatabaseExists();
 
     for (const obj of objects) {
-      const tableName = obj.name;
+      // Prefer explicit tableName (physical name) over obj.name (which may be a FQN).
+      const tableName = obj.tableName || obj.name;
 
       const jsonCols: string[] = [];
       const booleanCols: string[] = [];
@@ -516,6 +611,11 @@ export class SqlDriver implements DriverInterface {
         }
       }
 
+      // Columns created unconditionally by initObjects — skip them when
+      // iterating obj.fields to avoid duplicate-column errors (e.g. SQLite
+      // rejects CREATE TABLE with two columns of the same name).
+      const builtinColumns = new Set(['id', 'created_at', 'updated_at']);
+
       if (!exists) {
         await this.knex.schema.createTable(tableName, (table) => {
           table.string('id').primary();
@@ -523,6 +623,7 @@ export class SqlDriver implements DriverInterface {
           table.timestamp('updated_at').defaultTo(this.knex.fn.now());
           if (obj.fields) {
             for (const [name, field] of Object.entries(obj.fields)) {
+              if (builtinColumns.has(name)) continue;
               this.createColumn(table, name, field);
             }
           }
@@ -609,7 +710,7 @@ export class SqlDriver implements DriverInterface {
     return this.knex;
   }
 
-  private getBuilder(object: string, options?: DriverOptions) {
+  protected getBuilder(object: string, options?: DriverOptions) {
     let builder = this.knex(object);
     if (options?.transaction) {
       builder = builder.transacting(options.transaction as Knex.Transaction);
@@ -619,7 +720,7 @@ export class SqlDriver implements DriverInterface {
 
   // ── Filter helpers ──────────────────────────────────────────────────────────
 
-  private applyFilters(builder: Knex.QueryBuilder, filters: any) {
+  protected applyFilters(builder: Knex.QueryBuilder, filters: any) {
     if (!filters) return;
 
     if (!Array.isArray(filters) && typeof filters === 'object') {
@@ -637,7 +738,7 @@ export class SqlDriver implements DriverInterface {
       }
 
       for (const [key, value] of Object.entries(filters)) {
-        if (['filters', 'sort', 'limit', 'skip', 'offset', 'fields', 'orderBy'].includes(key)) continue;
+        if (['limit', 'offset', 'fields', 'orderBy'].includes(key)) continue;
         builder.where(key, value as any);
       }
       return;
@@ -700,7 +801,7 @@ export class SqlDriver implements DriverInterface {
     }
   }
 
-  private applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp: 'and' | 'or' = 'and') {
+  protected applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp: 'and' | 'or' = 'and') {
     if (!condition || typeof condition !== 'object') return;
 
     for (const [key, value] of Object.entries(condition)) {
@@ -771,13 +872,13 @@ export class SqlDriver implements DriverInterface {
 
   // ── Field mapping ───────────────────────────────────────────────────────────
 
-  private mapSortField(field: string): string {
+  protected mapSortField(field: string): string {
     if (field === 'createdAt') return 'created_at';
     if (field === 'updatedAt') return 'updated_at';
     return field;
   }
 
-  private mapAggregateFunc(func: string): string {
+  protected mapAggregateFunc(func: string): string {
     switch (func) {
       case 'count':
         return 'count';
@@ -796,7 +897,7 @@ export class SqlDriver implements DriverInterface {
 
   // ── Window function builder ─────────────────────────────────────────────────
 
-  private buildWindowFunction(spec: any): string {
+  protected buildWindowFunction(spec: any): string {
     const func = spec.function.toUpperCase();
     let sql = `${func}()`;
 
@@ -824,7 +925,7 @@ export class SqlDriver implements DriverInterface {
 
   // ── Column creation helper ──────────────────────────────────────────────────
 
-  private createColumn(table: Knex.CreateTableBuilder, name: string, field: any) {
+  protected createColumn(table: Knex.CreateTableBuilder, name: string, field: any) {
     if (field.multiple) {
       table.json(name);
       return;
@@ -903,13 +1004,23 @@ export class SqlDriver implements DriverInterface {
 
   // ── Database helpers ────────────────────────────────────────────────────────
 
-  private async ensureDatabaseExists() {
-    if (!this.isPostgres) return;
+  protected async ensureDatabaseExists() {
+    // SQLite auto-creates database files — no need to check
+    if (this.isSqlite) return;
+
+    // Only PostgreSQL and MySQL support programmatic database creation
+    if (!this.isPostgres && !this.isMysql) return;
 
     try {
       await this.knex.raw('SELECT 1');
     } catch (e: any) {
-      if (e.code === '3D000') {
+      // PostgreSQL: '3D000' = database does not exist
+      // MySQL:      'ER_BAD_DB_ERROR' (errno 1049) = unknown database
+      if (
+        e.code === '3D000' ||
+        e.code === 'ER_BAD_DB_ERROR' ||
+        e.errno === 1049
+      ) {
         await this.createDatabase();
       } else {
         throw e;
@@ -917,37 +1028,58 @@ export class SqlDriver implements DriverInterface {
     }
   }
 
-  private async createDatabase() {
+  protected async createDatabase() {
     const config = this.config as any;
     const connection = config.connection;
     let dbName = '';
     const adminConfig = { ...config };
 
-    if (typeof connection === 'string') {
-      const url = new URL(connection);
-      dbName = url.pathname.slice(1);
-      url.pathname = '/postgres';
-      adminConfig.connection = url.toString();
+    if (this.isPostgres) {
+      // PostgreSQL: connect to the 'postgres' maintenance database
+      if (typeof connection === 'string') {
+        const url = new URL(connection);
+        dbName = url.pathname.slice(1);
+        url.pathname = '/postgres';
+        adminConfig.connection = url.toString();
+      } else {
+        dbName = connection.database;
+        adminConfig.connection = { ...connection, database: 'postgres' };
+      }
+    } else if (this.isMysql) {
+      // MySQL: connect without specifying a database
+      if (typeof connection === 'string') {
+        const url = new URL(connection);
+        dbName = url.pathname.slice(1);
+        url.pathname = '/';
+        adminConfig.connection = url.toString();
+      } else {
+        dbName = connection.database;
+        const { database: _db, ...rest } = connection;
+        adminConfig.connection = rest;
+      }
     } else {
-      dbName = connection.database;
-      adminConfig.connection = { ...connection, database: 'postgres' };
+      return; // Unsupported dialect for auto-creation
     }
 
     const adminKnex = knex(adminConfig);
     try {
-      await adminKnex.raw(`CREATE DATABASE "${dbName}"`);
+      if (this.isPostgres) {
+        await adminKnex.raw(`CREATE DATABASE "${dbName}"`);
+      } else if (this.isMysql) {
+        await adminKnex.raw(`CREATE DATABASE IF NOT EXISTS \`${dbName}\``);
+      }
     } finally {
       await adminKnex.destroy();
     }
   }
 
-  private isJsonField(type: string, field: any): boolean {
+  protected isJsonField(type: string, field: any): boolean {
     return ['json', 'object', 'array', 'image', 'file', 'avatar', 'location'].includes(type) || field.multiple;
   }
 
   // ── SQLite serialisation ────────────────────────────────────────────────────
 
-  private formatInput(object: string, data: any): any {
+  protected formatInput(object: string, data: any): any {
     if (!this.isSqlite) return data;
 
     const fields = this.jsonFields[object];
@@ -962,7 +1094,7 @@ export class SqlDriver implements DriverInterface {
     return copy;
   }
 
-  private formatOutput(object: string, data: any): any {
+  protected formatOutput(object: string, data: any): any {
     if (!data) return data;
 
     if (this.isSqlite) {
@@ -994,7 +1126,7 @@ export class SqlDriver implements DriverInterface {
 
   // ── Introspection internals ─────────────────────────────────────────────────
 
-  private async introspectColumns(tableName: string): Promise<IntrospectedColumn[]> {
+  protected async introspectColumns(tableName: string): Promise<IntrospectedColumn[]> {
     const columnInfo = await this.knex(tableName).columnInfo();
     const columns: IntrospectedColumn[] = [];
 
@@ -1026,7 +1158,7 @@ export class SqlDriver implements DriverInterface {
     return columns;
   }
 
-  private async introspectForeignKeys(tableName: string): Promise<IntrospectedForeignKey[]> {
+  protected async introspectForeignKeys(tableName: string): Promise<IntrospectedForeignKey[]> {
     const foreignKeys: IntrospectedForeignKey[] = [];
 
     try {
@@ -1112,7 +1244,7 @@ export class SqlDriver implements DriverInterface {
     return foreignKeys;
   }
 
-  private async introspectPrimaryKeys(tableName: string): Promise<string[]> {
+  protected async introspectPrimaryKeys(tableName: string): Promise<string[]> {
     const primaryKeys: string[] = [];
 
     try {
@@ -1172,7 +1304,7 @@ export class SqlDriver implements DriverInterface {
     return primaryKeys;
   }
 
-  private async introspectUniqueConstraints(tableName: string): Promise<string[]> {
+  protected async introspectUniqueConstraints(tableName: string): Promise<string[]> {
     const uniqueColumns: string[] = [];
 
     try {

package/tsconfig.json

@@ -11,7 +11,10 @@
     "skipLibCheck": true,
     "noUnusedLocals": false,
     "noUnusedParameters": false,
-    "forceConsistentCasingInFileNames": true
+    "forceConsistentCasingInFileNames": true,
+    "paths": {
+      "knex": ["./node_modules/knex/types/index.d.ts"]
+    }
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist"]