@objectql/driver-excel 4.0.0 → 4.0.2

package/src/index.ts

@@ -1,3 +1,7 @@
+import { Data, Driver as DriverSpec } from '@objectstack/spec';
+type QueryAST = Data.QueryAST;
+type SortNode = Data.SortNode;
+type DriverInterface = DriverSpec.DriverInterface;
 /**
  * ObjectQL
  * Copyright (c) 2026-present ObjectStack Inc.
@@ -30,7 +34,6 @@
  */
 
 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';
@@ -102,7 +105,7 @@ export interface ExcelDriverConfig {
  * the standard DriverInterface from @objectstack/spec for compatibility
  * with the new kernel-based plugin system.
  */
-export class ExcelDriver implements Driver, DriverInterface {
+export class ExcelDriver implements Driver {
     // Driver metadata (ObjectStack-compatible)
     public readonly name = 'ExcelDriver';
     public readonly version = '4.0.0';
@@ -111,7 +114,13 @@ export class ExcelDriver implements Driver, DriverInterface {
         joins: false,
         fullTextSearch: false,
         jsonFields: true,
-        arrayFields: true
+        arrayFields: true,
+        queryFilters: true,
+        queryAggregations: false,
+        querySorting: true,
+        queryPagination: true,
+        queryWindowFunctions: false,
+        querySubqueries: false
     };
 
     private config: ExcelDriverConfig;
@@ -607,20 +616,39 @@ export class ExcelDriver implements Driver, DriverInterface {
         // Deep copy to avoid mutations
         results = results.map(r => ({ ...r }));
         
-        // Apply filters
+        // Apply filters from where clause (QueryAST format)
+        if (normalizedQuery.where) {
+            const legacyFilters = this.convertFilterConditionToArray(normalizedQuery.where);
+            if (legacyFilters) {
+                results = this.applyFilters(results, legacyFilters);
+            }
+        }
+        
+        // Apply filters from legacy filters clause
         if (normalizedQuery.filters) {
             results = this.applyFilters(results, normalizedQuery.filters);
         }
         
-        // Apply sorting
+        // 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
+        // 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);
         }
@@ -754,9 +782,15 @@ export class ExcelDriver implements Driver, DriverInterface {
     async count(objectName: string, filters: any, options?: any): Promise<number> {
         const records = this.data.get(objectName) || [];
         
-        // Extract actual filters from query object if needed
+        // Extract actual filters from query object
         let actualFilters = filters;
-        if (filters && !Array.isArray(filters) && filters.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;
         }
         
@@ -889,12 +923,13 @@ export class ExcelDriver implements Driver, DriverInterface {
         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.convertFilterNodeToLegacy(ast.filters),
-            sort: ast.sort?.map((s: SortNode) => [s.field, s.order]),
-            limit: ast.top,
-            skip: ast.skip,
+            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
@@ -1023,68 +1058,89 @@ export class ExcelDriver implements Driver, DriverInterface {
     // ========== Helper Methods ==========
 
     /**
-     * Convert FilterNode from QueryAST to legacy filter format.
+     * Convert FilterCondition (MongoDB-like format) to legacy array format.
+     * This allows the excel driver to use its existing filter evaluation logic.
      * 
-     * @param node - The FilterNode to convert
+     * @param condition - FilterCondition object or legacy array
      * @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');
+    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');
                         }
-                        andResults.push(...(Array.isArray(converted) ? converted : [converted]));
+                        result.push(...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');
+            } 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');
                         }
-                        orResults.push(...(Array.isArray(converted) ? converted : [converted]));
+                        result.push(...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]);
+            } 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);
                 }
-                return undefined;
-            
-            default:
-                return undefined;
+            } 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, while UnifiedQuery uses 'limit'.
-     * QueryAST sort is array of {field, order}, while UnifiedQuery is array of [field, order].
+     * 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 {};
@@ -1096,7 +1152,21 @@ export class ExcelDriver implements Driver, DriverInterface {
             normalized.limit = normalized.top;
         }
         
-        // Normalize sort format
+        // 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];

package/test/index.test.ts

@@ -233,7 +233,7 @@ describe('ExcelDriver', () => {
 
         it('should filter records with equality operator', async () => {
             const results = await driver.find(TEST_OBJECT, {
-                filters: [['role', '=', 'user']]
+                where: { role: { $eq: 'user' } }
             });
             expect(results.length).toBe(2);
             expect(results.every(r => r.role === 'user')).toBe(true);
@@ -241,7 +241,7 @@ describe('ExcelDriver', () => {
 
         it('should filter records with greater than operator', async () => {
             const results = await driver.find(TEST_OBJECT, {
-                filters: [['age', '>', 25]]
+                where: { age: { $gt: 25 } }
             });
             expect(results.length).toBe(2);
             expect(results.every(r => r.age > 25)).toBe(true);
@@ -249,25 +249,26 @@ describe('ExcelDriver', () => {
 
         it('should filter records with contains operator', async () => {
             const results = await driver.find(TEST_OBJECT, {
-                filters: [['name', 'contains', 'li']]
+                where: { name: { $regex: 'li' } }
             });
             expect(results.length).toBe(2); // Alice and Charlie
         });
 
         it('should support OR filters', async () => {
             const results = await driver.find(TEST_OBJECT, {
-                filters: [
-                    ['name', '=', 'Alice'],
-                    'or',
-                    ['name', '=', 'Bob']
-                ]
+                where: {
+                    $or: [
+                        { name: { $eq: 'Alice' } },
+                        { name: { $eq: 'Bob' } }
+                    ]
+                }
             });
             expect(results.length).toBe(2);
         });
 
         it('should sort records ascending', async () => {
             const results = await driver.find(TEST_OBJECT, {
-                sort: [['age', 'asc']]
+                orderBy: [{ field: 'age', order: 'asc' }]
             });
             expect(results[0].age).toBe(25);
             expect(results[1].age).toBe(30);
@@ -276,7 +277,7 @@ describe('ExcelDriver', () => {
 
         it('should sort records descending', async () => {
             const results = await driver.find(TEST_OBJECT, {
-                sort: [['age', 'desc']]
+                orderBy: [{ field: 'age', order: 'desc' }]
             });
             expect(results[0].age).toBe(35);
             expect(results[1].age).toBe(30);
@@ -292,7 +293,7 @@ describe('ExcelDriver', () => {
 
         it('should support pagination with skip', async () => {
             const results = await driver.find(TEST_OBJECT, {
-                skip: 1,
+                offset: 1,
                 limit: 2
             });
             expect(results.length).toBe(2);
@@ -315,7 +316,7 @@ describe('ExcelDriver', () => {
 
         it('should count filtered records', async () => {
             const count = await driver.count(TEST_OBJECT, {
-                filters: [['role', '=', 'user']]
+                where: { role: { $eq: 'user' } }
             });
             expect(count).toBe(2);
         });
@@ -354,7 +355,7 @@ describe('ExcelDriver', () => {
             expect(result.modifiedCount).toBe(2);
             
             const users = await driver.find(TEST_OBJECT, {
-                filters: [['role', '=', 'member']]
+                where: { role: { $eq: 'member' } }
             });
             expect(users).toHaveLength(2);
         });
@@ -465,7 +466,7 @@ describe('ExcelDriver', () => {
 
         it('should handle filters on empty data', async () => {
             const results = await driver.find(TEST_OBJECT, {
-                filters: [['name', '=', 'Alice']]
+                where: { name: { $eq: 'Alice' } }
             });
             expect(results).toEqual([]);
         });
@@ -582,15 +583,12 @@ describe('ExcelDriver', () => {
                 const result = await driver.executeQuery({
                     object: TEST_OBJECT,
                     fields: ['name', 'age'],
-                    filters: {
-                        type: 'comparison',
-                        field: 'age',
-                        operator: '>',
-                        value: 25
+                    where: {
+                        age: { $gt: 25 }
                     },
-                    sort: [{ field: 'age', order: 'asc' }],
-                    top: 10,
-                    skip: 0
+                    orderBy: [{ field: 'age', order: 'asc' }],
+                    limit: 10,
+                    offset: 0
                 });
 
                 expect(result.value).toHaveLength(2);
@@ -606,11 +604,10 @@ describe('ExcelDriver', () => {
 
                 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' }
+                    where: {
+                        $and: [
+                            { age: { $gt: 25 } },
+                            { city: { $eq: 'NYC' } }
                         ]
                     }
                 });
@@ -626,9 +623,9 @@ describe('ExcelDriver', () => {
 
                 const result = await driver.executeQuery({
                     object: TEST_OBJECT,
-                    sort: [{ field: 'name', order: 'asc' }],
-                    skip: 1,
-                    top: 1
+                    orderBy: [{ field: 'name', order: 'asc' }],
+                    offset: 1,
+                    limit: 1
                 });
 
                 expect(result.value).toHaveLength(1);