@objectql/driver-mongo 4.0.2 → 4.0.4

package/src/index.ts

@@ -1,7 +1,7 @@
-import { Data, Driver as DriverSpec } from '@objectstack/spec';
+import { Data, System as SystemSpec } from '@objectstack/spec';
 type QueryAST = Data.QueryAST;
 type SortNode = Data.SortNode;
-type DriverInterface = DriverSpec.DriverInterface;
+type DriverInterface = Data.DriverInterface;
 /**
  * ObjectQL
  * Copyright (c) 2026-present ObjectStack Inc.
@@ -11,7 +11,24 @@ type DriverInterface = DriverSpec.DriverInterface;
  */
 
 import { Driver } from '@objectql/types';
-import { MongoClient, Db, Filter, ObjectId, FindOptions } from 'mongodb';
+import { MongoClient, Db, Filter, ObjectId, FindOptions, FindOneAndUpdateOptions, UpdateFilter, ChangeStream, ChangeStreamDocument } from 'mongodb';
+
+/**
+ * Change stream event handler callback
+ */
+export type ChangeStreamHandler = (change: ChangeStreamDocument) => void | Promise<void>;
+
+/**
+ * Change stream options
+ */
+export interface ChangeStreamOptions {
+    /** Filter for specific operation types (insert, update, delete, replace) */
+    operationTypes?: ('insert' | 'update' | 'delete' | 'replace')[];
+    /** Full document lookup for update operations */
+    fullDocument?: 'updateLookup' | 'whenAvailable' | 'required';
+    /** Pipeline to filter change events */
+    pipeline?: any[];
+}
 
 /**
  * Command interface for executeCommand method
@@ -68,11 +85,13 @@ export class MongoDriver implements Driver {
     private db?: Db;
     private config: any;
     private connected: Promise<void>;
+    private changeStreams: Map<string, ChangeStream>;
 
     constructor(config: { url: string, dbName?: string }) {
         this.config = config;
         this.client = new MongoClient(config.url);
         this.connected = this.internalConnect();
+        this.changeStreams = new Map();
     }
 
     /**
@@ -391,7 +410,22 @@ export class MongoDriver implements Driver {
             mongoDoc._id = new ObjectId().toHexString();
         }
 
-        const result = await collection.insertOne(mongoDoc);
+        // Add timestamps if not already present
+        const now = new Date().toISOString();
+        if (!mongoDoc.created_at) {
+            mongoDoc.created_at = now;
+        }
+        if (!mongoDoc.updated_at) {
+            mongoDoc.updated_at = now;
+        }
+
+        // Pass session for transactional operations only if it exists
+        // Support both 'transaction' and 'session' option keys for compatibility
+        const session = options?.transaction || options?.session;
+        const result = session 
+            ? await collection.insertOne(mongoDoc, { session })
+            : await collection.insertOne(mongoDoc);
+        
         // Return API format document (convert _id to id)
         return this.mapFromMongo({ ...mongoDoc, _id: result.insertedId });
     }
@@ -401,19 +435,54 @@ export class MongoDriver implements Driver {
         
         // Map API document (id) to MongoDB document (_id) for update data
         // But we should not allow updating the _id field itself
-        const { id: _ignoredId, ...updateData } = data; // intentionally ignore id to prevent updating primary key
+        const { id: _ignoredId, created_at: _ignoredCreatedAt, ...updateData } = data; // intentionally ignore id and created_at to prevent updating them
         
         // Handle atomic operators if present
         const isAtomic = Object.keys(updateData).some(k => k.startsWith('$'));
-        const update = isAtomic ? updateData : { $set: updateData };
+        
+        // Build the update object with updated_at timestamp
+        let update: UpdateFilter<any>;
+        if (isAtomic) {
+            // When using atomic operators, add updated_at to $set
+            // The spread is safe because id and created_at were already removed via destructuring
+            update = { ...updateData } as any;
+            if (!update.$set) {
+                update.$set = {};
+            }
+            update.$set.updated_at = new Date().toISOString();
+        } else {
+            // For regular updates, add updated_at to the data
+            updateData.updated_at = new Date().toISOString();
+            update = { $set: updateData };
+        }
 
-        const result = await collection.updateOne({ _id: this.normalizeId(id) }, update);
-        return result.modifiedCount; // or return updated document?
+        // Use findOneAndUpdate to return the updated document
+        const mongoOptions: FindOneAndUpdateOptions = { returnDocument: 'after' };
+        // Support both 'transaction' and 'session' option keys for compatibility
+        const session = options?.transaction || options?.session;
+        if (session) {
+            mongoOptions.session = session;
+        }
+        
+        const result = await collection.findOneAndUpdate(
+            { _id: this.normalizeId(id) },
+            update,
+            mongoOptions
+        );
+        
+        // Return API format document (convert _id to id)
+        // findOneAndUpdate returns an object with a 'value' property containing the document
+        return this.mapFromMongo(result?.value);
     }
 
     async delete(objectName: string, id: string | number, options?: any) {
         const collection = await this.getCollection(objectName);
-        const result = await collection.deleteOne({ _id: this.normalizeId(id) });
+        // Pass session for transactional operations only if it exists
+        // Support both 'transaction' and 'session' option keys for compatibility
+        const session = options?.transaction || options?.session;
+        const result = session
+            ? await collection.deleteOne({ _id: this.normalizeId(id) }, { session })
+            : await collection.deleteOne({ _id: this.normalizeId(id) });
         return result.deletedCount;
     }
 
@@ -441,7 +510,11 @@ export class MongoDriver implements Driver {
             }
             return mongoDoc;
         });
-        const result = await collection.insertMany(mongoDocs);
+        // Support both 'transaction' and 'session' option keys for compatibility
+        const session = options?.transaction || options?.session;
+        const result = session
+            ? await collection.insertMany(mongoDocs, { session })
+            : await collection.insertMany(mongoDocs);
         // Return API format (convert _id to id)
         return Object.values(result.insertedIds).map(id => ({ id }));
     }
@@ -456,15 +529,23 @@ export class MongoDriver implements Driver {
         const isAtomic = Object.keys(updateData).some(k => k.startsWith('$'));
         const update = isAtomic ? updateData : { $set: updateData };
         
-        const result = await collection.updateMany(filter, update);
-        return result.modifiedCount;
+        // Support both 'transaction' and 'session' option keys for compatibility
+        const session = options?.transaction || options?.session;
+        const result = session
+            ? await collection.updateMany(filter, update, { session })
+            : await collection.updateMany(filter, update);
+        return { modifiedCount: result.modifiedCount };
     }
 
     async deleteMany(objectName: string, filters: any, options?: any): Promise<any> {
         const collection = await this.getCollection(objectName);
         const filter = this.mapFilters(filters);
-        const result = await collection.deleteMany(filter);
-        return result.deletedCount;
+        // Support both 'transaction' and 'session' option keys for compatibility
+        const session = options?.transaction || options?.session;
+        const result = session
+            ? await collection.deleteMany(filter, { session })
+            : await collection.deleteMany(filter);
+        return { deletedCount: result.deletedCount };
     }
 
     async aggregate(objectName: string, pipeline: any[], options?: any): Promise<any[]> {
@@ -474,12 +555,237 @@ export class MongoDriver implements Driver {
         return this.mapFromMongoArray(results);
     }
 
+    /**
+     * Get distinct values for a field
+     * @param objectName - The collection name
+     * @param field - The field to get distinct values from
+     * @param filters - Optional filters to apply
+     * @param options - Optional query options
+     * @returns Array of distinct values
+     */
+    async distinct(objectName: string, field: string, filters?: any, options?: any): Promise<any[]> {
+        const collection = await this.getCollection(objectName);
+        
+        // Convert ObjectQL filters to MongoDB query format
+        const filter = filters ? this.mapFilters(filters) : {};
+        
+        // Use MongoDB's native distinct method
+        const results = await collection.distinct(field, filter);
+        
+        return results;
+    }
+
+    /**
+     * Find one document and update it atomically
+     * @param objectName - The collection name
+     * @param filters - Query filters to find the document
+     * @param update - Update operations to apply
+     * @param options - Optional query options (e.g., returnDocument, upsert)
+     * @returns The updated document
+     * 
+     * @example
+     * // Find and update with returnDocument: 'after' to get the updated doc
+     * const updated = await driver.findOneAndUpdate('users', 
+     *   { email: 'user@example.com' }, 
+     *   { $set: { status: 'active' } },
+     *   { returnDocument: 'after' }
+     * );
+     */
+    async findOneAndUpdate(objectName: string, filters: any, update: any, options?: any): Promise<any> {
+        const collection = await this.getCollection(objectName);
+        
+        // Convert ObjectQL filters to MongoDB query format
+        const filter = this.mapFilters(filters);
+        
+        // MongoDB findOneAndUpdate options
+        const mongoOptions: any = {
+            returnDocument: options?.returnDocument || 'after', // 'before' or 'after'
+            upsert: options?.upsert || false
+        };
+        
+        // Execute the atomic find and update
+        const result = await collection.findOneAndUpdate(filter, update, mongoOptions);
+        
+        // Map MongoDB document to API format (convert _id to id)
+        // MongoDB driver v5+ returns { value: document, ok: number }
+        // Older versions (v4) return the document directly
+        // We handle both for backward compatibility
+        const doc = result?.value !== undefined ? result.value : result;
+        return doc ? this.mapFromMongo(doc) : null;
+    }
+
+    // ========== Transaction Support ==========
+    
+    /**
+     * Begin a new transaction session
+     * 
+     * @returns MongoDB ClientSession that can be used for transactional operations
+     * 
+     * @example
+     * const session = await driver.beginTransaction();
+     * try {
+     *   await driver.create('users', { name: 'Alice' }, { session });
+     *   await driver.create('orders', { userId: 'alice' }, { session });
+     *   await driver.commitTransaction(session);
+     * } catch (error) {
+     *   await driver.rollbackTransaction(session);
+     *   throw error;
+     * }
+     */
+    async beginTransaction(): Promise<any> {
+        await this.connected;
+        const session = this.client.startSession();
+        session.startTransaction();
+        return session;
+    }
+    
+    /**
+     * Commit a transaction
+     * 
+     * @param transaction - MongoDB ClientSession returned by beginTransaction()
+     * 
+     * @example
+     * const session = await driver.beginTransaction();
+     * // ... perform operations with { session } in options
+     * await driver.commitTransaction(session);
+     */
+    async commitTransaction(transaction: any): Promise<void> {
+        if (!transaction || typeof transaction.commitTransaction !== 'function') {
+            throw new Error('Invalid transaction object. Must be a MongoDB ClientSession.');
+        }
+        
+        try {
+            await transaction.commitTransaction();
+        } finally {
+            await transaction.endSession();
+        }
+    }
+    
+    /**
+     * Rollback a transaction
+     * 
+     * @param transaction - MongoDB ClientSession returned by beginTransaction()
+     * 
+     * @example
+     * const session = await driver.beginTransaction();
+     * try {
+     *   // ... perform operations
+     *   await driver.commitTransaction(session);
+     * } catch (error) {
+     *   await driver.rollbackTransaction(session);
+     * }
+     */
+    async rollbackTransaction(transaction: any): Promise<void> {
+        if (!transaction || typeof transaction.abortTransaction !== 'function') {
+            throw new Error('Invalid transaction object. Must be a MongoDB ClientSession.');
+        }
+        
+        try {
+            await transaction.abortTransaction();
+        } finally {
+            await transaction.endSession();
+        }
+    }
+
     async disconnect() {
+        // Close all active change streams
+        for (const [streamId, stream] of this.changeStreams.entries()) {
+            await stream.close();
+        }
+        this.changeStreams.clear();
+        
+        // Close the MongoDB client
         if (this.client) {
             await this.client.close();
         }
     }
 
