cordova-plugin-firebasex-firestore 2.0.2 → 2.0.4

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+# Version 2.0.4
+feat: add `runTransactionOnFirestoreDocument` to atomically compare field conditions on an existing document and apply field-path updates when all conditions match.
+
+# Version 2.0.3
+- (ios) bugfix: fix boolean filter values in `fetchFirestoreCollection`/`listenToFirestoreCollection` being evaluated incorrectly (always `true`) due to an incorrect `NSNumber`-to-`BOOL` conversion in `getFilterValueAsType:valueIndex:typeIndex:`.
+
 # Version 2.0.2
 - fix: pin core plugin dependency to v2
 

package/README.md

@@ -14,6 +14,7 @@ This plugin wraps the [Firebase Firestore SDK](https://firebase.google.com/docs/
   - [addDocumentToFirestoreCollection](#adddocumenttofirestorecollection)
   - [setDocumentInFirestoreCollection](#setdocumentinfirestorecollection)
   - [updateDocumentInFirestoreCollection](#updatedocumentinfirestorecollection)
+    - [runTransactionOnFirestoreDocument](#runtransactiononfirestoredocument)
   - [deleteDocumentFromFirestoreCollection](#deletedocumentfromfirestorecollection)
   - [documentExistsInFirestoreCollection](#documentexistsinfirestorecollection)
   - [fetchDocumentInFirestoreCollection](#fetchdocumentinfirestorecollection)
@@ -231,6 +232,43 @@ FirebasexFirestore.updateDocumentInFirestoreCollection(
 );
 ```
 
+## runTransactionOnFirestoreDocument
+
+Atomically compares field conditions on an existing document and applies field-path updates when
+all conditions match. The operation runs inside a native Firestore transaction, so concurrent
+claims cannot both pass the same preconditions. The success callback receives an object with a
+`status` of `updated`, `conflict`, or `missing`; Firestore and transport errors use the error
+callback.
+
+**Parameters**:
+
+-   {string} documentId - document ID of the document to compare and update.
+-   {object[]} conditions - conditions with `path`, optional `exists`, and optional `value` properties.
+-   {object} updates - field-path updates to apply without replacing unrelated document data.
+-   {string} collection - name of top-level collection containing the document.
+-   {boolean} timestamp (optional) - Add `lastUpdate` to the update. Default `false`.
+-   {function} success (optional) - callback receiving `{status: "updated"|"conflict"|"missing"}`.
+-   {function} error (optional) - callback which will be passed a {string} error message.
+
+```javascript
+FirebasexFirestore.runTransactionOnFirestoreDocument(
+    "my_doc",
+    [
+        {path: "some_property", exists: false}
+    ],
+    {"id": [{id: "new-id", timestamp: new Date().toISOString()}]},
+    "my_collection",
+    function (result) {
+        if (result.status === "updated") {
+            console.log("Document updated atomically");
+        }
+    },
+    function (error) {
+        console.error("Error running transaction: " + error);
+    }
+);
+```
+
 ## deleteDocumentFromFirestoreCollection
 
 Deletes an existing document with the given ID in a Firestore collection.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cordova-plugin-firebasex-firestore",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "Firestore module for cordova-plugin-firebasex",
   "cordova": {
     "id": "cordova-plugin-firebasex-firestore",
@@ -22,6 +22,7 @@
   "keywords": ["cordova", "firebase", "firestore"],
   "author": "Dave Alden",
   "license": "MIT",
+  "types": "types/index.d.ts",
   "dependencies": {
     "cordova-plugin-firebasex-core": "^2.0.0"
   },

package/plugin.xml

@@ -1,6 +1,6 @@
 <?xml version='1.0' encoding='utf-8'?>
 <plugin id="cordova-plugin-firebasex-firestore"
-        version="2.0.2"
+        version="2.0.4"
         xmlns="http://apache.org/cordova/ns/plugins/1.0"
         xmlns:android="http://schemas.android.com/apk/res/android">
 
@@ -63,7 +63,7 @@
                 <source url="https://cdn.cocoapods.org/"/>
             </config>
             <pods use-frameworks="true">
-                <pod name="FirebaseFirestore" spec="12.14.0" nospm="true" />
+                <pod name="FirebaseFirestore" tag="12.14.0" git="https://github.com/invertase/firestore-ios-sdk-frameworks.git" nospm="true" />
             </pods>
         </podspec>
 

package/src/android/FirebasexFirestorePlugin.java

@@ -23,6 +23,7 @@ import com.google.firebase.firestore.Query;
 import com.google.firebase.firestore.QueryDocumentSnapshot;
 import com.google.firebase.firestore.QuerySnapshot;
 import com.google.firebase.firestore.Query.Direction;
+import com.google.firebase.firestore.Transaction;
 import com.google.gson.Gson;
 import com.google.gson.reflect.TypeToken;
 
@@ -36,6 +37,7 @@ import org.json.JSONObject;
 import java.lang.reflect.Type;
 import java.util.Date;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 import java.util.Random;
@@ -75,7 +77,8 @@ public class FirebasexFirestorePlugin extends CordovaPlugin {
      * Dispatches Cordova actions to plugin methods.
      *
      * <p>Supported actions: addDocumentToFirestoreCollection, setDocumentInFirestoreCollection,
-     * updateDocumentInFirestoreCollection, deleteDocumentFromFirestoreCollection,
+    * updateDocumentInFirestoreCollection, deleteDocumentFromFirestoreCollection,
+    * runTransactionOnFirestoreDocument,
      * documentExistsInFirestoreCollection, fetchDocumentInFirestoreCollection,
      * fetchFirestoreCollection, listenToDocumentInFirestoreCollection,
      * listenToFirestoreCollection, removeFirestoreListener.
@@ -92,6 +95,9 @@ public class FirebasexFirestorePlugin extends CordovaPlugin {
             case "updateDocumentInFirestoreCollection":
                 this.updateDocumentInFirestoreCollection(args, callbackContext);
                 return true;
+            case "runTransactionOnFirestoreDocument":
+                this.runTransactionOnFirestoreDocument(args, callbackContext);
+                return true;
             case "deleteDocumentFromFirestoreCollection":
                 this.deleteDocumentFromFirestoreCollection(args, callbackContext);
                 return true;
@@ -144,6 +150,80 @@ public class FirebasexFirestorePlugin extends CordovaPlugin {
         return gson.fromJson(jsonString, type);
     }
 
+    /** Deserialises a JSON array of field conditions into maps. */
+    private List<Map<String, Object>> jsonStringToConditions(String jsonString) throws JSONException {
+        Type type = new TypeToken<List<Map<String, Object>>>() {}.getType();
+        return gson.fromJson(jsonString, type);
+    }
+
+    /** Marker returned when a field path does not exist in a document. */
+    private static final Object MISSING_FIELD = new Object();
+
+    /** Reads a nested field path from a Firestore document map. */
+    private Object getValueForFieldPath(Map<String, Object> document, String fieldPath) {
+        Object value = document;
+        String[] path = fieldPath.split("\\.");
+        for (String component : path) {
+            if (!(value instanceof Map) || !((Map<?, ?>) value).containsKey(component)) {
+                return MISSING_FIELD;
+            }
+            value = ((Map<?, ?>) value).get(component);
+        }
+        return value;
+    }
+
+    /** Compares JSON-compatible Firestore values without depending on numeric runtime types. */
+    private boolean firestoreValuesEqual(Object actual, Object expected) {
+        if (actual == expected) return true;
+        if (actual == null || expected == null) return false;
+        if (actual instanceof Number && expected instanceof Number) {
+            return Double.compare(((Number) actual).doubleValue(), ((Number) expected).doubleValue()) == 0;
+        }
+        if (actual instanceof Map && expected instanceof Map) {
+            Map<?, ?> actualMap = (Map<?, ?>) actual;
+            Map<?, ?> expectedMap = (Map<?, ?>) expected;
+            if (!actualMap.keySet().equals(expectedMap.keySet())) return false;
+            for (Object key : actualMap.keySet()) {
+                if (!firestoreValuesEqual(actualMap.get(key), expectedMap.get(key))) return false;
+            }
+            return true;
+        }
+        if (actual instanceof List && expected instanceof List) {
+            List<?> actualList = (List<?>) actual;
+            List<?> expectedList = (List<?>) expected;
+            if (actualList.size() != expectedList.size()) return false;
+            for (int i = 0; i < actualList.size(); i++) {
+                if (!firestoreValuesEqual(actualList.get(i), expectedList.get(i))) return false;
+            }
+            return true;
+        }
+        return actual.equals(expected);
+    }
+
+    /** Checks all declarative field conditions against a Firestore document. */
+    private boolean conditionsMatch(Map<String, Object> document, List<Map<String, Object>> conditions) {
+        for (Map<String, Object> condition : conditions) {
+            String fieldPath = (String) condition.get("path");
+            if (fieldPath == null || fieldPath.length() == 0) return false;
+
+            Object actual = getValueForFieldPath(document, fieldPath);
+            boolean actualExists = actual != MISSING_FIELD;
+            boolean expectedExists = !condition.containsKey("exists") || Boolean.TRUE.equals(condition.get("exists"));
+            if (actualExists != expectedExists) return false;
+            if (expectedExists && condition.containsKey("value") && !firestoreValuesEqual(actual, condition.get("value"))) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    /** Creates the stable result returned by an atomic document transaction. */
+    private Map<String, Object> transactionResult(String status) {
+        Map<String, Object> result = new HashMap<String, Object>();
+        result.put("status", status);
+        return result;
+    }
+
     /** Sanitises a Firestore data map and converts it to a JSONObject. */
     private JSONObject mapFirestoreDataToJsonObject(Map<String, Object> map) throws JSONException {
         map = sanitiseFirestoreHashMap(map);
@@ -430,6 +510,55 @@ public class FirebasexFirestorePlugin extends CordovaPlugin {
         });
     }
 
+    /** Atomically compares field conditions and updates a Firestore document when they match. */
+    private void runTransactionOnFirestoreDocument(JSONArray args, CallbackContext callbackContext) throws JSONException {
+        cordova.getThreadPool().execute(new Runnable() {
+            public void run() {
+                try {
+                    String documentId = args.getString(0);
+                    List<Map<String, Object>> conditions = jsonStringToConditions(args.getString(1));
+                    Map<String, Object> updates = jsonStringToMap(args.getString(2));
+                    String collection = args.getString(3);
+                    boolean timestamp = args.getBoolean(4);
+                    DocumentReference documentReference = firestore.collection(collection).document(documentId);
+
+                    firestore.runTransaction(new Transaction.Function<Map<String, Object>>() {
+                        @Override
+                        public Map<String, Object> apply(@NonNull Transaction transaction) throws FirebaseFirestoreException {
+                            DocumentSnapshot snapshot = transaction.get(documentReference);
+                            if (!snapshot.exists()) return transactionResult("missing");
+                            Map<String, Object> document = snapshot.getData();
+                            if (document == null || !conditionsMatch(document, conditions)) {
+                                return transactionResult("conflict");
+                            }
+
+                            Map<String, Object> transactionUpdates = new HashMap<String, Object>(updates);
+                            if (timestamp) transactionUpdates.put("lastUpdate", new Timestamp(new Date()));
+                            transaction.update(documentReference, transactionUpdates);
+                            return transactionResult("updated");
+                        }
+                    }).addOnSuccessListener(new OnSuccessListener<Map<String, Object>>() {
+                        @Override
+                        public void onSuccess(Map<String, Object> result) {
+                            try {
+                                callbackContext.success(new JSONObject(result));
+                            } catch (Exception e) {
+                                FirebasexCorePlugin.handleExceptionWithContext(e, callbackContext);
+                            }
+                        }
+                    }).addOnFailureListener(new OnFailureListener() {
+                        @Override
+                        public void onFailure(@NonNull Exception e) {
+                            FirebasexCorePlugin.handleExceptionWithContext(e, callbackContext);
+                        }
+                    });
+                } catch (Exception e) {
+                    FirebasexCorePlugin.handleExceptionWithContext(e, callbackContext);
+                }
+            }
+        });
+    }
+
     /** Deletes a document from a collection by its ID. */
     private void deleteDocumentFromFirestoreCollection(JSONArray args, CallbackContext callbackContext) throws JSONException {
         cordova.getThreadPool().execute(new Runnable() {

package/src/ios/FirebasexFirestorePlugin.h

@@ -21,6 +21,8 @@
 - (void)setDocumentInFirestoreCollection:(CDVInvokedUrlCommand *)command;
 /** Updates fields of an existing document. @param command args[0]: documentId, args[1]: document, args[2]: collection, args[3]: timestamp. */
 - (void)updateDocumentInFirestoreCollection:(CDVInvokedUrlCommand *)command;
+/** Atomically compares field conditions and updates a document. @param command args[0]: documentId, args[1]: conditions, args[2]: updates, args[3]: collection, args[4]: timestamp. */
+- (void)runTransactionOnFirestoreDocument:(CDVInvokedUrlCommand *)command;
 /** Deletes a document by ID. @param command args[0]: documentId, args[1]: collection. */
 - (void)deleteDocumentFromFirestoreCollection:(CDVInvokedUrlCommand *)command;
 /** Checks if a document exists. @param command args[0]: documentId, args[1]: collection. */

package/src/ios/FirebasexFirestorePlugin.m

@@ -120,6 +120,98 @@
     return value;
 }
 
+/** Reads a nested field path and reports whether that path exists. */
+- (id)valueForFieldPath:(NSString *)fieldPath inDocument:(NSDictionary *)document exists:(BOOL *)exists {
+    id value = document;
+    *exists = YES;
+    for (NSString *component in [fieldPath componentsSeparatedByString:@"."]) {
+        if (![value isKindOfClass:[NSDictionary class]] || [(NSDictionary *)value objectForKey:component] == nil) {
+            *exists = NO;
+            return nil;
+        }
+        value = [(NSDictionary *)value objectForKey:component];
+    }
+    return value;
+}
+
+/** Compares JSON-compatible Firestore values, including nested dictionaries and arrays. */
+- (BOOL)firestoreValuesEqual:(id)actual expected:(id)expected {
+    if (actual == expected) {
+        return YES;
+    }
+    if (actual == nil || expected == nil) {
+        return NO;
+    }
+    if ([actual isKindOfClass:[NSNumber class]] && [expected isKindOfClass:[NSNumber class]]) {
+        if ([self isBoolNumber:actual] != [self isBoolNumber:expected]) {
+            return NO;
+        }
+        return [actual isEqualToNumber:expected];
+    }
+    if ([actual isKindOfClass:[NSDictionary class]] && [expected isKindOfClass:[NSDictionary class]]) {
+        NSDictionary *actualDictionary = actual;
+        NSDictionary *expectedDictionary = expected;
+        if (actualDictionary.count != expectedDictionary.count) {
+            return NO;
+        }
+        for (id key in actualDictionary) {
+            if (![expectedDictionary objectForKey:key] ||
+                ![self firestoreValuesEqual:[actualDictionary objectForKey:key]
+                                     expected:[expectedDictionary objectForKey:key]]) {
+                return NO;
+            }
+        }
+        return YES;
+    }
+    if ([actual isKindOfClass:[NSArray class]] && [expected isKindOfClass:[NSArray class]]) {
+        NSArray *actualArray = actual;
+        NSArray *expectedArray = expected;
+        if (actualArray.count != expectedArray.count) {
+            return NO;
+        }
+        for (NSUInteger index = 0; index < actualArray.count; index++) {
+            if (![self firestoreValuesEqual:[actualArray objectAtIndex:index]
+                                     expected:[expectedArray objectAtIndex:index]]) {
+                return NO;
+            }
+        }
+        return YES;
+    }
+    return [actual isEqual:expected];
+}
+
+/** Checks all declarative field conditions against a Firestore document. */
+- (BOOL)conditionsMatch:(NSDictionary *)document conditions:(NSArray *)conditions {
+    for (NSDictionary *condition in conditions) {
+        if (![condition isKindOfClass:[NSDictionary class]]) {
+            return NO;
+        }
+        NSString *fieldPath = [condition objectForKey:@"path"];
+        if (![fieldPath isKindOfClass:[NSString class]] || fieldPath.length == 0) {
+            return NO;
+        }
+
+        BOOL actualExists = NO;
+        id actual = [self valueForFieldPath:fieldPath inDocument:document exists:&actualExists];
+        id existsValue = [condition objectForKey:@"exists"];
+        BOOL expectedExists = existsValue == nil ||
+            ([existsValue isKindOfClass:[NSNumber class]] && [existsValue boolValue]);
+        if (actualExists != expectedExists) {
+            return NO;
+        }
+        if (expectedExists && [condition objectForKey:@"value"] != nil &&
+            ![self firestoreValuesEqual:actual expected:[condition objectForKey:@"value"]]) {
+            return NO;
+        }
+    }
+    return YES;
+}
+
+/** Creates the stable result dictionary returned by an atomic document transaction. */
+- (NSDictionary *)transactionResult:(NSString *)status {
+    return @{ @"status": status };
+}
+
 #pragma mark - Query filters
 
 /**
@@ -190,7 +282,7 @@
 
     if ([type isEqual:@"boolean"]) {
         if ([typedValue isKindOfClass:[NSNumber class]]) {
-            typedValue = [NSNumber numberWithBool:typedValue];
+            typedValue = [NSNumber numberWithBool:[typedValue boolValue]];
         } else if ([typedValue isKindOfClass:[NSString class]]) {
             bool boolValue = [typedValue boolValue];
             typedValue = [NSNumber numberWithBool:boolValue];
@@ -321,6 +413,52 @@
     }];
 }
 
+/** Atomically compares field conditions and updates a Firestore document when they match. */
+- (void)runTransactionOnFirestoreDocument:(CDVInvokedUrlCommand *)command {
+    [self.commandDelegate runInBackground:^{
+        @try {
+            NSString *documentId = [command.arguments objectAtIndex:0];
+            NSArray *conditions = [command.arguments objectAtIndex:1];
+            NSDictionary *updates = [command.arguments objectAtIndex:2];
+            NSString *collection = [command.arguments objectAtIndex:3];
+            BOOL timestamp = [[command.arguments objectAtIndex:4] boolValue];
+            FIRDocumentReference *documentReference = [[self.firestore collectionWithPath:collection]
+                documentWithPath:documentId];
+
+            [self.firestore runTransactionWithBlock:^id _Nullable(FIRTransaction *transaction, NSError **error) {
+                FIRDocumentSnapshot *snapshot = [transaction getDocument:documentReference error:error];
+                if (error != nil && *error != nil) {
+                    return nil;
+                }
+                if (!snapshot.exists) {
+                    return [self transactionResult:@"missing"];
+                }
+                if (![self conditionsMatch:snapshot.data conditions:conditions]) {
+                    return [self transactionResult:@"conflict"];
+                }
+
+                NSMutableDictionary *transactionUpdates = [updates mutableCopy];
+                if (timestamp) {
+                    transactionUpdates[@"lastUpdate"] = [FIRTimestamp timestampWithDate:[NSDate date]];
+                }
+                [transaction updateData:transactionUpdates forDocument:documentReference];
+                return [self transactionResult:@"updated"];
+            } completion:^(id _Nullable result, NSError *_Nullable error) {
+                if (error != nil) {
+                    [[FirebasexCorePlugin sharedInstance] sendPluginErrorWithMessage:error.localizedDescription :command];
+                } else {
+                    [self.commandDelegate
+                        sendPluginResult:[CDVPluginResult resultWithStatus:CDVCommandStatus_OK
+                                                      messageAsDictionary:result]
+                              callbackId:command.callbackId];
+                }
+            }];
+        } @catch (NSException *exception) {
+            [[FirebasexCorePlugin sharedInstance] handlePluginExceptionWithContext:exception :command];
+        }
+    }];
+}
+
 /** Deletes a document from a collection by its ID. */
 - (void)deleteDocumentFromFirestoreCollection:(CDVInvokedUrlCommand *)command {
     [self.commandDelegate runInBackground:^{

package/types/index.d.ts

@@ -22,6 +22,23 @@ interface FirebasexFirestore {
         success: () => void,
         error: (err: string) => void
     ): void;
+    runTransactionOnFirestoreDocument(
+        documentId: string | number,
+        conditions: object[],
+        updates: object,
+        collection: string,
+        timestamp: boolean,
+        success: (result: { status: 'updated' | 'conflict' | 'missing' }) => void,
+        error: (err: string) => void
+    ): void;
+    runTransactionOnFirestoreDocument(
+        documentId: string | number,
+        conditions: object[],
+        updates: object,
+        collection: string,
+        success: (result: { status: 'updated' | 'conflict' | 'missing' }) => void,
+        error: (err: string) => void
+    ): void;
     deleteDocumentFromFirestoreCollection(
         documentId: string,
         collection: string,

package/www/firebasex-firestore.js

@@ -40,7 +40,7 @@ exports.addDocumentToFirestoreCollection = function (document, collection, times
     if (typeof collection !== 'string') return error("'collection' must be a string specifying the Firestore collection name");
     if (typeof document !== 'object' || typeof document.length === 'number') return error("'document' must be an object specifying record data");
 
-    if (typeof timestamp !== "boolean" && typeof error === "undefined") {
+    if (typeof timestamp !== "boolean") {
         error = success;
         success = timestamp;
         timestamp = false;
@@ -98,6 +98,36 @@ exports.updateDocumentInFirestoreCollection = function (documentId, document, co
     exec(success, error, SERVICE, "updateDocumentInFirestoreCollection", [documentId.toString(), document, collection, timestamp || false]);
 };
 
+/**
+ * Atomically compares fields on an existing document and updates it when all conditions match.
+ * Conditions use objects with a field path, an optional exists flag, and an optional value.
+ * Updates use Firestore field paths as keys, so nested fields can be changed without replacing
+ * unrelated data. The success callback receives {status: "updated"}, {status: "conflict"}, or
+ * {status: "missing"}.
+ *
+ * @param {string|number} documentId - The document identifier.
+ * @param {Array.<Object>} conditions - Field conditions to compare inside the transaction.
+ * @param {Object} updates - Field-path updates to apply when conditions match.
+ * @param {string} collection - The Firestore collection path.
+ * @param {boolean} [timestamp=false] - If true, updates the lastUpdate Timestamp field.
+ * @param {function} success - Called with the transaction result.
+ * @param {function} error - Called with an error message on failure.
+ */
+exports.runTransactionOnFirestoreDocument = function (documentId, conditions, updates, collection, timestamp, success, error) {
+    if (typeof documentId !== 'string' && typeof documentId !== 'number') return error("'documentId' must be a string or number specifying the Firestore document identifier");
+    if (!Array.isArray(conditions)) return error("'conditions' must be an array of field conditions");
+    if (typeof updates !== 'object' || updates === null || typeof updates.length === 'number') return error("'updates' must be an object specifying field-path updates");
+    if (typeof collection !== 'string') return error("'collection' must be a string specifying the Firestore collection name");
+
+    if (typeof timestamp !== "boolean" && typeof error === "undefined") {
+        error = success;
+        success = timestamp;
+        timestamp = false;
+    }
+
+    exec(success, error, SERVICE, "runTransactionOnFirestoreDocument", [documentId.toString(), conditions, updates, collection, timestamp || false]);
+};
+
 /**
  * Deletes a document from a Firestore collection.
  *