@objectql/driver-excel 4.0.2 → 4.0.3

package/src/index.ts

@@ -1,7 +1,5 @@
-import { Data, Driver as DriverSpec } from '@objectstack/spec';
-type QueryAST = Data.QueryAST;
-type SortNode = Data.SortNode;
-type DriverInterface = DriverSpec.DriverInterface;
+import { Data } from '@objectstack/spec';
+type DriverInterface = Data.DriverInterface;
 /**
  * ObjectQL
  * Copyright (c) 2026-present ObjectStack Inc.
@@ -13,54 +11,37 @@ type DriverInterface = DriverSpec.DriverInterface;
 /**
  * Excel Driver for ObjectQL (Production-Ready)
  * 
- * A driver for ObjectQL that reads and writes data from Excel (.xlsx) files.
- * Each worksheet in the Excel file represents an object type, with the first row
- * containing column headers (field names) and subsequent rows containing data.
+ * A persistent Excel-based driver for ObjectQL that stores data in Excel (.xlsx) files.
+ * Extends MemoryDriver with Excel file persistence using ExcelJS.
  * 
- * ✅ Features:
- * - Read data from Excel files
- * - Write data back to Excel files
- * - Multiple sheets support (one sheet per object type)
- * - Full CRUD operations
- * - Query support (filters, sorting, pagination)
- * - Automatic data type handling
- * - Secure: Uses ExcelJS (no known vulnerabilities)
+ * 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.
+ * 
+ * ✅ Production-ready features:
+ * - Persistent storage with Excel files
+ * - Support for both single-file and file-per-object modes
+ * - One worksheet per table/object (e.g., users sheet, projects sheet)
+ * - Atomic write operations
+ * - Full query support (filters, sorting, pagination) inherited from MemoryDriver
+ * - Human-readable Excel format
  * 
  * Use Cases:
  * - Import/export data from Excel spreadsheets
  * - Use Excel as a simple database for prototyping
  * - Data migration from Excel to other databases
  * - Generate reports in Excel format
+ * - Small to medium datasets (< 10k records per object)
  */
 
-import { Driver, ObjectQLError } from '@objectql/types';
-import * as ExcelJS from 'exceljs';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as ExcelJS from 'exceljs';
+import { ObjectQLError } from '@objectql/types';
+import { MemoryDriver, MemoryDriverConfig, Command, CommandResult } from '@objectql/driver-memory';
 
-/**
- * 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;
-}
+// Re-export Command and CommandResult for compatibility
+export type { Command, CommandResult };
 
 /**
  * File storage mode for the Excel driver.
@@ -70,7 +51,7 @@ export type FileStorageMode = 'single-file' | 'file-per-object';
 /**
  * Configuration options for the Excel driver.
  */
