fix: Allow an explicit MustExist precondition for update (#1985)

Author: dconeybe

dev/conformance/conformance-tests/update-exists-precond.json renamed to dev/conformance/conformance-tests/update-exists-false-precond.json

@@ -1,12 +1,12 @@
 {
   "tests": [
     {
-      "description": "update: Exists precondition is invalid",
-      "comment": "The Update method does not support an explicit exists precondition.",
+      "description": "update: Exists=false precondition is invalid",
+      "comment": "The Update method does not support an explicit exists=false precondition.",
       "update": {
         "docRefPath": "projects/projectID/databases/(default)/documents/C/d",
         "precondition": {
-          "exists": true
+          "exists": false
         },
         "jsonData": "{\"a\": 1}",
         "isError": true

dev/conformance/conformance-tests/update-exists-true-precond.json

@@ -0,0 +1,38 @@
+{
+  "tests": [
+    {
+      "description": "update: Exists=true precondition is valid",
+      "comment": "The Update method supports an explicit exists=true precondition.",
+      "update": {
+        "docRefPath": "projects/projectID/databases/(default)/documents/C/d",
+        "precondition": {
+          "exists": true
+        },
+        "jsonData": "{\"a\": 1}",
+        "request": {
+          "database": "projects/projectID/databases/(default)",
+          "writes": [
+            {
+              "update": {
+                "name": "projects/projectID/databases/(default)/documents/C/d",
+                "fields": {
+                  "a": {
+                    "integerValue": "1"
+                  }
+                }
+              },
+              "updateMask": {
+                "fieldPaths": [
+                  "a"
+                ]
+              },
+              "currentDocument": {
+                "exists": true
+              }
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

dev/conformance/conformance-tests/update-paths-exists-precond.json renamed to dev/conformance/conformance-tests/update-paths-exists-false-precond.json

@@ -1,12 +1,12 @@
 {
   "tests": [
     {
-      "description": "update-paths: Exists precondition is invalid",
-      "comment": "The Update method does not support an explicit exists precondition.",
+      "description": "update-paths: Exists=false precondition is invalid",
+      "comment": "The Update method does not support an explicit exists=false precondition.",
       "updatePaths": {
         "docRefPath": "projects/projectID/databases/(default)/documents/C/d",
         "precondition": {
-          "exists": true
+          "exists": false
         },
         "fieldPaths": [
           {

dev/conformance/conformance-tests/update-paths-exists-true-precond.json

@@ -0,0 +1,47 @@
+{
+  "tests": [
+    {
+      "description": "update-paths: Exists=true precondition is valid",
+      "comment": "The Update method supports an explicit exists=true precondition.",
+      "updatePaths": {
+        "docRefPath": "projects/projectID/databases/(default)/documents/C/d",
+        "precondition": {
+          "exists": true
+        },
+        "fieldPaths": [
+          {
+            "field": [
+              "a"
+            ]
+          }
+        ],
+        "jsonValues": [
+          "1"
+        ],
+        "request": {
+          "database": "projects/projectID/databases/(default)",
+          "writes": [
+            {
+              "update": {
+                "name": "projects/projectID/databases/(default)/documents/C/d",
+                "fields": {
+                  "a": {
+                    "integerValue": "1"
+                  }
+                }
+              },
+              "updateMask": {
+                "fieldPaths": [
+                  "a"
+                ]
+              },
+              "currentDocument": {
+                "exists": true
+              }
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

dev/src/write-batch.ts

@@ -660,12 +660,12 @@ export class WriteBatch implements firestore.WriteBatch {
  * @internal
  * @param arg The argument name or argument index (for varargs methods).
  * @param value The object to validate
- * @param allowExists Whether to allow the 'exists' preconditions.
+ * @param options Options describing other things for this function to validate.
  */
 function validatePrecondition(
   arg: string | number,
   value: unknown,
-  allowExists: boolean
+  options?: {allowedExistsValues?: boolean[]}
 ): void {
   if (typeof value !== 'object' || value === null) {
     throw new Error('Input is not an object.');
@@ -677,20 +677,22 @@ function validatePrecondition(
 
   if (precondition.exists !== undefined) {
     ++conditions;
-    if (!allowExists) {
+    if (typeof precondition.exists !== 'boolean') {
       throw new Error(
         `${invalidArgumentMessage(
           arg,
           'precondition'
-        )} "exists" is not an allowed precondition.`
+        )} "exists" is not a boolean.'`
       );
     }
-    if (typeof precondition.exists !== 'boolean') {
+    if (
+      options?.allowedExistsValues &&
+      options.allowedExistsValues.indexOf(precondition.exists) < 0
+    ) {
       throw new Error(
-        `${invalidArgumentMessage(
-          arg,
-          'precondition'
-        )} "exists" is not a boolean.'`
+        `${invalidArgumentMessage(arg, 'precondition')} ` +
+          `"exists" is not allowed to have the value ${precondition.exists} ` +
+          `(allowed values: ${options.allowedExistsValues.join(', ')})`
       );
     }
   }
@@ -733,7 +735,7 @@ function validateUpdatePrecondition(
   options?: RequiredArgumentOptions
 ): asserts value is {lastUpdateTime?: Timestamp} {
   if (!validateOptional(value, options)) {
-    validatePrecondition(arg, value, /* allowExists= */ false);
+    validatePrecondition(arg, value, {allowedExistsValues: [true]});
   }
 }
 
@@ -753,7 +755,7 @@ function validateDeletePrecondition(
   options?: RequiredArgumentOptions
 ): void {
   if (!validateOptional(value, options)) {
-    validatePrecondition(arg, value, /* allowExists= */ true);
+    validatePrecondition(arg, value);
   }
 }
 

dev/test/document.ts

@@ -1629,6 +1629,27 @@ describe('update document', () => {
     });
   });
 
+  it('allows explicitly specifying {exists:true} precondition', () => {
+    const overrides: ApiOverride = {
+      commit: request => {
+        requestEquals(
+          request,
+          update({
+            document: document('documentId', 'foo', 'bar'),
+            mask: updateMask('foo'),
+          })
+        );
+        return response(writeResult(1));
+      },
+    };
+
+    return createInstance(overrides).then(firestore => {
+      return firestore
+        .doc('collectionId/documentId')
+        .update('foo', 'bar', {exists: true});
+    });
+  });
+
   it('returns update time', () => {
     const overrides: ApiOverride = {
       commit: request => {
@@ -2069,7 +2090,7 @@ describe('update document', () => {
   it("doesn't accept argument after precondition", () => {
     expect(() => {
       firestore.doc('collectionId/documentId').update('foo', 'bar', {
-        exists: true,
+        exists: false,
       });
     }).to.throw(INVALID_ARGUMENTS_TO_UPDATE);