Add full backward compatibility for _id in MongoDB driver queries

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

docs/guide/drivers/mongo.md

@@ -85,25 +85,52 @@ const users = await app.find('users', query);
 
 ### Migration from Legacy Code
 
-If you have existing code using `_id`, you should migrate to using `id` for consistency:
+If you have existing code using `_id`, you have two options:
+
+1. **Recommended: Migrate to `id`** for consistency across drivers:
 
 **Before (Legacy):**
 ```typescript
 // ❌ Old way - inconsistent with SQL drivers
 const query = {
-  filters: [['_id', '=', '507f1f77bcf86cd799439011']]
+  filters: [['_id', '=', '507f1f77bcf86cd799439011']],
+  sort: [['_id', 'desc']],
+  fields: ['_id', 'name']
 };
 ```
 
 **After (Recommended):**
 ```typescript
 // ✅ New way - consistent across all drivers
 const query = {
-  filters: [['id', '=', '507f1f77bcf86cd799439011']]
+  filters: [['id', '=', '507f1f77bcf86cd799439011']],
+  sort: [['id', 'desc']],
+  fields: ['id', 'name']
 };
 ```
 
-**Note:** The MongoDB driver still accepts `_id` in filters for backward compatibility, but using `id` is strongly recommended for new code.
+2. **Backward Compatible Mode:** Continue using `_id` in queries (results still return `id`)
+
+The MongoDB driver **fully supports `_id` in filters, sorting, and field projections** for backward compatibility:
+
+```typescript
+// ✅ This works - backward compatible
+const query = {
+  filters: [['_id', '=', '507f1f77bcf86cd799439011']],
+  sort: [['_id', 'desc']],
+  fields: ['_id', 'name']
+};
+const users = await app.find('users', query);
+
+// Results ALWAYS use 'id' regardless of query field name
+console.log(users[0].id); // '507f1f77bcf86cd799439011'
+console.log(users[0]._id); // undefined
+```
+
+**Key Points:**
+- Queries accept both `id` and `_id` (automatically mapped to MongoDB's `_id`)
+- Results always return `id` field (never `_id`)
+- Using `id` is recommended for database portability
 
 ## ID Generation
 

docs/guide/migration-id-field.md

@@ -133,25 +133,34 @@ find src/ -type f -name "*.ts" -exec sed -i "s/\['_id'/\['id'/g" {} +
 
 ### MongoDB Driver
 
-The MongoDB driver maintains backward compatibility:
+The MongoDB driver maintains **full backward compatibility** for `_id` usage:
 
-- `_id` in filters still works (mapped to `id` internally)
-- `_id` in create operations is mapped to `id`
-- Results always return `id` (not `_id`)
+- `_id` in **filters** is automatically mapped to MongoDB's `_id`
+- `_id` in **sorting** is automatically mapped to MongoDB's `_id`
+- `_id` in **field projections** is automatically mapped to MongoDB's `_id`
+- `_id` in **create operations** is mapped to `id`
+- Results **always** return `id` (not `_id`)
 
 **Example:**
 ```typescript
-// Legacy code - still works but not recommended
+// Legacy code - fully supported for backward compatibility
 const query = {
-  filters: [['_id', '=', 'user-123']]
+  filters: [['_id', '=', 'user-123']],
+  sort: [['_id', 'desc']],
+  fields: ['_id', 'name', 'email']
 };
 const users = await app.find('users', query);
 
-// Result uses 'id' (not '_id')
+// Results use 'id' (not '_id')
 console.log(users[0].id); // 'user-123'
 console.log(users[0]._id); // undefined
 ```
 
+**No Breaking Changes:** Your existing queries using `_id` will continue to work without modification. However, migrating to `id` is recommended for:
+- Consistency with SQL drivers
+- Database portability
+- Future-proofing your code
+
 ### SQL Driver
 
 The SQL driver has always used `id`, so no migration needed for SQL-only codebases.

packages/drivers/mongo/src/index.ts

@@ -136,16 +136,16 @@ export class MongoDriver implements Driver {
             // map [['field', 'desc']] to { field: -1 }
             findOptions.sort = {};
             for (const [field, order] of query.sort) {
-                // Map 'id' to '_id' for sorting
-                const dbField = field === 'id' ? '_id' : field;
+                // 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) {
             findOptions.projection = {};
             for (const field of query.fields) {
-                // Map 'id' to '_id' for projection
-                const dbField = field === 'id' ? '_id' : field;
+                // Map both 'id' and '_id' to '_id' for backward compatibility
+                const dbField = (field === 'id' || field === '_id') ? '_id' : field;
                 (findOptions.projection as any)[dbField] = 1;
             }
         }

packages/drivers/mongo/test/index.test.ts

@@ -174,4 +174,50 @@ describe('MongoDriver', () => {
         expect(result).toHaveProperty('name', 'Charlie');
     });
 
+    // Backward compatibility tests for legacy '_id' usage
+    it('should accept "_id" field in filters for backward compatibility', async () => {
+        const query = {
+            filters: [['_id', '=', '12345']]
+        };
+        await driver.find('users', query);
+        
+        expect(mockCollection.find).toHaveBeenCalledWith(
+            { _id: '12345' },
+            expect.any(Object)
+        );
+    });
+
+    it('should accept "_id" in sorting for backward compatibility', async () => {
+        const query = {
+            sort: [['_id', 'asc']]
+        };
+        await driver.find('users', query);
+        
+        expect(mockCollection.find).toHaveBeenCalledWith(
+            {},
+            expect.objectContaining({ 
+                sort: { _id: 1 }
+            })
+        );
+    });
+
+    it('should accept "_id" in field projection for backward compatibility', async () => {
+        mockCollection.toArray.mockResolvedValueOnce([{ _id: '456', name: 'Dave' }]);
+        
+        const query = {
+            fields: ['_id', 'name']
+        };
+        const results = await driver.find('users', query);
+        
+        expect(mockCollection.find).toHaveBeenCalledWith(
+            {},
+            expect.objectContaining({ 
+                projection: { _id: 1, name: 1 }
+            })
+        );
+        
+        // Should still return 'id' instead of '_id' in results
+        expect(results[0]).toEqual({ id: '456', name: 'Dave' });
+    });
+
 });