feat(NODE-3333): support 'let' option for CRUD commands (#2829)

src/operations/delete.ts

@@ -18,6 +18,8 @@ export interface DeleteOptions extends CommandOperationOptions, WriteConcernOpti
   collation?: CollationOptions;
   /** Specify that the update query should only consider plans using the hinted index */
   hint?: string | Document;
+  /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
+  let?: Document;
 
   /** @deprecated use `removeOne` or `removeMany` to implicitly specify the limit */
   single?: boolean;
@@ -74,6 +76,10 @@ export class DeleteOperation extends CommandOperation<Document> {
       ordered
     };
 
+    if (options.let) {
+      command.let = options.let;
+    }
+
     if (options.explain !== undefined && maxWireVersion(server) < 3) {
       return callback
         ? callback(new MongoError(`server ${server.name} does not support explain on delete`))

src/operations/find.ts

@@ -61,6 +61,8 @@ export interface FindOptions<TSchema = Document> extends CommandOperationOptions
   allowPartialResults?: boolean;
   /** Determines whether to return the record identifier for each document. If true, adds a field $recordId to the returned documents. */
   showRecordId?: boolean;
+  /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
+  let?: Document;
 }
 
 const SUPPORTS_WRITE_CONCERN_AND_COLLATION = 5;
@@ -286,6 +288,10 @@ function makeFindCommand(ns: MongoDBNamespace, filter: Document, options: FindOp
     findCommand.allowDiskUse = options.allowDiskUse;
   }
 
+  if (options.let) {
+    findCommand.let = options.let;
+  }
+
   return findCommand;
 }
 

src/operations/find_and_modify.ts

@@ -27,6 +27,8 @@ export interface FindOneAndDeleteOptions extends CommandOperationOptions {
   projection?: Document;
   /** Determines which document the operation modifies if the query selects multiple documents. */
   sort?: Sort;
+  /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
+  let?: Document;
 }
 
 /** @public */
@@ -43,6 +45,8 @@ export interface FindOneAndReplaceOptions extends CommandOperationOptions {
   sort?: Sort;
   /** Upsert the document if it does not exist. */
   upsert?: boolean;
+  /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
+  let?: Document;
 }
 
 /** @public */
@@ -61,6 +65,8 @@ export interface FindOneAndUpdateOptions extends CommandOperationOptions {
   sort?: Sort;
   /** Upsert the document if it does not exist. */
   upsert?: boolean;
+  /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
+  let?: Document;
 }
 
 /** @internal */
@@ -74,6 +80,7 @@ interface FindAndModifyCmdBase {
   bypassDocumentValidation?: boolean;
   arrayFilters?: Document[];
   maxTimeMS?: number;
+  let?: Document;
   writeConcern?: WriteConcern | WriteConcernSettings;
 }
 
@@ -129,6 +136,10 @@ class FindAndModifyOperation extends CommandOperation<Document> {
       this.cmdBase.writeConcern = options.writeConcern;
     }
 
+    if (options.let) {
+      this.cmdBase.let = options.let;
+    }
+
     // force primary read preference
     this.readPreference = ReadPreference.primary;
 

src/operations/update.ts

@@ -25,6 +25,8 @@ export interface UpdateOptions extends CommandOperationOptions {
   hint?: string | Document;
   /** When true, creates a new document if no document matches the query */
   upsert?: boolean;
+  /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
+  let?: Document;
 }
 
 /** @public */
@@ -97,6 +99,10 @@ export class UpdateOperation extends CommandOperation<Document> {
       command.bypassDocumentValidation = options.bypassDocumentValidation;
     }
 
