@dereekb/firebase 13.2.2 → 13.3.0

package/src/lib/common/development/function.schedule.d.ts

@@ -1,27 +1,56 @@
 import { type Type } from 'arktype';
+/**
+ * Action types for the scheduled function development endpoint.
+ */
 export type ScheduledFunctionDevelopmentFunctionType = 'list' | 'run';
+/**
+ * Enum variant of {@link ScheduledFunctionDevelopmentFunctionType} for runtime usage.
+ */
 export declare enum ScheduledFunctionDevelopmentFunctionTypeEnum {
     LIST = "list",
     RUN = "run"
 }
+/**
+ * Parameters for the scheduled function development endpoint.
+ *
+ * Use `type: 'list'` to discover available scheduled functions, or `type: 'run'` with a function name to execute one.
+ */
 export interface ScheduledFunctionDevelopmentFirebaseFunctionParams {
     readonly type: ScheduledFunctionDevelopmentFunctionTypeEnum;
+    /** Name of the scheduled function to run (required when type is 'run'). */
     readonly run?: string;
 }
+/**
+ * ArkType validator for {@link ScheduledFunctionDevelopmentFirebaseFunctionParams}.
+ */
 export declare const scheduledFunctionDevelopmentFirebaseFunctionParamsType: Type<ScheduledFunctionDevelopmentFirebaseFunctionParams>;
+/**
+ * Entry in the list of available scheduled functions returned by the development endpoint.
+ */
 export declare class ScheduledFunctionDevelopmentFirebaseFunctionListEntry {
     name: string;
 }
+/**
+ * Result returned when listing available scheduled functions.
+ */
 export interface ScheduledFunctionDevelopmentFirebaseFunctionListResult {
     readonly type: 'list';
     readonly list: ScheduledFunctionDevelopmentFirebaseFunctionListEntry[];
 }
+/**
+ * Result returned after successfully running a scheduled function.
+ */
 export interface ScheduledFunctionDevelopmentFirebaseFunctionRunResult {
     readonly type: 'run';
     readonly success: true;
 }
+/**
+ * Union of all possible results from the scheduled function development endpoint.
+ */
 export type ScheduledFunctionDevelopmentFirebaseFunctionResult = ScheduledFunctionDevelopmentFirebaseFunctionListResult | ScheduledFunctionDevelopmentFirebaseFunctionRunResult;
 /**
- * Key used on the front-end and backend that refers to the specifier for the scheduled functions access.
+ * Development function specifier used to route requests to the scheduled function endpoint.
+ *
+ * Used as the `specifier` value in {@link OnCallDevelopmentParams}.
  */
 export declare const SCHEDULED_FUNCTION_DEV_FUNCTION_SPECIFIER = "scheduledFunction";

package/src/lib/common/firestore/accessor/accessor.wrap.modify.d.ts

