@objectstack/driver-sql 3.2.9 → 3.3.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/driver-sql@3.2.9 build /home/runner/work/spec/spec/packages/plugins/driver-sql
+> @objectstack/driver-sql@3.3.0 build /home/runner/work/spec/spec/packages/plugins/driver-sql
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.js     34.49 KB
-CJS dist/index.js.map 59.89 KB
-CJS ⚡️ Build success in 137ms
-ESM dist/index.mjs     32.82 KB
-ESM dist/index.mjs.map 59.82 KB
-ESM ⚡️ Build success in 147ms
+ESM dist/index.mjs     36.03 KB
+ESM dist/index.mjs.map 66.38 KB
+ESM ⚡️ Build success in 92ms
+CJS dist/index.js     37.71 KB
+CJS dist/index.js.map 66.46 KB
+CJS ⚡️ Build success in 91ms
 DTS Build start
-DTS ⚡️ Build success in 17850ms
-DTS dist/index.d.mts 4.86 KB
-DTS dist/index.d.ts  4.86 KB
+DTS ⚡️ Build success in 12673ms
+DTS dist/index.d.mts 7.76 KB
+DTS dist/index.d.ts  7.76 KB

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @objectstack/driver-sql
+
+## 3.3.0
+
+### Minor Changes
+
+- 814a6c4: sql driver
+
+### Patch Changes
+
+- @objectstack/spec@3.3.0
+- @objectstack/core@3.3.0

package/dist/index.d.mts

@@ -1,11 +1,11 @@
-import { QueryInput, DriverOptions } from '@objectstack/spec/data';
-import { DriverInterface } from '@objectstack/core';
-import { Knex } from 'knex';
+import { QueryAST, DriverOptions } from '@objectstack/spec/data';
+import { IDataDriver } from '@objectstack/spec/contracts';
+import knex, { Knex } from 'knex';
 
 /**
  * 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.
  */
 
@@ -41,84 +41,138 @@ 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.
  */
