@dereekb/firebase 13.10.8 → 13.11.0

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

@@ -12,7 +12,8 @@ export interface TestingFirestoreAccessorDriver extends FirestoreAccessorDriver
      *
      * This initialization step is useful for the client, where the rules file needs to be updated to reflect the collection names properly in order to ensure rules are correct.
      *
-     * @param collectionNames
+     * @param collectionNames - The original collection names to register fuzzed entries for.
+     * @returns The internal map of original collection names to fuzzed names (same reference as {@link TestingFirestoreAccessorDriver.getFuzzedCollectionsNameMap}).
      */
     initWithCollectionNames(collectionNames: string[]): Map<string, string>;
 }
@@ -31,6 +32,7 @@ export interface TestingFirestoreAccessorDriver extends FirestoreAccessorDriver
  * ```
  *
  * @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.
  */
 export declare function makeTestingFirestoreAccesorDriver(driver: FirestoreAccessorDriver): TestingFirestoreAccessorDriver;
 /**
@@ -43,8 +45,8 @@ export interface TestingFirestoreDrivers extends FirestoreDrivers {
 /**
  * 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}.
  */
 export declare function makeTestingFirestoreDrivers(drivers: FirestoreDrivers): TestingFirestoreDrivers;
 /**

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

@@ -14,6 +14,9 @@ export declare class MockItemCollectionFixtureInstance {
     readonly collections: MockItemCollections;
     get collection(): CollectionReference<MockItem>;
     /**
+     * Backwards-compatible alias for {@link MockItemCollectionFixtureInstance.mockItemCollection}.
+     *
+     * @returns The root {@link MockItemFirestoreCollection} from the fixture's underlying {@link MockItemCollections}.
      * @deprecated Use mockItemCollection instead.
      */
     get firestoreCollection(): MockItemFirestoreCollection;
@@ -56,5 +59,8 @@ export interface MockItemCollectionFirebaseContextConfig {
  *   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.
  */
 export declare function testWithMockItemCollectionFixture(_config?: MockItemCollectionFirebaseContextConfig): TestWrappedContextFactoryBuilder<MockItemCollectionFixture, TestFirestoreContextFixture>;

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

@@ -72,8 +72,8 @@ export declare const mockItemConverter: import("@dereekb/firebase").SnapshotConv
 /**
  * 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.
  */
 export declare function mockItemCollectionReference(context: FirestoreContext): CollectionReference<MockItem>;
 /**
@@ -88,6 +88,9 @@ export type MockItemFirestoreCollection = FirestoreCollection<MockItem, MockItem
  * 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}.
  */
 export declare function mockItemFirestoreCollection(firestoreContext: FirestoreContext): MockItemFirestoreCollection;
 /**
@@ -174,15 +177,12 @@ export declare const mockItemPrivateConverter: import("@dereekb/firebase").Snaps
     settings: MockItemSettingsMap;
     createdAt: Date;
 }, import("@dereekb/util").MaybeMap<object>, any>>>;
-/**
- * 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.
  */
 export declare function mockItemPrivateCollectionReferenceFactory(context: FirestoreContext): (parent: MockItemDocument) => CollectionReference<MockItemPrivate>;
 /**
@@ -195,10 +195,16 @@ export type MockItemPrivateFirestoreCollection = SingleItemFirestoreCollection<M
 export type MockItemPrivateFirestoreCollectionFactory = (parent: MockItemDocument) => MockItemPrivateFirestoreCollection;
 /**
  * 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}.
  */
 export declare function mockItemPrivateFirestoreCollection(firestoreContext: FirestoreContext): MockItemPrivateFirestoreCollectionFactory;
 /**
  * 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.
  */
 export declare function mockItemPrivateCollectionReference(context: FirestoreContext): CollectionGroup<MockItemPrivate>;
 /**
@@ -207,6 +213,9 @@ export declare function mockItemPrivateCollectionReference(context: FirestoreCon
 export type MockItemPrivateFirestoreCollectionGroup = FirestoreCollectionGroup<MockItemPrivate, MockItemPrivateDocument>;
 /**
  * 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}.
  */
 export declare function mockItemPrivateFirestoreCollectionGroup(firestoreContext: FirestoreContext): MockItemPrivateFirestoreCollectionGroup;
 /**
@@ -254,10 +263,11 @@ export declare const mockItemUserConverter: import("@dereekb/firebase").Snapshot
     uid: import("@dereekb/firebase").FirebaseAuthUserId;
 }, import("@dereekb/util").MaybeMap<object>, any>>>;
 /**
- * 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.
  */
 export declare function mockItemUserCollectionReferenceFactory(context: FirestoreContext): (parent: MockItemDocument) => CollectionReference<MockItemUser>;
 /**
@@ -274,10 +284,16 @@ export type MockItemUserFirestoreCollection = FirestoreCollectionWithParent<Mock
 export type MockItemUserFirestoreCollectionFactory = (parent: MockItemDocument) => MockItemUserFirestoreCollection;
 /**
  * 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}.
  */
 export declare function mockItemUserFirestoreCollection(firestoreContext: FirestoreContext): MockItemUserFirestoreCollectionFactory;
 /**
  * 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.
  */
 export declare function mockItemUserCollectionReference(context: FirestoreContext): CollectionGroup<MockItemUser>;
 /**
@@ -286,6 +302,9 @@ export declare function mockItemUserCollectionReference(context: FirestoreContex
 export type MockItemUserFirestoreCollectionGroup = FirestoreCollectionGroup<MockItemUser, MockItemUserDocument>;
 /**
  * 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}.
  */
 export declare function mockItemUserFirestoreCollectionGroup(firestoreContext: FirestoreContext): MockItemUserFirestoreCollectionGroup;
 /**
@@ -326,6 +345,9 @@ export declare const mockItemSubItemConverter: import("@dereekb/firebase").Snaps
 /**
  * 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.
  */
 export declare function mockItemSubItemCollectionReferenceFactory(context: FirestoreContext): (parent: MockItemDocument) => CollectionReference<MockItemSubItem>;
 /**
@@ -338,10 +360,16 @@ export type MockItemSubItemFirestoreCollection = FirestoreCollectionWithParent<M
 export type MockItemSubItemFirestoreCollectionFactory = (parent: MockItemDocument) => MockItemSubItemFirestoreCollection;
 /**
  * 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}.
  */
 export declare function mockItemSubItemFirestoreCollection(firestoreContext: FirestoreContext): MockItemSubItemFirestoreCollectionFactory;
 /**
  * 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.
  */
 export declare function mockItemSubItemCollectionReference(context: FirestoreContext): CollectionGroup<MockItemSubItem>;
 /**
@@ -350,6 +378,9 @@ export declare function mockItemSubItemCollectionReference(context: FirestoreCon
 export type MockItemSubItemFirestoreCollectionGroup = FirestoreCollectionGroup<MockItemSubItem, MockItemSubItemDocument>;
 /**
  * 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}.
  */
 export declare function mockItemSubItemFirestoreCollectionGroup(firestoreContext: FirestoreContext): MockItemSubItemFirestoreCollectionGroup;
 /**
@@ -390,6 +421,9 @@ export declare const mockItemSubItemDeepConverter: import("@dereekb/firebase").S
 /**
  * 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.
  */
 export declare function mockItemSubItemDeepCollectionReferenceFactory(context: FirestoreContext): (parent: MockItemSubItemDocument) => CollectionReference<MockItemSubItemDeep>;
 /**
@@ -402,10 +436,16 @@ export type MockItemSubItemDeepFirestoreCollection = FirestoreCollectionWithPare
 export type MockItemSubItemDeepFirestoreCollectionFactory = (parent: MockItemSubItemDocument) => MockItemSubItemDeepFirestoreCollection;
 /**
  * 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}.
  */
 export declare function mockItemSubItemDeepFirestoreCollection(firestoreContext: FirestoreContext): MockItemSubItemDeepFirestoreCollectionFactory;
 /**
  * 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.
  */
 export declare function mockItemSubItemDeepCollectionReference(context: FirestoreContext): CollectionGroup<MockItemSubItemDeep>;
 /**
@@ -414,6 +454,9 @@ export declare function mockItemSubItemDeepCollectionReference(context: Firestor
 export type MockItemSubItemDeepFirestoreCollectionGroup = FirestoreCollectionGroup<MockItemSubItemDeep, MockItemSubItemDeepDocument>;
 /**
  * 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}.
  */
 export declare function mockItemSubItemDeepFirestoreCollectionGroup(firestoreContext: FirestoreContext): MockItemSubItemDeepFirestoreCollectionGroup;
 /**

package/test/src/lib/common/mock/mock.item.query.d.ts

@@ -8,10 +8,16 @@ import { type FirestoreQueryConstraint, type DocumentReference } from '@dereekb/
  * 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}.
  */
 export declare function mockItemWithValue(value: string): FirestoreQueryConstraint;
 /**
  * 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.
  */
 export declare function mockItemWithTestValue(test: boolean): FirestoreQueryConstraint;
 /**
@@ -28,7 +34,7 @@ export declare function mockItemWithTestValue(test: boolean): FirestoreQueryCons
  * 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.
  */
 export declare function allChildMockItemSubItemDeepsWithinMockItem(mockItem: DocumentReference<MockItem>): FirestoreQueryConstraint[];

package/test/src/lib/common/mock/mock.item.service.d.ts

@@ -24,6 +24,9 @@ export declare abstract class MockItemCollections {
  * 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`.
  */
 export declare function makeMockItemCollections(firestoreContext: FirestoreContext): MockItemCollections;
 /**

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

@@ -41,5 +41,8 @@ export interface MockItemStorageFirebaseStorageContextConfig {
  *   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.
  */
 export declare function testWithMockItemStorageFixture(_config?: MockItemStorageFirebaseStorageContextConfig): TestWrappedContextFactoryBuilder<MockItemStorageFixture, TestFirebaseStorageContextFixture>;

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

@@ -21,6 +21,7 @@ export interface MakeTestingFirebaseStorageAccessorDriverConfig {
  *
  * @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.
  */
 export declare function makeTestingFirebaseStorageAccesorDriver(driver: FirebaseStorageAccessorDriver, config?: MakeTestingFirebaseStorageAccessorDriverConfig): TestingFirebaseStorageAccessorDriver;
 /**
@@ -37,8 +38,9 @@ export interface TestingFirebaseStorageDrivers extends FirebaseStorageDrivers {
 /**
  * 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.
  */
 export declare function makeTestingFirebaseStorageDrivers(drivers: FirebaseStorageDrivers, config?: MakeTestingFirebaseStorageAccessorDriverConfig): TestingFirebaseStorageDrivers;
 /**