Add POSTINSTALL.md and improve README.md

Patryk Lesiewicz · Patryk Lesiewicz · commit 051898295f4a · 2019-07-10T10:05:53.000-07:00
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
@@ -66,12 +66,14 @@ export class Counter {
   }
 
   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)
