Merge pull request #83 from FirebasePrivate/patryk/counter-docs

Patryk Lesiewicz · web-flow · commit c407d0b900af · 2019-07-11T14:12:30.000-07:00
Improve documentation
diff --git a/firestore-sharded-counter/POSTINSTALL.md b/firestore-sharded-counter/POSTINSTALL.md
@@ -0,0 +1,7 @@
+## Final step
+
+To finish the installation please set up a cloud scheduler job to call the controller function every minute. You can do it by running the following gcloud command.
+
+```
+gcloud scheduler jobs create http firestore-sharded-counter-controller --schedule="* * * * *" --uri=${function:controller.url} --project=${param:PROJECT_ID}
+```
diff --git a/firestore-sharded-counter/README.md b/firestore-sharded-counter/README.md
@@ -1,5 +1,34 @@
+# firestore-sharded-counter
+
+**DESCRIPTION**: Auto-scalable counters for your app.
+
+
+**FEATURES**:
+
+- Zero configuration, one mod for all your app needs
+- Automatically scales from 0 updates/sec to at least 10k updates/sec
+- Efficient for very low traffic counters
+- Handles gracefully bursts of up to thousands updates/sec
+- Can support thousands of updates/sec per counter and millions of counters in an app
+- Works well offline and provides latency compensation
+  - Counter updates are immediately visible locally even though the main counter is eventually updated
+
+
+**DETAILS**: This mod allows you to increment any fields in your documents at arbitrary rate.
+
+Client SDK, instead of incrementing the field directly, increments their own shard in `_counter_shards_` subcollection. A background task is periodically aggregating these shards and eventually rolling them up to the main counters.
+
+There are three cloud functions that orchestrate shard aggregations:
+1. A `worker` function is responsible for monitoring and aggregating a range of shards. There may be 0 or hundreds of  workers running concurrently to scale up to large workloads
+2. A `controller` function runs every minute and monitors the health of the workers. It can scale up and down the number of workers as needed and recover a worker on failure.
+3. A `onWrite` function triggers every time a shard is written and runs one-time aggregation. This improves latency for low workloads where no workers is running. To improve efficiency there's only one instance of this function running at any given time (`maxInstances` is set to 1).
+
 # Installation
-`firebase mods:install . --project=<my-project-id>`
+```
+firebase mods:install . --project=<my-project-id>
+
+Please check the post-install message for the final step to set up your mod.
+```
 
 # Web SDK
 ```
@@ -11,21 +40,26 @@
     </head>
     <body>
         <script>
-            // Initialize Firebase
+            // Initialize Firebase.
             var config = {};
             firebase.initializeApp(config);
             var db = firebase.firestore();
 
-            // Initialize counter
+            // Initialize the sharded counter.
             var views = new sharded.Counter(db.doc("pages/hello-world"), "stats.views");
             
-            // Increment the counter
-            views.incrementBy(firebase.firestore.FieldValue.increment(3));
+            // This will increment a field "stats.views" of the "pages/hello-world" document by 3.
+            views.incrementBy(3);
 
             // Listen to locally consistent values
             views.onSnapshot((snap) => {
-                console.log("Visits: " + snap.data());
+                console.log("Locally consistent view of visits: " + snap.data());
             });
+
+            // Alternatively if you don't mind counter delays, you can listen to the document directly.
+            db.doc("pages/hello-world").onSnapshot((snap) => {
+                console.log("Eventually consistent view of visits: " + snap.get("stats.views"));
+            })
         </script>
     </body>
 </html>
@@ -36,4 +70,4 @@
     cd functions/
     npm install
     npm run build
-```
+```
diff --git a/firestore-sharded-counter/clients/web/dist/sharded-counter.js b/firestore-sharded-counter/clients/web/dist/sharded-counter.js
diff --git a/firestore-sharded-counter/clients/web/src/index.ts b/firestore-sharded-counter/clients/web/src/index.ts
@@ -21,6 +21,13 @@ export class Counter {
   private shards: { [key: string]: number } = {};
   private notifyPromise: Promise<void> = null;
 
+  /**
+   * Constructs a sharded counter object that references to a field
+   * in a document that is a counter.
+   * 
+   * @param doc A reference to a document with a counter field.
+   * @param field A path to a counter field in the above document.
+   */
   constructor(
     private doc: firebase.firestore.DocumentReference,
     private field: string
@@ -37,6 +44,12 @@ export class Counter {
     this.shards[shardsRef.doc("\t\t\t\t" + this.shardId.substr(0, 1)).path] = 0;
   }
 
+  /**
+   * Get latency compensated view of the counter.
+   * 
+   * All local increments will be reflected in the counter even if the main
+   * counter hasn't been updated yet.
+   */
   public async get(options?: firebase.firestore.GetOptions): Promise<number> {
     const valuePromises = Object.keys(this.shards).map(async (path) => {
       const shard = await this.db.doc(path).get(options);
@@ -46,6 +59,12 @@ export class Counter {
     return values.reduce((a,b) => a + b, 0);
   }
 
+  /**
+   * Listen to latency compensated view of the counter.
+   * 
+   * All local increments to this counter will be immediately visible in the
+   * snapshot.
+   */
   public onSnapshot(observable: ((next: CounterSnapshot) => void)) {
     Object.keys(this.shards).forEach((path) => {
       this.db
@@ -65,19 +84,38 @@ export class Counter {
     });
   }
 
+  /**
+   * Increment the counter by a given value.
+   * 
+   * e.g.
+   * const counter = new sharded.Counter(db.doc("path/document"), "counter");
+   * counter.incrementBy(1);
+   */
   public incrementBy(
-    val: firebase.firestore.FieldValue
+    val: number
   ): Promise<void> {
+    // @ts-ignore
+    const increment: any = firebase.firestore.FieldValue.increment(val);
     const update: { [key: string]: any } = this.field
       .split(".")
       .reverse()
-      .reduce((value, name) => ({ [name]: value }), <any>val);
+      .reduce((value, name) => ({ [name]: value }), increment);
     return this.doc
       .collection(SHARD_COLLECTION_ID)
       .doc(this.shardId)
       .set(update, { merge: true });
   }
 
+  /**
+   * Access the assigned shard directly. Useful to update multiple counters
+   * at the same time, batches or transactions.
+   * 
+   * e.g.
+   * const counter = new sharded.Counter(db.doc("path/counter"), "");
+   * const shardRef = counter.shard();
+   * shardRef.set({"counter1", firestore.FieldValue.Increment(1),
+   *               "counter2", firestore.FieldValue.Increment(1));
+   */
   public shard(): firebase.firestore.DocumentReference {
     return this.doc.collection(SHARD_COLLECTION_ID).doc(this.shardId);
   }