+    /**
+     * Watch for changes in a collection using MongoDB Change Streams
+     * @param objectName - The collection name to watch
+     * @param handler - Callback function to handle change events
+     * @param options - Optional change stream configuration
+     * @returns Stream ID that can be used to close the stream later
+     * 
+     * @example
+     * const streamId = await driver.watch('users', async (change) => {
+     *   console.log('Change detected:', change.operationType);
+     *   if (change.operationType === 'insert') {
+     *     console.log('New document:', change.fullDocument);
+     *   }
+     * }, {
+     *   operationTypes: ['insert', 'update'],
+     *   fullDocument: 'updateLookup'
+     * });
+     * 
+     * // Later, to stop watching:
+     * await driver.unwatchChangeStream(streamId);
+     */
+    async watch(objectName: string, handler: ChangeStreamHandler, options?: ChangeStreamOptions): Promise<string> {
+        const collection = await this.getCollection(objectName);
+        
+        // Build change stream pipeline
+        const pipeline: any[] = options?.pipeline || [];
+        
+        // Add operation type filter if specified
+        if (options?.operationTypes && options.operationTypes.length > 0) {
+            pipeline.unshift({
+                $match: {
+                    operationType: { $in: options.operationTypes }
+                }
+            });
+        }
+        
+        // Configure change stream options
+        const streamOptions: any = {};
+        if (options?.fullDocument) {
+            streamOptions.fullDocument = options.fullDocument;
+        }
+        
+        // Create the change stream
+        const changeStream = collection.watch(pipeline, streamOptions);
+        
+        // Generate unique stream ID
+        const streamId = `${objectName}_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+        
+        // Store the stream
+        this.changeStreams.set(streamId, changeStream);
+        
+        // Handle change events
+        changeStream.on('change', async (change) => {
+            try {
+                await handler(change);
+            } catch (error) {
+                console.error(`[MongoDriver] Error in change stream handler for ${objectName}:`, error);
+            }
+        });
+        
+        changeStream.on('error', (error) => {
+            console.error(`[MongoDriver] Change stream error for ${objectName}:`, error);
+        });
+        
+        return streamId;
+    }
+
+    /**
+     * Stop watching a change stream
+     * @param streamId - The stream ID returned by watch()
+     */
+    async unwatchChangeStream(streamId: string): Promise<void> {
+        const stream = this.changeStreams.get(streamId);
+        if (stream) {
+            await stream.close();
+            this.changeStreams.delete(streamId);
+        }
+    }
+
+    /**
+     * Get all active change stream IDs
+     */
+    getActiveChangeStreams(): string[] {
+        return Array.from(this.changeStreams.keys());
+    }
+
     /**
      * Execute a query using QueryAST (DriverInterface v4.0 method)
      * 

package/test/index.test.ts

@@ -22,6 +22,7 @@ const mockCollection = {
         insertedCount: 2
     }),
     updateOne: jest.fn().mockResolvedValue({ modifiedCount: 1 }),
+    findOneAndUpdate: jest.fn().mockResolvedValue({ value: { _id: '123', name: 'Updated' } }),
     deleteOne: jest.fn().mockResolvedValue({ deletedCount: 1 }),
     countDocuments: jest.fn().mockResolvedValue(10)
 };
@@ -437,20 +438,19 @@ describe('MongoDriver', () => {
                     data: { name: 'Updated User' }
                 };
 
-                mockCollection.updateOne.mockResolvedValue({ 
-                    modifiedCount: 1,
-                    acknowledged: true
-                } as any);
-                mockCollection.findOne.mockResolvedValue({ 
-                    _id: '123', 
-                    name: 'Updated User' 
+                mockCollection.findOneAndUpdate.mockResolvedValue({ 
+                    value: {
+                        _id: '123', 
+                        name: 'Updated User',
+                        updated_at: new Date().toISOString()
+                    }
                 });
 
                 const result = await driver.executeCommand(command);
 
                 expect(result.success).toBe(true);
                 expect(result.affected).toBe(1);
-                expect(mockCollection.updateOne).toHaveBeenCalled();
+                expect(mockCollection.findOneAndUpdate).toHaveBeenCalled();
             });
 
             it('should execute delete command', async () => {
@@ -504,11 +504,13 @@ describe('MongoDriver', () => {
                     ]
                 };
 
-                mockCollection.updateOne.mockResolvedValue({ 
-                    modifiedCount: 1,
-                    acknowledged: true
-                } as any);
-                mockCollection.findOne.mockResolvedValue({ _id: '1', name: 'Updated 1' });
+                mockCollection.findOneAndUpdate.mockResolvedValue({ 
+                    value: {
+                        _id: '1', 
+                        name: 'Updated 1',
+                        updated_at: new Date().toISOString()
+                    }
+                });
 
                 const result = await driver.executeCommand(command);