@objectql/driver-mongo 3.0.1 → 4.0.1

package/src/index.ts

@@ -1,7 +1,70 @@
+import { Data, System } from '@objectstack/spec';
+type QueryAST = Data.QueryAST;
+type FilterNode = Data.FilterNode;
+type SortNode = Data.SortNode;
+type DriverInterface = System.DriverInterface;
+/**
+ * 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.
+ */
+
 import { Driver } from '@objectql/types';
 import { MongoClient, Db, Filter, ObjectId, FindOptions } from 'mongodb';
 
+/**
+ * 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;
+}
+
+/**
+ * MongoDB Driver for ObjectQL
+ * 
+ * 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.
+ * 
+ * The driver internally converts QueryAST format to MongoDB query format.
+ */
 export class MongoDriver implements Driver {
+    // Driver metadata (ObjectStack-compatible)
+    public readonly name = 'MongoDriver';
+    public readonly version = '3.0.1';
+    public readonly supports = {
+        transactions: true,
+        joins: false,
+        fullTextSearch: true,
+        jsonFields: true,
+        arrayFields: true,
+        queryFilters: true,
+        queryAggregations: true,
+        querySorting: true,
+        queryPagination: true,
+        queryWindowFunctions: false,
+        querySubqueries: false
+    };
+
     private client: MongoClient;
     private db?: Db;
     private config: any;
@@ -10,14 +73,39 @@ export class MongoDriver implements Driver {
     constructor(config: { url: string, dbName?: string }) {
         this.config = config;
         this.client = new MongoClient(config.url);
-        this.connected = this.connect();
+        this.connected = this.internalConnect();
     }
 
-    private async connect() {
+    /**
+     * Internal connect method used in constructor
+     */
+    private async internalConnect() {
         await this.client.connect();
         this.db = this.client.db(this.config.dbName);
     }
 
+    /**
+     * Connect to the database (for DriverInterface compatibility)
+     * This method ensures the connection is established.
+     */
+    async connect(): Promise<void> {
+        await this.connected;
+    }
+
+    /**
+     * Check database connection health
+     */
+    async checkHealth(): Promise<boolean> {
+        try {
+            await this.connected;
+            if (!this.db) return false;
+            await this.db.admin().ping();
+            return true;
+        } catch (error) {
+            return false;
+        }
+    }
+
     private async getCollection(objectName: string) {
         await this.connected;
         if (!this.db) throw new Error("Database not initialized");
@@ -162,29 +250,79 @@ export class MongoDriver implements Driver {
         return mongoCondition;
     }
 
+    /**
+     * 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 uses 'aggregations', while legacy uses 'aggregate'.
+     */
+    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 aggregations/aggregate
+        if (normalized.aggregations !== undefined && normalized.aggregate === undefined) {
+            // Convert QueryAST aggregations format to legacy aggregate format
+            normalized.aggregate = normalized.aggregations.map((agg: any) => ({
+                func: agg.function || agg.func,
+                field: agg.field,
+                alias: agg.alias
+            }));
+        }
+        
+        // Normalize sort format
+        if (normalized.sort && Array.isArray(normalized.sort)) {
+            // Check if it's already in the array format [field, order]
+            const firstSort = normalized.sort[0];
+            if (firstSort && typeof firstSort === 'object' && !Array.isArray(firstSort)) {
+                // Convert from QueryAST format {field, order} to internal format [field, order]
+                normalized.sort = normalized.sort.map((item: any) => [
+                    item.field,
+                    item.order || item.direction || item.dir || 'asc'
+                ]);
+            }
+        }
+        
+        return normalized;
+    }
+
     async find(objectName: string, query: any, options?: any): Promise<any[]> {
+        const normalizedQuery = this.normalizeQuery(query);
         const collection = await this.getCollection(objectName);
-        const filter = this.mapFilters(query.filters);
+        const filter = this.mapFilters(normalizedQuery.filters);
         
         const findOptions: FindOptions = {};
-        if (query.skip) findOptions.skip = query.skip;
-        if (query.limit) findOptions.limit = query.limit;
-        if (query.sort) {
+        if (normalizedQuery.skip) findOptions.skip = normalizedQuery.skip;
+        if (normalizedQuery.limit) findOptions.limit = normalizedQuery.limit;
+        if (normalizedQuery.sort) {
             // map [['field', 'desc']] to { field: -1 }
             findOptions.sort = {};
-            for (const [field, order] of query.sort) {
+            for (const [field, order] of normalizedQuery.sort) {
                 // Map both 'id' and '_id' to '_id' for backward compatibility
                 const dbField = (field === 'id' || field === '_id') ? '_id' : field;
                 (findOptions.sort as any)[dbField] = order === 'desc' ? -1 : 1;
             }
         }
-        if (query.fields && query.fields.length > 0) {
+        if (normalizedQuery.fields && normalizedQuery.fields.length > 0) {
             findOptions.projection = {};
-            for (const field of query.fields) {
+            for (const field of normalizedQuery.fields) {
                 // Map both 'id' and '_id' to '_id' for backward compatibility
                 const dbField = (field === 'id' || field === '_id') ? '_id' : field;
                 (findOptions.projection as any)[dbField] = 1;
             }
+            // Explicitly exclude _id if 'id' is not in the requested fields
+            const hasIdField = normalizedQuery.fields.some((f: string) => f === 'id' || f === '_id');
+            if (!hasIdField) {
+                (findOptions.projection as any)._id = 0;
+            }
         }
 
         const results = await collection.find(filter, findOptions).toArray();
@@ -245,7 +383,10 @@ export class MongoDriver implements Driver {
 
     async count(objectName: string, filters: any, options?: any): Promise<number> {
         const collection = await this.getCollection(objectName);
-        const filter = this.mapFilters(filters);
+        // Normalize to support both filter arrays and full query objects
+        const normalizedQuery = this.normalizeQuery(filters);
+        const actualFilters = normalizedQuery.filters || filters;
+        const filter = this.mapFilters(actualFilters);
         return await collection.countDocuments(filter);
     }
     
@@ -299,5 +440,205 @@ export class MongoDriver implements Driver {
             await this.client.close();
         }
     }
+
+    /**
+     * Execute a query using QueryAST (DriverInterface v4.0 method)
+     * 
+     * This is the new standard method for query execution using the
+     * ObjectStack QueryAST format.
+     * 
+     * @param ast - The QueryAST representing the query
+     * @param options - Optional execution options
+     * @returns Query results with value and count
+     */
+    async executeQuery(ast: QueryAST, options?: any): Promise<{ value: any[]; count?: number }> {
+        const objectName = ast.object || '';
+        
+        // Convert QueryAST to legacy query format
+        const legacyQuery: any = {
+            fields: ast.fields,
+            filters: this.convertFilterNodeToLegacy(ast.filters),
+            sort: ast.sort?.map((s: SortNode) => [s.field, s.order]),
+            limit: ast.top,
+            skip: ast.skip,
+        };
+        
+        // Use existing find method
+        const results = await this.find(objectName, legacyQuery, options);
+        
+        return {
+            value: results,
+            count: results.length
+        };
+    }
+
+    /**
+     * Execute a command (DriverInterface v4.0 method)
+     * 
+     * This method handles all mutation operations (create, update, delete)
+     * using a unified command interface.
+     * 
+     * @param command - The command to execute
+     * @param options - Optional execution options
+     * @returns Command execution result
+     */
+    async executeCommand(command: Command, options?: any): Promise<CommandResult> {
+        try {
+            const cmdOptions = { ...options, ...command.options };
+            
+            switch (command.type) {
+                case 'create':
+                    if (!command.data) {
+                        throw new Error('Create command requires data');
+                    }
+                    const created = await this.create(command.object, command.data, cmdOptions);
+                    return {
+                        success: true,
+                        data: created,
+                        affected: 1
+                    };
+                
+                case 'update':
+                    if (!command.id || !command.data) {
+                        throw new Error('Update command requires id and data');
+                    }
+                    const updated = await this.update(command.object, command.id, command.data, cmdOptions);
+                    return {
+                        success: true,
+                        data: updated,
+                        affected: updated ? 1 : 0
+                    };
+                
+                case 'delete':
+                    if (!command.id) {
+                        throw new Error('Delete command requires id');
+                    }
+                    const deleteCount = await this.delete(command.object, command.id, cmdOptions);
+                    return {
+                        success: true,
+                        affected: deleteCount
+                    };
+                
+                case 'bulkCreate':
+                    if (!command.records || !Array.isArray(command.records)) {
+                        throw new Error('BulkCreate command requires records array');
+                    }
+                    const bulkCreated = await this.createMany(command.object, command.records, cmdOptions);
+                    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');
+                    }
+                    let updateCount = 0;
+                    const updateResults = [];
+                    for (const update of command.updates) {
+                        const result = await this.update(command.object, update.id, update.data, cmdOptions);
+                        updateResults.push(result);
+                        if (result) updateCount++;
+                    }
+                    return {
+                        success: true,
+                        data: updateResults,
+                        affected: updateCount
+                    };
+                
+                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);
+                        deleted += result;
+                    }
+                    return {
+                        success: true,
+                        affected: deleted
+                    };
+                
+                default:
+                    const validTypes = ['create', 'update', 'delete', 'bulkCreate', 'bulkUpdate', 'bulkDelete'];
+                    throw new Error(`Unknown command type: ${(command as any).type}. Valid types are: ${validTypes.join(', ')}`);
+            }
+        } catch (error: any) {
+            return {
+                success: false,
+                error: error.message || 'Command execution failed',
+                affected: 0
+            };
+        }
+    }
+
+    /**
+     * Convert FilterNode (QueryAST format) to legacy filter array format
+     * This allows reuse of existing filter logic while supporting new QueryAST
+     * 
+     * @private
+     */
+    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':
+            case 'or':
+                // Convert AND/OR node to array with separator
+                if (!node.children || node.children.length === 0) return undefined;
+                const results: any[] = [];
+                const separator = node.type; // 'and' or 'or'
+                
+                for (const child of node.children) {
+                    const converted = this.convertFilterNodeToLegacy(child);
+                    if (converted) {
+                        if (results.length > 0) {
+                            results.push(separator);
+                        }
+                        results.push(...(Array.isArray(converted) ? converted : [converted]));
+                    }
+                }
+                return results.length > 0 ? results : undefined;
+            
+            case 'not':
+                // NOT is not directly supported in the legacy filter format
+                // MongoDB supports $not, but legacy array format doesn't have a NOT operator
+                // Use native MongoDB queries with $not instead:
+                // Example: { field: { $not: { $eq: value } } }
+                throw new Error(
+                    'NOT filters are not supported in legacy filter format. ' +
+                    'Use native MongoDB queries with $not operator instead. ' +
+                    'Example: { field: { $not: { $eq: value } } }'
+                );
+            
+            default:
+                return undefined;
+        }
+    }
+
+    /**
+     * Execute command (alternative signature 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> {
+        // MongoDB driver doesn't support raw command execution in the traditional SQL sense
+        // Use executeCommand() instead for mutations (create/update/delete)
+        // Example: await driver.executeCommand({ type: 'create', object: 'users', data: {...} })
+        throw new Error(
+            'MongoDB driver does not support raw command execution. ' +
+            'Use executeCommand() for mutations or aggregate() for complex queries. ' +
+            'Example: driver.executeCommand({ type: "create", object: "users", data: {...} })'
+        );
+    }
 }
 

package/test/index.test.ts

@@ -1,3 +1,11 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
 import { MongoDriver } from '../src';
 import { MongoClient } from 'mongodb';
 
@@ -9,6 +17,10 @@ const mockCollection = {
     toArray: jest.fn().mockResolvedValue([]),
     findOne: jest.fn().mockResolvedValue(null),
     insertOne: jest.fn().mockResolvedValue({ insertedId: '123' }),
+    insertMany: jest.fn().mockResolvedValue({ 
+        insertedIds: { 0: 'id1', 1: 'id2' },
+        insertedCount: 2
+    }),
     updateOne: jest.fn().mockResolvedValue({ modifiedCount: 1 }),
     deleteOne: jest.fn().mockResolvedValue({ deletedCount: 1 }),
     countDocuments: jest.fn().mockResolvedValue(10)
@@ -26,7 +38,10 @@ const mockClient = {
 jest.mock('mongodb', () => {
     return {
         MongoClient: jest.fn().mockImplementation(() => mockClient),
-        ObjectId: jest.fn(id => id) 
+        ObjectId: jest.fn().mockImplementation((id?: string) => ({
+            toHexString: () => id || 'generated-object-id',
+            toString: () => id || 'generated-object-id'
+        }))
     };
 });
 
@@ -320,4 +335,246 @@ describe('MongoDriver', () => {
         );
     });
 
+    describe('DriverInterface v4.0 methods', () => {
+        describe('executeQuery', () => {
+            it('should execute a simple QueryAST query', async () => {
+                const ast = {
+                    object: 'users',
+                    fields: ['name', 'email'],
+                    filters: {
+                        type: 'comparison' as const,
+                        field: 'status',
+                        operator: '=',
+                        value: 'active'
+                    },
+                    top: 10,
+                    skip: 0
+                };
+
+                mockCollection.toArray.mockResolvedValue([
+                    { name: 'User 1', email: 'user1@example.com' },
+                    { name: 'User 2', email: 'user2@example.com' }
+                ]);
+
+                const result = await driver.executeQuery(ast);
+
+                expect(result.value).toHaveLength(2);
+                expect(result.count).toBe(2);
+                expect(mockCollection.find).toHaveBeenCalled();
+            });
+
+            it('should handle complex QueryAST with AND filters', async () => {
+                const ast = {
+                    object: 'users',
+                    filters: {
+                        type: 'and' as const,
+                        children: [
+                            {
+                                type: 'comparison' as const,
+                                field: 'status',
+                                operator: '=',
+                                value: 'active'
+                            },
+                            {
+                                type: 'comparison' as const,
+                                field: 'age',
+                                operator: '>',
+                                value: 18
+                            }
+                        ]
+                    }
+                };
+
+                mockCollection.toArray.mockResolvedValue([]);
+
+                const result = await driver.executeQuery(ast);
+
+                expect(result.value).toEqual([]);
+                expect(mockCollection.find).toHaveBeenCalled();
+            });
+
+            it('should handle QueryAST with sort', async () => {
+                const ast = {
+                    object: 'users',
+                    sort: [
+                        { field: 'name', order: 'asc' as const }
+                    ]
+                };
+
+                mockCollection.toArray.mockResolvedValue([]);
+
+                await driver.executeQuery(ast);
+
+                expect(mockCollection.find).toHaveBeenCalledWith(
+                    {},
+                    expect.objectContaining({
+                        sort: { name: 1 }
+                    })
+                );
+            });
+        });
+
+        describe('executeCommand', () => {
+            it('should execute create command', async () => {
+                const command = {
+                    type: 'create' as const,
+                    object: 'users',
+                    data: { name: 'New User', email: 'new@example.com' }
+                };
+
+                mockCollection.insertOne.mockResolvedValue({ 
+                    insertedId: 'new123',
+                    acknowledged: true
+                } as any);
+
+                const result = await driver.executeCommand(command);
+
+                expect(result.success).toBe(true);
+                expect(result.affected).toBe(1);
+                expect(result.data).toBeDefined();
+                expect(mockCollection.insertOne).toHaveBeenCalled();
+            });
+
+            it('should execute update command', async () => {
+                const command = {
+                    type: 'update' as const,
+                    object: 'users',
+                    id: '123',
+                    data: { name: 'Updated User' }
+                };
+
+                mockCollection.updateOne.mockResolvedValue({ 
+                    modifiedCount: 1,
+                    acknowledged: true
+                } as any);
+                mockCollection.findOne.mockResolvedValue({ 
+                    _id: '123', 
+                    name: 'Updated User' 
+                });
+
+                const result = await driver.executeCommand(command);
+
+                expect(result.success).toBe(true);
+                expect(result.affected).toBe(1);
+                expect(mockCollection.updateOne).toHaveBeenCalled();
+            });
+
+            it('should execute delete command', async () => {
+                const command = {
+                    type: 'delete' as const,
+                    object: 'users',
+                    id: '123'
+                };
+
+                mockCollection.deleteOne.mockResolvedValue({ 
+                    deletedCount: 1,
+                    acknowledged: true
+                } as any);
+
+                const result = await driver.executeCommand(command);
+
+                expect(result.success).toBe(true);
+                expect(result.affected).toBe(1);
+                expect(mockCollection.deleteOne).toHaveBeenCalled();
+            });
+
+            it('should execute bulkCreate command', async () => {
+                const command = {
+                    type: 'bulkCreate' as const,
+                    object: 'users',
+                    records: [
+                        { name: 'User 1', email: 'user1@example.com' },
+                        { name: 'User 2', email: 'user2@example.com' }
+                    ]
+                };
+
+                mockCollection.insertOne.mockResolvedValue({ 
+                    insertedId: 'id1',
+                    acknowledged: true
+                } as any);
+
+                const result = await driver.executeCommand(command);
+
+                expect(result.success).toBe(true);
+                expect(result.affected).toBe(2);
+                expect(result.data).toHaveLength(2);
+            });
+
+            it('should execute bulkUpdate command', async () => {
+                const command = {
+                    type: 'bulkUpdate' as const,
+                    object: 'users',
+                    updates: [
+                        { id: '1', data: { name: 'Updated 1' } },
+                        { id: '2', data: { name: 'Updated 2' } }
+                    ]
+                };
+
+                mockCollection.updateOne.mockResolvedValue({ 
+                    modifiedCount: 1,
+                    acknowledged: true
+                } as any);
+                mockCollection.findOne.mockResolvedValue({ _id: '1', name: 'Updated 1' });
+
+                const result = await driver.executeCommand(command);
+
+                expect(result.success).toBe(true);
+                expect(result.affected).toBe(2);
+            });
+
+            it('should execute bulkDelete command', async () => {
+                const command = {
+                    type: 'bulkDelete' as const,
+                    object: 'users',
+                    ids: ['1', '2', '3']
+                };
+
+                mockCollection.deleteOne.mockResolvedValue({ 
+                    deletedCount: 1,
+                    acknowledged: true
+                } as any);
+
+                const result = await driver.executeCommand(command);
+
+                expect(result.success).toBe(true);
+                expect(result.affected).toBe(3);
+            });
+
+            it('should handle command errors gracefully', async () => {
+                const command = {
+                    type: 'create' as const,
+                    object: 'users',
+                    data: undefined // Invalid data
+                };
+
+                const result = await driver.executeCommand(command);
+
+                expect(result.success).toBe(false);
+                expect(result.error).toBeDefined();
+                expect(result.affected).toBe(0);
+            });
+
+            it('should reject unknown command types', async () => {
+                const command = {
+                    type: 'invalidCommand' as any,
+                    object: 'users'
+                };
+
+                const result = await driver.executeCommand(command);
+
+                expect(result.success).toBe(false);
+                expect(result.error).toContain('Unknown command type');
+                expect(result.error).toContain('Valid types are');
+            });
+        });
+
+        describe('execute', () => {
+            it('should throw error as MongoDB does not support raw command execution', async () => {
+                await expect(driver.execute('SELECT * FROM users')).rejects.toThrow(
+                    'MongoDB driver does not support raw command execution'
+                );
+            });
+        });
+    });
+
 });