@objectql/driver-excel 3.0.1 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectql/driver-excel",
-  "version": "3.0.1",
+  "version": "4.0.0",
   "description": "Excel file driver for ObjectQL - Read/write data from Excel files (.xlsx) with flexible storage modes",
   "keywords": [
     "objectql",
@@ -16,6 +16,7 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
+    "@objectstack/spec": "^0.2.0",
     "exceljs": "^4.4.0",
     "@objectql/types": "3.0.1"
   },

package/src/index.ts

@@ -1,3 +1,11 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
 /**
  * Excel Driver for ObjectQL (Production-Ready)
  * 
@@ -22,10 +30,35 @@
  */
 
 import { Driver, ObjectQLError } from '@objectql/types';
+import { DriverInterface, QueryAST, FilterNode, SortNode } from '@objectstack/spec';
 import * as ExcelJS from 'exceljs';
 import * as fs from 'fs';
 import * as path from 'path';
 
+/**
+ * Command interface for executeCommand method
+ */
+export interface Command {
+    type: 'create' | 'update' | 'delete' | 'bulkCreate' | 'bulkUpdate' | 'bulkDelete';
+    object: string;
+    data?: any;
+    id?: string | number;
+    ids?: Array<string | number>;
+    records?: any[];
+    updates?: Array<{id: string | number, data: any}>;
+    options?: any;
+}
+
+/**
+ * Command result interface
+ */
+export interface CommandResult {
+    success: boolean;
+    data?: any;
+    affected: number;
+    error?: string;
+}
+
 /**
  * File storage mode for the Excel driver.
  */
