Allow using custom masks to enable field removal (#143)

Co-authored-by: Yuval Rosen <[email protected]>

Author: YuvAIR

.github/README.md

@@ -90,6 +90,13 @@ To update only specific fields of a document at this location, we can set the `m
 firestore.updateDocument("FirstCollection/FirstDocument", data, true);
 ```
 
+Or alternatiavely, we can set the `mask` parameter to an array of field names:
+```javascript
+firestore.updateDocument("FirstCollection/FirstDocument", data, ["field1", "field2", "fieldN"]);
+```
+this is useful for [this](https://firebase.google.com/docs/firestore/reference/rest/v1beta1/projects.databases.documents/patch#query-parameters):
+> If the document exists on the server and has fields not referenced in the mask, they are left unchanged. Fields referenced in the mask, but not present in the input document (the `data` in our example), are deleted from the document on the server.
+
 ##### Deleting Documents
 To delete a document at this location, we can use the `deleteDocument` function:
 ```javascript

Firestore.ts

@@ -93,10 +93,12 @@ class Firestore implements FirestoreRead, FirestoreWrite, FirestoreDelete {
    *
    * @param {string} path the path of the document to update. If document name not provided, a random ID will be generated.
    * @param {object} fields the document's new fields
-   * @param {boolean} mask if true, the update will use a mask
+   * @param {boolean|string[]} mask if true, the update will mask the given fields,
+   * if is an array (of field names), that array would be used as the mask.
+   * (that way you can, for example, include a field in `mask`, but not in `fields`, and by doing so, delete that field)
    * @return {object} the Document object written to Firestore
    */
-  updateDocument(path: string, fields: Record<string, any>, mask = false): Document {
+  updateDocument(path: string, fields: Record<string, any>, mask?: boolean | string[]): Document {
     const request = new Request(this.baseUrl, this.authToken);
     return this.updateDocument_(path, fields, request, mask);
   }

FirestoreWrite.ts

@@ -30,16 +30,25 @@ class FirestoreWrite {
    * @param {string} path the path of the document to update
    * @param {object} fields the document's new fields
    * @param {string} request the Firestore Request object to manipulate
-   * @param {boolean} mask if true, the update will use a mask. i.e. true: updates only specific fields, false: overwrites document with specified fields
+   * @param {boolean|string[]} mask the update will mask the given fields,
+   * if is an array (of field names), that array would be used as the mask. i.e. true: updates only specific fields, false: overwrites document with specified fields
+   * see jsdoc of the `updateDocument` method in Firestore.ts for more details
    * @return {object} the Document object written to Firestore
    */
-  updateDocument_(path: string, fields: Record<string, any>, request: Request, mask = false): Document {
+  updateDocument_(path: string, fields: Record<string, any>, request: Request, mask?: boolean | string[]): Document {
     if (mask) {
+      const maskData = typeof mask === 'boolean' ? Object.keys(fields) : mask;
+
+      // Object.keys always returns an array, so this is only for when the given mask is not a boolean.
+      if (!Array.isArray(maskData)) {
+        throw new Error('Mask must be a boolean or an array of strings!');
+      }
+
       // abort request if fields object is empty
-      if (!Object.keys(fields).length) {
+      if (!maskData.length) {
         throw new Error('Missing fields in Mask!');
       }
-      for (const field in fields) {
+      for (const field of maskData) {
         request.addParam('updateMask.fieldPaths', `\`${field.replace(/`/g, '\\`')}\``);
       }
     }

Tests.ts

@@ -168,6 +168,28 @@ class Tests implements TestManager {
     GSUnit.assertObjectEquals(expected, updatedDoc.obj);
   }
 
+  Test_Update_Document_Mask_Array(): void {
+    const expected: { [key: string]: string } = {
+      field1: 'value1',
+      field2: 'value2',
+      field3: 'value3',
+    };
+    const path = 'Test Collection/Updatable Document MaskArray';
+    this.db.createDocument(path, expected);
+    const updater: { [key: string]: string } = { field2: 'new value2' };
+    const updaterMask = ['field1', 'field2'];
+    const updatedDoc = this.db.updateDocument(path, updater, updaterMask);
+    for (const field of updaterMask) {
+      if (field in updater) {
+        expected[field] = updater[field];
+      } else {
+        delete expected[field];
+      }
+    }
+    GSUnit.assertEquals(path, updatedDoc.path);
+    GSUnit.assertObjectEquals(expected, updatedDoc.obj);
+  }
+
   Test_Update_Document_Overwrite_Missing(): void {
     const path = 'Test Collection/Missing Document Overwrite';
     const expected = { 'boolean value': false };