@objectql/driver-mongo 4.0.1 → 4.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectql/driver-mongo",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "MongoDB driver for ObjectQL - Native aggregation pipeline translation for high-performance NoSQL operations",
   "keywords": [
     "objectql",
@@ -16,9 +16,9 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@objectstack/spec": "^0.3.1",
+    "@objectstack/spec": "^0.8.0",
     "mongodb": "^5.9.2",
-    "@objectql/types": "4.0.1"
+    "@objectql/types": "4.0.3"
   },
   "devDependencies": {
     "mongodb-memory-server": "^11.0.1"

package/src/index.ts

@@ -1,8 +1,7 @@
-import { Data, System } from '@objectstack/spec';
+import { Data, System as SystemSpec } from '@objectstack/spec';
 type QueryAST = Data.QueryAST;
-type FilterNode = Data.FilterNode;
 type SortNode = Data.SortNode;
-type DriverInterface = System.DriverInterface;
+type DriverInterface = Data.DriverInterface;
 /**
  * ObjectQL
  * Copyright (c) 2026-present ObjectStack Inc.
@@ -12,7 +11,24 @@ type DriverInterface = System.DriverInterface;
  */
 
 import { Driver } from '@objectql/types';
-import { MongoClient, Db, Filter, ObjectId, FindOptions } from 'mongodb';
+import { MongoClient, Db, Filter, ObjectId, FindOptions, 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
@@ -69,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();
     }
 
     /**
@@ -150,12 +168,72 @@ export class MongoDriver implements Driver {
     }
 
     private mapFilters(filters: any): Filter<any> {
-        if (!filters || filters.length === 0) return {};
+        if (!filters) return {};
+        
+        // If filters is an object (FilterCondition format), map id fields to _id
+        if (typeof filters === 'object' && !Array.isArray(filters)) {
+            return this.mapIdFieldsInFilter(filters);
+        }
+        
+        // If filters is an array (legacy format), convert it
+        if (Array.isArray(filters) && filters.length === 0) return {};
         
         const result = this.buildFilterConditions(filters);
         return result;
     }
 
+    /**
+     * Recursively map 'id' fields to '_id' in FilterCondition objects
+     * and normalize primitive values to use $eq operator when inside logical operators
+     */
+    private mapIdFieldsInFilter(filter: any, insideLogicalOp: boolean = false): any {
+        if (!filter || typeof filter !== 'object') {
+            return filter;
+        }
+
+        const result: any = {};
+        
+        for (const [key, value] of Object.entries(filter)) {
+            // Handle logical operators
+            if (key === '$and' || key === '$or') {
+                if (Array.isArray(value)) {
+                    // Pass true to indicate we're inside a logical operator
+                    result[key] = value.map(v => this.mapIdFieldsInFilter(v, true));
+                }
+            } 
+            // Map 'id' to '_id'
+            else if (key === 'id') {
+                // If value is already an object with operators, recurse
+                if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                    result['_id'] = this.mapIdFieldsInFilter(value, insideLogicalOp);
+                } else {
+                    // Primitive value - wrap with $eq only if inside logical operator
+                    result['_id'] = insideLogicalOp ? { $eq: value } : value;
+                }
+            }
+            // Skip MongoDB operator keys (starting with $) - but still recurse for nested mappings
+            else if (key.startsWith('$')) {
+                // Recursively process to handle nested objects that might contain 'id' fields
+                if (typeof value === 'object' && value !== null) {
+                    result[key] = this.mapIdFieldsInFilter(value, insideLogicalOp);
+                } else {
+                    result[key] = value;
+                }
+            }
+            // Recursively handle nested objects (already operator-wrapped values)
+            else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                result[key] = this.mapIdFieldsInFilter(value, insideLogicalOp);
+            }
+            // Primitive field values
+            else {
+                // Wrap with $eq only if inside a logical operator
+                result[key] = insideLogicalOp ? { $eq: value } : value;
+            }
+        }
+        
+        return result;
+    }
+
     /**
      * Build MongoDB filter conditions from ObjectQL filter array.
      * Supports nested filter groups and logical operators (AND/OR).
@@ -258,68 +336,45 @@ export class MongoDriver implements Driver {
      * 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 {};
+    async find(objectName: string, query: any, options?: any): Promise<any[]> {
+        const collection = await this.getCollection(objectName);
         
-        const normalized: any = { ...query };
+        // Handle both new format (where) and legacy format (filters)
+        const filterCondition = query.where || query.filters;
+        const filter = this.mapFilters(filterCondition);
         
-        // 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
-            }));
-        }
+        const findOptions: FindOptions = {};
         
-        // 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'
-                ]);
-            }
-        }
+        // Handle pagination - support both new format (offset/limit) and legacy format (skip/top)
+        const offsetValue = query.offset ?? query.skip;
+        const limitValue = query.limit ?? query.top;
         
-        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(normalizedQuery.filters);
+        if (offsetValue !== undefined) findOptions.skip = offsetValue;
+        if (limitValue !== undefined) findOptions.limit = limitValue;
         
-        const findOptions: FindOptions = {};
-        if (normalizedQuery.skip) findOptions.skip = normalizedQuery.skip;
-        if (normalizedQuery.limit) findOptions.limit = normalizedQuery.limit;
-        if (normalizedQuery.sort) {
-            // map [['field', 'desc']] to { field: -1 }
+        // Handle sort - support both new format (orderBy) and legacy format (sort)
+        const sortArray = query.orderBy || query.sort;
+        if (sortArray && Array.isArray(sortArray)) {
             findOptions.sort = {};
-            for (const [field, order] of normalizedQuery.sort) {
+            for (const item of sortArray) {
+                // Support both {field, order} object format and [field, order] array format
+                const field = item.field || item[0];
+                const order = item.order || item[1] || 'asc';
                 // 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 (normalizedQuery.fields && normalizedQuery.fields.length > 0) {
+        
+        if (query.fields && query.fields.length > 0) {
             findOptions.projection = {};
-            for (const field of normalizedQuery.fields) {
+            for (const field of query.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');
+            const hasIdField = query.fields.some((f: string) => f === 'id' || f === '_id');
             if (!hasIdField) {
                 (findOptions.projection as any)._id = 0;
             }
@@ -383,9 +438,12 @@ export class MongoDriver implements Driver {
 
     async count(objectName: string, filters: any, options?: any): Promise<number> {
         const collection = await this.getCollection(objectName);
-        // Normalize to support both filter arrays and full query objects
-        const normalizedQuery = this.normalizeQuery(filters);
-        const actualFilters = normalizedQuery.filters || filters;
+        // Handle both filter objects and query objects
+        let actualFilters = filters;
+        if (filters && (filters.where || filters.filters)) {
+            // It's a query object with 'where' or 'filters' property
+            actualFilters = filters.where || filters.filters;
+        }
         const filter = this.mapFilters(actualFilters);
         return await collection.countDocuments(filter);
     }
@@ -435,12 +493,164 @@ 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;
+    }
+
     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)
      * 
@@ -452,19 +662,9 @@ export class MongoDriver implements Driver {
      * @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);
+        // QueryAST is now the same format as our internal query
+        // Just pass it directly to find
+        const results = await this.find(ast.object || '', ast, options);
         
         return {
             value: results,
@@ -575,54 +775,9 @@ export class MongoDriver implements Driver {
     }
 
     /**
-     * Convert FilterNode (QueryAST format) to legacy filter array format
+     * Convert FilterCondition (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)
      *