@objectql/driver-excel 3.0.1 → 4.0.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @objectql/driver-excel
 
+## 4.0.1
+
+### Patch Changes
+
+- **Release Version 4.0.1**
+
+  This patch release includes the latest repository improvements and infrastructure updates:
+  - Added comprehensive GitHub workflows for CI/CD, testing, and quality assurance
+  - Enhanced documentation and developer experience
+  - Improved build and release processes with Changesets
+  - Added Excel driver for reading/writing Excel files as data sources
+  - Repository structure and tooling improvements
+  - Bug fixes and stability enhancements
+
+- Updated dependencies
+  - @objectql/types@4.0.1
+
 ## 3.0.1
 
 ### Patch Changes
@@ -7,7 +24,6 @@
 - 79d04e1: Patch release for January 2026 updates
 
   This patch includes minor improvements and maintenance updates:
-
   - Enhanced type safety across core packages
   - Improved error handling in drivers
   - Documentation updates
@@ -30,7 +46,6 @@
   This is a coordinated major release that unifies all ObjectQL packages to version 2.0.0, establishing a synchronized versioning strategy across the entire ecosystem.
 
   ### 🎯 Key Changes
-
   - **Unified Versioning**: All core packages now share the same version number (2.0.0)
   - **Fixed Group Management**: Updated changeset configuration to include all @objectql packages in the fixed versioning group
   - **Simplified Maintenance**: Future releases will automatically maintain version consistency across the entire monorepo
@@ -38,7 +53,6 @@
   ### 📦 Packages Included
 
   All ObjectQL packages are now synchronized at version 2.0.0:
-
   - Foundation: `@objectql/types`, `@objectql/core`, `@objectql/platform-node`
   - Drivers: `@objectql/driver-sql`, `@objectql/driver-mongo`, `@objectql/driver-redis`, `@objectql/driver-fs`, `@objectql/driver-memory`, `@objectql/driver-localstorage`, `@objectql/driver-excel`, `@objectql/sdk`
   - Runtime: `@objectql/server`

package/dist/index.d.ts

@@ -1,3 +1,12 @@
+import { Data } from '@objectstack/spec';
+type QueryAST = Data.QueryAST;
+/**
+ * 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)
  *
@@ -21,6 +30,31 @@
  * - Generate reports in Excel format
  */
 import { Driver } from '@objectql/types';
+/**
+ * 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.
  */
@@ -55,8 +89,27 @@ 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 declare class ExcelDriver implements Driver {
+    readonly name = "ExcelDriver";
+    readonly version = "4.0.0";
+    readonly supports: {
+        transactions: boolean;
+        joins: boolean;
+        fullTextSearch: boolean;
+        jsonFields: boolean;
+        arrayFields: boolean;
+        queryFilters: boolean;
+        queryAggregations: boolean;
+        querySorting: boolean;
+        queryPagination: boolean;
+        queryWindowFunctions: boolean;
+        querySubqueries: boolean;
+    };
     private config;
     private workbook;
     private workbooks;
@@ -70,6 +123,15 @@ export declare class ExcelDriver implements Driver {
      * This must be called after construction before using the driver.
      */
     init(): Promise<void>;
+    /**
+     * Connect to the database (for DriverInterface compatibility)
+     * This calls init() to load the workbook.
+     */
+    connect(): Promise<void>;
+    /**
+     * Check database connection health
+     */
+    checkHealth(): Promise<boolean>;
     /**
      * Factory method to create and initialize the driver.
      */
@@ -188,6 +250,55 @@ export declare class ExcelDriver implements Driver {
      * Disconnect (flush any pending writes).
      */
     disconnect(): Promise<void>;
+    /**
+     * 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
+     */
+    executeQuery(ast: QueryAST, options?: any): Promise<{
+        value: any[];
+        count?: number;
+    }>;
+    /**
+     * 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
+     */
+    executeCommand(command: Command, options?: any): Promise<CommandResult>;
+    /**
+     * Execute raw command (for compatibility)
+     *
+     * @param command - Command string or object
+     * @param parameters - Command parameters
+     * @param options - Execution options
+     */
+    execute(command: any, parameters?: any[], options?: any): Promise<any>;
+    /**
+     * Convert FilterNode from QueryAST to legacy filter format.
+     *
+     * @param node - The FilterNode to convert
+     * @returns Legacy filter array format
+     */
+    private convertFilterNodeToLegacy;
+    /**
+     * 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;
     /**
      * Apply filters to an array of records (in-memory filtering).
      */
@@ -213,3 +324,4 @@ export declare class ExcelDriver implements Driver {
      */
     private generateId;
 }
+export {};

package/dist/index.js

@@ -1,26 +1,4 @@
 "use strict";
-/**
- * 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.
- *
- * ✅ 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)
- *
- * 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
- */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -56,6 +34,35 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExcelDriver = void 0;
+/**
+ * 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)
+ *
+ * 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.
+ *
+ * ✅ 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)
+ *
+ * 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
+ */
 const types_1 = require("@objectql/types");
 const ExcelJS = __importStar(require("exceljs"));
 const fs = __importStar(require("fs"));
@@ -67,9 +74,29 @@ const path = __importStar(require("path"));
  * 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.
  */
 class ExcelDriver {
     constructor(config) {
+        // Driver metadata (ObjectStack-compatible)
+        this.name = 'ExcelDriver';
+        this.version = '4.0.0';
+        this.supports = {
+            transactions: false,
+            joins: false,
+            fullTextSearch: false,
+            jsonFields: true,
+            arrayFields: true,
+            queryFilters: true,
+            queryAggregations: false,
+            querySorting: true,
+            queryPagination: true,
+            queryWindowFunctions: false,
+            querySubqueries: false
+        };
         this.config = {
             autoSave: true,
             createIfMissing: true,
@@ -96,6 +123,46 @@ class ExcelDriver {
     async init() {
         await this.loadWorkbook();
     }
+    /**
+     * Connect to the database (for DriverInterface compatibility)
+     * This calls init() to load the workbook.
+     */
+    async connect() {
+        await this.init();
+    }
+    /**
+     * Check database connection health
+     */
+    async checkHealth() {
+        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.
      */
@@ -459,6 +526,8 @@ class ExcelDriver {
      * Find multiple records matching the query criteria.
      */
     async find(objectName, query = {}, options) {
+        // 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) {
@@ -467,23 +536,23 @@ class ExcelDriver {
         // Deep copy to avoid mutations
         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;
     }
@@ -690,7 +759,226 @@ class ExcelDriver {
             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, options) {
+        var _a;
+        const objectName = ast.object || '';
+        // Convert QueryAST to legacy query format
+        const legacyQuery = {
+            fields: ast.fields,
+            filters: this.convertFilterNodeToLegacy(ast.filters),
+            sort: (_a = ast.sort) === null || _a === void 0 ? void 0 : _a.map((s) => [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, options) {
+        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.type}`);
+            }
+        }
+        catch (error) {
+            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, parameters, options) {
+        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
+     */
+    convertFilterNodeToLegacy(node) {
+        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 = [];
+                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 = [];
+                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].
+     */
+    normalizeQuery(query) {
+        if (!query)
+            return {};
+        const normalized = { ...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) => [
+                    item.field,
+                    item.order || item.direction || item.dir || 'asc'
+                ]);
+            }
+        }
+        return normalized;
+    }
     /**
      * Apply filters to an array of records (in-memory filtering).
      */