+    if (options.let) {
+      command.let = options.let;
+    }
+
     const statementWithCollation = this.statements.find(statement => !!statement.collation);
     if (
       collationNotSupported(server, options) ||

test/functional/unified-spec-runner/operations.ts

@@ -215,7 +215,8 @@ operations.set('createIndex', async ({ entities, operation }) => {
 
 operations.set('deleteOne', async ({ entities, operation }) => {
   const collection = entities.getEntity('collection', operation.object);
-  return collection.deleteOne(operation.arguments.filter);
+  const { filter, ...options } = operation.arguments;
+  return collection.deleteOne(filter, options);
 });
 
 operations.set('dropCollection', async ({ entities, operation }) => {
@@ -230,8 +231,8 @@ operations.set('endSession', async ({ entities, operation }) => {
 
 operations.set('find', async ({ entities, operation }) => {
   const collection = entities.getEntity('collection', operation.object);
-  const { filter, sort, batchSize, limit } = operation.arguments;
-  return collection.find(filter, { sort, batchSize, limit }).toArray();
+  const { filter, sort, batchSize, limit, let: vars } = operation.arguments;
+  return collection.find(filter, { sort, batchSize, limit, let: vars }).toArray();
 });
 
 operations.set('findOneAndReplace', async ({ entities, operation }) => {
@@ -398,12 +399,14 @@ operations.set('runCommand', async ({ entities, operation }: OperationFunctionPa
 
 operations.set('updateMany', async ({ entities, operation }) => {
   const collection = entities.getEntity('collection', operation.object);
-  return collection.updateMany(operation.arguments.filter, operation.arguments.update);
+  const { filter, update, ...options } = operation.arguments;
+  return collection.updateMany(filter, update, options);
 });
 
 operations.set('updateOne', async ({ entities, operation }) => {
   const collection = entities.getEntity('collection', operation.object);
-  return collection.updateOne(operation.arguments.filter, operation.arguments.update);
+  const { filter, update, ...options } = operation.arguments;
+  return collection.updateOne(filter, update, options);
 });
 
 export async function executeOperationAndCheck(

test/spec/crud/unified/aggregate-let.json

@@ -44,6 +44,109 @@
           "minServerVersion": "5.0"
         }
       ],
+      "operations": [
+        {
+          "name": "aggregate",
+          "object": "collection0",
+          "arguments": {
+            "pipeline": [
+              {
+                "$match": {
+                  "$expr": {
+                    "$eq": [
+                      "$_id",
+                      "$$id"
+                    ]
+                  }
+                }
+              },
+              {
+                "$project": {
+                  "_id": 0,
+                  "x": "$$x",
+                  "y": "$$y",
+                  "rand": "$$rand"
+                }
+              }
+            ],
+            "let": {
+              "id": 1,
+              "x": "foo",
+              "y": {
+                "$literal": "bar"
+              },
+              "rand": {
+                "$rand": {}
+              }
+            }
+          },
+          "expectResult": [
+            {
+              "x": "foo",
+              "y": "bar",
+              "rand": {
+                "$$type": "double"
+              }
+            }
+          ]
+        }
+      ],
+      "expectEvents": [
+        {
+          "client": "client0",
+          "events": [
+            {
+              "commandStartedEvent": {
+                "command": {
+                  "aggregate": "coll0",
+                  "pipeline": [
+                    {
+                      "$match": {
+                        "$expr": {
+                          "$eq": [
+                            "$_id",
+                            "$$id"
+                          ]
+                        }
+                      }
+                    },
+                    {
+                      "$project": {
+                        "_id": 0,
+                        "x": "$$x",
+                        "y": "$$y",
+                        "rand": "$$rand"
+                      }
+                    }
+                  ],
+                  "let": {
+                    "id": 1,
+                    "x": "foo",
+                    "y": {
+                      "$literal": "bar"
+                    },
+                    "rand": {
+                      "$rand": {}
+                    }
+                  }
+                }
+              }
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "description": "Aggregate with let option and dollar-prefixed $literal value",
+      "runOnRequirements": [
+        {
+          "minServerVersion": "5.0",
+          "topologies": [
+            "single",
+            "replicaset"
+          ]
+        }
+      ],
       "operations": [
         {
           "name": "aggregate",

test/spec/crud/unified/aggregate-let.yml

@@ -22,9 +22,45 @@ initialData: &initialData
       - { _id: 1 }
 
 tests:
+  # TODO: Once SERVER-57403 is resolved, this test can be removed in favor of
+  # the "dollar-prefixed $literal value" test below.
   - description: "Aggregate with let option"
     runOnRequirements:
       - minServerVersion: "5.0"
+    operations:
+      - name: aggregate
+        object: *collection0
+        arguments:
+          pipeline: &pipeline0
+            # $match takes a query expression, so $expr is necessary to utilize
+            # an aggregate expression context and access "let" variables.
+            - $match: { $expr: { $eq: ["$_id", "$$id"] } }
+            - $project: { _id: 0, x: "$$x", y: "$$y", rand: "$$rand" }
+          # Values in "let" must be constant or closed expressions that do not
+          # depend on document values. This test demonstrates a basic constant
+          # value, a value wrapped with $literal (to avoid expression parsing),
+          # and a closed expression (e.g. $rand).
+          let: &let0
+            id: 1
+            x: foo
+            y: { $literal: "bar" }
+            rand: { $rand: {} }
+        expectResult:
+          - { x: "foo", y: "bar", rand: { $$type: "double" } }
+    expectEvents:
+      - client: *client0
+        events:
+          - commandStartedEvent:
+              command:
+                aggregate: *collection0Name
+                pipeline: *pipeline0
+                let: *let0
+
+  - description: "Aggregate with let option and dollar-prefixed $literal value"
+    runOnRequirements:
+      - minServerVersion: "5.0"
+        # TODO: Remove topology restrictions once SERVER-57403 is resolved
+        topologies: ["single", "replicaset"]
     operations:
       - name: aggregate
         object: *collection0