@@ -64,8 +97,23 @@ export interface ExcelDriverConfig {
  * in a separate worksheet, with the first row containing column headers.
  * 
  * Uses ExcelJS library for secure Excel file operations.
+ * 
+ * Implements both the legacy Driver interface from @objectql/types and
+ * the standard DriverInterface from @objectstack/spec for compatibility
+ * with the new kernel-based plugin system.
  */
-export class ExcelDriver implements Driver {
+export class ExcelDriver implements Driver, DriverInterface {
+    // Driver metadata (ObjectStack-compatible)
+    public readonly name = 'ExcelDriver';
+    public readonly version = '4.0.0';
+    public readonly supports = {
+        transactions: false,
+        joins: false,
+        fullTextSearch: false,
+        jsonFields: true,
+        arrayFields: true
+    };
+
     private config: ExcelDriverConfig;
     private workbook!: ExcelJS.Workbook;
     private workbooks: Map<string, ExcelJS.Workbook>; // For file-per-object mode
@@ -106,6 +154,46 @@ export class ExcelDriver implements Driver {
         await this.loadWorkbook();
     }
 
+    /**
+     * Connect to the database (for DriverInterface compatibility)
+     * This calls init() to load the workbook.
+     */
+    async connect(): Promise<void> {
+        await this.init();
+    }
+
+    /**
+     * Check database connection health
+     */
+    async checkHealth(): Promise<boolean> {
+        try {
+            if (this.fileStorageMode === 'single-file') {
+                // Check if file exists or can be created
+                if (!fs.existsSync(this.filePath)) {
+                    if (!this.config.createIfMissing) {
+                        return false;
+                    }
+                    // Check if directory is writable
+                    const dir = path.dirname(this.filePath);
+                    if (!fs.existsSync(dir)) {
+                        return false;
+                    }
+                }
+                return true;
+            } else {
+                // Check if directory exists or can be created
+                if (!fs.existsSync(this.filePath)) {
+                    if (!this.config.createIfMissing) {
+                        return false;
+                    }
+                }
+                return true;
+            }
+        } catch (error) {
+            return false;
+        }
+    }
+
     /**
      * Factory method to create and initialize the driver.
      */
@@ -507,6 +595,8 @@ export class ExcelDriver implements Driver {
      * Find multiple records matching the query criteria.
      */
     async find(objectName: string, query: any = {}, options?: any): Promise<any[]> {
+        // Normalize query to support both legacy and QueryAST formats
+        const normalizedQuery = this.normalizeQuery(query);
         let results = this.data.get(objectName) || [];
         
         // Return empty array if no data
@@ -518,26 +608,26 @@ export class ExcelDriver implements Driver {
         results = results.map(r => ({ ...r }));
         
         // Apply filters
-        if (query.filters) {
-            results = this.applyFilters(results, query.filters);
+        if (normalizedQuery.filters) {
+            results = this.applyFilters(results, normalizedQuery.filters);
         }
         
         // Apply sorting
-        if (query.sort && Array.isArray(query.sort)) {
-            results = this.applySort(results, query.sort);
+        if (normalizedQuery.sort && Array.isArray(normalizedQuery.sort)) {
+            results = this.applySort(results, normalizedQuery.sort);
         }
         
         // Apply pagination
-        if (query.skip) {
-            results = results.slice(query.skip);
+        if (normalizedQuery.skip) {
+            results = results.slice(normalizedQuery.skip);
         }
-        if (query.limit) {
-            results = results.slice(0, query.limit);
+        if (normalizedQuery.limit) {
+            results = results.slice(0, normalizedQuery.limit);
         }
         
         // Apply field projection
-        if (query.fields && Array.isArray(query.fields)) {
-            results = results.map(doc => this.projectFields(doc, query.fields));
+        if (normalizedQuery.fields && Array.isArray(normalizedQuery.fields)) {
+            results = results.map(doc => this.projectFields(doc, normalizedQuery.fields));
         }
         
         return results;
@@ -784,8 +874,244 @@ export class ExcelDriver implements Driver {
         }
     }
 
+    /**
+     * Execute a query using QueryAST (DriverInterface v4.0 method)
+     * 
+     * This method handles all query operations using the standard QueryAST format
+     * from @objectstack/spec. It converts the AST to the legacy query format
+     * and delegates to the existing find() method.
+     * 
+     * @param ast - The query AST to execute
+     * @param options - Optional execution options
+     * @returns Query results with value array and count
+     */
+    async executeQuery(ast: QueryAST, options?: any): Promise<{ value: any[]; count?: number }> {
+        const objectName = ast.object || '';
+        
+        // Convert QueryAST to legacy query format
+        const legacyQuery: any = {
+            fields: ast.fields,
+            filters: this.convertFilterNodeToLegacy(ast.filters),
+            sort: ast.sort?.map((s: SortNode) => [s.field, s.order]),
+            limit: ast.top,
+            skip: ast.skip,
+        };
+        
+        // Use existing find method
+        const results = await this.find(objectName, legacyQuery, options);
+        
+        return {
+            value: results,
+            count: results.length
+        };
+    }
+
+    /**
+     * Execute a command (DriverInterface v4.0 method)
+     * 
+     * This method handles all mutation operations (create, update, delete)
+     * using a unified command interface.
+     * 
+     * @param command - The command to execute
+     * @param options - Optional execution options
+     * @returns Command execution result
+     */
+    async executeCommand(command: Command, options?: any): Promise<CommandResult> {
+        try {
+            const cmdOptions = { ...options, ...command.options };
+            
+            switch (command.type) {
+                case 'create':
+                    if (!command.data) {
+                        throw new Error('Create command requires data');
+                    }
+                    const created = await this.create(command.object, command.data, cmdOptions);
+                    return {
+                        success: true,
+                        data: created,
+                        affected: 1
+                    };
+                
+                case 'update':
+                    if (!command.id || !command.data) {
+                        throw new Error('Update command requires id and data');
+                    }
+                    const updated = await this.update(command.object, command.id, command.data, cmdOptions);
+                    return {
+                        success: true,
+                        data: updated,
+                        affected: 1
+                    };
+                
+                case 'delete':
+                    if (!command.id) {
+                        throw new Error('Delete command requires id');
+                    }
+                    await this.delete(command.object, command.id, cmdOptions);
+                    return {
+                        success: true,
+                        affected: 1
+                    };
+                
+                case 'bulkCreate':
+                    if (!command.records || !Array.isArray(command.records)) {
+                        throw new Error('BulkCreate command requires records array');
+                    }
+                    const bulkCreated = [];
+                    for (const record of command.records) {
+                        const created = await this.create(command.object, record, cmdOptions);
+                        bulkCreated.push(created);
+                    }
+                    return {
+                        success: true,
+                        data: bulkCreated,
+                        affected: command.records.length
+                    };
+                
+                case 'bulkUpdate':
+                    if (!command.updates || !Array.isArray(command.updates)) {
+                        throw new Error('BulkUpdate command requires updates array');
+                    }
+                    const updateResults = [];
+                    for (const update of command.updates) {
+                        const result = await this.update(command.object, update.id, update.data, cmdOptions);
+                        updateResults.push(result);
+                    }
+                    return {
+                        success: true,
+                        data: updateResults,
+                        affected: command.updates.length
+                    };
+                
+                case 'bulkDelete':
+                    if (!command.ids || !Array.isArray(command.ids)) {
+                        throw new Error('BulkDelete command requires ids array');
+                    }
+                    let deleted = 0;
+                    for (const id of command.ids) {
+                        const result = await this.delete(command.object, id, cmdOptions);
+                        if (result) deleted++;
+                    }
+                    return {
+                        success: true,
+                        affected: deleted
+                    };
+                
+                default:
+                    throw new Error(`Unsupported command type: ${(command as any).type}`);
+            }
+        } catch (error: any) {
+            return {
+                success: false,
+                affected: 0,
+                error: error.message || 'Unknown error occurred'
+            };
+        }
+    }
+
+    /**
+     * Execute raw command (for compatibility)
+     * 
+     * @param command - Command string or object
+     * @param parameters - Command parameters
+     * @param options - Execution options
+     */
+    async execute(command: any, parameters?: any[], options?: any): Promise<any> {
+        throw new Error('Excel driver does not support raw command execution. Use executeCommand() instead.');
+    }
+
     // ========== Helper Methods ==========
 
+    /**
+     * Convert FilterNode from QueryAST to legacy filter format.
+     * 
+     * @param node - The FilterNode to convert
+     * @returns Legacy filter array format
+     */
+    private convertFilterNodeToLegacy(node?: FilterNode): any {
+        if (!node) return undefined;
+        
+        switch (node.type) {
+            case 'comparison':
+                // Convert comparison node to [field, operator, value] format
+                const operator = node.operator || '=';
+                return [[node.field, operator, node.value]];
+            
+            case 'and':
+                // Convert AND node to array with 'and' separator
+                if (!node.children || node.children.length === 0) return undefined;
+                const andResults: any[] = [];
+                for (const child of node.children) {
+                    const converted = this.convertFilterNodeToLegacy(child);
+                    if (converted) {
+                        if (andResults.length > 0) {
+                            andResults.push('and');
+                        }
+                        andResults.push(...(Array.isArray(converted) ? converted : [converted]));
+                    }
+                }
+                return andResults.length > 0 ? andResults : undefined;
+            
+            case 'or':
+                // Convert OR node to array with 'or' separator
+                if (!node.children || node.children.length === 0) return undefined;
+                const orResults: any[] = [];
+                for (const child of node.children) {
+                    const converted = this.convertFilterNodeToLegacy(child);
+                    if (converted) {
+                        if (orResults.length > 0) {
+                            orResults.push('or');
+                        }
+                        orResults.push(...(Array.isArray(converted) ? converted : [converted]));
+                    }
+                }
+                return orResults.length > 0 ? orResults : undefined;
+            
+            case 'not':
+                // NOT is complex - we'll just process the first child for now
+                if (node.children && node.children.length > 0) {
+                    return this.convertFilterNodeToLegacy(node.children[0]);
+                }
+                return undefined;
+            
+            default:
+                return undefined;
+        }
+    }
+
+    /**
+     * Normalizes query format to support both legacy UnifiedQuery and QueryAST formats.
+     * This ensures backward compatibility while supporting the new @objectstack/spec interface.
+     * 
+     * QueryAST format uses 'top' for limit, while UnifiedQuery uses 'limit'.
+     * QueryAST sort is array of {field, order}, while UnifiedQuery is array of [field, order].
+     */
+    private normalizeQuery(query: any): any {
+        if (!query) return {};
+        
+        const normalized: any = { ...query };
+        
+        // Normalize limit/top
+        if (normalized.top !== undefined && normalized.limit === undefined) {
+            normalized.limit = normalized.top;
+        }
+        
+        // Normalize sort format
+        if (normalized.sort && Array.isArray(normalized.sort)) {
+            // Check if it's already in the array format [field, order]
+            const firstSort = normalized.sort[0];
+            if (firstSort && typeof firstSort === 'object' && !Array.isArray(firstSort)) {
+                // Convert from QueryAST format {field, order} to internal format [field, order]
+                normalized.sort = normalized.sort.map((item: any) => [
+                    item.field,
+                    item.order || item.direction || item.dir || 'asc'
+                ]);
+            }
+        }
+        
+        return normalized;
+    }
+
     /**
      * Apply filters to an array of records (in-memory filtering).
      */

package/test/index.test.ts

@@ -1,3 +1,11 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
 /**
  * Excel Driver Tests
  * 
@@ -563,4 +571,180 @@ describe('ExcelDriver', () => {
             expect(deleted).toBeNull();
         });
     });
+
+    describe('DriverInterface v4.0 Methods', () => {
+        describe('executeQuery', () => {
+            it('should execute query with QueryAST format', async () => {
+                await driver.create(TEST_OBJECT, { name: 'Alice', age: 30 });
+                await driver.create(TEST_OBJECT, { name: 'Bob', age: 25 });
+                await driver.create(TEST_OBJECT, { name: 'Charlie', age: 35 });
+
+                const result = await driver.executeQuery({
+                    object: TEST_OBJECT,
+                    fields: ['name', 'age'],
+                    filters: {
+                        type: 'comparison',
+                        field: 'age',
+                        operator: '>',
+                        value: 25
+                    },
+                    sort: [{ field: 'age', order: 'asc' }],
+                    top: 10,
+                    skip: 0
+                });
+
+                expect(result.value).toHaveLength(2);
+                expect(result.value[0].name).toBe('Alice');
+                expect(result.value[1].name).toBe('Charlie');
+                expect(result.count).toBe(2);
+            });
+
+            it('should handle AND filters', async () => {
+                await driver.create(TEST_OBJECT, { name: 'Alice', age: 30, city: 'NYC' });
+                await driver.create(TEST_OBJECT, { name: 'Bob', age: 25, city: 'LA' });
+                await driver.create(TEST_OBJECT, { name: 'Charlie', age: 35, city: 'NYC' });
+
+                const result = await driver.executeQuery({
+                    object: TEST_OBJECT,
+                    filters: {
+                        type: 'and',
+                        children: [
+                            { type: 'comparison', field: 'age', operator: '>', value: 25 },
+                            { type: 'comparison', field: 'city', operator: '=', value: 'NYC' }
+                        ]
+                    }
+                });
+
+                expect(result.value).toHaveLength(2);
+                expect(result.value.every((u: any) => u.city === 'NYC')).toBe(true);
+            });
+
+            it('should handle pagination with skip and top', async () => {
+                await driver.create(TEST_OBJECT, { name: 'Alice', age: 30 });
+                await driver.create(TEST_OBJECT, { name: 'Bob', age: 25 });
+                await driver.create(TEST_OBJECT, { name: 'Charlie', age: 35 });
+
+                const result = await driver.executeQuery({
+                    object: TEST_OBJECT,
+                    sort: [{ field: 'name', order: 'asc' }],
+                    skip: 1,
+                    top: 1
+                });
+
+                expect(result.value).toHaveLength(1);
+                expect(result.value[0].name).toBe('Bob');
+            });
+        });
+
+        describe('executeCommand', () => {
+            it('should execute create command', async () => {
+                const result = await driver.executeCommand({
+                    type: 'create',
+                    object: TEST_OBJECT,
+                    data: { name: 'Alice', email: 'alice@test.com' }
+                });
+
+                expect(result.success).toBe(true);
+                expect(result.affected).toBe(1);
+                expect(result.data).toHaveProperty('id');
+                expect(result.data.name).toBe('Alice');
+            });
+
+            it('should execute update command', async () => {
+                const created = await driver.create(TEST_OBJECT, { name: 'Alice', age: 30 });
+
+                const result = await driver.executeCommand({
+                    type: 'update',
+                    object: TEST_OBJECT,
+                    id: created.id,
+                    data: { age: 31 }
+                });
+
+                expect(result.success).toBe(true);
+                expect(result.affected).toBe(1);
+                expect(result.data.age).toBe(31);
+            });
+
+            it('should execute delete command', async () => {
+                const created = await driver.create(TEST_OBJECT, { name: 'Alice' });
+
+                const result = await driver.executeCommand({
+                    type: 'delete',
+                    object: TEST_OBJECT,
+                    id: created.id
+                });
+
+                expect(result.success).toBe(true);
+                expect(result.affected).toBe(1);
+
+                const remaining = await driver.find(TEST_OBJECT, {});
+                expect(remaining).toHaveLength(0);
+            });
+
+            it('should execute bulkCreate command', async () => {
+                const result = await driver.executeCommand({
+                    type: 'bulkCreate',
+                    object: TEST_OBJECT,
+                    records: [
+                        { name: 'Alice', age: 30 },
+                        { name: 'Bob', age: 25 },
+                        { name: 'Charlie', age: 35 }
+                    ]
+                });
+
+                expect(result.success).toBe(true);
+                expect(result.affected).toBe(3);
+                expect(result.data).toHaveLength(3);
+            });
+
+            it('should execute bulkUpdate command', async () => {
+                const user1 = await driver.create(TEST_OBJECT, { name: 'Alice', age: 30 });
+                const user2 = await driver.create(TEST_OBJECT, { name: 'Bob', age: 25 });
+
+                const result = await driver.executeCommand({
+                    type: 'bulkUpdate',
+                    object: TEST_OBJECT,
+                    updates: [
+                        { id: user1.id, data: { age: 31 } },
+                        { id: user2.id, data: { age: 26 } }
+                    ]
+                });
+
+                expect(result.success).toBe(true);
+                expect(result.affected).toBe(2);
+                expect(result.data).toHaveLength(2);
+            });
+
+            it('should execute bulkDelete command', async () => {
+                const user1 = await driver.create(TEST_OBJECT, { name: 'Alice' });
+                const user2 = await driver.create(TEST_OBJECT, { name: 'Bob' });
+                const user3 = await driver.create(TEST_OBJECT, { name: 'Charlie' });
+
+                const result = await driver.executeCommand({
+                    type: 'bulkDelete',
+                    object: TEST_OBJECT,
+                    ids: [user1.id, user2.id]
+                });
+
+                expect(result.success).toBe(true);
+                expect(result.affected).toBe(2);
+
+                const remaining = await driver.find(TEST_OBJECT, {});
+                expect(remaining).toHaveLength(1);
+                expect(remaining[0].name).toBe('Charlie');
+            });
+
+            it('should return error for invalid command', async () => {
+                const result = await driver.executeCommand({
+                    type: 'create',
+                    object: TEST_OBJECT
+                    // Missing data
+                } as any);
+
+                expect(result.success).toBe(false);
+                expect(result.affected).toBe(0);
+                expect(result.error).toBeDefined();
+            });
+        });
+    });
 });