@objectql/driver-mongo 3.0.1 → 4.0.0

package/MIGRATION.md

@@ -0,0 +1,213 @@
+# MongoDB Driver Migration Guide (Phase 4)
+
+## Overview
+
+The MongoDB driver has been migrated to support the standard `DriverInterface` from `@objectstack/spec` while maintaining full backward compatibility with the existing `Driver` interface from `@objectql/types`.
+
+## What Changed
+
+### 1. Driver Metadata
+
+The driver now exposes metadata for ObjectStack compatibility:
+
+```typescript
+const driver = new MongoDriver(config);
+console.log(driver.name);     // 'MongoDriver'
+console.log(driver.version);  // '3.0.1'
+console.log(driver.supports); // { transactions: true, joins: false, ... }
+```
+
+### 2. Lifecycle Methods
+
+New optional lifecycle methods for DriverInterface compatibility:
+
+```typescript
+// Connect (ensures connection is established)
+await driver.connect();
+
+// Check connection health
+const healthy = await driver.checkHealth(); // true/false
+
+// Disconnect (existing method)
+await driver.disconnect();
+```
+
+### 3. QueryAST Format Support
+
+The driver now supports the new QueryAST format from `@objectstack/spec`:
+
+#### Legacy UnifiedQuery Format (Still Supported)
+```typescript
+const query = {
+    fields: ['name', 'age'],
+    filters: [['age', '>', 18]],
+    sort: [['name', 'asc']],
+    limit: 10,
+    skip: 0
+};
+```
+
+#### New QueryAST Format (Now Supported)
+```typescript
+const query = {
+    object: 'users',
+    fields: ['name', 'age'],
+    filters: [['age', '>', 18]],
+    sort: [{ field: 'name', order: 'asc' }],
+    top: 10,      // Instead of 'limit'
+    skip: 0
+};
+```
+
+### Key Differences
+
+| Aspect | Legacy Format | QueryAST Format |
+|--------|--------------|-----------------|
+| Limit | `limit: 10` | `top: 10` |
+| Sort | `[['field', 'dir']]` | `[{field, order}]` |
+
+## Migration Strategy
+
+The driver uses a **normalization layer** that automatically converts QueryAST format to the internal format:
+
+```typescript
+private normalizeQuery(query: any): any {
+    // Converts 'top' → 'limit'
+    // Handles both sort formats
+}
+```
+
+This means:
+- ✅ Existing code continues to work without changes
+- ✅ New code can use QueryAST format
+- ✅ Both formats work interchangeably
+- ✅ No breaking changes
+
+## Usage Examples
+
+### Using Legacy Format (Unchanged)
+```typescript
+import { MongoDriver } from '@objectql/driver-mongo';
+
+const driver = new MongoDriver({
+    url: 'mongodb://localhost:27017',
+    dbName: 'mydb'
+});
+
+// Works as before
+const results = await driver.find('users', {
+    filters: [['active', '=', true]],
+    sort: [['created_at', 'desc']],
+    limit: 20
+});
+```
+
+### Using QueryAST Format (New)
+```typescript
+import { MongoDriver } from '@objectql/driver-mongo';
+
+const driver = new MongoDriver({
+    url: 'mongodb://localhost:27017',
+    dbName: 'mydb'
+});
+
+// New format
+const results = await driver.find('users', {
+    filters: [['active', '=', true]],
+    sort: [{ field: 'created_at', order: 'desc' }],
+    top: 20
+});
+```
+
+### Using with ObjectStack Kernel
+```typescript
+import { ObjectQL } from '@objectql/core';
+import { MongoDriver } from '@objectql/driver-mongo';
+
+const app = new ObjectQL({
+    datasources: {
+        default: new MongoDriver({
+            url: 'mongodb://localhost:27017',
+            dbName: 'mydb'
+        })
+    }
+});
+
+await app.init();
+
+// The kernel will use QueryAST format internally
+const ctx = app.createContext({ userId: 'user123' });
+const repo = ctx.object('users');
+const users = await repo.find({ filters: [['active', '=', true]] });
+```
+
+## Testing
+
+Comprehensive tests have been added in `test/queryast.test.ts`:
+
+```bash
+npm test -- queryast.test.ts
+```
+
+Test coverage includes:
+- Driver metadata exposure
+- Lifecycle methods (connect, checkHealth, disconnect)
+- QueryAST format with `top` parameter
+- Object-based sort notation
+- Backward compatibility with legacy format
+- Mixed format support
+- Field mapping (id/_id conversion)
+
+## Implementation Details
+
+### Files Changed
+- `package.json`: Added `@objectstack/spec@^0.2.0` dependency
+- `src/index.ts`: 
+  - Added driver metadata properties
+  - Added `normalizeQuery()` method (~45 lines)
+  - Added `connect()` and `checkHealth()` methods (~25 lines)
+  - Updated `find()` to use normalization
+  - Refactored internal `connect()` to `internalConnect()`
+- `test/queryast.test.ts`: New comprehensive test suite (240+ lines)
+
+### Lines of Code
+- **Added**: ~310 lines (including tests and docs)
+- **Modified**: ~15 lines (method signatures and refactoring)
+- **Deleted**: 0 lines
+
+## Driver Capabilities
+
+The MongoDB driver supports:
+- **Transactions**: ✅ Yes
+- **Joins**: ❌ No (MongoDB is document-oriented)
+- **Full-Text Search**: ✅ Yes (MongoDB text search)
+- **JSON Fields**: ✅ Yes (native BSON support)
+- **Array Fields**: ✅ Yes (native array support)
+
+## ID Field Mapping
+
+The driver maintains smart ID mapping:
+- API uses `id` field
+- MongoDB uses `_id` field
+- Automatic bidirectional conversion
+- Both `id` and `_id` can be used in queries for backward compatibility
+
+## Next Steps
+
+With MongoDB driver migration complete, the pattern is established for migrating other drivers:
+
+1. ✅ SQL Driver (completed)
+2. ✅ MongoDB Driver (completed)
+3. 🔜 Memory Driver (recommended next - used for testing)
+4. 🔜 Other drivers (bulk migration)
+
+## Backward Compatibility Guarantee
+
+**100% backward compatible** - all existing code using the MongoDB driver will continue to work without any changes. The QueryAST support is additive, not replacing.
+
+## References
+
+- [ObjectStack Spec Package](https://www.npmjs.com/package/@objectstack/spec)
+- [SQL Driver Migration Guide](../sql/MIGRATION.md)
+- [Runtime Integration Docs](../../foundation/core/RUNTIME_INTEGRATION.md)
+- [Driver Interface Documentation](../../foundation/types/src/driver.ts)

package/README.md

@@ -2,6 +2,8 @@
 
 MongoDB driver for ObjectQL. Supports basic CRUD, filtering, and aggregation pipelines on MongoDB.
 
+**Now with ObjectStack QueryAST support!** This driver implements both the legacy `Driver` interface and the new `DriverInterface` from `@objectstack/spec` for seamless integration with the ObjectStack ecosystem.
+
 ## Installation
 
 ```bash
@@ -24,3 +26,59 @@ const objectql = new ObjectQL({
     }
 });
 ```
+
+## Features
+
+- ✅ **100% Backward Compatible** - All existing code continues to work
+- ✅ **QueryAST Support** - Supports the new `@objectstack/spec` query format
+- ✅ **Smart ID Mapping** - Automatic conversion between `id` (API) and `_id` (MongoDB)
+- ✅ **Full-Text Search** - MongoDB text search capabilities
+- ✅ **Array & JSON Fields** - Native BSON support for complex data types
+- ✅ **Aggregation Pipelines** - Native MongoDB aggregation support
+
+## Driver Metadata
+
+```typescript
+console.log(driver.name);     // 'MongoDriver'
+console.log(driver.version);  // '3.0.1'
+console.log(driver.supports); 
+// {
+//   transactions: true,
+//   joins: false,
+//   fullTextSearch: true,
+//   jsonFields: true,
+//   arrayFields: true
+// }
+```
+
+## QueryAST Format
+
+The driver now supports both legacy and QueryAST formats:
+
+### Legacy Format
+```typescript
+const results = await driver.find('users', {
+    filters: [['age', '>', 18]],
+    sort: [['name', 'asc']],
+    limit: 10,
+    skip: 0
+});
+```
+
+### QueryAST Format
+```typescript
+const results = await driver.find('users', {
+    filters: [['age', '>', 18]],
+    sort: [{ field: 'name', order: 'asc' }],
+    top: 10,  // Instead of 'limit'
+    skip: 0
+});
+```
+
+## Migration Guide
+
+See [MIGRATION.md](./MIGRATION.md) for detailed information about the ObjectStack migration and QueryAST format support.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,5 +1,56 @@
+/**
+ * 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';
-export declare class MongoDriver implements Driver {
+import { DriverInterface, QueryAST } from '@objectstack/spec';
+/**
+ * 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 declare class MongoDriver implements Driver, DriverInterface {
+    readonly name = "MongoDriver";
+    readonly version = "3.0.1";
+    readonly supports: {
+        transactions: boolean;
+        joins: boolean;
+        fullTextSearch: boolean;
+        jsonFields: boolean;
+        arrayFields: boolean;
+    };
     private client;
     private db?;
     private config;
@@ -8,7 +59,19 @@ export declare class MongoDriver implements Driver {
         url: string;
         dbName?: string;
     });
-    private connect;
+    /**
+     * Internal connect method used in constructor
+     */
+    private internalConnect;
+    /**
+     * Connect to the database (for DriverInterface compatibility)
+     * This method ensures the connection is established.
+     */
+    connect(): Promise<void>;
+    /**
+     * Check database connection health
+     */
+    checkHealth(): Promise<boolean>;
     private getCollection;
     private normalizeId;
     /**
@@ -33,6 +96,15 @@ export declare class MongoDriver implements Driver {
      * Build a single MongoDB condition from field, operator, and value.
      */
     private buildSingleCondition;
+    /**
+     * 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;
     find(objectName: string, query: any, options?: any): Promise<any[]>;
     findOne(objectName: string, id: string | number, query?: any, options?: any): Promise<any>;
     create(objectName: string, data: any, options?: any): Promise<any>;
@@ -44,4 +116,44 @@ export declare class MongoDriver implements Driver {
     deleteMany(objectName: string, filters: any, options?: any): Promise<any>;
     aggregate(objectName: string, pipeline: any[], options?: any): Promise<any[]>;
     disconnect(): Promise<void>;
+    /**
+     * 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
+     */
+    executeQuery(ast: QueryAST, options?: any): Promise<{
+        value: any[];
+        count?: number;
+    }>;
+    /**
+     * 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
+     */
+    executeCommand(command: Command, options?: any): Promise<CommandResult>;
+    /**
+     * Convert FilterNode (QueryAST format) to legacy filter array format
+     * This allows reuse of existing filter logic while supporting new QueryAST
+     *
+     * @private
+     */
+    private convertFilterNodeToLegacy;
+    /**
+     * Execute command (alternative signature for compatibility)
+     *
+     * @param command - Command string or object
+     * @param parameters - Command parameters
+     * @param options - Execution options
+     */
+    execute(command: any, parameters?: any[], options?: any): Promise<any>;
 }