-declare class SqlDriver implements DriverInterface {
-    readonly name = "com.objectstack.driver.sql";
-    readonly version = "1.0.0";
+declare class SqlDriver implements IDataDriver {
+    readonly name: string;
+    readonly version: string;
     readonly supports: {
+        create: boolean;
+        read: boolean;
+        update: boolean;
+        delete: boolean;
+        bulkCreate: boolean;
+        bulkUpdate: boolean;
+        bulkDelete: boolean;
         transactions: boolean;
-        joins: boolean;
-        fullTextSearch: boolean;
-        jsonFields: boolean;
-        arrayFields: boolean;
+        savepoints: boolean;
         queryFilters: boolean;
         queryAggregations: boolean;
         querySorting: boolean;
         queryPagination: boolean;
         queryWindowFunctions: boolean;
         querySubqueries: boolean;
+        queryCTE: boolean;
+        joins: boolean;
+        fullTextSearch: boolean;
+        jsonQuery: boolean;
+        geospatialQuery: boolean;
+        streaming: boolean;
+        jsonFields: boolean;
+        arrayFields: boolean;
+        vectorSearch: boolean;
+        schemaSync: boolean;
+        migrations: boolean;
+        indexes: boolean;
+        connectionPooling: boolean;
+        preparedStatements: boolean;
+        queryCache: boolean;
     };
-    private knex;
-    private config;
-    private jsonFields;
-    private booleanFields;
-    private tablesWithTimestamps;
+    protected knex: Knex;
+    protected config: Knex.Config;
+    protected jsonFields: Record<string, string[]>;
+    protected booleanFields: Record<string, string[]>;
+    protected tablesWithTimestamps: Set<string>;
     /** Whether the underlying database is a SQLite variant (sqlite3 or better-sqlite3). */
-    private get isSqlite();
+    protected get isSqlite(): boolean;
     /** Whether the underlying database is PostgreSQL. */
-    private get isPostgres();
+    protected get isPostgres(): boolean;
     /** Whether the underlying database is MySQL. */
-    private get isMysql();
+    protected get isMysql(): boolean;
     constructor(config: SqlDriverConfig);
     connect(): Promise<void>;
     checkHealth(): Promise<boolean>;
     disconnect(): Promise<void>;
-    find(object: string, query: QueryInput, options?: DriverOptions): Promise<any[]>;
-    findOne(object: string, query: QueryInput, options?: DriverOptions): Promise<any>;
+    find(object: string, query: QueryAST, options?: DriverOptions): Promise<any[]>;
+    findOne(object: string, query: QueryAST, options?: DriverOptions): Promise<any>;
+    /**
+     * 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.
+     */
+    findStream(object: string, query: QueryAST, options?: DriverOptions): AsyncGenerator<Record<string, any>>;
     create(object: string, data: Record<string, any>, options?: DriverOptions): Promise<any>;
     update(object: string, id: string | number, data: Record<string, any>, options?: DriverOptions): Promise<any>;
-    delete(object: string, id: string | number, options?: DriverOptions): Promise<any>;
+    upsert(object: string, data: Record<string, any>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, any>>;
+    delete(object: string, id: string | number, options?: DriverOptions): Promise<boolean>;
     bulkCreate(object: string, data: any[], options?: DriverOptions): Promise<any>;
-    updateMany(object: string, query: QueryInput, data: any, options?: DriverOptions): Promise<any>;
-    deleteMany(object: string, query: QueryInput, options?: DriverOptions): Promise<any>;
-    count(object: string, query: QueryInput, options?: DriverOptions): Promise<number>;
+    /**
+     * 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.
+     */
+    bulkUpdate(object: string, updates: Array<{
+        id: string | number;
+        data: Record<string, any>;
+    }>, options?: DriverOptions): Promise<Record<string, any>[]>;
+    bulkDelete(object: string, ids: Array<string | number>, options?: DriverOptions): Promise<void>;
+    updateMany(object: string, query: QueryAST, data: any, options?: DriverOptions): Promise<number>;
+    deleteMany(object: string, query: QueryAST, options?: DriverOptions): Promise<number>;
+    count(object: string, query?: QueryAST, options?: DriverOptions): Promise<number>;
     execute(command: any, params?: any[], options?: DriverOptions): Promise<any>;
     beginTransaction(): Promise<Knex.Transaction>;
+    /** IDataDriver standard */
+    commit(transaction: unknown): Promise<void>;
+    /** IDataDriver standard */
+    rollback(transaction: unknown): Promise<void>;
+    /** @deprecated Use commit() instead */
     commitTransaction(trx: Knex.Transaction): Promise<void>;
+    /** @deprecated Use rollback() instead */
     rollbackTransaction(trx: Knex.Transaction): Promise<void>;
     aggregate(object: string, query: any, options?: DriverOptions): Promise<any>;
     distinct(object: string, field: string, filters?: any, options?: DriverOptions): Promise<any[]>;
     findWithWindowFunctions(object: string, query: any, options?: DriverOptions): Promise<any[]>;
+    /** IDataDriver standard: analyze query performance */
+    explain(object: string, query: any, options?: DriverOptions): Promise<any>;
     analyzeQuery(object: string, query: any, options?: DriverOptions): Promise<any>;
     syncSchema(object: string, schema: unknown, _options?: DriverOptions): Promise<void>;
+    dropTable(object: string, _options?: DriverOptions): Promise<void>;
     /**
      * Batch-initialise tables from an array of object definitions.
      */
     initObjects(objects: Array<{
         name: string;
+        tableName?: string;
         fields?: Record<string, any>;
     }>): Promise<void>;
     introspectSchema(): Promise<IntrospectedSchema>;
     /** Expose the underlying Knex instance for advanced usage. */
     getKnex(): Knex;
-    private getBuilder;
-    private applyFilters;
-    private applyFilterCondition;
-    private mapSortField;
-    private mapAggregateFunc;
-    private buildWindowFunction;
-    private createColumn;
-    private ensureDatabaseExists;
-    private createDatabase;
-    private isJsonField;
-    private formatInput;
-    private formatOutput;
-    private introspectColumns;
-    private introspectForeignKeys;
-    private introspectPrimaryKeys;
-    private introspectUniqueConstraints;
+    protected getBuilder(object: string, options?: DriverOptions): knex.Knex.QueryBuilder<any, {
+        _base: any;
+        _hasSelection: false;
+        _keys: never;
+        _aliases: {};
+        _single: false;
+        _intersectProps: {};
+        _unionProps: never;
+    }[]>;
+    protected applyFilters(builder: Knex.QueryBuilder, filters: any): void;
+    protected applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp?: 'and' | 'or'): void;
+    protected mapSortField(field: string): string;
+    protected mapAggregateFunc(func: string): string;
+    protected buildWindowFunction(spec: any): string;
+    protected createColumn(table: Knex.CreateTableBuilder, name: string, field: any): void;
+    protected ensureDatabaseExists(): Promise<void>;
+    protected createDatabase(): Promise<void>;
+    protected isJsonField(type: string, field: any): boolean;
+    protected formatInput(object: string, data: any): any;
+    protected formatOutput(object: string, data: any): any;
+    protected introspectColumns(tableName: string): Promise<IntrospectedColumn[]>;
+    protected introspectForeignKeys(tableName: string): Promise<IntrospectedForeignKey[]>;
+    protected introspectPrimaryKeys(tableName: string): Promise<string[]>;
+    protected introspectUniqueConstraints(tableName: string): Promise<string[]>;
 }
 
 declare const _default: {

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { QueryInput, DriverOptions } from '@objectstack/spec/data';
-import { DriverInterface } from '@objectstack/core';
-import { Knex } from 'knex';
+import { QueryAST, DriverOptions } from '@objectstack/spec/data';
+import { IDataDriver } from '@objectstack/spec/contracts';
+import knex, { Knex } from 'knex';
 
 /**
  * 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.
  */
 
@@ -41,84 +41,138 @@ 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.
  */
-declare class SqlDriver implements DriverInterface {
-    readonly name = "com.objectstack.driver.sql";
-    readonly version = "1.0.0";
+declare class SqlDriver implements IDataDriver {
+    readonly name: string;
+    readonly version: string;
     readonly supports: {
+        create: boolean;
+        read: boolean;
+        update: boolean;
+        delete: boolean;
+        bulkCreate: boolean;
+        bulkUpdate: boolean;
+        bulkDelete: boolean;
         transactions: boolean;
-        joins: boolean;
-        fullTextSearch: boolean;
-        jsonFields: boolean;
-        arrayFields: boolean;
+        savepoints: boolean;
         queryFilters: boolean;
         queryAggregations: boolean;
         querySorting: boolean;
         queryPagination: boolean;
         queryWindowFunctions: boolean;
         querySubqueries: boolean;
+        queryCTE: boolean;
+        joins: boolean;
+        fullTextSearch: boolean;
+        jsonQuery: boolean;
+        geospatialQuery: boolean;
+        streaming: boolean;
+        jsonFields: boolean;
+        arrayFields: boolean;
+        vectorSearch: boolean;
+        schemaSync: boolean;
+        migrations: boolean;
+        indexes: boolean;
+        connectionPooling: boolean;
+        preparedStatements: boolean;
+        queryCache: boolean;
     };
-    private knex;
-    private config;
-    private jsonFields;
-    private booleanFields;
-    private tablesWithTimestamps;
+    protected knex: Knex;
+    protected config: Knex.Config;
+    protected jsonFields: Record<string, string[]>;
+    protected booleanFields: Record<string, string[]>;
+    protected tablesWithTimestamps: Set<string>;
     /** Whether the underlying database is a SQLite variant (sqlite3 or better-sqlite3). */
-    private get isSqlite();
+    protected get isSqlite(): boolean;
     /** Whether the underlying database is PostgreSQL. */
-    private get isPostgres();
+    protected get isPostgres(): boolean;
     /** Whether the underlying database is MySQL. */
-    private get isMysql();
+    protected get isMysql(): boolean;
     constructor(config: SqlDriverConfig);
     connect(): Promise<void>;
     checkHealth(): Promise<boolean>;
     disconnect(): Promise<void>;
-    find(object: string, query: QueryInput, options?: DriverOptions): Promise<any[]>;
-    findOne(object: string, query: QueryInput, options?: DriverOptions): Promise<any>;
+    find(object: string, query: QueryAST, options?: DriverOptions): Promise<any[]>;
+    findOne(object: string, query: QueryAST, options?: DriverOptions): Promise<any>;
+    /**
+     * 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.
+     */
+    findStream(object: string, query: QueryAST, options?: DriverOptions): AsyncGenerator<Record<string, any>>;
     create(object: string, data: Record<string, any>, options?: DriverOptions): Promise<any>;
     update(object: string, id: string | number, data: Record<string, any>, options?: DriverOptions): Promise<any>;
-    delete(object: string, id: string | number, options?: DriverOptions): Promise<any>;
+    upsert(object: string, data: Record<string, any>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, any>>;
+    delete(object: string, id: string | number, options?: DriverOptions): Promise<boolean>;
     bulkCreate(object: string, data: any[], options?: DriverOptions): Promise<any>;
-    updateMany(object: string, query: QueryInput, data: any, options?: DriverOptions): Promise<any>;
-    deleteMany(object: string, query: QueryInput, options?: DriverOptions): Promise<any>;
-    count(object: string, query: QueryInput, options?: DriverOptions): Promise<number>;
+    /**
+     * 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.
+     */
+    bulkUpdate(object: string, updates: Array<{
+        id: string | number;
+        data: Record<string, any>;
+    }>, options?: DriverOptions): Promise<Record<string, any>[]>;
+    bulkDelete(object: string, ids: Array<string | number>, options?: DriverOptions): Promise<void>;
+    updateMany(object: string, query: QueryAST, data: any, options?: DriverOptions): Promise<number>;
+    deleteMany(object: string, query: QueryAST, options?: DriverOptions): Promise<number>;
+    count(object: string, query?: QueryAST, options?: DriverOptions): Promise<number>;
     execute(command: any, params?: any[], options?: DriverOptions): Promise<any>;
     beginTransaction(): Promise<Knex.Transaction>;
+    /** IDataDriver standard */
+    commit(transaction: unknown): Promise<void>;
+    /** IDataDriver standard */
+    rollback(transaction: unknown): Promise<void>;
+    /** @deprecated Use commit() instead */
     commitTransaction(trx: Knex.Transaction): Promise<void>;
+    /** @deprecated Use rollback() instead */
     rollbackTransaction(trx: Knex.Transaction): Promise<void>;
     aggregate(object: string, query: any, options?: DriverOptions): Promise<any>;
     distinct(object: string, field: string, filters?: any, options?: DriverOptions): Promise<any[]>;
     findWithWindowFunctions(object: string, query: any, options?: DriverOptions): Promise<any[]>;
+    /** IDataDriver standard: analyze query performance */
+    explain(object: string, query: any, options?: DriverOptions): Promise<any>;
     analyzeQuery(object: string, query: any, options?: DriverOptions): Promise<any>;
     syncSchema(object: string, schema: unknown, _options?: DriverOptions): Promise<void>;
+    dropTable(object: string, _options?: DriverOptions): Promise<void>;
     /**
      * Batch-initialise tables from an array of object definitions.
      */
     initObjects(objects: Array<{
         name: string;
+        tableName?: string;
         fields?: Record<string, any>;
     }>): Promise<void>;
     introspectSchema(): Promise<IntrospectedSchema>;
     /** Expose the underlying Knex instance for advanced usage. */
     getKnex(): Knex;
-    private getBuilder;
-    private applyFilters;
-    private applyFilterCondition;
-    private mapSortField;
-    private mapAggregateFunc;
-    private buildWindowFunction;
-    private createColumn;
-    private ensureDatabaseExists;
-    private createDatabase;
-    private isJsonField;
-    private formatInput;
-    private formatOutput;
-    private introspectColumns;
-    private introspectForeignKeys;
-    private introspectPrimaryKeys;
-    private introspectUniqueConstraints;
+    protected getBuilder(object: string, options?: DriverOptions): knex.Knex.QueryBuilder<any, {
+        _base: any;
+        _hasSelection: false;
+        _keys: never;
+        _aliases: {};
+        _single: false;
+        _intersectProps: {};
+        _unionProps: never;
+    }[]>;
+    protected applyFilters(builder: Knex.QueryBuilder, filters: any): void;
+    protected applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp?: 'and' | 'or'): void;
+    protected mapSortField(field: string): string;
+    protected mapAggregateFunc(func: string): string;
+    protected buildWindowFunction(spec: any): string;
+    protected createColumn(table: Knex.CreateTableBuilder, name: string, field: any): void;
+    protected ensureDatabaseExists(): Promise<void>;
+    protected createDatabase(): Promise<void>;
+    protected isJsonField(type: string, field: any): boolean;
+    protected formatInput(object: string, data: any): any;
+    protected formatOutput(object: string, data: any): any;
+    protected introspectColumns(tableName: string): Promise<IntrospectedColumn[]>;
+    protected introspectForeignKeys(tableName: string): Promise<IntrospectedForeignKey[]>;
+    protected introspectPrimaryKeys(tableName: string): Promise<string[]>;
+    protected introspectUniqueConstraints(tableName: string): Promise<string[]>;
 }
 
 declare const _default: {