@dereekb/firebase 13.10.8 → 13.11.0

package/test/index.esm.js

@@ -258,6 +258,7 @@ function _ts_generator$6(thisArg, body) {
  * ```
  *
  * @param driver - The base driver to wrap with fuzzing behavior.
+ * @returns A {@link TestingFirestoreAccessorDriver} with `collection`, `subcollection`, and `collectionGroup` rewired to use fuzzed paths, plus helpers to inspect the fuzz map.
  */ function makeTestingFirestoreAccesorDriver(driver) {
     var fuzzerKey = 0;
     var time = new Date().getTime();
@@ -314,8 +315,8 @@ function _ts_generator$6(thisArg, body) {
 /**
  * Extends the input drivers to generate new drivers for a testing environment.
  *
- * @param drivers
- * @returns
+ * @param drivers - The base Firestore drivers to wrap.
+ * @returns A {@link TestingFirestoreDrivers} marked with `firestoreDriverType: 'testing'` and a wrapped accessor driver from {@link makeTestingFirestoreAccesorDriver}.
  */ function makeTestingFirestoreDrivers(drivers) {
     return _object_spread_props$2(_object_spread$3({}, drivers), {
         firestoreDriverType: 'testing',
@@ -411,6 +412,7 @@ var bucketTestNameKey = 0;
  *
  * @param driver - The base storage accessor driver to wrap.
  * @param config - Optional configuration controlling test bucket behavior.
+ * @returns A driver with the same surface as `driver`, but with `getDefaultBucket` overridden to return a unique test bucket name when {@link MakeTestingFirebaseStorageAccessorDriverConfig.useTestDefaultBucket} requires it.
  */ function makeTestingFirebaseStorageAccesorDriver(driver, config) {
     var useTestDefaultBucket = (config !== null && config !== void 0 ? config : {}).useTestDefaultBucket;
     // The default bucket is only used if another bucket is not input.
@@ -427,8 +429,9 @@ var bucketTestNameKey = 0;
 /**
  * Extends the input drivers to generate new drivers for a testing environment.
  *
- * @param drivers
- * @returns
+ * @param drivers - The base Firebase Storage drivers to wrap.
+ * @param config - Optional config forwarded to {@link makeTestingFirebaseStorageAccesorDriver}; controls test-bucket override behavior.
+ * @returns A {@link TestingFirebaseStorageDrivers} marked with `storageDriverType: 'testing'` and a wrapped accessor driver.
  */ function makeTestingFirebaseStorageDrivers(drivers, config) {
     return _object_spread_props$1(_object_spread$2({}, drivers), {
         storageDriverType: 'testing',
@@ -846,6 +849,11 @@ function _ts_generator$5(thisArg, body) {
  *
  * Combines the Firestore client drivers with the rules test environment and context
  * to produce a context suitable for client-side Firestore tests.
+ *
+ * @param drivers - Testing Firestore drivers used to back the context (typically with collection name fuzzing).
+ * @param rulesTestEnvironment - The shared `@firebase/rules-unit-testing` environment for the suite.
+ * @param rulesTestContext - The per-test rules context (authenticated or unauthenticated) used to obtain the Firestore instance.
+ * @returns A {@link RulesUnitTestTestFirestoreContext} that exposes the rules-test environment and context alongside the standard Firestore context.
  */ function makeRulesTestFirestoreContext(drivers, rulesTestEnvironment, rulesTestContext) {
     var context = _object_spread_props(_object_spread$1({}, firestoreContextFactory(drivers)(rulesTestContext.firestore())), {
         drivers: drivers,
@@ -859,6 +867,11 @@ function _ts_generator$5(thisArg, body) {
  *
  * Combines the Storage client drivers with the rules test environment and context
  * to produce a context suitable for client-side Firebase Storage tests.
+ *
+ * @param drivers - Testing Firebase Storage drivers used to back the context (typically with a unique test bucket).
+ * @param rulesTestEnvironment - The shared `@firebase/rules-unit-testing` environment for the suite.
+ * @param rulesTestContext - The per-test rules context used to obtain the Storage instance.
+ * @returns A {@link RulesUnitTestTestFirebaseStorageContext} that exposes the rules-test environment and context alongside the standard Storage context.
  */ function makeRulesTestFirebaseStorageContext(drivers, rulesTestEnvironment, rulesTestContext) {
     var context = _object_spread_props(_object_spread$1({}, firebaseStorageContextFactory(drivers)(rulesTestContext.storage())), {
         drivers: drivers,
@@ -942,6 +955,9 @@ function _ts_generator$5(thisArg, body) {
  * preventing interference between parallel workers sharing the same Firebase Storage emulator. The Storage
  * emulator maintains rules globally (not per-project), so concurrent `setRules` calls from multiple workers
  * can momentarily leave the emulator in a transitional state that causes `storage/unauthorized` errors.
+ *
+ * @param inputConfig - Optional partial config; `testEnvironment` defaults to an empty object and `rulesContext` defaults to undefined (unauthenticated).
+ * @returns A function that, given a `buildTests` callback, registers Vitest hooks (`beforeAll`/`afterAll`/`beforeEach`/`afterEach`) and invokes the callback with a {@link RulesUnitTestFirebaseTestingContextFixture}.
  */ var firebaseRulesUnitTestBuilder = function firebaseRulesUnitTestBuilder(inputConfig) {
     var _ref;
     var config = {
@@ -1253,8 +1269,8 @@ function _is_native_reflect_construct$4() {
 /**
  * Used to build a mockItemCollection from a firestore instance with a converter setup.
  *
- * @param firestore
- * @returns
+ * @param context - The Firestore context to resolve the root collection against.
+ * @returns A typed {@link CollectionReference} for the root MockItem collection.
  */ function mockItemCollectionReference(context) {
     return context.collection(mockItemIdentity.collectionName);
 }
@@ -1266,6 +1282,9 @@ function _is_native_reflect_construct$4() {
  * const collection = mockItemFirestoreCollection(firestoreContext);
  * const doc = collection.documentAccessor().newDocument();
  * ```
+ *
+ * @param firestoreContext - The Firestore context (test or production) used to resolve the underlying collection reference.
+ * @returns A {@link MockItemFirestoreCollection} wired with the {@link mockItemConverter} and {@link mockItemIdentity}.
  */ function mockItemFirestoreCollection(firestoreContext) {
     return firestoreContext.firestoreCollection({
         converter: mockItemConverter,
@@ -1370,13 +1389,11 @@ function _is_native_reflect_construct$4() {
     })
 });
 /**
- * Used to build a mockItemCollection from a firestore instance with a converter setup.
- *
- * @param firestore
- * @returns
- */ /**
  * Creates a factory that produces {@link CollectionReference} instances for {@link MockItemPrivate}
  * subcollections under a given {@link MockItemDocument} parent.
+ *
+ * @param context - The Firestore context used to resolve subcollections.
+ * @returns A function that, given a parent {@link MockItemDocument}, returns a typed {@link CollectionReference} for that parent's MockItemPrivate subcollection.
  */ function mockItemPrivateCollectionReferenceFactory(context) {
     return function(parent) {
         return context.subcollection(parent.documentRef, mockItemPrivateIdentity.collectionName);
@@ -1384,6 +1401,9 @@ function _is_native_reflect_construct$4() {
 }
 /**
  * Creates a factory for producing {@link MockItemPrivateFirestoreCollection} instances bound to a parent {@link MockItemDocument}.
+ *
+ * @param firestoreContext - The Firestore context used to resolve the underlying subcollection.
+ * @returns A factory that, given a parent {@link MockItemDocument}, returns a single-item collection wired with {@link mockItemPrivateConverter}.
  */ function mockItemPrivateFirestoreCollection(firestoreContext) {
     var factory = mockItemPrivateCollectionReferenceFactory(firestoreContext);
     return function(parent) {
@@ -1401,11 +1421,17 @@ function _is_native_reflect_construct$4() {
 }
 /**
  * Creates a {@link CollectionGroup} reference for querying all {@link MockItemPrivate} documents across parents.
+ *
+ * @param context - The Firestore context used to resolve the collection group.
+ * @returns A typed {@link CollectionGroup} reference for the MockItemPrivate collection name.
  */ function mockItemPrivateCollectionReference(context) {
     return context.collectionGroup(mockItemPrivateIdentity.collectionName);
 }
 /**
  * Creates a {@link MockItemPrivateFirestoreCollectionGroup} for cross-parent queries on {@link MockItemPrivate}.
+ *
+ * @param firestoreContext - The Firestore context used to resolve the underlying collection group reference.
+ * @returns A typed {@link MockItemPrivateFirestoreCollectionGroup} wired with the {@link mockItemPrivateConverter}.
  */ function mockItemPrivateFirestoreCollectionGroup(firestoreContext) {
     return firestoreContext.firestoreCollectionGroup({
         modelIdentity: mockItemPrivateIdentity,
@@ -1458,10 +1484,11 @@ var mockItemUserIdentifier = '0';
     })
 });
 /**
- * Used to build a mockItemCollection from a firestore instance with a converter setup.
+ * Creates a factory that produces {@link CollectionReference} instances for {@link MockItemUser}
+ * subcollections under a given {@link MockItemDocument} parent.
  *
- * @param firestore
- * @returns
+ * @param context - The Firestore context used to resolve subcollections.
+ * @returns A function that, given a parent {@link MockItemDocument}, returns a typed {@link CollectionReference} for that parent's MockItemUser subcollection.
  */ function mockItemUserCollectionReferenceFactory(context) {
     return function(parent) {
         return context.subcollection(parent.documentRef, mockItemUserCollectionName);
@@ -1472,6 +1499,9 @@ var mockItemUserIdentifier = '0';
  */ var mockItemUserAccessorFactory = copyUserRelatedDataAccessorFactoryFunction();
 /**
  * Creates a factory for producing {@link MockItemUserFirestoreCollection} instances bound to a parent {@link MockItemDocument}.
+ *
+ * @param firestoreContext - The Firestore context used to resolve the underlying subcollection.
+ * @returns A factory that, given a parent {@link MockItemDocument}, returns a per-parent collection wired with {@link mockItemUserConverter} and {@link mockItemUserAccessorFactory}.
  */ function mockItemUserFirestoreCollection(firestoreContext) {
     var factory = mockItemUserCollectionReferenceFactory(firestoreContext);
     return function(parent) {
@@ -1490,11 +1520,17 @@ var mockItemUserIdentifier = '0';
 }
 /**
  * Creates a {@link CollectionGroup} reference for querying all {@link MockItemUser} documents across parents.
+ *
+ * @param context - The Firestore context used to resolve the collection group.
+ * @returns A typed {@link CollectionGroup} reference for the MockItemUser collection name.
  */ function mockItemUserCollectionReference(context) {
     return context.collectionGroup(mockItemUserCollectionName);
 }
 /**
  * Creates a {@link MockItemUserFirestoreCollectionGroup} for cross-parent queries on {@link MockItemUser}.
+ *
+ * @param firestoreContext - The Firestore context used to resolve the underlying collection group reference.
+ * @returns A typed {@link MockItemUserFirestoreCollectionGroup} wired with the {@link mockItemUserConverter} and {@link mockItemUserAccessorFactory}.
  */ function mockItemUserFirestoreCollectionGroup(firestoreContext) {
     return firestoreContext.firestoreCollectionGroup({
         modelIdentity: mockItemUserIdentity,
@@ -1544,6 +1580,9 @@ var mockItemUserIdentifier = '0';
 /**
  * Creates a factory that produces {@link CollectionReference} instances for {@link MockItemSubItem}
  * subcollections under a given {@link MockItemDocument} parent.
+ *
+ * @param context - The Firestore context used to resolve subcollections.
+ * @returns A function that, given a parent {@link MockItemDocument}, returns a typed {@link CollectionReference} for that parent's MockItemSubItem subcollection.
  */ function mockItemSubItemCollectionReferenceFactory(context) {
     return function(parent) {
         return context.subcollection(parent.documentRef, mockItemSubItemIdentity.collectionName);
@@ -1551,6 +1590,9 @@ var mockItemUserIdentifier = '0';
 }
 /**
  * Creates a factory for producing {@link MockItemSubItemFirestoreCollection} instances bound to a parent {@link MockItemDocument}.
+ *
+ * @param firestoreContext - The Firestore context used to resolve the underlying subcollection.
+ * @returns A factory that, given a parent {@link MockItemDocument}, returns a per-parent collection wired with {@link mockItemSubItemConverter}.
  */ function mockItemSubItemFirestoreCollection(firestoreContext) {
     var factory = mockItemSubItemCollectionReferenceFactory(firestoreContext);
     return function(parent) {
@@ -1568,11 +1610,17 @@ var mockItemUserIdentifier = '0';
 }
 /**
  * Creates a {@link CollectionGroup} reference for querying all {@link MockItemSubItem} documents across parents.
+ *
+ * @param context - The Firestore context used to resolve the collection group.
+ * @returns A typed {@link CollectionGroup} reference for the MockItemSubItem collection name.
  */ function mockItemSubItemCollectionReference(context) {
     return context.collectionGroup(mockItemSubItemIdentity.collectionName);
 }
 /**
  * Creates a {@link MockItemSubItemFirestoreCollectionGroup} for cross-parent queries on {@link MockItemSubItem}.
+ *
+ * @param firestoreContext - The Firestore context used to resolve the underlying collection group reference.
+ * @returns A typed {@link MockItemSubItemFirestoreCollectionGroup} wired with the {@link mockItemSubItemConverter}.
  */ function mockItemSubItemFirestoreCollectionGroup(firestoreContext) {
     return firestoreContext.firestoreCollectionGroup({
         modelIdentity: mockItemSubItemIdentity,
@@ -1621,6 +1669,9 @@ var mockItemUserIdentifier = '0';
 /**
  * Creates a factory that produces {@link CollectionReference} instances for {@link MockItemSubItemDeep}
  * subcollections under a given {@link MockItemSubItemDocument} parent.
+ *
+ * @param context - The Firestore context used to resolve subcollections.
+ * @returns A function that, given a parent {@link MockItemSubItemDocument}, returns a typed {@link CollectionReference} for that parent's MockItemSubItemDeep subcollection.
  */ function mockItemSubItemDeepCollectionReferenceFactory(context) {
     return function(parent) {
         return context.subcollection(parent.documentRef, mockItemSubItemDeepIdentity.collectionName);
@@ -1628,6 +1679,9 @@ var mockItemUserIdentifier = '0';
 }
 /**
  * Creates a factory for producing {@link MockItemSubItemDeepFirestoreCollection} instances bound to a parent {@link MockItemSubItemDocument}.
+ *
+ * @param firestoreContext - The Firestore context used to resolve the underlying subcollection.
+ * @returns A factory that, given a parent {@link MockItemSubItemDocument}, returns a per-parent collection wired with {@link mockItemSubItemDeepConverter}.
  */ function mockItemSubItemDeepFirestoreCollection(firestoreContext) {
     var factory = mockItemSubItemDeepCollectionReferenceFactory(firestoreContext);
     return function(parent) {
@@ -1645,11 +1699,17 @@ var mockItemUserIdentifier = '0';
 }
 /**
  * Creates a {@link CollectionGroup} reference for querying all {@link MockItemSubItemDeep} documents across parents.
+ *
+ * @param context - The Firestore context used to resolve the collection group.
+ * @returns A typed {@link CollectionGroup} reference for the MockItemSubItemDeep collection name.
  */ function mockItemSubItemDeepCollectionReference(context) {
     return context.collectionGroup(mockItemSubItemDeepIdentity.collectionName);
 }
 /**
  * Creates a {@link MockItemSubItemDeepFirestoreCollectionGroup} for cross-parent queries on {@link MockItemSubItemDeep}.
+ *
+ * @param firestoreContext - The Firestore context used to resolve the underlying collection group reference.
+ * @returns A typed {@link MockItemSubItemDeepFirestoreCollectionGroup} wired with the {@link mockItemSubItemDeepConverter}.
  */ function mockItemSubItemDeepFirestoreCollectionGroup(firestoreContext) {
     return firestoreContext.firestoreCollectionGroup({
         modelIdentity: mockItemSubItemDeepIdentity,
@@ -1704,6 +1764,9 @@ function _class_call_check$4(instance, Constructor) {
  * Creates a concrete {@link MockItemCollections} instance with all collections bound to the given {@link FirestoreContext}.
  *
  * This is the primary way to instantiate the full set of mock collections for a test run.
+ *
+ * @param firestoreContext - The Firestore context (typically a {@link TestFirestoreContext}) that backs every collection.
+ * @returns A fully populated {@link MockItemCollections} with each mock collection, factory, and collection group wired to `firestoreContext`.
  */ function makeMockItemCollections(firestoreContext) {
     return {
         mockItemCollection: mockItemFirestoreCollection(firestoreContext),
@@ -1929,6 +1992,9 @@ function _is_native_reflect_construct$3() {
         {
             key: "firestoreCollection",
             get: /**
+     * Backwards-compatible alias for {@link MockItemCollectionFixtureInstance.mockItemCollection}.
+     *
+     * @returns The root {@link MockItemFirestoreCollection} from the fixture's underlying {@link MockItemCollections}.
      * @deprecated Use mockItemCollection instead.
      */ function get() {
                 return this.collections.mockItemCollection;
@@ -2017,6 +2083,9 @@ function _is_native_reflect_construct$3() {
  *   it('should work', () => { ... });
  * }));
  * ```
+ *
+ * @param _config - Reserved for future setup/teardown configuration; currently unused.
+ * @returns A factory builder that wraps a parent {@link TestFirestoreContextFixture} with a {@link MockItemCollectionFixture} per test.
  */ function testWithMockItemCollectionFixture(_config) {
     return instanceWrapTestContextFactory({
         wrapFixture: function wrapFixture(fixture) {
@@ -2183,6 +2252,9 @@ function _is_native_reflect_construct$2() {
  *   it('should upload', () => { ... });
  * }));
  * ```
+ *
+ * @param _config - Reserved for future setup/teardown configuration; currently unused.
+ * @returns A factory builder that wraps a parent {@link TestFirebaseStorageContextFixture} with a {@link MockItemStorageFixture} per test.
  */ function testWithMockItemStorageFixture(_config) {
     return instanceWrapTestContextFactory({
         wrapFixture: function wrapFixture(fixture) {
@@ -2355,11 +2427,17 @@ function _is_native_reflect_construct$1() {
  * const constraint = mockItemWithValue('hello');
  * const results = await collection.query(constraint);
  * ```
+ *
+ * @param value - The exact `value` to match.
+ * @returns A `where('value', '==', value)` constraint typed for {@link MockItem}.
  */ function mockItemWithValue(value) {
     return where('value', '==', value);
 }
 /**
  * Creates a Firestore query constraint that filters {@link MockItem} documents by their `test` boolean field.
+ *
+ * @param test - The boolean value of the `test` field to match.
+ * @returns A `where('test', '==', test)` constraint.
  */ function mockItemWithTestValue(test) {
     return where('test', '==', test);
 }
@@ -2377,8 +2455,8 @@ function _is_native_reflect_construct$1() {
  * From:
  * https://medium.com/firebase-developers/how-to-query-collections-in-firestore-under-a-certain-path-6a0d686cebd2
  *
- * @param parent
- * @returns
+ * @param mockItem - The parent {@link MockItem} document reference whose descendant documents the constraint should bound to.
+ * @returns An array of constraints (suitable for use on a collection group query) that restricts results to documents under the given parent path.
  */ function allChildMockItemSubItemDeepsWithinMockItem(mockItem) {
     return allChildDocumentsUnderParent(mockItem);
 }
@@ -5056,6 +5134,27 @@ function _ts_generator$3(thisArg, body) {
         };
     }
 }
+/**
+ * Creates a gate that calls `done()` once both `setSeen()` and `setCompleted()` have been invoked.
+ *
+ * Used to coordinate streamed-emission and post-mutation callbacks in stream-update tests.
+ *
+ * @param done - The Vitest async-test completion callback to invoke once both sides of the gate have fired.
+ * @returns A two-method gate; the test calls `setSeen()` from the stream subscription and `setCompleted()` from the mutation continuation, and `done()` runs only after both have happened (in either order).
+ */ function makeAwaitBothGate(done) {
+    var seen = false;
+    var completed = false;
+    return {
+        setSeen: function setSeen() {
+            seen = true;
+            if (completed) done();
+        },
+        setCompleted: function setCompleted() {
+            completed = true;
+            if (seen) done();
+        }
+    };
+}
 /**
  * Describes query driver tests, using a MockItemCollectionFixture.
  *
@@ -6194,20 +6293,13 @@ function _ts_generator$3(thisArg, body) {
                                 sub.destroy();
                             });
                             it('should emit when the query results update (an item is added).', callbackTest(function(done) {
-                                var tryComplete = function tryComplete() {
-                                    if (addSeen && addCompleted) {
-                                        done();
-                                    }
-                                };
                                 var itemsToAdd = 1;
-                                var addCompleted = false;
-                                var addSeen = false;
+                                var gate = makeAwaitBothGate(done);
                                 sub.subscription = querySubItems().streamDocs().pipe(filter(function(x) {
                                     return x.docs.length > allSubItems.length;
                                 })).subscribe(function(results) {
-                                    addSeen = true;
                                     expect(results.docs.length).toBe(allSubItems.length + itemsToAdd);
-                                    tryComplete();
+                                    gate.setSeen();
                                 });
                                 // add one item
                                 void makeDocuments(f.instance.mockItemSubItemCollection(parentA).documentAccessor(), {
@@ -6218,32 +6310,23 @@ function _ts_generator$3(thisArg, body) {
                                         };
                                     }
                                 }).then(function() {
-                                    addCompleted = true;
-                                    tryComplete();
+                                    gate.setCompleted();
                                 });
                             }));
                             it('should emit when the query results update (an item is removed).', callbackTest(function(done) {
-                                var tryComplete = function tryComplete() {
-                                    if (deleteSeen && deleteCompleted) {
-                                        done();
-                                    }
-                                };
                                 var itemsToRemove = 1;
-                                var deleteCompleted = false;
-                                var deleteSeen = false;
+                                var gate = makeAwaitBothGate(done);
                                 sub.subscription = querySubItems().streamDocs().pipe(filter(function(x) {
                                     return x.docs.length < allSubItems.length;
                                 })).subscribe(function(results) {
-                                    deleteSeen = true;
                                     expect(results.docs.length).toBe(allSubItems.length - itemsToRemove);
-                                    tryComplete();
+                                    gate.setSeen();
                                 });
                                 void allSubItems[0].accessor.exists().then(function(exists) {
                                     expect(exists).toBe(true);
                                     // remove one item
                                     return allSubItems[0].accessor.delete().then(function() {
-                                        deleteCompleted = true;
-                                        tryComplete();
+                                        gate.setCompleted();
                                     });
                                 });
                             }));
@@ -6442,20 +6525,13 @@ function _ts_generator$3(thisArg, body) {
                     sub.destroy();
                 });
                 it('should emit when the query results update (an item is added).', callbackTest(function(done) {
-                    var tryComplete = function tryComplete() {
-                        if (addSeen && addCompleted) {
-                            done();
-                        }
-                    };
                     var itemsToAdd = 1;
-                    var addCompleted = false;
-                    var addSeen = false;
+                    var gate = makeAwaitBothGate(done);
                     sub.subscription = queryDocument().streamDocs().pipe(filter(function(documents) {
                         return documents.length > items.length;
                     })).subscribe(function(documents) {
-                        addSeen = true;
                         expect(documents.length).toBe(items.length + itemsToAdd);
-                        tryComplete();
+                        gate.setSeen();
                     });
                     // add one item
                     void waitForMs(10).then(function() {
@@ -6468,32 +6544,23 @@ function _ts_generator$3(thisArg, body) {
                                 };
                             }
                         }).then(function() {
-                            addCompleted = true;
-                            tryComplete();
+                            gate.setCompleted();
                         });
                     });
                 }));
                 it('should emit when the query results update (an item is removed).', callbackTest(function(done) {
-                    var tryComplete = function tryComplete() {
-                        if (deleteSeen && deleteCompleted) {
-                            done();
-                        }
-                    };
                     var itemsToRemove = 1;
-                    var deleteCompleted = false;
-                    var deleteSeen = false;
+                    var gate = makeAwaitBothGate(done);
                     sub.subscription = queryDocument().streamDocs().pipe(skip(1)).subscribe(function(documents) {
-                        deleteSeen = true;
                         expect(documents.length).toBe(items.length - itemsToRemove);
-                        tryComplete();
+                        gate.setSeen();
                     });
                     void waitForMs(10).then(function() {
                         return items[0].exists().then(function(exists) {
                             expect(exists).toBe(true);
                             // remove one item
                             return items[0].accessor.delete().then(function() {
-                                deleteCompleted = true;
-                                tryComplete();
+                                gate.setCompleted();
                             });
                         });
                     });
@@ -6508,18 +6575,11 @@ function _ts_generator$3(thisArg, body) {
                     sub.destroy();
                 });
                 it('should emit when the query results update (an item is added).', callbackTest(function(done) {
-                    var tryComplete = function tryComplete() {
-                        if (addSeen && addCompleted) {
-                            done();
-                        }
-                    };
                     var itemsToAdd = 1;
-                    var addCompleted = false;
-                    var addSeen = false;
+                    var gate = makeAwaitBothGate(done);
                     sub.subscription = queryDocument().streamDocSnapshotDataPairs().pipe(filter(function(documents) {
                         return documents.length > items.length;
                     })).subscribe(function(documents) {
-                        addSeen = true;
                         expect(documents.length).toBe(items.length + itemsToAdd);
                         documents.forEach(function(x) {
                             // validate each document returned
@@ -6531,7 +6591,7 @@ function _ts_generator$3(thisArg, body) {
                             expect(x.snapshot.ref).toBeDefined();
                             expect(x.snapshot.id).toBe(x.document.id);
                         });
-                        tryComplete();
+                        gate.setSeen();
                     });
                     // add one item
                     void waitForMs(10).then(function() {
@@ -6544,32 +6604,23 @@ function _ts_generator$3(thisArg, body) {
                                 };
                             }
                         }).then(function() {
-                            addCompleted = true;
-                            tryComplete();
+                            gate.setCompleted();
                         });
                     });
                 }));
                 it('should emit when the query results update (an item is removed).', callbackTest(function(done) {
-                    var tryComplete = function tryComplete() {
-                        if (deleteSeen && deleteCompleted) {
-                            done();
-                        }
-                    };
                     var itemsToRemove = 1;
-                    var deleteCompleted = false;
-                    var deleteSeen = false;
+                    var gate = makeAwaitBothGate(done);
                     sub.subscription = queryDocument().streamDocs().pipe(skip(1)).subscribe(function(documents) {
-                        deleteSeen = true;
                         expect(documents.length).toBe(items.length - itemsToRemove);
-                        tryComplete();
+                        gate.setSeen();
                     });
                     void waitForMs(10).then(function() {
                         return items[0].exists().then(function(exists) {
                             expect(exists).toBe(true);
                             // remove one item
                             return items[0].accessor.delete().then(function() {
-                                deleteCompleted = true;
-                                tryComplete();
+                                gate.setCompleted();
                             });
                         });
                     });
@@ -6597,20 +6648,13 @@ function _ts_generator$3(thisArg, body) {
                     sub.destroy();
                 });
                 it('should emit when the query results update (an item is added).', callbackTest(function(done) {
-                    var tryComplete = function tryComplete() {
-                        if (addSeen && addCompleted) {
-                            done();
-                        }
-                    };
                     var itemsToAdd = 1;
-                    var addCompleted = false;
-                    var addSeen = false;
+                    var gate = makeAwaitBothGate(done);
                     sub.subscription = query().streamDocs().pipe(filter(function(x) {
                         return x.docs.length > items.length;
                     })).subscribe(function(results) {
-                        addSeen = true;
                         expect(results.docs.length).toBe(items.length + itemsToAdd);
-                        tryComplete();
+                        gate.setSeen();
                     });
                     // add one item
                     void waitForMs(10).then(function() {
@@ -6623,32 +6667,23 @@ function _ts_generator$3(thisArg, body) {
                                 };
                             }
                         }).then(function() {
-                            addCompleted = true;
-                            tryComplete();
+                            gate.setCompleted();
                         });
                     });
                 }));
                 it('should emit when the query results update (an item is removed).', callbackTest(function(done) {
-                    var tryComplete = function tryComplete() {
-                        if (deleteSeen && deleteCompleted) {
-                            done();
-                        }
-                    };
                     var itemsToRemove = 1;
-                    var deleteCompleted = false;
-                    var deleteSeen = false;
+                    var gate = makeAwaitBothGate(done);
                     sub.subscription = query().streamDocs().pipe(skip(1)).subscribe(function(results) {
-                        deleteSeen = true;
                         expect(results.docs.length).toBe(items.length - itemsToRemove);
-                        tryComplete();
+                        gate.setSeen();
                     });
                     void waitForMs(10).then(function() {
                         return items[0].accessor.exists().then(function(exists) {
                             expect(exists).toBe(true);
                             // remove one item
                             return items[0].accessor.delete().then(function() {
-                                deleteCompleted = true;
-                                tryComplete();
+                                gate.setCompleted();
                             });
                         });
                     });

package/test/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.10.8",
+  "version": "13.11.0",
   "peerDependencies": {
-    "@dereekb/date": "13.10.8",
-    "@dereekb/firebase": "13.10.8",
-    "@dereekb/model": "13.10.8",
-    "@dereekb/rxjs": "13.10.8",
-    "@dereekb/util": "13.10.8",
+    "@dereekb/date": "13.11.0",
+    "@dereekb/firebase": "13.11.0",
+    "@dereekb/model": "13.11.0",
+    "@dereekb/rxjs": "13.11.0",
+    "@dereekb/util": "13.11.0",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.1.0",
     "firebase": "^12.12.1",

package/test/src/lib/client/firebase.d.ts

@@ -58,6 +58,11 @@ export interface RulesUnitTestTestFirestoreContext extends TestFirestoreContext
  *
  * Combines the Firestore client drivers with the rules test environment and context
  * to produce a context suitable for client-side Firestore tests.
+ *
+ * @param drivers - Testing Firestore drivers used to back the context (typically with collection name fuzzing).
+ * @param rulesTestEnvironment - The shared `@firebase/rules-unit-testing` environment for the suite.
+ * @param rulesTestContext - The per-test rules context (authenticated or unauthenticated) used to obtain the Firestore instance.
+ * @returns A {@link RulesUnitTestTestFirestoreContext} that exposes the rules-test environment and context alongside the standard Firestore context.
  */
 export declare function makeRulesTestFirestoreContext(drivers: TestingFirestoreDrivers, rulesTestEnvironment: RulesTestEnvironment, rulesTestContext: RulesTestContext): TestFirestoreContext;
 /**
@@ -72,6 +77,11 @@ export interface RulesUnitTestTestFirebaseStorageContext extends TestFirebaseSto
  *
  * Combines the Storage client drivers with the rules test environment and context
  * to produce a context suitable for client-side Firebase Storage tests.
+ *
+ * @param drivers - Testing Firebase Storage drivers used to back the context (typically with a unique test bucket).
+ * @param rulesTestEnvironment - The shared `@firebase/rules-unit-testing` environment for the suite.
+ * @param rulesTestContext - The per-test rules context used to obtain the Storage instance.
+ * @returns A {@link RulesUnitTestTestFirebaseStorageContext} that exposes the rules-test environment and context alongside the standard Storage context.
  */
 export declare function makeRulesTestFirebaseStorageContext(drivers: TestingFirebaseStorageDrivers, rulesTestEnvironment: RulesTestEnvironment, rulesTestContext: RulesTestContext): TestFirebaseStorageContext;
 /**
@@ -112,6 +122,9 @@ export declare class RulesUnitTestFirebaseTestingContextFixture extends TestFire
  * preventing interference between parallel workers sharing the same Firebase Storage emulator. The Storage
  * emulator maintains rules globally (not per-project), so concurrent `setRules` calls from multiple workers
  * can momentarily leave the emulator in a transitional state that causes `storage/unauthorized` errors.
+ *
+ * @param inputConfig - Optional partial config; `testEnvironment` defaults to an empty object and `rulesContext` defaults to undefined (unauthenticated).
+ * @returns A function that, given a `buildTests` callback, registers Vitest hooks (`beforeAll`/`afterAll`/`beforeEach`/`afterEach`) and invokes the callback with a {@link RulesUnitTestFirebaseTestingContextFixture}.
  */
 export declare const firebaseRulesUnitTestBuilder: TestContextBuilderFunction<RulesUnitTestTestFirebaseInstance, RulesUnitTestFirebaseTestingContextFixture, RulesUnitTestingConfig>;
 /**