-export interface ExcelDriverConfig {
+export interface ExcelDriverConfig extends MemoryDriverConfig {
     /** 
      * Path to the Excel file or directory.
      * - In 'single-file' mode: Path to a single .xlsx file
@@ -87,17 +68,21 @@ export interface ExcelDriverConfig {
     
     /** Optional: Auto-save changes to file (default: true) */
     autoSave?: boolean;
+    
     /** Optional: Create file if it doesn't exist (default: true) */
     createIfMissing?: boolean;
-    /** Optional: Enable strict mode (throw on missing objects) */
-    strictMode?: boolean;
 }
 
 /**
  * Excel Driver Implementation
  * 
- * Stores ObjectQL documents in Excel worksheets. Each object type is stored
- * in a separate worksheet, with the first row containing column headers.
+ * Extends MemoryDriver with Excel file persistence.
+ * All query and aggregation logic is inherited from MemoryDriver.
+ * Only the persistence layer (load/save) is overridden.
+ * 
+ * Stores ObjectQL documents in Excel worksheets with format:
+ * - Single-file mode: All objects as worksheets in one .xlsx file
+ * - File-per-object mode: Each object in a separate .xlsx file
  * 
  * Uses ExcelJS library for secure Excel file operations.
  * 
@@ -105,54 +90,38 @@ export interface ExcelDriverConfig {
  * the standard DriverInterface from @objectstack/spec for compatibility
  * with the new kernel-based plugin system.
  */
-export class ExcelDriver implements Driver {
-    // 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,
-        queryFilters: true,
-        queryAggregations: false,
-        querySorting: true,
-        queryPagination: true,
-        queryWindowFunctions: false,
-        querySubqueries: false
-    };
-
-    private config: ExcelDriverConfig;
-    private workbook!: ExcelJS.Workbook;
-    private workbooks: Map<string, ExcelJS.Workbook>; // For file-per-object mode
-    private data: Map<string, any[]>;
-    private idCounters: Map<string, number>;
+export class ExcelDriver extends MemoryDriver {
     private filePath: string;
     private fileStorageMode: FileStorageMode;
+    private autoSave: boolean;
+    private createIfMissing: boolean;
+    private workbook!: ExcelJS.Workbook; // For single-file mode
+    private workbooks: Map<string, ExcelJS.Workbook>; // For file-per-object mode
+    private fileLocks: Map<string, boolean>; // Simple in-memory file locks
 
     constructor(config: ExcelDriverConfig) {
-        this.config = {
-            autoSave: true,
-            createIfMissing: true,
-            strictMode: false,
-            fileStorageMode: 'single-file',
-            ...config
-        };
+        // Initialize parent with inherited config properties
+        super({
+            strictMode: config.strictMode,
+            initialData: config.initialData,
+            indexes: config.indexes
+        });
+        
+        // Override driver name and version
+        (this as any).name = 'ExcelDriver';
+        (this as any).version = '4.0.0';
         
         this.filePath = path.resolve(config.filePath);
-        this.fileStorageMode = this.config.fileStorageMode!;
-        this.data = new Map<string, any[]>();
-        this.idCounters = new Map<string, number>();
+        this.fileStorageMode = config.fileStorageMode || 'single-file';
+        this.autoSave = config.autoSave !== false;
+        this.createIfMissing = config.createIfMissing !== false;
         this.workbooks = new Map<string, ExcelJS.Workbook>();
-        
+        this.fileLocks = new Map<string, boolean>();
+
         // Initialize workbook for single-file mode
         if (this.fileStorageMode === 'single-file') {
             this.workbook = new ExcelJS.Workbook();
         }
-        
-        // Note: Actual file loading happens in init()
-        // Call init() after construction or use the async create() factory method
     }
 
     /**
@@ -165,56 +134,41 @@ export class ExcelDriver implements Driver {
 
     /**
      * Connect to the database (for DriverInterface compatibility)
-     * This calls init() to load the workbook.
      */
     async connect(): Promise<void> {
         await this.init();
     }
 
+    /**
+     * Factory method to create and initialize the driver.
+     */
+    static async create(config: ExcelDriverConfig): Promise<ExcelDriver> {
+        const driver = new ExcelDriver(config);
+        await driver.init();
+        return driver;
+    }
+
     /**
      * 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;
-                    }
+                if (!fs.existsSync(this.filePath) && !this.createIfMissing) {
+                    return false;
                 }
-                return true;
+                const dir = path.dirname(this.filePath);
+                return fs.existsSync(dir) || this.createIfMissing;
             } else {
-                // Check if directory exists or can be created
-                if (!fs.existsSync(this.filePath)) {
-                    if (!this.config.createIfMissing) {
-                        return false;
-                    }
-                }
-                return true;
+                return fs.existsSync(this.filePath) || this.createIfMissing;
             }
-        } catch (error) {
+        } catch {
             return false;
         }
     }
 
-    /**
-     * Factory method to create and initialize the driver.
-     */
-    static async create(config: ExcelDriverConfig): Promise<ExcelDriver> {
-        const driver = new ExcelDriver(config);
-        await driver.init();
-        return driver;
-    }
-
     /**
      * Load workbook from file or create a new one.
-     * Handles both single-file and file-per-object modes.
      */
     private async loadWorkbook(): Promise<void> {
         if (this.fileStorageMode === 'single-file') {
@@ -225,39 +179,37 @@ export class ExcelDriver implements Driver {
     }
 
     /**
-     * Load workbook in single-file mode (all objects in one Excel file).
+     * Load workbook in single-file mode.
      */
     private async loadSingleFileWorkbook(): Promise<void> {
         this.workbook = new ExcelJS.Workbook();
         
         if (fs.existsSync(this.filePath)) {
+            await this.acquireLock(this.filePath);
             try {
                 await this.workbook.xlsx.readFile(this.filePath);
                 this.loadDataFromWorkbook();
             } catch (error) {
+                this.releaseLock(this.filePath);
                 const errorMessage = (error as Error).message;
                 
-                // Provide helpful error messages for common issues
                 let detailedMessage = `Failed to read Excel file: ${this.filePath}`;
                 if (errorMessage.includes('corrupted') || errorMessage.includes('invalid')) {
                     detailedMessage += ' - File may be corrupted or not a valid .xlsx file';
                 } else if (errorMessage.includes('permission') || errorMessage.includes('EACCES')) {
-                    detailedMessage += ' - Permission denied. Check file permissions.';
+                    detailedMessage += ' - Permission denied';
                 } else if (errorMessage.includes('EBUSY')) {
-                    detailedMessage += ' - File is locked by another process. Close it and try again.';
+                    detailedMessage += ' - File is locked by another process';
                 }
                 
                 throw new ObjectQLError({
                     code: 'FILE_READ_ERROR',
                     message: detailedMessage,
-                    details: { 
-                        filePath: this.filePath,
-                        error: errorMessage 
-                    }
+                    details: { filePath: this.filePath, error: errorMessage }
                 });
             }
-        } else if (this.config.createIfMissing) {
-            // Create new empty workbook
+            this.releaseLock(this.filePath);
+        } else if (this.createIfMissing) {
             await this.saveWorkbook();
         } else {
             throw new ObjectQLError({
@@ -269,12 +221,11 @@ export class ExcelDriver implements Driver {
     }
 
     /**
-     * Load workbooks in file-per-object mode (each object in separate Excel file).
+     * Load workbooks in file-per-object mode.
      */
     private async loadFilePerObjectWorkbooks(): Promise<void> {
-        // Ensure directory exists
         if (!fs.existsSync(this.filePath)) {
-            if (this.config.createIfMissing) {
+            if (this.createIfMissing) {
                 fs.mkdirSync(this.filePath, { recursive: true });
             } else {
                 throw new ObjectQLError({
@@ -285,7 +236,6 @@ export class ExcelDriver implements Driver {
             }
         }
 
-        // Check if it's actually a directory
         const stats = fs.statSync(this.filePath);
         if (!stats.isDirectory()) {
             throw new ObjectQLError({
@@ -295,147 +245,89 @@ export class ExcelDriver implements Driver {
             });
         }
 
-        // Load all existing .xlsx files in the directory
         const files = fs.readdirSync(this.filePath);
         for (const file of files) {
-            if (file.endsWith('.xlsx') && !file.startsWith('~$')) {
+            if (file.endsWith('.xlsx')) {
                 const objectName = file.replace('.xlsx', '');
                 const filePath = path.join(this.filePath, file);
                 
+                await this.acquireLock(filePath);
                 try {
                     const workbook = new ExcelJS.Workbook();
                     await workbook.xlsx.readFile(filePath);
                     this.workbooks.set(objectName, workbook);
-                    
-                    // Load data from first worksheet
-                    const worksheet = workbook.worksheets[0];
-                    if (worksheet) {
-                        this.loadDataFromSingleWorksheet(worksheet, objectName);
-                    }
+                    this.loadDataFromWorkbookForObject(workbook, objectName);
                 } catch (error) {
-                    console.warn(`[ExcelDriver] Warning: Failed to load file ${file}:`, (error as Error).message);
+                    console.warn(`[ExcelDriver] Failed to load ${file}:`, error);
                 }
+                this.releaseLock(filePath);
             }
         }
     }
 
     /**
-     * Load data from workbook into memory.
-     * 
-     * Expected Excel format:
-     * - First row contains column headers (field names)
-     * - Subsequent rows contain data records
-     * - Each worksheet represents one object type
+     * Load all data from single-file workbook into memory.
      */
     private loadDataFromWorkbook(): void {
-        this.workbook.eachSheet((worksheet) => {
-            this.loadDataFromSingleWorksheet(worksheet, worksheet.name);
+        this.workbook.worksheets.forEach(worksheet => {
+            const objectName = worksheet.name;
+            const records = this.parseWorksheet(worksheet);
+            
+            for (const record of records) {
+                const id = record.id || record._id;
+                const key = `${objectName}:${id}`;
+                this.store.set(key, record);
+            }
         });
     }
 
     /**
-     * Load data from a single worksheet into memory.
+     * Load data from workbook for a specific object.
      */
-    private loadDataFromSingleWorksheet(worksheet: ExcelJS.Worksheet, objectName: string): void {
-        const records: any[] = [];
-        
-        // Get headers from first row
-        const headerRow = worksheet.getRow(1);
-        const headers: string[] = [];
-        headerRow.eachCell((cell: any, colNumber: number) => {
-            const headerValue = cell.value;
-            if (headerValue) {
-                headers[colNumber - 1] = String(headerValue);
-            }
-        });
-        
-        // Warn if worksheet has no headers (might be corrupted or wrong format)
-        if (headers.length === 0 && worksheet.rowCount > 0) {
-            console.warn(`[ExcelDriver] Warning: Worksheet "${objectName}" has no headers in first row. Skipping.`);
-            return;
-        }
-        
-        // Skip first row (headers) and read data rows
-        let rowsProcessed = 0;
-        let rowsSkipped = 0;
-        
-        worksheet.eachRow((row: any, rowNumber: number) => {
-            if (rowNumber === 1) return; // Skip header row
-            
-            const record: any = {};
-            let hasData = false;
-            
-            row.eachCell((cell: any, colNumber: number) => {
-                const header = headers[colNumber - 1];
-                if (header) {
-                    record[header] = cell.value;
-                    hasData = true;
-                }
-            });
+    private loadDataFromWorkbookForObject(workbook: ExcelJS.Workbook, objectName: string): void {
+        workbook.worksheets.forEach(worksheet => {
+            const records = this.parseWorksheet(worksheet);
             
-            // Skip completely empty rows
-            if (!hasData) {
-                rowsSkipped++;
-                return;
-            }
-            
-            // Ensure ID exists
-            if (!record.id) {
-                record.id = this.generateId(objectName);
+            for (const record of records) {
+                const id = record.id || record._id;
+                const key = `${objectName}:${id}`;
+                this.store.set(key, record);
             }
-            
-            records.push(record);
-            rowsProcessed++;
         });
-        
-        // Log summary for debugging
-        if (rowsSkipped > 0) {
-            console.warn(`[ExcelDriver] Worksheet "${objectName}": Processed ${rowsProcessed} rows, skipped ${rowsSkipped} empty rows`);
-        }
-        
-        this.data.set(objectName, records);
-        this.updateIdCounter(objectName, records);
     }
 
     /**
-     * Update ID counter based on existing records.
-     * 
-     * Attempts to extract counter from auto-generated IDs (format: objectName-timestamp-counter).
-     * If IDs don't follow this format, counter starts from existing record count.
+     * Parse worksheet into array of records.
      */
-    private updateIdCounter(objectName: string, records: any[]): void {
-        let maxCounter = 0;
-        for (const record of records) {
-            if (record.id) {
-                // Try to extract counter from generated IDs (format: objectName-timestamp-counter)
-                const idStr = String(record.id);
-                const parts = idStr.split('-');
-                
-                // Only parse if it matches the expected auto-generated format
-                if (parts.length === 3 && parts[0] === objectName && !isNaN(Number(parts[2]))) {
-                    const counter = Number(parts[2]);
-                    if (counter > maxCounter) {
-                        maxCounter = counter;
+    private parseWorksheet(worksheet: ExcelJS.Worksheet): any[] {
+        const records: any[] = [];
+        const headers: string[] = [];
+        
+        worksheet.eachRow((row, rowNumber) => {
+            if (rowNumber === 1) {
+                row.eachCell((cell) => {
+                    headers.push(String(cell.value || ''));
+                });
+            } else {
+                const record: any = {};
+                row.eachCell((cell, colNumber) => {
+                    const header = headers[colNumber - 1];
+                    if (header) {
+                        record[header] = cell.value;
                     }
+                });
+                if (Object.keys(record).length > 0) {
+                    records.push(record);
                 }
             }
-        }
-        
-        // If no auto-generated IDs found, start from record count to avoid collisions
-        if (maxCounter === 0 && records.length > 0) {
-            maxCounter = records.length;
-        }
+        });
         
-        this.idCounters.set(objectName, maxCounter);
+        return records;
     }
 
     /**
      * Save workbook to file.
      */
-    /**
-     * Save workbook to file.
-     * Handles both single-file and file-per-object modes.
-     */
     private async saveWorkbook(objectName?: string): Promise<void> {
         if (this.fileStorageMode === 'single-file') {
             await this.saveSingleFileWorkbook();
@@ -448,14 +340,13 @@ export class ExcelDriver implements Driver {
      * Save workbook in single-file mode.
      */
     private async saveSingleFileWorkbook(): Promise<void> {
+        const dir = path.dirname(this.filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        
+        await this.acquireLock(this.filePath);
         try {
-            // Ensure directory exists
-            const dir = path.dirname(this.filePath);
-            if (!fs.existsSync(dir)) {
-                fs.mkdirSync(dir, { recursive: true });
-            }
-            
-            // Write workbook to file
             await this.workbook.xlsx.writeFile(this.filePath);
         } catch (error) {
             throw new ObjectQLError({
@@ -463,6 +354,8 @@ export class ExcelDriver implements Driver {
                 message: `Failed to write Excel file: ${this.filePath}`,
                 details: { error: (error as Error).message }
             });
+        } finally {
+            this.releaseLock(this.filePath);
         }
     }
 
@@ -479,8 +372,9 @@ export class ExcelDriver implements Driver {
             });
         }
 
+        const filePath = path.join(this.filePath, `${objectName}.xlsx`);
+        await this.acquireLock(filePath);
         try {
-            const filePath = path.join(this.filePath, `${objectName}.xlsx`);
             await workbook.xlsx.writeFile(filePath);
         } catch (error) {
             throw new ObjectQLError({
@@ -488,13 +382,13 @@ export class ExcelDriver implements Driver {
                 message: `Failed to write Excel file for object: ${objectName}`,
                 details: { objectName, error: (error as Error).message }
             });
+        } finally {
+            this.releaseLock(filePath);
         }
     }
 
     /**
-     * Sync in-memory data to workbook.
-     * 
-     * Creates or updates a worksheet for the given object type.
+     * Sync in-memory data to workbook and save.
      */
     private async syncToWorkbook(objectName: string): Promise<void> {
         if (this.fileStorageMode === 'single-file') {
@@ -508,7 +402,7 @@ export class ExcelDriver implements Driver {
      * Sync data to worksheet in single-file mode.
      */
     private async syncToSingleFileWorkbook(objectName: string): Promise<void> {
-        const records = this.data.get(objectName) || [];
+        const records = this.getObjectRecords(objectName);
         
         // Remove existing worksheet if it exists
         const existingSheet = this.workbook.getWorksheet(objectName);
@@ -518,34 +412,9 @@ export class ExcelDriver implements Driver {
         
         // Create new worksheet
         const worksheet = this.workbook.addWorksheet(objectName);
+        this.populateWorksheet(worksheet, records);
         
-        if (records.length > 0) {
-            // Get all unique keys from records to create headers
-            const headers = new Set<string>();
-            records.forEach(record => {
-                Object.keys(record).forEach(key => headers.add(key));
-            });
-            const headerArray = Array.from(headers);
-            
-            // Add header row
-            worksheet.addRow(headerArray);
-            
-            // Add data rows
-            records.forEach(record => {
-                const row = headerArray.map(header => record[header]);
-                worksheet.addRow(row);
-            });
-            
-            // Auto-fit columns
-            worksheet.columns.forEach((column: any) => {
-                if (column.header) {
-                    column.width = Math.max(10, String(column.header).length + 2);
-                }
-            });
-        }
-        
-        // Auto-save if enabled
-        if (this.config.autoSave) {
+        if (this.autoSave) {
             await this.saveWorkbook();
         }
     }
@@ -554,9 +423,8 @@ export class ExcelDriver implements Driver {
      * Sync data to separate file in file-per-object mode.
      */
     private async syncToFilePerObjectWorkbook(objectName: string): Promise<void> {
-        const records = this.data.get(objectName) || [];
+        const records = this.getObjectRecords(objectName);
         
-        // Get or create workbook for this object
         let workbook = this.workbooks.get(objectName);
         if (!workbook) {
             workbook = new ExcelJS.Workbook();
@@ -568,789 +436,145 @@ export class ExcelDriver implements Driver {
         
         // Create new worksheet
         const worksheet = workbook.addWorksheet(objectName);
+        this.populateWorksheet(worksheet, records);
         
-        if (records.length > 0) {
-            // Get all unique keys from records to create headers
-            const headers = new Set<string>();
-            records.forEach(record => {
-                Object.keys(record).forEach(key => headers.add(key));
-            });
-            const headerArray = Array.from(headers);
-            
-            // Add header row
-            worksheet.addRow(headerArray);
-            
-            // Add data rows
-            records.forEach(record => {
-                const row = headerArray.map(header => record[header]);
-                worksheet.addRow(row);
-            });
-            
-            // Auto-fit columns
-            worksheet.columns.forEach((column: any) => {
-                if (column.header) {
-                    column.width = Math.max(10, String(column.header).length + 2);
-                }
-            });
-        }
-        
-        // Auto-save if enabled
-        if (this.config.autoSave) {
+        if (this.autoSave) {
             await this.saveWorkbook(objectName);
         }
     }
 
     /**
-     * Find multiple records matching the query criteria.
+     * Get all records for an object from memory store.
      */
-    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
-        if (results.length === 0) {
-            return [];
-        }
-        
-        // Deep copy to avoid mutations
-        results = results.map(r => ({ ...r }));
+    private getObjectRecords(objectName: string): any[] {
+        const records: any[] = [];
+        const prefix = `${objectName}:`;
         
-        // Apply filters from where clause (QueryAST format)
-        if (normalizedQuery.where) {
-            const legacyFilters = this.convertFilterConditionToArray(normalizedQuery.where);
-            if (legacyFilters) {
-                results = this.applyFilters(results, legacyFilters);
+        for (const [key, value] of this.store.entries()) {
+            if (key.startsWith(prefix)) {
+                records.push(value);
             }
         }
         
-        // Apply filters from legacy filters clause
-        if (normalizedQuery.filters) {
-            results = this.applyFilters(results, normalizedQuery.filters);
-        }
-        
-        // Apply sorting from orderBy (QueryAST format)
-        if (normalizedQuery.orderBy && Array.isArray(normalizedQuery.orderBy)) {
-            results = this.applySort(results, normalizedQuery.orderBy);
-        }
-        
-        // Apply sorting from legacy sort clause
-        if (normalizedQuery.sort && Array.isArray(normalizedQuery.sort)) {
-            results = this.applySort(results, normalizedQuery.sort);
-        }
-        
-        // Apply pagination with offset (QueryAST format)
-        if (normalizedQuery.offset) {
-            results = results.slice(normalizedQuery.offset);
-        }
-        
-        // Apply pagination with skip (legacy format)
-        if (normalizedQuery.skip) {
-            results = results.slice(normalizedQuery.skip);
-        }
-        
-        if (normalizedQuery.limit) {
-            results = results.slice(0, normalizedQuery.limit);
-        }
-        
-        // Apply field projection
-        if (normalizedQuery.fields && Array.isArray(normalizedQuery.fields)) {
-            results = results.map(doc => this.projectFields(doc, normalizedQuery.fields));
-        }
-        
-        return results;
+        return records;
     }
 
     /**
-     * Find a single record by ID or query.
+     * Populate worksheet with records.
      */
-    async findOne(objectName: string, id: string | number, query?: any, options?: any): Promise<any> {
-        const records = this.data.get(objectName) || [];
-        
-        // If ID is provided, fetch directly
-        if (id) {
-            const record = records.find(r => r.id === String(id));
-            return record ? { ...record } : null;
-        }
-        
-        // If query is provided, use find and return first result
-        if (query) {
-            const results = await this.find(objectName, { ...query, limit: 1 }, options);
-            return results[0] || null;
+    private populateWorksheet(worksheet: ExcelJS.Worksheet, records: any[]): void {
+        if (records.length === 0) {
+            return;
         }
-        
-        return null;
-    }
 
-    /**
-     * Create a new record.
-     */
-    async create(objectName: string, data: any, options?: any): Promise<any> {
-        // Get or create object data array
-        if (!this.data.has(objectName)) {
-            this.data.set(objectName, []);
-        }
-        
-        const records = this.data.get(objectName)!;
-        
-        // Generate ID if not provided
-        const id = data.id || this.generateId(objectName);
-        
-        // Check if record already exists
-        if (records.some(r => r.id === id)) {
-            throw new ObjectQLError({
-                code: 'DUPLICATE_RECORD',
-                message: `Record with id '${id}' already exists in '${objectName}'`,
-                details: { objectName, id }
-            });
-        }
-        
-        const now = new Date().toISOString();
-        const doc = {
-            id,
-            ...data,
-            created_at: data.created_at || now,
-            updated_at: data.updated_at || now
-        };
+        // Get all unique keys from records to create headers
+        const headers = new Set<string>();
+        records.forEach(record => {
+            Object.keys(record).forEach(key => headers.add(key));
+        });
+        const headerArray = Array.from(headers);
         
-        records.push(doc);
-        await this.syncToWorkbook(objectName);
+        // Add header row
+        worksheet.addRow(headerArray);
         
-        return { ...doc };
-    }
-
-    /**
-     * Update an existing record.
-     */
-    async update(objectName: string, id: string | number, data: any, options?: any): Promise<any> {
-        const records = this.data.get(objectName) || [];
-        const index = records.findIndex(r => r.id === String(id));
+        // Add data rows
+        records.forEach(record => {
+            const row = headerArray.map(header => record[header]);
+            worksheet.addRow(row);
+        });
         
-        if (index === -1) {
-            if (this.config.strictMode) {
-                throw new ObjectQLError({
-                    code: 'RECORD_NOT_FOUND',
-                    message: `Record with id '${id}' not found in '${objectName}'`,
-                    details: { objectName, id }
-                });
+        // Auto-fit columns
+        worksheet.columns.forEach((column: any) => {
+            if (column.header) {
+                column.width = Math.max(10, String(column.header).length + 2);
             }
-            return null;
-        }
-        
-        const existing = records[index];
-        const doc = {
-            ...existing,
-            ...data,
-            id: existing.id, // Preserve ID
-            created_at: existing.created_at, // Preserve created_at
-            updated_at: new Date().toISOString()
-        };
-        
-        records[index] = doc;
-        await this.syncToWorkbook(objectName);
-        
-        return { ...doc };
+        });
     }
 
     /**
-     * Delete a record.
+     * Simple file locking mechanism.
      */
-    async delete(objectName: string, id: string | number, options?: any): Promise<any> {
-        const records = this.data.get(objectName) || [];
-        const index = records.findIndex(r => r.id === String(id));
+    private async acquireLock(filePath: string): Promise<void> {
+        const maxRetries = 10;
+        const retryDelay = 100;
         
-        if (index === -1) {
-            if (this.config.strictMode) {
-                throw new ObjectQLError({
-                    code: 'RECORD_NOT_FOUND',
-                    message: `Record with id '${id}' not found in '${objectName}'`,
-                    details: { objectName, id }
-                });
+        for (let i = 0; i < maxRetries; i++) {
+            if (!this.fileLocks.get(filePath)) {
+                this.fileLocks.set(filePath, true);
+                return;
             }
-            return false;
+            await new Promise(resolve => setTimeout(resolve, retryDelay));
         }
         
-        records.splice(index, 1);
-        await this.syncToWorkbook(objectName);
-        
-        return true;
-    }
-
-    /**
-     * Count records matching filters.
-     */
-    async count(objectName: string, filters: any, options?: any): Promise<number> {
-        const records = this.data.get(objectName) || [];
-        
-        // Extract actual filters from query object
-        let actualFilters = filters;
-        
-        // Support QueryAST format with 'where' clause
-        if (filters && filters.where) {
-            actualFilters = this.convertFilterConditionToArray(filters.where);
-        }
-        // Support legacy format with 'filters' clause
-        else if (filters && !Array.isArray(filters) && filters.filters) {
-            actualFilters = filters.filters;
-        }
-        
-        // If no filters or empty object/array, return total count
-        if (!actualFilters || 
-            (Array.isArray(actualFilters) && actualFilters.length === 0) ||
-            (typeof actualFilters === 'object' && !Array.isArray(actualFilters) && Object.keys(actualFilters).length === 0)) {
-            return records.length;
-        }
-        
-        // Count only records matching filters
-        return records.filter(record => this.matchesFilters(record, actualFilters)).length;
+        throw new ObjectQLError({
+            code: 'FILE_LOCK_TIMEOUT',
+            message: `Failed to acquire lock for file: ${filePath}`,
+            details: { filePath }
+        });
     }
 
     /**
-     * Get distinct values for a field.
+     * Release file lock.
      */
-    async distinct(objectName: string, field: string, filters?: any, options?: any): Promise<any[]> {
-        const records = this.data.get(objectName) || [];
-        const values = new Set<any>();
-        
-        for (const record of records) {
-            if (!filters || this.matchesFilters(record, filters)) {
-                const value = record[field];
-                if (value !== undefined && value !== null) {
-                    values.add(value);
-                }
-            }
-        }
-        
-        return Array.from(values);
+    private releaseLock(filePath: string): void {
+        this.fileLocks.delete(filePath);
     }
 
     /**
-     * Create multiple records at once.
+     * Override create to persist to Excel.
      */
-    async createMany(objectName: string, data: any[], options?: any): Promise<any> {
-        const results = [];
-        for (const item of data) {
-            const result = await this.create(objectName, item, options);
-            results.push(result);
-        }
-        return results;
+    async create(objectName: string, data: any, options?: any): Promise<any> {
+        const result = await super.create(objectName, data, options);
+        await this.syncToWorkbook(objectName);
+        return result;
     }
 
     /**
-     * Update multiple records matching filters.
+     * Override update to persist to Excel.
      */
-    async updateMany(objectName: string, filters: any, data: any, options?: any): Promise<any> {
-        const records = this.data.get(objectName) || [];
-        let count = 0;
-        
-        for (let i = 0; i < records.length; i++) {
-            if (this.matchesFilters(records[i], filters)) {
-                records[i] = {
-                    ...records[i],
-                    ...data,
-                    id: records[i].id, // Preserve ID
-                    created_at: records[i].created_at, // Preserve created_at
-                    updated_at: new Date().toISOString()
-                };
-                count++;
-            }
-        }
-        
-        if (count > 0) {
+    async update(objectName: string, id: string | number, data: any, options?: any): Promise<any> {
+        const result = await super.update(objectName, id, data, options);
+        if (result) {
             await this.syncToWorkbook(objectName);
         }
-        
-        return { modifiedCount: count };
+        return result;
     }
 
     /**
-     * Delete multiple records matching filters.
+     * Override delete to persist to Excel.
      */
-    async deleteMany(objectName: string, filters: any, options?: any): Promise<any> {
-        const records = this.data.get(objectName) || [];
-        const initialLength = records.length;
-        
-        const filtered = records.filter(record => !this.matchesFilters(record, filters));
-        this.data.set(objectName, filtered);
-        
-        const deletedCount = initialLength - filtered.length;
-        
-        if (deletedCount > 0) {
+    async delete(objectName: string, id: string | number, options?: any): Promise<any> {
+        const result = await super.delete(objectName, id, options);
+        if (result) {
             await this.syncToWorkbook(objectName);
         }
-        
-        return { deletedCount };
+        return result;
     }
 
     /**
-     * Manually save the workbook to file.
-     */
-    /**
-     * Manually save the workbook to file.
+     * Manually save all data to Excel file(s).
      */
     async save(): Promise<void> {
         if (this.fileStorageMode === 'single-file') {
-            await this.saveWorkbook();
-        } else {
-            // Save all object files in file-per-object mode
-            for (const objectName of this.data.keys()) {
-                await this.saveWorkbook(objectName);
-            }
-        }
-    }
-
-    /**
-     * Disconnect (flush any pending writes).
-     */
-    async disconnect(): Promise<void> {
-        if (this.config.autoSave) {
-            await this.save();
-        }
-    }
-
-    /**
-     * 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
-        // Note: Convert FilterCondition (MongoDB-like) to array format for excel driver
-        const legacyQuery: any = {
-            fields: ast.fields,
-            filters: this.convertFilterConditionToArray(ast.where),
-            sort: ast.orderBy?.map((s: SortNode) => [s.field, s.order]),
-            limit: ast.limit,
-            skip: ast.offset,
-        };
-        
-        // 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 FilterCondition (MongoDB-like format) to legacy array format.
-     * This allows the excel driver to use its existing filter evaluation logic.
-     * 
-     * @param condition - FilterCondition object or legacy array
-     * @returns Legacy filter array format
-     */
-    private convertFilterConditionToArray(condition?: any): any[] | undefined {
-        if (!condition) return undefined;
-        
-        // If already an array, return as-is
-        if (Array.isArray(condition)) {
-            return condition;
-        }
-        
-        // If it's an object (FilterCondition), convert to array format
-        // This is a simplified conversion - a full implementation would need to handle all operators
-        const result: any[] = [];
-        
-        for (const [key, value] of Object.entries(condition)) {
-            if (key === '$and' && Array.isArray(value)) {
-                // Handle $and: [cond1, cond2, ...]
-                for (let i = 0; i < value.length; i++) {
-                    const converted = this.convertFilterConditionToArray(value[i]);
-                    if (converted && converted.length > 0) {
-                        if (result.length > 0) {
-                            result.push('and');
-                        }
-                        result.push(...converted);
-                    }
-                }
-            } else if (key === '$or' && Array.isArray(value)) {
-                // Handle $or: [cond1, cond2, ...]
-                for (let i = 0; i < value.length; i++) {
-                    const converted = this.convertFilterConditionToArray(value[i]);
-                    if (converted && converted.length > 0) {
-                        if (result.length > 0) {
-                            result.push('or');
-                        }
-                        result.push(...converted);
-                    }
-                }
-            } else if (key === '$not' && typeof value === 'object') {
-                // Handle $not: { condition }
-                // Note: NOT is complex to represent in array format, so we skip it for now
-                const converted = this.convertFilterConditionToArray(value);
-                if (converted) {
-                    result.push(...converted);
-                }
-            } else if (typeof value === 'object' && value !== null) {
-                // Handle field-level conditions like { field: { $eq: value } }
-                const field = key;
-                for (const [operator, operandValue] of Object.entries(value)) {
-                    let op: string;
-                    switch (operator) {
-                        case '$eq': op = '='; break;
-                        case '$ne': op = '!='; break;
-                        case '$gt': op = '>'; break;
-                        case '$gte': op = '>='; break;
-                        case '$lt': op = '<'; break;
-                        case '$lte': op = '<='; break;
-                        case '$in': op = 'in'; break;
-                        case '$nin': op = 'nin'; break;
-                        case '$regex': op = 'like'; break;
-                        default: op = '=';
-                    }
-                    result.push([field, op, operandValue]);
-                }
-            } else {
-                // Handle simple equality: { field: value }
-                result.push([key, '=', value]);
-            }
-        }
-        
-        return result.length > 0 ? result : 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, 'offset' for skip, and 'orderBy' for sort.
-     * QueryAST uses 'where' for filters with MongoDB-like operators.
-     * UnifiedQuery uses 'limit', 'skip', 'sort', and 'filters'.
-     */
-    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 offset/skip (both are preserved for backward compatibility)
-        // The find() method will check both
-        
-        // Normalize orderBy to sort format if orderBy is present
-        if (normalized.orderBy && Array.isArray(normalized.orderBy)) {
-            // Check if it's already in the legacy array format [field, order]
-            const firstSort = normalized.orderBy[0];
-            if (firstSort && typeof firstSort === 'object' && !Array.isArray(firstSort) && firstSort.field) {
-                // It's in QueryAST format {field, order}, keep as-is
-                // The find() method will handle it
-                normalized.orderBy = normalized.orderBy;
-            }
-        }
-        
-        // Normalize sort format (legacy)
-        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).
-     */
-    private applyFilters(records: any[], filters: any[]): any[] {
-        if (!filters || filters.length === 0) {
-            return records;
-        }
-        
-        return records.filter(record => this.matchesFilters(record, filters));
-    }
-
-    /**
-     * Check if a single record matches the filter conditions.
-     */
-    private matchesFilters(record: any, filters: any[]): boolean {
-        if (!filters || filters.length === 0) {
-            return true;
-        }
-        
-        let conditions: boolean[] = [];
-        let operators: string[] = [];
-        
-        for (const item of filters) {
-            if (typeof item === 'string') {
-                // Logical operator (and/or)
-                operators.push(item.toLowerCase());
-            } else if (Array.isArray(item)) {
-                const [field, operator, value] = item;
-                
-                // Handle nested filter groups
-                if (typeof field !== 'string') {
-                    // Nested group - recursively evaluate
-                    conditions.push(this.matchesFilters(record, item));
-                } else {
-                    // Single condition
-                    const matches = this.evaluateCondition(record[field], operator, value);
-                    conditions.push(matches);
-                }
+            // Sync all objects to single file (collect unique object names first)
+            const objectNames = new Set<string>();
+            for (const [key] of this.store.entries()) {
+                objectNames.add(key.split(':')[0]);
             }
-        }
-        
-        // Combine conditions with operators
-        if (conditions.length === 0) {
-            return true;
-        }
-        
-        let result = conditions[0];
-        for (let i = 0; i < operators.length; i++) {
-            const op = operators[i];
-            const nextCondition = conditions[i + 1];
-            
-            if (op === 'or') {
-                result = result || nextCondition;
-            } else { // 'and' or default
-                result = result && nextCondition;
+            for (const objectName of objectNames) {
+                await this.syncToSingleFileWorkbook(objectName);
             }
-        }
-        
-        return result;
-    }
-
-    /**
-     * Evaluate a single filter condition.
-     */
-    private evaluateCondition(fieldValue: any, operator: string, compareValue: any): boolean {
-        switch (operator) {
-            case '=':
-            case '==':
-                return fieldValue === compareValue;
-            case '!=':
-            case '<>':
-                return fieldValue !== compareValue;
-            case '>':
-                return fieldValue > compareValue;
-            case '>=':
-                return fieldValue >= compareValue;
-            case '<':
-                return fieldValue < compareValue;
-            case '<=':
-                return fieldValue <= compareValue;
-            case 'in':
-                return Array.isArray(compareValue) && compareValue.includes(fieldValue);
-            case 'nin':
-            case 'not in':
-                return Array.isArray(compareValue) && !compareValue.includes(fieldValue);
-            case 'contains':
-            case 'like':
-                return String(fieldValue).toLowerCase().includes(String(compareValue).toLowerCase());
-            case 'startswith':
-            case 'starts_with':
-                return String(fieldValue).toLowerCase().startsWith(String(compareValue).toLowerCase());
-            case 'endswith':
-            case 'ends_with':
-                return String(fieldValue).toLowerCase().endsWith(String(compareValue).toLowerCase());
-            case 'between':
-                return Array.isArray(compareValue) && 
-                       fieldValue >= compareValue[0] && 
-                       fieldValue <= compareValue[1];
-            default:
-                throw new ObjectQLError({
-                    code: 'UNSUPPORTED_OPERATOR',
-                    message: `[ExcelDriver] Unsupported operator: ${operator}`,
-                });
-        }
-    }
-
-    /**
-     * Apply sorting to an array of records.
-     */
-    private applySort(records: any[], sort: any[]): any[] {
-        const sorted = [...records];
-        
-        // Apply sorts in reverse order for correct precedence
-        for (let i = sort.length - 1; i >= 0; i--) {
-            const sortItem = sort[i];
-            
-            let field: string;
-            let direction: string;
-            
-            if (Array.isArray(sortItem)) {
-                [field, direction] = sortItem;
-            } else if (typeof sortItem === 'object') {
-                field = sortItem.field;
-                direction = sortItem.order || sortItem.direction || sortItem.dir || 'asc';
-            } else {
-                continue;
+            await this.saveWorkbook();
+        } else {
+            // Save all object files
+            const objectNames = new Set<string>();
+            for (const [key] of this.store.entries()) {
+                objectNames.add(key.split(':')[0]);
             }
-            
-            sorted.sort((a, b) => {
-                const aVal = a[field];
-                const bVal = b[field];
-                
-                // Handle null/undefined
-                if (aVal == null && bVal == null) return 0;
-                if (aVal == null) return 1;
-                if (bVal == null) return -1;
-                
-                // Compare values
-                if (aVal < bVal) return direction === 'asc' ? -1 : 1;
-                if (aVal > bVal) return direction === 'asc' ? 1 : -1;
-                return 0;
-            });
-        }
-        
-        return sorted;
-    }
-
-    /**
-     * Project specific fields from a document.
-     */
-    private projectFields(doc: any, fields: string[]): any {
-        const result: any = {};
-        for (const field of fields) {
-            if (doc[field] !== undefined) {
-                result[field] = doc[field];
+            for (const objectName of objectNames) {
+                await this.syncToFilePerObjectWorkbook(objectName);
+                await this.saveWorkbook(objectName);
             }
         }
-        return result;
-    }
-
-    /**
-     * Generate a unique ID for a record.
-     */
-    private generateId(objectName: string): string {
-        const counter = (this.idCounters.get(objectName) || 0) + 1;
-        this.idCounters.set(objectName, counter);
-        
-        // Use timestamp + counter for better uniqueness
-        const timestamp = Date.now();
-        return `${objectName}-${timestamp}-${counter}`;
     }
 }