@@ -5,15 +5,16 @@ import { type DocumentData, type SetOptions } from '../types';
 import { type FirestoreDocumentDataAccessor, type FirestoreDocumentDataAccessorSetFunction } from './accessor';
 import { AbstractFirestoreDocumentDataAccessorWrapper, type InterceptAccessorFactoryFunction } from './accessor.wrap';
 /**
- * Data accessor modes.
- * - always: Always modifies on update, set, or create.
- * - update: Only modifies when calling set with options
- * - set:    Only modifies when calling create or set without options
- * - create: Only modifies on create calls
+ * Controls when the modifier function is applied to document data.
+ *
+ * - `'always'`: Modifies data on every create, set, and update operation
+ * - `'update'`: Only modifies when calling `set()` with merge options (updating existing documents)
+ * - `'set'`: Only modifies when calling `create()` or `set()` without merge options (new documents)
+ * - `'create'`: Only modifies on `create()` calls
  */
 export type ModifyBeforeSetFistoreDataAccessorMode = 'always' | 'update' | 'set' | 'create';
 /**
- * Input fora ModifyBeforeSetFirestoreDocumentDataAccessorWrapper
+ * Input passed to the modifier function, containing the document data and reference context.
  */
 export interface ModifyBeforeSetFistoreDataAccessorInput<T> extends DocumentReferenceRef<T> {
     /**
@@ -37,7 +38,14 @@ export interface ModifyBeforeSetConfig<T extends object> {
     readonly modifier: ArrayOrValue<ModifyBeforeSetModifierFunction<T>>;
 }
 /**
- * FirestoreDocumentDataAccessorWrapper that applies a modifier function to data being set. When the modifier functions are applied can be changed by the mode.
+ * Accessor wrapper that applies a modifier function to data before it is written to Firestore.
+ *
+ * The `when` mode in the config controls which write operations trigger the modifier.
+ * Common use case: automatically copying the document ID into a `uid` field for {@link UserRelated} models
+ * via {@link copyUserRelatedDataModifierConfig}.
+ *
+ * @template T - The document data type
+ * @template D - The raw document data type in Firestore
  */
 export declare class ModifyBeforeSetFirestoreDocumentDataAccessorWrapper<T extends object, D = DocumentData> extends AbstractFirestoreDocumentDataAccessorWrapper<T, D> {
     readonly config: ModifyBeforeSetConfig<T>;
@@ -46,18 +54,34 @@ export declare class ModifyBeforeSetFirestoreDocumentDataAccessorWrapper<T exten
     constructor(accessor: FirestoreDocumentDataAccessor<T, D>, config: ModifyBeforeSetConfig<T>);
 }
 /**
- * Creates a ModifyBeforeSetModifierFunction<T> to copy the documentRef's id to the target field on the data.
+ * Creates a modifier function that copies the document reference's ID into the specified field on the data.
  *
- * @param fieldName
- * @returns
+ * Useful for models that need to store their own document ID as a field (e.g., `uid` on {@link UserRelated} models).
+ *
+ * @param fieldName - The field to copy the document ID into
+ * @returns A modifier function that sets the field to the document's ID
  */
 export declare function copyDocumentIdToFieldModifierFunction<T extends object>(fieldName: keyof T): ModifyBeforeSetModifierFunction<T>;
+/**
+ * Creates an {@link InterceptAccessorFactoryFunction} that wraps all created accessors with
+ * {@link ModifyBeforeSetFirestoreDocumentDataAccessorWrapper} using the provided config.
+ */
 export declare function modifyBeforeSetInterceptAccessorFactoryFunction<T extends object, D = DocumentData>(config: ModifyBeforeSetConfig<T>): InterceptAccessorFactoryFunction<T, D>;
+/**
+ * Creates a modifier that copies the document ID to the `uid` field for {@link UserRelated} models.
+ */
 export declare function copyDocumentIdForUserRelatedModifierFunction<T extends UserRelated>(): ModifyBeforeSetModifierFunction<T>;
 /**
- * Returns a pre-configured ModifyBeforeSetConfig<T> for UserRelated models
- * @returns
+ * Returns a pre-configured {@link ModifyBeforeSetConfig} for {@link UserRelated} models
+ * that copies the document ID to the `uid` field on set operations (new document creation).
  */
 export declare function copyUserRelatedDataModifierConfig<T extends UserRelated>(): ModifyBeforeSetConfig<T>;
+/**
+ * Cached singleton factory for the UserRelated data modifier accessor interceptor.
+ */
 export declare const COPY_USER_RELATED_DATA_ACCESSOR_FACTORY_FUNCTION: import("@dereekb/util").CachedFactoryWithInput<InterceptAccessorFactoryFunction<import("../..").FirebaseAuthUserIdRef, DocumentData>, unknown>;
+/**
+ * Returns a typed {@link InterceptAccessorFactoryFunction} that applies the UserRelated
+ * document ID copy modifier to all accessors created by the factory.
+ */
 export declare function copyUserRelatedDataAccessorFactoryFunction<T extends UserRelated, D = DocumentData>(): InterceptAccessorFactoryFunction<T, D>;

package/src/lib/common/firestore/accessor/array.d.ts

@@ -1,11 +1,21 @@
 import { type WriteResult } from '../types';
 import { type FirestoreAccessorArrayUpdate, type FirestoreDocumentDataAccessor } from './accessor';
+/**
+ * Function that applies array union/remove operations to a Firestore document's array fields.
+ *
+ * @template T - The document data type
+ */
 export type ArrayFieldUpdateWithAccessorFunction<T> = (data: FirestoreAccessorArrayUpdate<T>) => Promise<WriteResult | void>;
 /**
- * https://cloud.google.com/firestore/docs/samples/firestore-data-set-array-operations-async
- * https://firebase.google.com/docs/firestore/manage-data/add-data#update_elements_in_an_array
+ * Creates a function that performs atomic array field operations (union/remove) on a Firestore document.
+ *
+ * The returned function filters out falsy/empty values from the update data and skips
+ * the operation entirely if no valid fields remain. Uses Firestore's built-in `arrayUnion`
+ * and `arrayRemove` operations, which are safe for concurrent updates.
+ *
+ * @param accessor - The document accessor to perform the array update on
+ * @returns A function that applies array updates to the document
  *
- * @param accessor
- * @returns
+ * @see https://firebase.google.com/docs/firestore/manage-data/add-data#update_elements_in_an_array
  */
 export declare function arrayUpdateWithAccessorFunction<T>(accessor: FirestoreDocumentDataAccessor<T>): ArrayFieldUpdateWithAccessorFunction<T>;

package/src/lib/common/firestore/accessor/document.d.ts

@@ -8,6 +8,23 @@ import { type FirestoreDocumentContext } from './context';
 import { type Building, type Maybe } from '@dereekb/util';
 import { type InterceptAccessorFactoryFunction } from './accessor.wrap';
 import { type FirestoreDataConverterFactory, type FirestoreDataConverterFactoryRef, type InterceptFirestoreDataConverterFactory } from './converter';
+/**
+ * Represents a typed Firestore document with full CRUD capabilities and reactive streaming.
+ *
+ * This is the primary interface for interacting with individual Firestore documents in the application.
+ * It combines document reference metadata, data conversion, and all read/write operations into a
+ * single cohesive interface. Documents are created via {@link FirestoreDocumentAccessor} which provides
+ * the appropriate execution context (standard, transaction, or batch).
+ *
+ * Key capabilities:
+ * - **Read**: `snapshot()`, `snapshotData()`, `exists()`
+ * - **Stream**: `snapshotStream()`, `snapshotDataStream()` for real-time updates
+ * - **Write**: `create()`, `update()`, `increment()`, `arrayUpdate()`
+ * - **Identity**: `id`, `key` (full path), `modelType`, `collectionName`
+ *
+ * @template T - The document data type
+ * @template I - The model identity type (provides modelType and collectionName)
+ */
 export interface FirestoreDocument<T, I extends FirestoreModelIdentity = FirestoreModelIdentity> extends FirestoreDataConverterRef<T>, DocumentReferenceRef<T>, CollectionReferenceRef<T>, FirestoreModelIdentityRef<I>, FirestoreModelTypeRef<FirestoreModelIdentityModelType<I>>, FirestoreCollectionNameRef<FirestoreModelIdentityCollectionName<I>>, FirestoreModelKeyRef, FirestoreModelIdRef {
     readonly accessor: FirestoreDocumentDataAccessor<T>;
     readonly id: string;
@@ -26,7 +43,19 @@ export interface FirestoreDocument<T, I extends FirestoreModelIdentity = Firesto
  */
 export type FirestoreDocumentData<D extends FirestoreDocument<any>> = D extends FirestoreDocument<infer T> ? T : never;
 /**
- * Abstract FirestoreDocument implementation that extends a FirestoreDocumentDataAccessor.
+ * Abstract base implementation of {@link FirestoreDocument}.
+ *
+ * Provides the standard implementation for all document operations by delegating to the
+ * underlying {@link FirestoreDocumentDataAccessor}. The `update()` method uses the document's
+ * converter (via {@link updateWithAccessorUpdateAndConverterFunction}) so that partial updates
+ * go through the same conversion pipeline as full writes.
+ *
+ * Subclasses must implement `modelIdentity` to provide the model type and collection name.
+ * Also exposes `stream$` and `data$` lazy observables for reactive consumption.
+ *
+ * @template T - The document data type
+ * @template D - The concrete document subclass type (for self-referential typing)
+ * @template I - The model identity type
  */
 export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFirestoreDocument<T, any, I>, I extends FirestoreModelIdentity = FirestoreModelIdentity> implements FirestoreDocument<T>, LimitedFirestoreDocumentAccessorRef<T, D>, CollectionReferenceRef<T> {
     private readonly _accessor;
@@ -106,10 +135,24 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
      */
     arrayUpdate(data: FirestoreAccessorArrayUpdate<T>): Promise<WriteResult | void>;
 }
+/**
+ * Reference to a {@link LimitedFirestoreDocumentAccessor}.
+ */
 export interface LimitedFirestoreDocumentAccessorRef<T, D extends FirestoreDocument<T> = FirestoreDocument<T>, A extends LimitedFirestoreDocumentAccessor<T, D> = LimitedFirestoreDocumentAccessor<T, D>> {
     readonly documentAccessor: A;
 }
 export type FirestoreDocumentAccessorRef<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> = LimitedFirestoreDocumentAccessorRef<T, D, FirestoreDocumentAccessor<T, D>>;
+/**
+ * Provides document loading capabilities without the ability to create new documents.
+ *
+ * Used in contexts where you have a document reference or key but don't have (or need) access
+ * to the parent collection — for example, in subcollection accessors or when loading documents
+ * from known paths. For full access including `newDocument()` and `loadDocumentForId()`,
+ * use {@link FirestoreDocumentAccessor}.
+ *
+ * @template T - The document data type
+ * @template D - The concrete FirestoreDocument subclass
+ */
 export interface LimitedFirestoreDocumentAccessor<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends FirestoreDataConverterRef<T>, FirestoreModelTypeModelIdentityRef, FirestoreAccessorDriverRef {
     readonly databaseContext: FirestoreDocumentContext<T>;
     /**
@@ -145,6 +188,16 @@ export interface LimitedFirestoreDocumentAccessor<T, D extends FirestoreDocument
      */
     readonly converterFactory: FirestoreDataConverterFactory<T>;
 }
+/**
+ * Full document accessor with collection-level operations including creating new documents.
+ *
+ * Extends {@link LimitedFirestoreDocumentAccessor} with `newDocument()` (auto-generates an ID)
+ * and `loadDocumentForId()` (loads by document ID relative to the collection). This is the
+ * standard accessor used when you have access to the collection reference.
+ *
+ * @template T - The document data type
+ * @template D - The concrete FirestoreDocument subclass
+ */
 export interface FirestoreDocumentAccessor<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends LimitedFirestoreDocumentAccessor<T, D>, CollectionReferenceRef<T>, FirestoreAccessorDriverRef {
     readonly databaseContext: FirestoreDocumentContext<T>;
     /**
@@ -166,7 +219,10 @@ export interface FirestoreDocumentAccessor<T, D extends FirestoreDocument<T> = F
     documentRefForId(id: FirestoreModelId): DocumentReference<T>;
 }
 /**
- * Used to generate a FirestoreDocument from an input FirestoreDocumentDataAccessor instance.
+ * Factory function that creates a typed {@link FirestoreDocument} from a raw data accessor.
+ *
+ * Used by the accessor factory system to create concrete document instances (e.g., `NotificationDocument`)
+ * from their underlying accessor and document accessor context.
  */
 export type FirestoreDocumentFactoryFunction<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> = (accessor: FirestoreDocumentDataAccessor<T>, documentAccessor: LimitedFirestoreDocumentAccessor<T, D>) => D;
 /**
@@ -240,6 +296,13 @@ export interface FirestoreDocumentAccessorContextExtension<T, D extends Firestor
 }
 export declare function firestoreDocumentAccessorContextExtension<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>({ documentAccessor, firestoreAccessorDriver }: FirestoreDocumentAccessorContextExtensionConfig<T, D>): FirestoreDocumentAccessorContextExtension<T, D>;
 export declare function firestoreDocumentAccessorContextExtension<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>({ documentAccessor, firestoreAccessorDriver }: LimitedFirestoreDocumentAccessorContextExtensionConfig<T, D>): LimitedFirestoreDocumentAccessorContextExtension<T, D>;
+/**
+ * A {@link FirestoreDocument} that resides in a subcollection and provides access to its parent document reference.
+ *
+ * @template P - The parent document's data type
+ * @template T - This document's data type
+ * @template I - The model identity type
+ */
 export interface FirestoreDocumentWithParent<P, T, I extends FirestoreModelIdentity = FirestoreModelIdentity> extends FirestoreDocument<T, I> {
     readonly parent: DocumentReference<P>;
 }
@@ -247,6 +310,15 @@ export declare abstract class AbstractFirestoreDocumentWithParent<P, T, D extend
     get parent(): DocumentReference<P>;
     constructor(accessor: FirestoreDocumentDataAccessor<T>, documentAccessor: LimitedFirestoreDocumentAccessor<T, D>);
 }
+/**
+ * Accessor for collections that contain only a single known document (e.g., system state, user profile).
+ *
+ * Provides convenience methods that load the single document by its fixed identifier,
+ * supporting both transaction and write batch contexts.
+ *
+ * @template T - The document data type
+ * @template D - The concrete FirestoreDocument subclass
+ */
 export interface FirestoreSingleDocumentAccessor<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> {
     readonly singleItemIdentifier: string;
     loadDocument(): D;
@@ -259,6 +331,9 @@ export interface FirestoreSingleDocumentAccessorConfig<T, D extends FirestoreDoc
     readonly accessors: FirestoreDocumentAccessorContextExtension<T, D>;
 }
 export declare function firestoreSingleDocumentAccessor<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: FirestoreSingleDocumentAccessorConfig<T, D>): FirestoreSingleDocumentAccessor<T, D>;
+/**
+ * Default document ID used for single-document collections. The document is stored at path `<collection>/0`.
+ */
 export declare const DEFAULT_SINGLE_ITEM_FIRESTORE_COLLECTION_DOCUMENT_IDENTIFIER = "0";
 export type SingleItemFirestoreCollectionDocumentIdentifier = string;
 export interface SingleItemFirestoreCollectionDocumentIdentifierRef {

package/src/lib/common/firestore/accessor/increment.d.ts

@@ -1,10 +1,22 @@
 import { type WriteResult } from '../types';
 import { type FirestoreAccessorIncrementUpdate, type FirestoreDocumentDataAccessor } from './accessor';
+/**
+ * Function that applies an atomic increment update to a Firestore document's numeric fields.
+ *
+ * @template T - The document data type
+ */
 export type IncrementUpdateWithAccessorFunction<T> = (data: FirestoreAccessorIncrementUpdate<T>) => Promise<WriteResult | void>;
 /**
- * https://cloud.google.com/firestore/docs/samples/firestore-data-set-numeric-increment
+ * Creates a function that atomically increments numeric fields in a Firestore document.
+ *
+ * The returned function filters out falsy/empty values from the increment data and skips
+ * the update entirely if no valid fields remain. This avoids unnecessary Firestore writes.
+ *
+ * Uses Firestore's built-in atomic increment operation, which is safe for concurrent updates.
+ *
+ * @param accessor - The document accessor to perform the increment on
+ * @returns A function that applies increment updates to the document
  *
- * @param accessor
- * @returns
+ * @see https://cloud.google.com/firestore/docs/samples/firestore-data-set-numeric-increment
  */
 export declare function incrementUpdateWithAccessorFunction<T>(accessor: FirestoreDocumentDataAccessor<T>): IncrementUpdateWithAccessorFunction<T>;

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

@@ -19,11 +19,12 @@ export type FirestoreModelType = ModelTypeString;
  * An all lowercase name that references a collection. Is usually the lowercase version of the FirestoreModelType.
  *
  * This is the part of the path that identifies what the collection is. Collection names are used in
- * Firestore paths and should follow Firestore naming conventions (lowercase, no spaces).
+ * Firestore paths and should follow Firestore naming conventions (lowercase, no spaces, no special characters, since "_" is reserved/used for TwoWayFlatFirestoreModelKey).
  *
  * Each collection name in the app should be unique, as usage of CollectionGroups would cause collections
  * with the same name to be returned regardless of their location in the document hierarchy.
  *
+ *
  * @example 'u', 'ps', 'or'
  */
 export type FirestoreCollectionName = string;
@@ -494,7 +495,15 @@ export interface FirestoreModelKeyRef {
     readonly key: FirestoreModelKey;
 }
 /**
- * Instance that provides several accessors for accessing documents of a collection.
+ * Base interface for accessing documents in a Firestore collection.
+ *
+ * Combines document accessor factories, query capabilities, and iteration support into a single
+ * interface. This is the foundation for both {@link FirestoreCollection} (full access) and
+ * collection group queries (limited access without collection reference).
+ *
+ * @template T - The document data type
+ * @template D - The concrete FirestoreDocument subclass
+ * @template A - The accessor type (limited or full)
  */
 export interface FirestoreCollectionLike<T, D extends FirestoreDocument<T> = FirestoreDocument<T>, A extends LimitedFirestoreDocumentAccessor<T, D> = LimitedFirestoreDocumentAccessor<T, D>> extends FirestoreContextReference, FirestoreModelIdentityRef, QueryLikeReferenceRef<T>, FirestoreItemPageIterationFactory<T>, FirestoreQueryFactory<T>, LimitedFirestoreDocumentAccessorFactory<T, D, A>, LimitedFirestoreDocumentAccessorForTransactionFactory<T, D, A>, LimitedFirestoreDocumentAccessorForWriteBatchFactory<T, D, A>, FirestoreCollectionQueryFactory<T, D> {
 }
@@ -504,9 +513,18 @@ export interface FirestoreCollectionLike<T, D extends FirestoreDocument<T> = Fir
 export interface FirestoreCollectionConfig<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends FirestoreContextReference, FirestoreDrivers, Omit<FirestoreItemPageIterationBaseConfig<T>, 'queryLike'>, Partial<QueryLikeReferenceRef<T>>, FirestoreDocumentAccessorFactoryConfig<T, D> {
 }
 /**
- * Instance that provides several accessors for accessing documents of a collection.
+ * Full Firestore collection interface with document CRUD, querying, iteration, and context support.
+ *
+ * This is the primary interface used to interact with a Firestore collection. It provides:
+ * - **Document access**: Create, load, and manage documents via {@link FirestoreDocumentAccessor}
+ * - **Querying**: Build typed queries via the query factory
+ * - **Iteration**: Paginate through results via firestore iteration factories
+ * - **Context support**: Create accessors for transactions and write batches
+ *
+ * Created via {@link makeFirestoreCollection}.
  *
- * Provides a full FirestoreDocumentAccessor instead of limited accessors.
+ * @template T - The document data type
+ * @template D - The concrete FirestoreDocument subclass
  */
 export interface FirestoreCollection<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends FirestoreCollectionLike<T, D, FirestoreDocumentAccessor<T, D>>, CollectionReferenceRef<T>, FirestoreDocumentAccessorFactory<T, D>, FirestoreDocumentAccessorForTransactionFactory<T, D>, FirestoreDocumentAccessorForWriteBatchFactory<T, D> {
     readonly config: FirestoreCollectionConfig<T, D>;

package/src/lib/common/firestore/collection/collection.util.d.ts

@@ -3,7 +3,17 @@ import { type FirestoreModelId } from './collection';
 /**
  * Creates a valid FirestoreModelId from an email address.
  *
- * @param emailAddress
- * @returns
+ * Replaces `@` with `AAA` and strips all non-alphanumeric characters, producing an ID
+ * that satisfies Firestore's document ID constraints. This encoding is one-way; the
+ * original email cannot be recovered from the result.
+ *
+ * @param emailAddress - The email address to convert
+ * @returns A Firestore-safe document ID derived from the email
+ *
+ * @example
+ * ```ts
+ * const id = firestoreModelIdFromEmail('user@example.com');
+ * // id === 'userAAAexamplecom'
+ * ```
  */
 export declare function firestoreModelIdFromEmail(emailAddress: EmailAddress): FirestoreModelId;

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

@@ -5,14 +5,41 @@ import { type WriteBatchFirestoreDocumentContextFactory } from '../accessor/cont
 import { type TransactionFirestoreDocumentContextFactory } from '../accessor/context.transaction';
 import { type FirestoreWriteBatchFactoryDriver } from './batch';
 import { type FirestoreTransactionFactoryDriver } from './transaction';
+/**
+ * Creates a {@link CollectionGroup} reference spanning all collections with the given ID.
+ */
 export type FirestoreAccessorDriverCollectionGroupFunction = <T = DocumentData>(firestore: Firestore, collectionId: string) => CollectionGroup<T>;
+/**
+ * Creates a {@link CollectionReference} at the specified path.
+ */
 export type FirestoreAccessorDriverCollectionRefFunction = <T = DocumentData>(firestore: Firestore, path: string, ...pathSegments: string[]) => CollectionReference<T>;
+/**
+ * Creates a {@link CollectionReference} for a subcollection under the given document.
+ */
 export type FirestoreAccessorDriverSubcollectionRefFunction = <T = DocumentData>(document: DocumentReference, path: string, ...pathSegments: string[]) => CollectionReference<T>;
+/**
+ * Creates a {@link DocumentReference} within a collection, optionally at a specific path.
+ * When no path is provided, a new auto-generated document ID is used.
+ */
 export type FirestoreAccessorDriverDocumentRefFunction = <T = DocumentData>(collection: CollectionReference<T>, path?: string, ...pathSegments: string[]) => DocumentReference<T>;
+/**
+ * Creates a {@link DocumentReference} from a full slash-separated Firestore path (e.g., `'users/abc123'`).
+ */
 export type FirestoreAccessorDriverFullPathDocumentRefFunction = <T = DocumentData>(firestore: Firestore, fullPath: string) => DocumentReference<T>;
+/**
+ * Transforms collection paths, typically by appending a random suffix, to isolate concurrent
+ * test runs from each other. Only used in testing environments.
+ */
 export type FirestoreAccessorPathFuzzerFunction = (path: FirestoreCollectionName) => FirestoreCollectionName;
 /**
- * A driver to use for query functionality.
+ * Driver interface for document and collection CRUD operations.
+ *
+ * Provides factory functions for creating Firestore references (documents, collections,
+ * subcollections, collection groups) as well as context factories for standard, batch,
+ * and transaction execution modes. Platform implementations (Web SDK, Admin SDK, test mocks)
+ * each provide their own implementation of this interface.
+ *
+ * @see {@link FirestoreQueryDriver} for the complementary query execution driver
  */
 export interface FirestoreAccessorDriver extends FirestoreTransactionFactoryDriver, FirestoreWriteBatchFactoryDriver {
     readonly doc: FirestoreAccessorDriverDocumentRefFunction;

package/src/lib/common/firestore/driver/batch.d.ts

@@ -1,21 +1,23 @@
 import { type Factory } from '@dereekb/util';
 import { type Firestore, type WriteBatch } from '../types';
 /**
- * Factory for a WriteBatch.
+ * Creates a new {@link WriteBatch} for atomically committing multiple write operations.
  */
 export type WriteBatchFactory = Factory<WriteBatch>;
 /**
- * Factory for making a WriteBatchFactory for the input Firestore.
+ * Creates a {@link WriteBatchFactory} bound to the given Firestore instance.
+ * Used by the driver layer to provide batch writing capabilities per-Firestore.
  */
 export type WriteBatchForFirestoreFactory = (firestore: Firestore) => WriteBatchFactory;
 /**
- * Reference to a WriteBatchFactory.
+ * Holds a reference to a {@link WriteBatchFactory} for creating write batches.
  */
 export interface WriteBatchFactoryReference {
     readonly batch: WriteBatchFactory;
 }
 /**
- * Driver for prividing a WriteBatchForFirestoreFactory
+ * Driver component that provides {@link WriteBatch} creation for a Firestore instance.
+ * Implemented by platform-specific drivers (Web SDK, Admin SDK).
  */
 export interface FirestoreWriteBatchFactoryDriver {
     readonly writeBatchFactoryForFirestore: WriteBatchForFirestoreFactory;

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

@@ -1,9 +1,26 @@
 import { type FirestoreAccessorDriverRef } from './accessor';
 import { type FirestoreQueryDriverRef } from './query';
+/**
+ * Optional human-readable identifier for the Firestore driver (e.g., 'firebase-admin', 'firebase-web', 'testing').
+ */
 export type FirestoreDriverIdentifier = string;
+/**
+ * Indicates whether the driver targets a real Firestore instance or a test environment.
+ *
+ * Used to conditionally enable behaviors like path fuzzing in tests, or to gate
+ * production-only optimizations.
+ */
 export type FirestoreDriverType = 'production' | 'testing';
 /**
- * Implements all Firestore related driver reference interfaces.
+ * Combined driver interface that provides all Firestore operational capabilities.
+ *
+ * This is the top-level driver abstraction that platform-specific implementations
+ * (e.g., Firebase Web SDK, Firebase Admin SDK, or test mocks) must satisfy.
+ * It is consumed by {@link FirestoreContext} to wire up collection factories, query
+ * execution, batch writes, and transactions in a platform-agnostic way.
+ *
+ * @see {@link FirestoreAccessorDriver} for document/collection CRUD operations
+ * @see {@link FirestoreQueryDriver} for query execution operations
  */
 export interface FirestoreDrivers extends FirestoreQueryDriverRef, FirestoreAccessorDriverRef {
     firestoreDriverIdentifier?: FirestoreDriverIdentifier;

package/src/lib/common/firestore/driver/query.d.ts

@@ -2,15 +2,34 @@ import { type FieldPath, type SnapshotListenOptions, type Transaction, type Quer
 import { type Observable } from 'rxjs';
 import { type FirestoreQueryConstraint } from '../query/constraint';
 import { type Maybe } from '@dereekb/util';
+/**
+ * Applies query constraints to a base query and returns the constrained query.
+ */
 export type FirestoreQueryDriverQueryFunction = <T>(query: Query<T>, ...queryConstraints: FirestoreQueryConstraint[]) => Query<T>;
+/**
+ * Returns the platform-specific {@link FieldPath} sentinel for the document ID.
+ * Used internally by `whereDocumentId()` constraints.
+ */
 export type FirestoreDocumentIdFieldPathAccessor = () => FieldPath;
+/**
+ * Low-level driver for building queries from constraint objects.
+ *
+ * Tracks which constraint types (where, orderBy, limit, etc.) the current platform
+ * supports and provides the function to apply them to a query.
+ */
 export interface FirestoreQueryConstraintFunctionsDriver {
     readonly availableConstraintTypes: Set<string>;
     readonly query: FirestoreQueryDriverQueryFunction;
     readonly documentIdFieldPath: FirestoreDocumentIdFieldPathAccessor;
 }
 /**
- * A driver to use for query functionality.
+ * Driver interface for executing Firestore queries.
+ *
+ * Extends {@link FirestoreQueryConstraintFunctionsDriver} with methods for counting,
+ * fetching, and streaming query results. Platform implementations (Web SDK, Admin SDK,
+ * test mocks) each provide their own implementation.
+ *
+ * @see {@link FirestoreAccessorDriver} for the complementary document CRUD driver
  */
 export interface FirestoreQueryDriver extends FirestoreQueryConstraintFunctionsDriver {
     /**

package/src/lib/common/firestore/driver/query.handler.d.ts

@@ -1,9 +1,32 @@
 import { type Query } from '../types';
 import { type FirestoreQueryConstraintHandlerMap } from '../query/constraint';
 import { type FirestoreQueryConstraintFunctionsDriver } from './query';
+/**
+ * Configuration for building a {@link FirestoreQueryConstraintFunctionsDriver} from a
+ * handler map pattern. Each platform (Web SDK, Admin SDK) provides its own handler map
+ * that maps constraint type strings to builder functions.
+ *
+ * @template B - The platform-specific query builder type (e.g., the Firestore Query itself)
+ */
 export interface MakeFirestoreQueryConstraintFunctionsDriver<B> extends Omit<FirestoreQueryConstraintFunctionsDriver, 'query' | 'availableConstraintTypes'> {
+    /** Maps constraint type names to handler functions that apply them to the builder. */
     mapping: FirestoreQueryConstraintHandlerMap<B>;
+    /** Initializes a builder from a base query. */
     init: <T>(query: Query<T>) => B;
+    /** Converts the finalized builder back to a query. */
     build: <T>(builder: B) => Query<T>;
 }
+/**
+ * Creates a {@link FirestoreQueryConstraintFunctionsDriver} from a handler map configuration.
+ *
+ * This factory enables platform-specific query implementations to register their constraint
+ * handlers declaratively. The returned driver applies constraints sequentially using the
+ * registered handlers and throws if an unsupported constraint type is encountered.
+ *
+ * @template B - The platform-specific query builder type
+ * @param config - The handler map configuration
+ * @returns A fully configured constraint functions driver
+ *
+ * @throws {Error} When a query uses a constraint type not present in the handler map
+ */
 export declare function makeFirestoreQueryConstraintFunctionsDriver<B>(config: MakeFirestoreQueryConstraintFunctionsDriver<B>): FirestoreQueryConstraintFunctionsDriver;

package/src/lib/common/firestore/driver/transaction.d.ts

@@ -1,25 +1,37 @@
 import { type Firestore, type Transaction, type ReadOnlyTransactionOptions, type ReadWriteTransactionOptions } from '../types';
 /**
- * Function that runs in a transaction context and returns a value.
+ * Function that executes within a Firestore transaction context and returns a result.
+ *
+ * @template T - The return type of the transaction
  */
 export type TransactionFunction<T = unknown> = (transaction: Transaction) => Promise<T>;
 /**
- * Factory for running transactions. Creates a new Transaction, runs it with the input TransactionFunction, and returns the result.
+ * Executes a Firestore transaction by creating a new {@link Transaction}, running the provided
+ * function within it, and returning the result. Handles retries automatically on contention.
  *
- * All transactions require a read. The read should occur before any writes occur. Not reading within a Transaction can leave
- * the transaction in a bad state. (It also defeats the idempotent purpose of transactions!)
+ * **Important:** All transactions must include at least one read before any writes.
+ * Omitting reads can leave the transaction in a bad state and defeats the idempotent
+ * purpose of transactions.
  */
 export type RunTransaction = <T>(fn: TransactionFunction<T>, options?: RunTransactionParams) => Promise<T>;
+/**
+ * Options for controlling transaction behavior — either read-only or read-write.
+ */
 export type RunTransactionParams = ReadOnlyTransactionOptions | ReadWriteTransactionOptions;
 /**
- * Factory for making a RunTransactionFunction for the input Firestore.
+ * Creates a {@link RunTransaction} function bound to the given Firestore instance.
+ * Used by the driver layer to provide transaction capabilities per-Firestore.
  */
 export type RunTransactionForFirestoreFactory = (firestore: Firestore) => RunTransaction;
+/**
+ * Holds a reference to a {@link RunTransaction} function for executing transactions.
+ */
 export interface RunTransactionFactoryReference {
     readonly runTransaction: RunTransaction;
 }
 /**
- * Driver for prividing a RunTransactionForFirestoreFactory
+ * Driver component that provides {@link Transaction} execution for a Firestore instance.
+ * Implemented by platform-specific drivers (Web SDK, Admin SDK).
  */
 export interface FirestoreTransactionFactoryDriver {
     readonly transactionFactoryForFirestore: RunTransactionForFirestoreFactory;