Merge pull request #1118 from KkevinLi/dev-database-transactions

Realtime database Transaction Implementation

Author: EddyVerbruggen

docs/DATABASE.md

@@ -408,6 +408,64 @@ but if you only want to for instance wipe everything at `/users`, do this:
 ```
 </details>
 
+### Transaction
+Transactions are used when you want to atomically modify data at this location. This
+ensures there are no conflicts with other clients writing to the same location at the
+same time.
+
+You can look at the [docs](https://firebase.google.com/docs/reference/js/firebase.database.Reference#transaction) for more information.
+
+Note that a return value of `null` will delete the value at this location whereas returning
+undefined will abort the transaction. On success a promise is returned containing
+{committed:boolean, snapshot: DataSnapshot} and an error will be returned if the transaciton
+failed.
+
+<details>
+ <summary>Native API</summary>
+
+```typescript
+firebase.transaction(path, (currentValue => {
+      if (currentValue === null) {
+        return 0;
+      } else {
+        // console.log('User ada already exists.');
+        return ++currentValue; // Abort the transaction.
+      }
+    })) // firebase.Datasnapshot follows the web datasnapshot interface
+     .then((result: { committed: boolean, snapshot: firebase.DataSnapshot }) => {
+        console.log(result.committed + " snapshotValue: " + result.snapshot.val());
+      }).catch(err => console.log("Encountered an error " + err));
+```
+</details>
+
+<details>
+ <summary>Web API</summary>
+
+```typescript
+firebaseWebApi.database().ref(path).transaction(currentValue => {
+      if (currentValue === null) {
+        return { name: { first: 'Ada', last: 'Lovelace' } };
+      } else {
+        // console.log('User ada already exists.');
+        return; // Abort the transaction.
+      }
+    })
+      .then((result: { committed: boolean, snapshot: firebase.DataSnapshot }) => {
+        console.log(result.committed + " snapshotValue: " + result.snapshot.val());
+      }).catch(err => console.log("Encountered an error " + err));
+
+
+firebaseWebApi.database().ref(path).transaction(currentValue => {
+      if (currentValue === null) {
+        return null; // Do nothing if this value doesn't exist
+       //return 0    // If you want to put a 0 in if no value exist
+      } else {
+        return ++currentValue; // increment the value
+      }
+    })
+```
+</details>
+
 ### keepInSync
 The Firebase Realtime Database synchronizes and stores a local copy of the data for active listeners (see the methods above). In addition, you can keep specific locations in sync.
 

src/app/database/index.ts

@@ -245,6 +245,17 @@ export module database {
     public onDisconnect(): firebase.OnDisconnect {
       return firebase.onDisconnect(this.path);
     }
+
+    public transaction(
+      transactionUpdate: (a: any) => any,
+      onComplete?: (
+        a: Error | null,
+        b: boolean,
+        c: firebase.DataSnapshot | null
+      ) => any,
+      applyLocally?: boolean): Promise<any> {
+      return firebase.transaction(this.path, transactionUpdate, onComplete);
+    }
   }
 
   export interface ThenableReference extends Reference /*, PromiseLike<any> */

src/firebase.android.ts

@@ -11,7 +11,7 @@ import * as appModule from "tns-core-modules/application";
 import { AndroidActivityResultEventData } from "tns-core-modules/application";
 import { ad as AndroidUtils } from "tns-core-modules/utils/utils";
 import lazy from "tns-core-modules/utils/lazy";
-import { firestore, User, OnDisconnect as OnDisconnectBase } from "./firebase";
+import { firestore, User, OnDisconnect as OnDisconnectBase, DataSnapshot } from "./firebase";
 
 declare const android, com: any;
 
@@ -1335,6 +1335,10 @@ firebase.updateProfile = arg => {
   });
 };
 
+ /***********************************************
+   * Start Realtime Database Functions
+   ***********************************************/
+
 firebase.keepInSync = (path, switchOn) => {
   return new Promise((resolve, reject) => {
     try {
@@ -1793,6 +1797,65 @@ firebase.onDisconnect = (path: string): OnDisconnectBase => {
   return new OnDisconnect(disconnectInstance);
 };
 
+firebase.transaction = (path: string, transactionUpdate: (currentState) => any,
+  onComplete: (a: Error | null, b: boolean, c: DataSnapshot) => Promise<any>) => {
+  return new Promise((resolve, reject) => {
+    if (!firebase.initialized) {
+      console.error("Please run firebase.init() before firebase.transaction()");
+      throw new Error("FirebaseApp is not initialized. Make sure you run firebase.init() first");
+    }
+    const dbRef: com.google.firebase.database.DatabaseReference = firebase.instance.child(path);
+    const handler: com.google.firebase.database.Transaction.Handler = new com.google.firebase.database.Transaction.Handler({
+      doTransaction: (mutableData: com.google.firebase.database.MutableData) => {
+        const desiredValue = transactionUpdate(mutableData.getValue());
+        // Java does not have undefined, but web transactions use undefined to detect if an abort() is desired.
+        if (desiredValue === undefined) {
+          return com.google.firebase.database.Transaction.abort();
+        } else {
+          mutableData.setValue(firebase.toValue(desiredValue));
+          return com.google.firebase.database.Transaction.success(mutableData);
+        }
+      },
+      onComplete: (databaseError: com.google.firebase.database.DatabaseError, commited: boolean, snapshot: com.google.firebase.database.DataSnapshot) => {
+        databaseError !== null ? reject(databaseError.getMessage()) :
+          resolve({ committed: commited, snapshot: nativeSnapshotToWebSnapshot(snapshot) });
+      }
+    });
+    dbRef.runTransaction(handler);
+  });
+};
+
+// Converts Android DataSnapshot into Web Datasnapshot
+function nativeSnapshotToWebSnapshot(snapshot: com.google.firebase.database.DataSnapshot): DataSnapshot {
+  function forEach(action: (datasnapshot: DataSnapshot) => any): boolean {
+    let innerSnapshot: DataSnapshot;
+    for (let iterator = snapshot.getChildren().iterator(); iterator.hasNext();) {
+      innerSnapshot = nativeSnapshotToWebSnapshot(iterator.next());
+      if (action(innerSnapshot)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  return {
+    key: snapshot.getKey(),
+    ref: snapshot.getRef(),
+    child: (path: string) => nativeSnapshotToWebSnapshot(snapshot.child(path)),
+    exists: () => snapshot.exists(),
+    forEach: (func: (datasnapshot) => any) => forEach(func),
+    getPriority: () => firebase.toJsObject(snapshot.getPriority()),
+    hasChild: (path: string) => snapshot.hasChild(path),
+    hasChildren: () => snapshot.hasChildren(),
+    numChildren: () => snapshot.getChildrenCount(),
+    toJSON: () => firebase.toJsObject(snapshot.toString()),
+    val: () => firebase.toJsObject(snapshot.getValue())
+  };
+}
+
+ /***********************************************
+   * END Realtime Database Functions
+   ***********************************************/
+
 firebase.sendCrashLog = arg => {
   return new Promise((resolve, reject) => {
     try {
@@ -2006,6 +2069,7 @@ firebase.firestore.runTransaction = (updateFunction: (transaction: firestore.Tra
   });
 };
 
+
 /*
 class FirestoreTransaction implements firestore.Transaction {
 

src/firebase.d.ts

@@ -527,6 +527,22 @@ export interface OnDisconnect {
   ): Promise<any>;
   update(values: Object): Promise<any>;
 }
+export interface DataSnapshot {
+  key: string,
+  ref: any, // TODO: Type it so that it returns a databaseReference.
+  child(path: string): DataSnapshot,
+  exists(): boolean,
+  forEach(action: (snapshot: DataSnapshot) => any) : boolean,
+  getPriority(): string | number | null,
+  hasChild(path: string): boolean,
+  hasChildren(): boolean,
+  numChildren(): number,
+  toJSON(): Object,
+  val(): any
+};
+
+export function transaction(path: string, transactionUpdate: (a: any) => any,
+  onComplete?: (error: Error | null, committed: boolean, dataSnapshot: DataSnapshot) => any): Promise<any>;
 
 export function push(path: string, value: any): Promise<PushResult>;
 

src/firebase.ios.ts

@@ -9,7 +9,7 @@ import * as firebaseMessaging from "./messaging/messaging";
 import * as application from "tns-core-modules/application/application";
 import { ios as iOSUtils } from "tns-core-modules/utils/utils";
 import * as firebaseFunctions from './functions/functions';
-import { firestore, User, OnDisconnect as OnDisconnectBase } from "./firebase";
+import { firestore, User, OnDisconnect as OnDisconnectBase, transaction, DataSnapshot } from "./firebase";
 import { firebaseUtils } from "./utils";
 
 firebase._gIDAuthentication = null;
@@ -1176,6 +1176,10 @@ firebase.updateProfile = arg => {
   });
 };
 
+ /***********************************************
+   * START Realtime Database Functions
+   ***********************************************/
+
 firebase._addObservers = (to, updateCallback) => {
   const listeners = [];
   listeners.push(to.observeEventTypeWithBlock(FIRDataEventType.ChildAdded, snapshot => {
@@ -1531,6 +1535,66 @@ firebase.onDisconnect = (path: string): OnDisconnect => {
   return new OnDisconnect(dbRef, path);
 };
 
+firebase.transaction = (path: string, transactionUpdate: (currentState) => any,
+  onComplete: (a: Error | null, b: boolean, c: DataSnapshot) => Promise<any>) => {
+  return new Promise<any>((resolve, reject) => {
+    if (!firebase.initialized) {
+      console.error("Please run firebase.init() before firebase.transaction()");
+      throw new Error("FirebaseApp is not initialized. Make sure you run firebase.init() first");
+    }
+    const dbRef: FIRDatabaseReference = FIRDatabase.database().reference().child(path);
+
+    dbRef.runTransactionBlockAndCompletionBlock(
+      (mutableData: FIRMutableData): FIRTransactionResult => {
+        const desiredValue = transactionUpdate(mutableData.value);
+        if (desiredValue === undefined) {
+          return FIRTransactionResult.abort();
+        } else {
+          mutableData.value = desiredValue;
+          return FIRTransactionResult.successWithValue(mutableData);
+        }
+      },
+      (error: NSError, commited: boolean, snapshot: FIRDataSnapshot): void => {
+        error !== null ? reject(error.localizedDescription) :
+          resolve({ committed: commited, snapshot: nativeSnapshotToWebSnapshot(snapshot) });
+      }
+    );
+  });
+};
+
+// Converts FIRDataSnapshot into Web DataSnapshot
+function nativeSnapshotToWebSnapshot(snapshot: FIRDataSnapshot): DataSnapshot {
+  function forEach(action: (datasnapshot: DataSnapshot) => any): boolean {
+    const iterator: NSEnumerator<FIRDataSnapshot> = snapshot.children;
+    let innerSnapshot: FIRDataSnapshot;
+    let datasnapshot: DataSnapshot;
+    while (innerSnapshot = iterator.nextObject()) {
+      datasnapshot = nativeSnapshotToWebSnapshot(innerSnapshot);
+      if (action(datasnapshot)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  return {
+    key: snapshot.key,
+    ref: snapshot.ref,
+    child: (path: string) => nativeSnapshotToWebSnapshot(snapshot.childSnapshotForPath(path)),
+    exists: () => snapshot.exists(),
+    forEach: (func: (datasnapshot) => any) => forEach(func),
+    getPriority: () => firebaseUtils.toJsObject(snapshot.priority),
+    hasChild: (path: string) => snapshot.hasChild(path),
+    hasChildren: () => snapshot.hasChildren(),
+    numChildren: () => snapshot.childrenCount,
+    toJSON: () => snapshot.valueInExportFormat(),
+    val: () => firebaseUtils.toJsObject(snapshot.value)
+  };
+}
+
+ /***********************************************
+   * END Realtime Database Functions
+   ***********************************************/
+
 firebase.sendCrashLog = arg => {
   return new Promise((resolve, reject) => {
     try {