@dereekb/firebase 13.2.2 → 13.3.0

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

@@ -1,10 +1,22 @@
 import { type Maybe } from '@dereekb/util';
 import { type CollectionReference, type FirestoreCollection, type FirestoreContext, AbstractFirestoreDocument, type SingleItemFirestoreCollection, type FirestoreCollectionWithParent, AbstractFirestoreDocumentWithParent, type ExpectedFirestoreModelData, type FirestoreModelData, type CollectionGroup, type FirestoreCollectionGroup, type UserRelated, type UserRelatedById, type SystemStateStoredData, type SystemStateStoredDataConverterMap, type SystemStateStoredDataFieldConverterConfig } from '@dereekb/firebase';
 import { type GrantedReadRole } from '@dereekb/model';
+/**
+ * Union of all mock model identity types used in the test suite.
+ *
+ * Each member corresponds to one of the mock Firestore models defined in this file.
+ * Useful for generic constraints that need to accept any mock model identity.
+ */
 export type MockItemTypes = typeof mockItemIdentity | typeof mockItemPrivateIdentity | typeof mockItemUserIdentity | typeof mockItemSubItemIdentity | typeof mockItemSubItemDeepIdentity;
+/**
+ * {@link firestoreModelIdentity} for the root-level mock item collection (`mockItem` / `mi`).
+ */
 export declare const mockItemIdentity: import("@dereekb/firebase").RootFirestoreModelIdentity<"mockItem", "mi">;
 /**
- * Converted data for a test item in our firestore collection.
+ * Application-level data for the root mock Firestore model.
+ *
+ * This is the converted (in-memory) representation. For the raw database representation,
+ * see {@link MockItemData}.
  */
 export interface MockItem {
     value?: Maybe<string>;
@@ -25,7 +37,15 @@ export interface MockItem {
      */
     test: boolean;
 }
+/**
+ * Possible granted roles for {@link MockItem}. Includes the standard read role plus an admin role.
+ */
 export type MockItemRoles = GrantedReadRole | 'admin';
+/**
+ * {@link AbstractFirestoreDocument} implementation for {@link MockItem}.
+ *
+ * Provides document-level access to a single MockItem in Firestore.
+ */
 export declare class MockItemDocument extends AbstractFirestoreDocument<MockItem, MockItemDocument, typeof mockItemIdentity> {
     get modelIdentity(): import("@dereekb/firebase").RootFirestoreModelIdentity<"mockItem", "mi">;
 }
@@ -56,22 +76,61 @@ export declare const mockItemConverter: import("@dereekb/firebase").SnapshotConv
  * @returns
  */
 export declare function mockItemCollectionReference(context: FirestoreContext): CollectionReference<MockItem>;
+/**
+ * Typed {@link FirestoreCollection} for {@link MockItem} documents.
+ */
 export type MockItemFirestoreCollection = FirestoreCollection<MockItem, MockItemDocument>;
+/**
+ * Creates a {@link MockItemFirestoreCollection} bound to the given {@link FirestoreContext}.
+ *
+ * @example
+ * ```ts
+ * const collection = mockItemFirestoreCollection(firestoreContext);
+ * const doc = collection.documentAccessor().newDocument();
+ * ```
+ */
 export declare function mockItemFirestoreCollection(firestoreContext: FirestoreContext): MockItemFirestoreCollection;
+/**
+ * {@link firestoreModelIdentity} for the MockItemPrivate subcollection (`mockItemPrivate` / `mip`).
+ *
+ * This is a child identity of {@link mockItemIdentity}, meaning MockItemPrivate documents
+ * live as subcollections under MockItem documents.
+ */
 export declare const mockItemPrivateIdentity: import("@dereekb/firebase").FirestoreModelIdentityWithParent<import("@dereekb/firebase").RootFirestoreModelIdentity<"mockItem", "mi">, "mockItemPrivate", "mip">;
+/**
+ * Bitwise-encoded settings object representing cardinal directions.
+ *
+ * Used in conjunction with {@link mockItemSettingsItemDencoder} to test
+ * {@link firestoreBitwiseObjectMap} encoding/decoding in Firestore.
+ */
 export interface MockItemSettingsItem {
     north?: boolean;
     south?: boolean;
     east?: boolean;
     west?: boolean;
 }
+/**
+ * Enum indices for {@link MockItemSettingsItem} cardinal directions, used by the bitwise dencoder.
+ */
 export declare enum MockItemSettingsItemEnum {
     NORTH = 0,
     SOUTH = 1,
     EAST = 2,
     WEST = 3
 }
+/**
+ * Bitwise dencoder (encoder/decoder) for {@link MockItemSettingsItem}.
+ *
+ * Converts between a boolean-keyed object and a compact bitwise integer
+ * representation for efficient Firestore storage.
+ */
 export declare const mockItemSettingsItemDencoder: import("@dereekb/util").BitwiseObjectDencoder<MockItemSettingsItem>;
+/**
+ * Map of string keys to {@link MockItemSettingsItem} values.
+ *
+ * Stored in Firestore using {@link firestoreBitwiseObjectMap}, where each entry
+ * is encoded as a compact bitwise integer.
+ */
 export type MockItemSettingsMap = Record<string, MockItemSettingsItem>;
 /**
  * Private data for each MockItem.
@@ -85,13 +144,19 @@ export interface MockItemPrivate {
     settings: MockItemSettingsMap;
     createdAt: Date;
 }
+/**
+ * Possible granted roles for {@link MockItemPrivate}.
+ */
 export type MockItemPrivateRoles = GrantedReadRole | 'admin';
 /**
- * FirestoreDocument for MockItem
+ * {@link AbstractFirestoreDocument} implementation for {@link MockItemPrivate}.
  */
 export declare class MockItemPrivateDocument extends AbstractFirestoreDocument<MockItemPrivate, MockItemPrivateDocument, typeof mockItemPrivateIdentity> {
     get modelIdentity(): import("@dereekb/firebase").FirestoreModelIdentityWithParent<import("@dereekb/firebase").RootFirestoreModelIdentity<"mockItem", "mi">, "mockItemPrivate", "mip">;
 }
+/**
+ * Raw Firestore storage type for {@link MockItemPrivate}.
+ */
 export type MockItemPrivateData = FirestoreModelData<MockItemPrivate, {}>;
 /**
  * Used to build a FirestoreDataConverter. Fields are configured via configuration. See the SnapshotConverterFunctions for more info.
@@ -115,13 +180,40 @@ export declare const mockItemPrivateConverter: import("@dereekb/firebase").Snaps
  * @param firestore
  * @returns
  */
+/**
+ * Creates a factory that produces {@link CollectionReference} instances for {@link MockItemPrivate}
+ * subcollections under a given {@link MockItemDocument} parent.
+ */
 export declare function mockItemPrivateCollectionReferenceFactory(context: FirestoreContext): (parent: MockItemDocument) => CollectionReference<MockItemPrivate>;
+/**
+ * Typed {@link SingleItemFirestoreCollection} for {@link MockItemPrivate}, constrained to one document per parent.
+ */
 export type MockItemPrivateFirestoreCollection = SingleItemFirestoreCollection<MockItemPrivate, MockItem, MockItemPrivateDocument>;
+/**
+ * Factory function type that creates a {@link MockItemPrivateFirestoreCollection} for a given parent.
+ */
 export type MockItemPrivateFirestoreCollectionFactory = (parent: MockItemDocument) => MockItemPrivateFirestoreCollection;
+/**
+ * Creates a factory for producing {@link MockItemPrivateFirestoreCollection} instances bound to a parent {@link MockItemDocument}.
+ */
 export declare function mockItemPrivateFirestoreCollection(firestoreContext: FirestoreContext): MockItemPrivateFirestoreCollectionFactory;
+/**
+ * Creates a {@link CollectionGroup} reference for querying all {@link MockItemPrivate} documents across parents.
+ */
 export declare function mockItemPrivateCollectionReference(context: FirestoreContext): CollectionGroup<MockItemPrivate>;
+/**
+ * Typed {@link FirestoreCollectionGroup} for querying {@link MockItemPrivate} across all parent documents.
+ */
 export type MockItemPrivateFirestoreCollectionGroup = FirestoreCollectionGroup<MockItemPrivate, MockItemPrivateDocument>;
+/**
+ * Creates a {@link MockItemPrivateFirestoreCollectionGroup} for cross-parent queries on {@link MockItemPrivate}.
+ */
 export declare function mockItemPrivateFirestoreCollectionGroup(firestoreContext: FirestoreContext): MockItemPrivateFirestoreCollectionGroup;
+/**
+ * {@link firestoreModelIdentity} for the MockItemUser subcollection (`mockItemUser` / `miu`).
+ *
+ * Child of {@link mockItemIdentity}. Represents per-user data associated with a {@link MockItem}.
+ */
 export declare const mockItemUserIdentity: import("@dereekb/firebase").FirestoreModelIdentityWithParent<import("@dereekb/firebase").RootFirestoreModelIdentity<"mockItem", "mi">, "mockItemUser", "miu">;
 /**
  * An item associated per user to this item.
@@ -129,18 +221,27 @@ export declare const mockItemUserIdentity: import("@dereekb/firebase").Firestore
 export interface MockItemUser extends UserRelated, UserRelatedById {
     name: string;
 }
+/**
+ * Possible granted roles for {@link MockItemUser}.
+ */
 export type MockItemUserRoles = GrantedReadRole | 'admin';
 /**
- * FirestoreDocument for MockItem
+ * {@link AbstractFirestoreDocument} implementation for {@link MockItemUser}.
  */
 export declare class MockItemUserDocument extends AbstractFirestoreDocument<MockItemUser, MockItemUserDocument, typeof mockItemUserIdentity> {
     get modelIdentity(): import("@dereekb/firebase").FirestoreModelIdentityWithParent<import("@dereekb/firebase").RootFirestoreModelIdentity<"mockItem", "mi">, "mockItemUser", "miu">;
 }
+/**
+ * Raw Firestore storage type for {@link MockItemUser}.
+ */
 export type MockItemUserData = FirestoreModelData<MockItemUser, {}>;
 /**
  * Firestore collection path name.
  */
 export declare const mockItemUserCollectionName = "mockItemUser";
+/**
+ * Default document identifier used for MockItemUser in tests.
+ */
 export declare const mockItemUserIdentifier = "0";
 /**
  * Used to build a FirestoreDataConverter. Fields are configured via configuration. See the SnapshotConverterFunctions for more info.
@@ -159,13 +260,40 @@ export declare const mockItemUserConverter: import("@dereekb/firebase").Snapshot
  * @returns
  */
 export declare function mockItemUserCollectionReferenceFactory(context: FirestoreContext): (parent: MockItemDocument) => CollectionReference<MockItemUser>;
+/**
+ * Accessor factory for {@link MockItemUser} that copies user-related fields (uid) when creating documents.
+ */
 export declare const mockItemUserAccessorFactory: import("@dereekb/firebase").InterceptAccessorFactoryFunction<MockItemUser, import("@dereekb/firebase").DocumentData>;
+/**
+ * Typed {@link FirestoreCollectionWithParent} for {@link MockItemUser} documents under a {@link MockItem}.
+ */
 export type MockItemUserFirestoreCollection = FirestoreCollectionWithParent<MockItemUser, MockItem, MockItemUserDocument>;
+/**
+ * Factory function type that creates a {@link MockItemUserFirestoreCollection} for a given parent.
+ */
 export type MockItemUserFirestoreCollectionFactory = (parent: MockItemDocument) => MockItemUserFirestoreCollection;
+/**
+ * Creates a factory for producing {@link MockItemUserFirestoreCollection} instances bound to a parent {@link MockItemDocument}.
+ */
 export declare function mockItemUserFirestoreCollection(firestoreContext: FirestoreContext): MockItemUserFirestoreCollectionFactory;
+/**
+ * Creates a {@link CollectionGroup} reference for querying all {@link MockItemUser} documents across parents.
+ */
 export declare function mockItemUserCollectionReference(context: FirestoreContext): CollectionGroup<MockItemUser>;
+/**
+ * Typed {@link FirestoreCollectionGroup} for querying {@link MockItemUser} across all parent documents.
+ */
 export type MockItemUserFirestoreCollectionGroup = FirestoreCollectionGroup<MockItemUser, MockItemUserDocument>;
+/**
+ * Creates a {@link MockItemUserFirestoreCollectionGroup} for cross-parent queries on {@link MockItemUser}.
+ */
 export declare function mockItemUserFirestoreCollectionGroup(firestoreContext: FirestoreContext): MockItemUserFirestoreCollectionGroup;
+/**
+ * {@link firestoreModelIdentity} for the MockItemSubItem subcollection (`mockItemSub` / `misi`).
+ *
+ * Child of {@link mockItemIdentity}. Unlike {@link MockItemPrivate} (single item) or {@link MockItemUser} (per-user),
+ * there can be an unlimited number of sub-items per parent MockItem.
+ */
 export declare const mockItemSubItemIdentity: import("@dereekb/firebase").FirestoreModelIdentityWithParent<import("@dereekb/firebase").RootFirestoreModelIdentity<"mockItem", "mi">, "mockItemSub", "misi">;
 /**
  * Data for a sub item in our firestore collection.
@@ -175,25 +303,61 @@ export declare const mockItemSubItemIdentity: import("@dereekb/firebase").Firest
 export interface MockItemSubItem {
     value?: Maybe<number>;
 }
+/**
+ * Possible granted roles for {@link MockItemSubItem}.
+ */
 export type MockItemSubItemRoles = GrantedReadRole | 'admin';
 /**
- * FirestoreDocument for MockItem
+ * {@link AbstractFirestoreDocumentWithParent} implementation for {@link MockItemSubItem}.
+ *
+ * Maintains a reference to its parent {@link MockItem} document.
  */
 export declare class MockItemSubItemDocument extends AbstractFirestoreDocumentWithParent<MockItem, MockItemSubItem, MockItemSubItemDocument, typeof mockItemSubItemIdentity> {
     get modelIdentity(): import("@dereekb/firebase").FirestoreModelIdentityWithParent<import("@dereekb/firebase").RootFirestoreModelIdentity<"mockItem", "mi">, "mockItemSub", "misi">;
 }
+/**
+ * Raw Firestore storage type for {@link MockItemSubItem}. All fields match the application type exactly.
+ */
 export type MockItemSubItemData = ExpectedFirestoreModelData<MockItemSubItem>;
 /**
  * Used to build a FirestoreDataConverter. Fields are configured via configuration. See the SnapshotConverterFunctions for more info.
  */
 export declare const mockItemSubItemConverter: import("@dereekb/firebase").SnapshotConverterFunctions<MockItemSubItem, import("@dereekb/util").ReplaceType<MockItemSubItem, object, any>>;
+/**
+ * Creates a factory that produces {@link CollectionReference} instances for {@link MockItemSubItem}
+ * subcollections under a given {@link MockItemDocument} parent.
+ */
 export declare function mockItemSubItemCollectionReferenceFactory(context: FirestoreContext): (parent: MockItemDocument) => CollectionReference<MockItemSubItem>;
+/**
+ * Typed {@link FirestoreCollectionWithParent} for {@link MockItemSubItem} documents under a {@link MockItem}.
+ */
 export type MockItemSubItemFirestoreCollection = FirestoreCollectionWithParent<MockItemSubItem, MockItem, MockItemSubItemDocument, MockItemDocument>;
+/**
+ * Factory function type that creates a {@link MockItemSubItemFirestoreCollection} for a given parent.
+ */
 export type MockItemSubItemFirestoreCollectionFactory = (parent: MockItemDocument) => MockItemSubItemFirestoreCollection;
+/**
+ * Creates a factory for producing {@link MockItemSubItemFirestoreCollection} instances bound to a parent {@link MockItemDocument}.
+ */
 export declare function mockItemSubItemFirestoreCollection(firestoreContext: FirestoreContext): MockItemSubItemFirestoreCollectionFactory;
+/**
+ * Creates a {@link CollectionGroup} reference for querying all {@link MockItemSubItem} documents across parents.
+ */
 export declare function mockItemSubItemCollectionReference(context: FirestoreContext): CollectionGroup<MockItemSubItem>;
+/**
+ * Typed {@link FirestoreCollectionGroup} for querying {@link MockItemSubItem} across all parent documents.
+ */
 export type MockItemSubItemFirestoreCollectionGroup = FirestoreCollectionGroup<MockItemSubItem, MockItemSubItemDocument>;
+/**
+ * Creates a {@link MockItemSubItemFirestoreCollectionGroup} for cross-parent queries on {@link MockItemSubItem}.
+ */
 export declare function mockItemSubItemFirestoreCollectionGroup(firestoreContext: FirestoreContext): MockItemSubItemFirestoreCollectionGroup;
+/**
+ * {@link firestoreModelIdentity} for the MockItemSubItemDeep subcollection (`mockItemSubItemDeep` / `misid`).
+ *
+ * Child of {@link mockItemSubItemIdentity}, making this a three-level-deep nested collection
+ * (MockItem -> MockItemSubItem -> MockItemSubItemDeep). Useful for testing deeply nested document access patterns.
+ */
 export declare const mockItemSubItemDeepIdentity: import("@dereekb/firebase").FirestoreModelIdentityWithParent<import("@dereekb/firebase").FirestoreModelIdentityWithParent<import("@dereekb/firebase").RootFirestoreModelIdentity<"mockItem", "mi">, "mockItemSub", "misi">, "mockItemSubItemDeep", "misid">;
 /**
  * Data for a sub item in our firestore collection.
@@ -203,31 +367,81 @@ export declare const mockItemSubItemDeepIdentity: import("@dereekb/firebase").Fi
 export interface MockItemSubItemDeep {
     value?: Maybe<number>;
 }
+/**
+ * Possible granted roles for {@link MockItemSubItemDeep}.
+ */
 export type MockItemSubItemDeepRoles = GrantedReadRole | 'admin';
 /**
- * FirestoreDocument for MockSubItem
+ * {@link AbstractFirestoreDocumentWithParent} implementation for {@link MockItemSubItemDeep}.
+ *
+ * Maintains a reference to its parent {@link MockItemSubItem} document.
  */
 export declare class MockItemSubItemDeepDocument extends AbstractFirestoreDocumentWithParent<MockItemSubItem, MockItemSubItemDeep, MockItemSubItemDeepDocument, typeof mockItemSubItemDeepIdentity> {
     get modelIdentity(): import("@dereekb/firebase").FirestoreModelIdentityWithParent<import("@dereekb/firebase").FirestoreModelIdentityWithParent<import("@dereekb/firebase").RootFirestoreModelIdentity<"mockItem", "mi">, "mockItemSub", "misi">, "mockItemSubItemDeep", "misid">;
 }
+/**
+ * Raw Firestore storage type for {@link MockItemSubItemDeep}. All fields match the application type exactly.
+ */
 export type MockItemSubItemDeepData = ExpectedFirestoreModelData<MockItemSubItemDeep>;
 /**
  * Used to build a FirestoreDataConverter. Fields are configured via configuration. See the SnapshotConverterFunctions for more info.
  */
 export declare const mockItemSubItemDeepConverter: import("@dereekb/firebase").SnapshotConverterFunctions<MockItemSubItemDeep, import("@dereekb/util").ReplaceType<MockItemSubItemDeep, object, any>>;
+/**
+ * Creates a factory that produces {@link CollectionReference} instances for {@link MockItemSubItemDeep}
+ * subcollections under a given {@link MockItemSubItemDocument} parent.
+ */
 export declare function mockItemSubItemDeepCollectionReferenceFactory(context: FirestoreContext): (parent: MockItemSubItemDocument) => CollectionReference<MockItemSubItemDeep>;
+/**
+ * Typed {@link FirestoreCollectionWithParent} for {@link MockItemSubItemDeep} documents under a {@link MockItemSubItem}.
+ */
 export type MockItemSubItemDeepFirestoreCollection = FirestoreCollectionWithParent<MockItemSubItemDeep, MockItemSubItem, MockItemSubItemDeepDocument, MockItemSubItemDocument>;
+/**
+ * Factory function type that creates a {@link MockItemSubItemDeepFirestoreCollection} for a given parent.
+ */
 export type MockItemSubItemDeepFirestoreCollectionFactory = (parent: MockItemSubItemDocument) => MockItemSubItemDeepFirestoreCollection;
+/**
+ * Creates a factory for producing {@link MockItemSubItemDeepFirestoreCollection} instances bound to a parent {@link MockItemSubItemDocument}.
+ */
 export declare function mockItemSubItemDeepFirestoreCollection(firestoreContext: FirestoreContext): MockItemSubItemDeepFirestoreCollectionFactory;
+/**
+ * Creates a {@link CollectionGroup} reference for querying all {@link MockItemSubItemDeep} documents across parents.
+ */
 export declare function mockItemSubItemDeepCollectionReference(context: FirestoreContext): CollectionGroup<MockItemSubItemDeep>;
+/**
+ * Typed {@link FirestoreCollectionGroup} for querying {@link MockItemSubItemDeep} across all parent documents.
+ */
 export type MockItemSubItemDeepFirestoreCollectionGroup = FirestoreCollectionGroup<MockItemSubItemDeep, MockItemSubItemDeepDocument>;
+/**
+ * Creates a {@link MockItemSubItemDeepFirestoreCollectionGroup} for cross-parent queries on {@link MockItemSubItemDeep}.
+ */
 export declare function mockItemSubItemDeepFirestoreCollectionGroup(firestoreContext: FirestoreContext): MockItemSubItemDeepFirestoreCollectionGroup;
+/**
+ * System state type identifier for mock system state data.
+ *
+ * Used as the key in {@link mockItemSystemStateStoredDataConverterMap}.
+ */
 export declare const MOCK_SYSTEM_STATE_TYPE = "mockitemsystemstate";
+/**
+ * Custom data stored within a mock system state document.
+ *
+ * Extends {@link SystemStateStoredData} with a `lat` (last-updated-at) timestamp field
+ * to test sub-object field conversion in system state documents.
+ */
 export interface MockSystemData extends SystemStateStoredData {
     /**
      * Last updated at
      */
     lat: Date;
 }
+/**
+ * Field converter config for {@link MockSystemData}, handling the `lat` date field conversion.
+ */
 export declare const mockItemSystemDataConverter: SystemStateStoredDataFieldConverterConfig<MockSystemData>;
+/**
+ * Maps system state type identifiers to their corresponding field converter configs.
+ *
+ * Used when creating the mock system state Firestore collection to register
+ * the {@link MockSystemData} converter under the {@link MOCK_SYSTEM_STATE_TYPE} key.
+ */
 export declare const mockItemSystemStateStoredDataConverterMap: SystemStateStoredDataConverterMap;

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

@@ -1,2 +1,8 @@
 import { type FirestoreModelKey } from '@dereekb/firebase';
+/**
+ * Type alias for a {@link FirestoreModelKey} identifying a {@link MockItemUser} document.
+ *
+ * Provides semantic clarity when a function parameter specifically expects a MockItemUser key
+ * rather than a generic model key.
+ */
 export type MockItemUserKey = FirestoreModelKey;

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

@@ -1,6 +1,18 @@
 import { type MockItem } from './mock.item';
 import { type FirestoreQueryConstraint, type DocumentReference } from '@dereekb/firebase';
+/**
+ * Creates a Firestore query constraint that filters {@link MockItem} documents by their `value` field.
+ *
+ * @example
+ * ```ts
+ * const constraint = mockItemWithValue('hello');
+ * const results = await collection.query(constraint);
+ * ```
+ */
 export declare function mockItemWithValue(value: string): FirestoreQueryConstraint;
+/**
+ * Creates a Firestore query constraint that filters {@link MockItem} documents by their `test` boolean field.
+ */
 export declare function mockItemWithTestValue(test: boolean): FirestoreQueryConstraint;
 /**
  * This sorts all fields by their document ID, then filters in between two specific document id paths in order to only return values between a specific path.

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

@@ -1,6 +1,13 @@
 import { type MockItem, type MockItemSubItemDeep, type MockItemSubItemDeepDocument, type MockItemSubItemDeepFirestoreCollectionFactory, type MockItemSubItemDeepFirestoreCollectionGroup, type MockItemSubItemDeepRoles, type MockItemDocument, type MockItemFirestoreCollection, type MockItemPrivate, type MockItemPrivateDocument, type MockItemPrivateFirestoreCollectionFactory, type MockItemPrivateFirestoreCollectionGroup, type MockItemPrivateRoles, type MockItemRoles, type MockItemSubItem, type MockItemSubItemDocument, type MockItemSubItemFirestoreCollectionFactory, type MockItemSubItemFirestoreCollectionGroup, type MockItemSubItemRoles, type MockItemTypes, type MockItemUser, type MockItemUserDocument, type MockItemUserFirestoreCollectionFactory, type MockItemUserFirestoreCollectionGroup, type MockItemUserRoles } from './mock.item';
 import { type FirebaseAppModelContext, type FirestoreContext, type SystemStateFirestoreCollection, type SystemState, type SystemStateDocument, type SystemStateTypes } from '@dereekb/firebase';
 import { type GrantedRoleMap } from '@dereekb/model';
+/**
+ * Abstract class defining the shape of all mock item Firestore collections.
+ *
+ * Implementations provide concrete collection instances for each mock model type,
+ * including root collections, subcollection factories, and collection groups.
+ * Use {@link makeMockItemCollections} to create a concrete instance from a {@link FirestoreContext}.
+ */
 export declare abstract class MockItemCollections {
     abstract readonly mockItemCollection: MockItemFirestoreCollection;
     abstract readonly mockItemPrivateCollectionFactory: MockItemPrivateFirestoreCollectionFactory;
@@ -13,21 +20,63 @@ export declare abstract class MockItemCollections {
     abstract readonly mockItemSubItemDeepCollectionGroup: MockItemSubItemDeepFirestoreCollectionGroup;
     abstract readonly mockItemSystemStateCollection: SystemStateFirestoreCollection;
 }
+/**
+ * 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.
+ */
 export declare function makeMockItemCollections(firestoreContext: FirestoreContext): MockItemCollections;
+/**
+ * Model service factory for {@link MockItem}. Returns configurable roles from `context.rolesToReturn`, defaulting to `{ read: true }`.
+ */
 export declare const mockItemFirebaseModelServiceFactory: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItem, MockItemDocument, MockItemRoles>;
+/**
+ * Model service factory for {@link MockItemPrivate}. Returns configurable roles from `context.rolesToReturn`, defaulting to `{ read: true }`.
+ */
 export declare const mockItemPrivateFirebaseModelServiceFactory: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemPrivate, MockItemPrivateDocument, MockItemPrivateRoles>;
+/**
+ * Model service factory for {@link MockItemUser}. Grants read access if the authenticated user owns the document;
+ * otherwise uses `context.rolesToReturn`.
+ */
 export declare const mockItemUserFirebaseModelServiceFactory: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemUser, MockItemUserDocument, MockItemUserRoles>;
+/**
+ * Model service factory for {@link MockItemSubItem}. Returns configurable roles from `context.rolesToReturn`, defaulting to `{ read: true }`.
+ */
 export declare const mockItemSubItemFirebaseModelServiceFactory: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemSubItem, MockItemSubItemDocument, MockItemSubItemRoles>;
+/**
+ * Model service factory for {@link MockItemSubItemDeep}. Returns configurable roles from `context.rolesToReturn`, defaulting to `{ read: true }`.
+ */
 export declare const mockItemSubItemDeepFirebaseModelServiceFactory: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemSubItemDeep, MockItemSubItemDeepDocument, MockItemSubItemDeepRoles>;
+/**
+ * Model service factory for {@link SystemState}. Only grants access to system admins via {@link grantFullAccessIfAdmin}.
+ */
 export declare const mockItemSystemStateFirebaseModelServiceFactory: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, SystemState<import("@dereekb/firebase").SystemStateStoredData>, SystemStateDocument<import("@dereekb/firebase").SystemStateStoredData>, "sysadmin">;
+/**
+ * Union of all model identity types used in the mock Firebase service layer, including system state.
+ */
 export type MockModelTypes = SystemStateTypes | MockItemTypes;
+/**
+ * The application context type for mock Firebase models. Provides access to all mock collections.
+ */
 export type MockFirebaseContextAppContext = MockItemCollections;
+/**
+ * Base context for mock Firebase model operations.
+ *
+ * Combines the standard {@link FirebaseAppModelContext} (which provides `app` and `auth`)
+ * with an optional `rolesToReturn` override used by mock role-map functions to return
+ * predetermined roles in tests.
+ */
 export type MockFirebaseBaseContext = FirebaseAppModelContext<MockFirebaseContextAppContext> & {
     /**
      * Configured in the context and in mockItem role map functions to return this value if provided.
      */
     rolesToReturn?: GrantedRoleMap<any>;
 };
+/**
+ * Registry of all mock model service factories, keyed by model name.
+ *
+ * Passed to {@link firebaseModelsService} to create the composite {@link mockFirebaseModelServices}.
+ */
 export declare const MOCK_FIREBASE_MODEL_SERVICE_FACTORIES: {
     systemState: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, SystemState<import("@dereekb/firebase").SystemStateStoredData>, SystemStateDocument<import("@dereekb/firebase").SystemStateStoredData>, "sysadmin">;
     mockItem: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItem, MockItemDocument, MockItemRoles>;
@@ -36,6 +85,11 @@ export declare const MOCK_FIREBASE_MODEL_SERVICE_FACTORIES: {
     mockItemSub: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemSubItem, MockItemSubItemDocument, MockItemSubItemRoles>;
     mockItemSubItemDeep: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemSubItemDeep, MockItemSubItemDeepDocument, MockItemSubItemDeepRoles>;
 };
+/**
+ * Composite model service built from {@link MOCK_FIREBASE_MODEL_SERVICE_FACTORIES}.
+ *
+ * Provides permission checking and collection access for all mock models in a unified API.
+ */
 export declare const mockFirebaseModelServices: import("@dereekb/firebase").FirebaseModelsService<{
     systemState: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, SystemState<import("@dereekb/firebase").SystemStateStoredData>, SystemStateDocument<import("@dereekb/firebase").SystemStateStoredData>, "sysadmin">;
     mockItem: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItem, MockItemDocument, MockItemRoles>;
@@ -44,6 +98,12 @@ export declare const mockFirebaseModelServices: import("@dereekb/firebase").Fire
     mockItemSub: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemSubItem, MockItemSubItemDocument, MockItemSubItemRoles>;
     mockItemSubItemDeep: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemSubItemDeep, MockItemSubItemDeepDocument, MockItemSubItemDeepRoles>;
 }, MockFirebaseContext>;
+/**
+ * Full mock Firebase context type used throughout the test suite.
+ *
+ * Extends {@link MockFirebaseBaseContext} with an optional reference to the composite
+ * {@link mockFirebaseModelServices} instance.
+ */
 export type MockFirebaseContext = MockFirebaseBaseContext & {
     service?: typeof mockFirebaseModelServices;
 };

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

@@ -1,5 +1,10 @@
 import { AbstractWrappedFixtureWithInstance, type TestWrappedContextFactoryBuilder } from '@dereekb/util/test';
 import { type TestFirebaseStorage, type TestFirebaseStorageContextFixture, type TestFirebaseStorageInstance } from '../storage/storage.instance';
+/**
+ * Provides access to Firebase Storage for a single test run within a mock item context.
+ *
+ * Created by {@link MockItemStorageFixture} and exposes the parent fixture's storage and storage context.
+ */
 export declare class MockItemStorageFixtureInstance implements TestFirebaseStorageInstance {
     readonly fixture: MockItemStorageFixture;
     constructor(fixture: MockItemStorageFixture);
@@ -7,12 +12,34 @@ export declare class MockItemStorageFixtureInstance implements TestFirebaseStora
     get storageContext(): import("..").TestFirebaseStorageContext;
 }
 /**
- * Used to expose a CollectionReference to MockItem for simple tests.
+ * Test fixture that wraps a {@link TestFirebaseStorageContextFixture} and provides access to
+ * Firebase Storage via {@link MockItemStorageFixtureInstance}.
+ *
+ * Use {@link testWithMockItemStorageFixture} to create a factory builder for this fixture.
  */
 export declare class MockItemStorageFixture extends AbstractWrappedFixtureWithInstance<MockItemStorageFixtureInstance, TestFirebaseStorageContextFixture> implements TestFirebaseStorage {
     get storage(): import("@dereekb/firebase").FirebaseStorage;
     get storageContext(): import("..").TestFirebaseStorageContext;
 }
+/**
+ * Configuration options for {@link testWithMockItemStorageFixture}.
+ *
+ * Currently empty; reserved for future setup/teardown customization.
+ */
 export interface MockItemStorageFirebaseStorageContextConfig {
 }
+/**
+ * Creates a {@link TestWrappedContextFactoryBuilder} that sets up a {@link MockItemStorageFixture}
+ * around a parent {@link TestFirebaseStorageContextFixture}.
+ *
+ * Compose with a Firebase test context factory to get a fully wired storage test environment:
+ *
+ * @example
+ * ```ts
+ * const f = testWithMockItemStorageFixture()(authorizedFirebaseFactory);
+ * describe('storage test', () => f.with((instance) => {
+ *   it('should upload', () => { ... });
+ * }));
+ * ```
+ */
 export declare function testWithMockItemStorageFixture(config?: MockItemStorageFirebaseStorageContextConfig): TestWrappedContextFactoryBuilder<MockItemStorageFixture, TestFirebaseStorageContextFixture>;

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

@@ -1,7 +1,27 @@
 import { type FirebaseStorageAccessorDriver, type FirebaseStorageContext, type FirebaseStorageDrivers } from '@dereekb/firebase';
+/**
+ * Configuration for {@link makeTestingFirebaseStorageAccesorDriver}.
+ */
 export interface MakeTestingFirebaseStorageAccessorDriverConfig {
+    /**
+     * Whether to generate a unique test bucket name as the default bucket.
+     *
+     * When `true`, a randomized bucket name is always generated. When `false`, the
+     * original driver's default bucket is preserved. When omitted, a test bucket is
+     * generated only if the base driver does not already define a default bucket.
+     */
     useTestDefaultBucket?: boolean;
 }
+/**
+ * Creates a {@link TestingFirebaseStorageAccessorDriver} that wraps the given driver,
+ * optionally replacing its default bucket with a unique test bucket name.
+ *
+ * The generated bucket name incorporates a timestamp and random component so that
+ * parallel test runs do not collide on the same bucket.
+ *
+ * @param driver - The base storage accessor driver to wrap.
+ * @param config - Optional configuration controlling test bucket behavior.
+ */
 export declare function makeTestingFirebaseStorageAccesorDriver(driver: FirebaseStorageAccessorDriver, config?: MakeTestingFirebaseStorageAccessorDriverConfig): TestingFirebaseStorageAccessorDriver;
 /**
  * Used to override/extend a FirebaseStorageAccessorDriver to provide better isolation between tests.
@@ -21,7 +41,17 @@ export interface TestingFirebaseStorageDrivers extends FirebaseStorageDrivers {
  * @returns
  */
 export declare function makeTestingFirebaseStorageDrivers(drivers: FirebaseStorageDrivers, config?: MakeTestingFirebaseStorageAccessorDriverConfig): TestingFirebaseStorageDrivers;
+/**
+ * Extension applied to a {@link FirebaseStorageContext} to expose the testing-specific drivers.
+ *
+ * Mixed into the base context type via {@link TestFirebaseStorageContext} so that
+ * test code can access the isolated storage driver.
+ */
 export interface TestingFirebaseStorageContextExtension {
     drivers: TestingFirebaseStorageDrivers;
 }
+/**
+ * A {@link FirebaseStorageContext} augmented with {@link TestingFirebaseStorageContextExtension},
+ * giving tests access to isolated storage drivers with unique bucket names.
+ */
 export type TestFirebaseStorageContext<C = FirebaseStorageContext> = C & TestingFirebaseStorageContextExtension;

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

@@ -1,19 +1,41 @@
 import { AbstractTestContextFixture, type TestContextFactory } from '@dereekb/util/test';
 import { type FirebaseStorage } from '@dereekb/firebase';
 import { type TestFirebaseStorageContext } from './storage';
+/**
+ * Interface describing the minimum shape of a Firebase Storage test instance.
+ *
+ * Provides access to both the raw {@link FirebaseStorage} reference and the
+ * {@link TestFirebaseStorageContext} that includes testing-specific drivers.
+ */
 export interface TestFirebaseStorage {
     readonly storageContext: TestFirebaseStorageContext;
     readonly storage: FirebaseStorage;
 }
+/**
+ * Test instance that wraps a {@link TestFirebaseStorageContext} and provides convenient
+ * access to the underlying Firebase Storage reference.
+ *
+ * The context includes a test-specific default bucket name to isolate storage operations
+ * between test runs.
+ */
 export declare class TestFirebaseStorageInstance implements TestFirebaseStorage {
     readonly storageContext: TestFirebaseStorageContext;
     constructor(storageContext: TestFirebaseStorageContext);
     get storage(): FirebaseStorage;
 }
+/**
+ * Test fixture that manages the lifecycle of a {@link TestFirebaseStorageInstance}.
+ *
+ * Extends {@link AbstractTestContextFixture} to handle setup/teardown of the Firebase Storage
+ * test environment, including isolated bucket naming.
+ */
 export declare class TestFirebaseStorageContextFixture<F extends TestFirebaseStorageInstance = TestFirebaseStorageInstance> extends AbstractTestContextFixture<F> {
     get storage(): FirebaseStorage;
     get storageContext(): TestFirebaseStorageContext;
 }
+/**
+ * Factory type for creating {@link TestFirebaseStorageContextFixture} instances in test suites.
+ */
 export type TestFirebaseStorageContextFactory = TestContextFactory<TestFirebaseStorageContextFixture>;
 /**
  * @deprecated Use TestFirebaseStorageContextFactory instead.