@dereekb/firebase 13.2.2 → 13.3.1

package/test/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.2.2",
+  "version": "13.3.1",
   "peerDependencies": {
-    "@dereekb/date": "13.2.2",
-    "@dereekb/firebase": "13.2.2",
-    "@dereekb/model": "13.2.2",
-    "@dereekb/rxjs": "13.2.2",
-    "@dereekb/util": "13.2.2",
+    "@dereekb/date": "13.3.1",
+    "@dereekb/firebase": "13.3.1",
+    "@dereekb/model": "13.3.1",
+    "@dereekb/rxjs": "13.3.1",
+    "@dereekb/util": "13.3.1",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.0.0",
     "firebase": "^12.0.0",

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

@@ -1,5 +1,23 @@
 import { type TestContextFactory } from '@dereekb/util/test';
 import { type RulesUnitTestFirebaseTestingContextFixture } from './firebase';
+/**
+ * Default user ID used for the authenticated context in client-side Firebase tests.
+ */
 export declare const TESTING_AUTHORIZED_FIREBASE_USER_ID = "0";
+/**
+ * Convenience type alias for a test context factory that produces {@link RulesUnitTestFirebaseTestingContextFixture} instances.
+ */
 export type FirebaseTestContextFactory = TestContextFactory<RulesUnitTestFirebaseTestingContextFixture>;
+/**
+ * Pre-configured {@link FirebaseTestContextFactory} that provides a fully authorized (all reads/writes allowed)
+ * Firebase emulator context for both Firestore and Storage.
+ *
+ * Uses permissive security rules and authenticates as {@link TESTING_AUTHORIZED_FIREBASE_USER_ID}.
+ * This is the most common base factory for client-side mock item tests.
+ *
+ * @example
+ * ```ts
+ * const f = testWithMockItemCollectionFixture()(authorizedFirebaseFactory);
+ * ```
+ */
 export declare const authorizedFirebaseFactory: FirebaseTestContextFactory;

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

@@ -5,11 +5,26 @@ import { type FirebaseStorage, type Firestore } from '@dereekb/firebase';
 import { type TestFirebaseStorageContext, type TestingFirebaseStorageDrivers } from '../common/storage/storage';
 import { TestFirebaseContextFixture, type TestFirebaseInstance } from '../common/firebase.instance';
 import { type TestFirebaseStorageInstance } from '../common/storage/storage.instance';
+/**
+ * Combined driver type providing both Firestore and Firebase Storage testing drivers.
+ */
 export type TestingFirebaseDrivers = TestingFirestoreDrivers & TestingFirebaseStorageDrivers;
+/**
+ * Configuration for the authenticated context used in rules unit tests.
+ *
+ * When provided, the test runs as the specified user. When omitted,
+ * tests run as an unauthenticated context.
+ */
 export interface RulesUnitTestingContextConfig {
     readonly userId: string;
     readonly tokenOptions?: Maybe<TokenOptions>;
 }
+/**
+ * Extended {@link TestEnvironmentConfig} with additional options for emulator setup.
+ *
+ * The `collectionNames` field is required when using testing drivers that fuzz collection names
+ * to isolate parallel test runs.
+ */
 export interface RulesUnitTestingTestEnvironmentConfig extends TestEnvironmentConfig {
     /**
      * List of collection names used in the environment. Is required if using testing drivers.
@@ -18,20 +33,53 @@ export interface RulesUnitTestingTestEnvironmentConfig extends TestEnvironmentCo
     readonly firestore?: EmulatorConfig;
     readonly storage?: EmulatorConfig;
 }
+/**
+ * Top-level configuration for {@link firebaseRulesUnitTestBuilder}.
+ *
+ * Combines the emulator environment config with an optional authenticated context.
+ */
 export interface RulesUnitTestingConfig {
     readonly testEnvironment: RulesUnitTestingTestEnvironmentConfig;
     readonly rulesContext?: Maybe<RulesUnitTestingContextConfig>;
 }
+/**
+ * Extends {@link TestFirestoreContext} with references to the underlying `@firebase/rules-unit-testing` objects.
+ *
+ * Useful when a test needs direct access to the rules test environment (e.g., for clearing data or
+ * switching auth contexts).
+ */
 export interface RulesUnitTestTestFirestoreContext extends TestFirestoreContext {
     readonly rulesTestEnvironment: RulesTestEnvironment;
     readonly rulesTestContext: RulesTestContext;
 }
+/**
+ * Creates a {@link TestFirestoreContext} backed by the rules unit testing emulator.
+ *
+ * Combines the Firestore client drivers with the rules test environment and context
+ * to produce a context suitable for client-side Firestore tests.
+ */
 export declare function makeRulesTestFirestoreContext(drivers: TestingFirestoreDrivers, rulesTestEnvironment: RulesTestEnvironment, rulesTestContext: RulesTestContext): TestFirestoreContext;
+/**
+ * Extends {@link TestFirebaseStorageContext} with references to the underlying `@firebase/rules-unit-testing` objects.
+ */
 export interface RulesUnitTestTestFirebaseStorageContext extends TestFirebaseStorageContext {
     readonly rulesTestEnvironment: RulesTestEnvironment;
     readonly rulesTestContext: RulesTestContext;
 }
+/**
+ * Creates a {@link TestFirebaseStorageContext} backed by the rules unit testing emulator.
+ *
+ * Combines the Storage client drivers with the rules test environment and context
+ * to produce a context suitable for client-side Firebase Storage tests.
+ */
 export declare function makeRulesTestFirebaseStorageContext(drivers: TestingFirebaseStorageDrivers, rulesTestEnvironment: RulesTestEnvironment, rulesTestContext: RulesTestContext): TestFirebaseStorageContext;
+/**
+ * Test instance that provides both Firestore and Firebase Storage contexts via the
+ * `@firebase/rules-unit-testing` emulator.
+ *
+ * Lazily initializes contexts on first access using {@link cachedGetter}.
+ * Used as the instance type for {@link RulesUnitTestFirebaseTestingContextFixture}.
+ */
 export declare class RulesUnitTestTestFirebaseInstance implements TestFirebaseInstance, TestFirebaseStorageInstance {
     readonly drivers: TestingFirebaseDrivers;
     readonly rulesTestEnvironment: RulesTestEnvironment;
@@ -44,6 +92,12 @@ export declare class RulesUnitTestTestFirebaseInstance implements TestFirebaseIn
     get firestore(): Firestore;
     get storage(): FirebaseStorage;
 }
+/**
+ * Concrete {@link TestFirebaseContextFixture} for client-side rules unit tests.
+ *
+ * Manages the lifecycle of a {@link RulesUnitTestTestFirebaseInstance}, handling
+ * setup and teardown of the emulator environment between test suites.
+ */
 export declare class RulesUnitTestFirebaseTestingContextFixture extends TestFirebaseContextFixture<RulesUnitTestTestFirebaseInstance> {
 }
 /**
@@ -52,4 +106,10 @@ export declare class RulesUnitTestFirebaseTestingContextFixture extends TestFire
  * This can be used to easily build a testing context that sets up RulesTestEnvironment for tests that sets itself up and tears itself down.
  */
 export declare const firebaseRulesUnitTestBuilder: import("@dereekb/util/test").TestContextBuilderFunction<RulesUnitTestTestFirebaseInstance, RulesUnitTestFirebaseTestingContextFixture, RulesUnitTestingConfig>;
+/**
+ * Registers `beforeAll`/`afterAll` hooks to suppress verbose Firestore log output during tests.
+ *
+ * Sets the log level to `'error'` before tests and restores it to `'warn'` afterward.
+ * Call this at the top level of a `describe` block to reduce test noise.
+ */
 export declare function changeFirestoreLogLevelBeforeAndAfterTests(): void;

package/test/src/lib/common/firebase.instance.d.ts

@@ -4,6 +4,13 @@ import { type TestFirestoreContext } from './firestore/firestore';
 import { type TestFirestoreInstance } from './firestore/firestore.instance';
 import { type TestFirebaseStorageContext } from './storage/storage';
 import { type TestFirebaseStorageInstance } from './storage/storage.instance';
+/**
+ * Combined test instance that provides access to both Firestore and Firebase Storage test contexts.
+ *
+ * Use this when your tests need to interact with both Firestore documents and storage files
+ * within the same test scenario. Implements both {@link TestFirestoreInstance} and
+ * {@link TestFirebaseStorageInstance} so it can be used wherever either is expected.
+ */
 export declare class TestFirebaseInstance implements TestFirestoreInstance, TestFirebaseStorageInstance {
     readonly firestoreContext: TestFirestoreContext;
     readonly storageContext: TestFirebaseStorageContext;
@@ -11,12 +18,26 @@ export declare class TestFirebaseInstance implements TestFirestoreInstance, Test
     get firestore(): Firestore;
     get storage(): FirebaseStorage;
 }
+/**
+ * Test fixture that manages the lifecycle of a {@link TestFirebaseInstance}, providing
+ * convenient access to both Firestore and Storage test contexts.
+ *
+ * Extends {@link AbstractTestContextFixture} to handle setup/teardown of the combined
+ * Firebase test environment. Use this as the base fixture when writing tests that
+ * exercise both Firestore and Storage functionality together.
+ */
 export declare class TestFirebaseContextFixture<F extends TestFirebaseInstance = TestFirebaseInstance> extends AbstractTestContextFixture<F> {
     get firestore(): Firestore;
     get firestoreContext(): TestFirestoreContext;
     get storage(): FirebaseStorage;
     get storageContext(): TestFirebaseStorageContext;
 }
+/**
+ * Factory type for creating {@link TestFirebaseContextFixture} instances in test suites.
+ *
+ * Pass this to test utility functions that need to set up a combined Firestore + Storage
+ * test environment.
+ */
 export type TestFirebaseContextFactory = TestContextFactory<TestFirebaseContextFixture>;
 /**
  * @deprecated Use TestFirebaseContextFactory instead.

package/test/src/lib/common/firestore/firestore.d.ts

@@ -15,6 +15,22 @@ export interface TestingFirestoreAccessorDriver extends FirestoreAccessorDriver
      */
     initWithCollectionNames(collectionNames: string[]): Map<string, string>;
 }
+/**
+ * Creates a {@link TestingFirestoreAccessorDriver} that wraps the given driver with collection name fuzzing.
+ *
+ * Each collection/subcollection/collectionGroup path is replaced with a unique fuzzed name
+ * (incorporating a timestamp and random component) so that parallel tests never read or write
+ * each other's documents. The mapping from original to fuzzed names is retrievable via
+ * {@link TestingFirestoreAccessorDriver.getFuzzedCollectionsNameMap}.
+ *
+ * @example
+ * ```ts
+ * const testDriver = makeTestingFirestoreAccesorDriver(productionDriver);
+ * // "mockItems" -> "1678901234_42_mockItems_1"
+ * ```
+ *
+ * @param driver - The base driver to wrap with fuzzing behavior.
+ */
 export declare function makeTestingFirestoreAccesorDriver(driver: FirestoreAccessorDriver): TestingFirestoreAccessorDriver;
 /**
  * Drivers used for testing. Provides additional functionality for controlling collection access to prevent cross-test contamination.
@@ -30,9 +46,33 @@ export interface TestingFirestoreDrivers extends FirestoreDrivers {
  * @returns
  */
 export declare function makeTestingFirestoreDrivers(drivers: FirestoreDrivers): TestingFirestoreDrivers;
+/**
+ * Extension applied to a {@link FirestoreContext} to expose the testing-specific drivers.
+ *
+ * This is mixed into the base context type via {@link TestFirestoreContext} so that
+ * test code can access the fuzzed driver and its collection name map.
+ */
 export interface TestingFirestoreContextExtension {
     drivers: TestingFirestoreDrivers;
 }
+/**
+ * A {@link FirestoreContext} augmented with {@link TestingFirestoreContextExtension},
+ * giving tests access to fuzzed collection drivers for isolation.
+ */
 export type TestFirestoreContext<C = FirestoreContext> = C & TestingFirestoreContextExtension;
+/**
+ * Function that clears a single Firestore collection used during testing.
+ *
+ * @param collectionName - The original (un-fuzzed) collection name.
+ * @param realCollectionName - The fuzzed collection name that actually exists in Firestore.
+ */
 export type ClearTestFirestoreCollectionFunction = (collectionName: string, realCollectionName: string) => Promise<void>;
+/**
+ * Iterates over every fuzzed collection in the given test context and invokes the
+ * provided cleanup function for each one. Use this in `afterAll`/`afterEach` hooks
+ * to remove test data and avoid cross-test contamination.
+ *
+ * @param context - The test context whose fuzzed collections should be cleared.
+ * @param clearCollection - Callback that performs the actual deletion for a single collection.
+ */
 export declare function clearTestFirestoreContextCollections(context: TestFirestoreContext, clearCollection: ClearTestFirestoreCollectionFunction): Promise<void>;

package/test/src/lib/common/firestore/firestore.instance.d.ts

@@ -1,15 +1,31 @@
 import { AbstractTestContextFixture, type TestContextFactory } from '@dereekb/util/test';
 import { type Firestore } from '@dereekb/firebase';
 import { type TestFirestoreContext } from './firestore';
+/**
+ * Test instance that wraps a {@link TestFirestoreContext} and provides convenient access
+ * to the underlying Firestore instance.
+ *
+ * Acts as the core building block for Firestore-only test scenarios. The context includes
+ * fuzzed collection names to ensure test isolation.
+ */
 export declare class TestFirestoreInstance {
     readonly firestoreContext: TestFirestoreContext;
     constructor(firestoreContext: TestFirestoreContext);
     get firestore(): Firestore;
 }
+/**
+ * Test fixture that manages the lifecycle of a {@link TestFirestoreInstance}.
+ *
+ * Extends {@link AbstractTestContextFixture} to handle setup/teardown of the Firestore
+ * test environment, including fuzzed collection drivers for test isolation.
+ */
 export declare class TestFirestoreContextFixture<F extends TestFirestoreInstance = TestFirestoreInstance> extends AbstractTestContextFixture<F> {
     get firestore(): Firestore;
     get firestoreContext(): TestFirestoreContext;
 }
+/**
+ * Factory type for creating {@link TestFirestoreContextFixture} instances in test suites.
+ */
 export type TestFirestoreContextFactory = TestContextFactory<TestFirestoreContextFixture>;
 /**
  * @deprecated Use TestFirestoreContextFactory instead.

package/test/src/lib/common/firestore/test.driver.accessor.d.ts

@@ -2,19 +2,56 @@ import { type Transaction, type DocumentReference, type WriteBatch, type Firesto
 import { type MockItemCollectionFixture } from '../mock';
 import { type Getter } from '@dereekb/util';
 /**
- * Describes accessor driver tests, using a MockItemCollectionFixture.
+ * Registers a shared test suite that validates {@link FirestoreAccessorDriver} behavior
+ * (CRUD operations, transactions, write batches, subcollections, and collection groups)
+ * against a live or emulated Firestore instance.
  *
- * @param f
+ * Call this once per driver implementation (e.g., client SDK, Admin SDK) to verify
+ * that the driver conforms to the expected Firestore accessor contract.
+ *
+ * @param f - Fixture providing the mock item collections and parent context for the tests.
  */
 export declare function describeFirestoreAccessorDriverTests(f: MockItemCollectionFixture): void;
+/**
+ * Configuration object for {@link describeFirestoreDocumentAccessorTests}.
+ *
+ * Supplies the test suite with the context, document factories, test data, and
+ * assertion helpers needed to validate document-level accessor operations
+ * (get, set, update, create, delete, stream, transactions, write batches).
+ */
 export interface DescribeAccessorTests<T> {
+    /** The Firestore context used for running transactions and creating batches. */
     context: FirestoreContext;
+    /** Returns the document under test. Called fresh in each `beforeEach`. */
     firestoreDocument: Getter<FirestoreDocument<T>>;
+    /**
+     * Returns partial data for the first of two sequential updates within a transaction.
+     * Used to verify that non-overlapping fields survive a second update.
+     */
     dataForFirstOfTwoUpdates: () => Partial<T>;
+    /** Returns partial data used for standard update/set assertions. */
     dataForUpdate: () => Partial<T>;
+    /**
+     * Optional predicate that checks whether fields from the first update
+     * are still present after the second update was applied. When provided,
+     * the multi-update transaction test will assert this returns `true`.
+     */
     hasRemainingDataFromFirstOfTwoUpdate?: (data: T) => boolean;
+    /** Predicate that returns `true` when the document's data reflects a successful update. */
     hasDataFromUpdate: (data: T) => boolean;
+    /** Loads the document within a transaction context for transaction-based tests. */
     loadDocumentForTransaction: (transaction: Transaction, ref?: DocumentReference<T>) => AbstractFirestoreDocument<T, any>;
+    /** Loads the document within a write batch context for batch-based tests. */
     loadDocumentForWriteBatch: (writeBatch: WriteBatch, ref?: DocumentReference<T>) => FirestoreDocument<T, any>;
 }
+/**
+ * Registers a shared test suite that validates document-level accessor operations
+ * (get, set, update, create, delete, stream, transactions, and write batches)
+ * for a single Firestore document type.
+ *
+ * This is called internally by {@link describeFirestoreAccessorDriverTests} for each
+ * mock document type, but can also be invoked directly when testing custom document types.
+ *
+ * @param init - Factory that returns a fresh {@link DescribeAccessorTests} config for each test.
+ */
 export declare function describeFirestoreDocumentAccessorTests<T>(init: () => DescribeAccessorTests<T>): void;

package/test/src/lib/common/firestore/test.driver.utility.d.ts

@@ -1,7 +1,13 @@
 import { type MockItemCollectionFixture } from '../mock';
 /**
- * Describes utility driver tests, using a MockItemCollectionFixture.
+ * Registers a shared test suite that validates Firestore document utility functions
+ * (snapshot helpers, document loaders, data extraction, reactive streams, and caching)
+ * against a live or emulated Firestore instance.
  *
- * @param f
+ * Covers functions from `document.utility.ts`, `document.rxjs.ts`, and `query.util.ts`
+ * such as {@link getDocumentSnapshots}, {@link loadDocumentsForKeys},
+ * {@link latestSnapshotsFromDocuments}, {@link streamDocumentSnapshotsData}, and more.
+ *
+ * @param f - Fixture providing the mock item collection and parent context for the tests.
  */
 export declare function describeFirestoreDocumentUtilityTests(f: MockItemCollectionFixture): void;

package/test/src/lib/common/firestore/test.iterator.d.ts

@@ -1,7 +1,12 @@
 import { type MockItemCollectionFixture } from '../mock';
 /**
- * Describes accessor driver tests, using a MockItemCollectionFixture.
+ * Registers a shared test suite that validates Firestore pagination and iteration behavior
+ * (page-based queries, snapshot/item accumulators, and loading-state integration)
+ * against a live or emulated Firestore instance.
  *
- * @param f
+ * Tests cover {@link FirestoreItemPageIterationFactoryFunction}, {@link firebaseQuerySnapshotAccumulator},
+ * {@link firebaseQueryItemAccumulator}, and related RxJS accumulator utilities.
+ *
+ * @param f - Fixture providing the mock item collection and parent context for the tests.
  */
 export declare function describeFirestoreIterationTests(f: MockItemCollectionFixture): void;

package/test/src/lib/common/mock/mock.item.collection.fixture.d.ts

@@ -3,6 +3,12 @@ import { AbstractWrappedFixtureWithInstance, type TestWrappedContextFactoryBuild
 import { type TestFirestoreContextFixture } from '../firestore/firestore.instance';
 import { type MockItemFirestoreCollection, type MockItem } from './mock.item';
 import { type MockItemCollections } from './mock.item.service';
+/**
+ * Provides direct access to all mock item Firestore collections for a single test run.
+ *
+ * Created by {@link MockItemCollectionFixture} and exposes convenience getters for each
+ * mock collection/collection-group. Delegates collection creation to {@link makeMockItemCollections}.
+ */
 export declare class MockItemCollectionFixtureInstance {
     readonly fixture: MockItemCollectionFixture;
     readonly collections: MockItemCollections;
@@ -23,10 +29,32 @@ export declare class MockItemCollectionFixtureInstance {
     constructor(fixture: MockItemCollectionFixture);
 }
 /**
- * Used to expose a CollectionReference to MockItem for simple tests.
+ * Test fixture that wraps a {@link TestFirestoreContextFixture} and provides access to
+ * all mock item collections via {@link MockItemCollectionFixtureInstance}.
+ *
+ * Use {@link testWithMockItemCollectionFixture} to create a factory builder for this fixture.
  */
 export declare class MockItemCollectionFixture extends AbstractWrappedFixtureWithInstance<MockItemCollectionFixtureInstance, TestFirestoreContextFixture> {
 }
+/**
+ * Configuration options for {@link testWithMockItemCollectionFixture}.
+ *
+ * Currently empty; reserved for future setup/teardown customization.
+ */
 export interface MockItemCollectionFirebaseContextConfig {
 }
+/**
+ * Creates a {@link TestWrappedContextFactoryBuilder} that sets up a {@link MockItemCollectionFixture}
+ * around a parent {@link TestFirestoreContextFixture}.
+ *
+ * Compose with a Firebase test context factory to get a fully wired test environment:
+ *
+ * @example
+ * ```ts
+ * const f = testWithMockItemCollectionFixture()(authorizedFirebaseFactory);
+ * describe('my test', () => f.with((instance) => {
+ *   it('should work', () => { ... });
+ * }));
+ * ```
+ */
 export declare function testWithMockItemCollectionFixture(config?: MockItemCollectionFirebaseContextConfig): TestWrappedContextFactoryBuilder<MockItemCollectionFixture, TestFirestoreContextFixture>;