Add docs

Author: dconeybe

packages/firestore/src/util/testing_hooks.ts

@@ -20,20 +20,20 @@
  * internal state and events during integration tests. Do not use this class
  * except for testing purposes.
  *
- * There are two ways to retrieve an instance of this class:
+ * There are two ways to retrieve the global singleton instance of this class:
  * 1. The `instance` property, which returns null if the global singleton
- *      instance has not been created.
+ *      instance has not been created. Use this property if the caller should
+ *      "do nothing" if there are no testing hooks registered, such as when
+ *      delivering an event to notify registered callbacks.
  * 2. The `getOrCreateInstance()` method, which creates the global singleton
- *      instance if it has not been created.
- *
- * Use the former method if the caller should "do nothing" there are no testing
- * hooks registered. Use the latter if the instance is needed to, for example,
- * register a testing hook.
+ *      instance if it has not been created. Use this method if the instance is
+ *      needed to, for example, register a callback.
  *
  * @internal
  */
 export class TestingHooks {
-  private readonly onExistenceFilterMismatchCallbacks: Array<
+  private readonly onExistenceFilterMismatchCallbacks: Map<
+    Symbol,
     (arg: unknown) => void
   > = [];
 
@@ -61,30 +61,30 @@ export class TestingHooks {
   /**
    * Registers a callback to be notified when an existence filter mismatch
    * occurs in the Watch listen stream.
-   * @param callback the callback to invoke upon existence filter mismatch.
+   *
+   * The relative order in which callbacks are notified is unspecified; do not
+   * rely on any particular ordering.
+   *
+   * @param callback the callback to invoke upon existence filter mismatch. The
+   * type of the argument to this callback is intentionally declared as
+   * `unknown`, rather than something more specific, to discourage its use
+   * unless you really, really know what you are doing. If you know what you are
+   * doing then you know the type and how to interpret it.
+   *
    * @return a function that, when called, unregisters the given callback; only
    * the first invocation of the returned function does anything; all subsequent
    * invocations do nothing.
    */
   onExistenceFilterMismatch(callback: (arg: unknown) => void): () => void {
-    this.onExistenceFilterMismatchCallbacks.push(callback);
-
-    let removed = false;
-    return () => {
-      if (!removed) {
-        const index = this.onExistenceFilterMismatchCallbacks.indexOf(callback);
-        this.onExistenceFilterMismatchCallbacks.splice(index, 1);
-        removed = true;
-      }
-    };
+    const key = Symbol();
+    this.onExistenceFilterMismatchCallbacks.set(key, callback);
+    return () => this.onExistenceFilterMismatchCallbacks.delete(key);
   }
 
   /**
    * Invokes all currently-registered `onExistenceFilterMismatch` callbacks.
-   * @param arg the argument to specify to the callbacks; the type of this
-   * argument is intentionally declared as `unknown` to discourage casual use;
-   * the specific use of this callback in tests knows the structure of the
-   * given argument and will use it accordingly.
+   * @param arg the argument to specify to the callbacks; see the documentation
+   * for `onExistenceFilterMismatch()` for details.
    */
   notifyOnExistenceFilterMismatch(arg: unknown): void {
     this.onExistenceFilterMismatchCallbacks.forEach(callback => callback(arg));

packages/firestore/test/integration/util/testing_hooks_util.ts

@@ -18,10 +18,10 @@
 import { _TestingHooks as TestingHooks } from './firebase_export';
 
 /**
- * Captures all existence filter mismatches that occur during the execution of
- * the given code block.
- * @param callback The callback to invoke, during whose invocation the existence
- * filter mismatches will be captured.
+ * Captures all existence filter mismatches in the Watch 'Listen' stream that
+ * occur during the execution of the given code block.
+ * @param callback The callback to invoke; during the invocation of this
+ * callback all existence filter mismatches will be captured.
  * @return the captured existence filter mismatches.
  */
 export async function captureExistenceFilterMismatches(
@@ -32,20 +32,24 @@ export async function captureExistenceFilterMismatches(
     results.push(
       existenceFilterMismatchInfoFromRaw(arg as RawExistenceFilterMismatchInfo)
     );
+
   const unregister =
     TestingHooks.getOrCreateInstance().onExistenceFilterMismatch(
       callbackWrapper
     );
+
   try {
     await callback();
   } finally {
     unregister();
   }
+
   return results;
 }
 
 /**
- * The shape of the object specified to `onExistenceFilterMismatch` callbacks.
+ * The shape of the object specified to
+ * `TestingUtils.onExistenceFilterMismatch()` callbacks.
  */
 interface RawExistenceFilterMismatchInfo {
   actualCount: number;
@@ -66,38 +70,51 @@ interface RawExistenceFilterMismatchInfo {
 }
 
 /**
- * Information about an existence filter mismatch.
+ * Information about an existence filter mismatch, capturing during an
+ * invocation of `captureExistenceFilterMismatches()`.
  */
 export interface ExistenceFilterMismatchInfo {
+  /** The number of documents that match the query in the local cache. */
   actualCount: number;
+  /** The number of documents that matched the query on the server. */
   expectedCount: number;
-  bloomFilter?: ExistenceFilterBloomFilter;
+  /** The bloom filter provided by the server, or null if not provided. */
+  bloomFilter: ExistenceFilterBloomFilter | null;
 }
 
 /**
  * Information about a bloom filter in an existence filter.
  */
 export interface ExistenceFilterBloomFilter {
+  /** Whether the bloom filter was able to be used to avert a full requery. */
   applied: boolean;
+  /** The number of hash functions used in the bloom filter. */
   hashCount: number;
+  /** The number of bytes in the bloom filter. */
   bitmapLength: number;
+  /** The number of bits of "padding" in the last byte of the bloom filter. */
   padding: number;
 }
 
+/**
+ * Creates a `ExistenceFilterMismatchInfo` object from the raw object given
+ * by `TestingUtils`.
+ */
 function existenceFilterMismatchInfoFromRaw(
   raw: RawExistenceFilterMismatchInfo
 ): ExistenceFilterMismatchInfo {
-  const result: ExistenceFilterMismatchInfo = {
+  return {
     actualCount: raw.actualCount,
-    expectedCount: raw.change.existenceFilter.count
+    expectedCount: raw.change.existenceFilter.count,
+    bloomFilter: bloomFilterFromRawExistenceFilterMismatchInfo(raw)
   };
-  const bloomFilter = bloomFilterFromRawExistenceFilterMismatchInfo(raw);
-  if (bloomFilter) {
-    result.bloomFilter = bloomFilter;
-  }
-  return result;
 }
 
+/**
+ * Creates an `ExistenceFilterBloomFilter` object from the raw object given
+ * by `TestingUtils`, returning null if the given object does not defined a
+ * bloom filter.
+ */
 function bloomFilterFromRawExistenceFilterMismatchInfo(
   raw: RawExistenceFilterMismatchInfo
 ): null | ExistenceFilterBloomFilter {