@dereekb/firebase 11.1.7 → 12.0.0

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

@@ -6,48 +6,208 @@ import { type FirestoreQueryConstraint } from '../query/constraint';
 import { type Transaction } from '../types';
 import { type Observable } from 'rxjs';
 import { type FirestoreDocumentSnapshotDataPairWithData } from '../accessor';
+/**
+ * An executable Firestore query that returns typed document objects.
+ *
+ * This interface extends the basic FirestoreExecutableQuery with methods that automatically
+ * convert Firestore document snapshots to fully-typed application model objects. It provides
+ * a fluent API for querying collections and processing the results as either Promises or
+ * Observables.
+ *
+ * @template T - The data type of the documents
+ * @template D - The FirestoreDocument type that wraps the data
+ *
+ * @example
+ * // Create a query for active users created in the last 30 days
+ * const recentActiveUsers = usersCollection.queryDocument(
+ *   where('status', '==', 'active'),
+ *   where('createdAt', '>=', thirtyDaysAgo)
+ * );
+ *
+ * // Get all matching users
+ * const users = await recentActiveUsers.getDocs();
+ *
+ * // Or stream updates in real-time
+ * recentActiveUsers.streamDocs().subscribe(users => {
+ *   console.log('Active users updated:', users);
+ * });
+ */
 export interface FirestoreCollectionExecutableDocumentQuery<T, D extends FirestoreDocument<T>> {
+    /**
+     * The underlying base query that this document query wraps.
+     * This gives access to the raw Firestore query functionality if needed.
+     */
     readonly baseQuery: FirestoreExecutableQuery<T>;
     /**
-     * Returns the number of result documents.
+     * Returns the total number of documents that match this query.
+     *
+     * This is useful for pagination or checking if results exist without
+     * retrieving the full documents.
+     *
+     * @returns A promise that resolves to the count of matching documents
      */
     countDocs(): Promise<number>;
     /**
      * Limits the results to a single document, then returns that first/single document if it exists.
+     *
+     * This is a convenience method for queries where you expect a single result or
+     * are only interested in the first match.
+     *
+     * @param transaction - Optional transaction to perform this operation in
+     * @returns A promise that resolves to the first matching document or undefined if none exists
      */
     getFirstDoc(transaction?: Transaction): Promise<Maybe<D>>;
     /**
-     * Limits the results to a single document, then returns that first/single FirestoreDocumentSnapshotDataPair for the document if it exists.
+     * Limits the results to a single document, then returns that first/single
+     * FirestoreDocumentSnapshotDataPair for the document if it exists.
+     *
+     * This provides both the document snapshot and converted data object,
+     * giving access to metadata like create/update times while still having
+     * the typed document data.
+     *
+     * @param transaction - Optional transaction to perform this operation in
+     * @returns A promise that resolves to the first matching document pair or undefined if none exists
      */
     getFirstDocSnapshotDataPair(transaction?: Transaction): Promise<Maybe<FirestoreDocumentSnapshotDataPairWithData<D>>>;
     /**
-     * Returns the results in a Promise.
+     * Returns all matching documents as a Promise of document array.
+     *
+     * This retrieves all documents matching the query constraints and converts
+     * them to the appropriate document model type.
+     *
+     * @param transaction - Optional transaction to perform this operation in
+     * @returns A promise that resolves to an array of typed documents
      */
     getDocs(transaction?: Transaction): Promise<D[]>;
     /**
-     * Returns the FirestoreDocumentSnapshotDataPairs results in a Promise.
+     * Returns all matching documents as a Promise of document snapshot data pairs.
+     *
+     * This retrieves all documents matching the query constraints and provides both
+     * the raw snapshots and converted document models, useful when you need access
+     * to metadata like create/update times.
+     *
+     * @param transaction - Optional transaction to perform this operation in
+     * @returns A promise that resolves to an array of document snapshot data pairs
      */
     getDocSnapshotDataPairs(transaction?: Transaction): Promise<FirestoreDocumentSnapshotDataPairWithData<D>[]>;
     /**
-     * Streams the results as an Observable.
+     * Streams the query results as an Observable that emits whenever the query results change.
+     *
+     * This sets up a real-time listener for the query and automatically converts
+     * snapshots to typed document models. The Observable emits the complete result set
+     * each time any document in the set changes.
+     *
+     * @returns An Observable that emits arrays of typed documents
      */
     streamDocs(): Observable<D[]>;
     /**
-     * Streams the FirestoreDocumentSnapshotDataPair results as an Observable.
+     * Streams the query results as an Observable of document snapshot data pairs.
+     *
+     * Similar to streamDocs(), but provides both the raw snapshots and converted document
+     * models, giving access to metadata while maintaining type safety.
+     *
+     * @returns An Observable that emits arrays of document snapshot data pairs
      */
     streamDocSnapshotDataPairs(): Observable<FirestoreDocumentSnapshotDataPairWithData<D>[]>;
     /**
-     * Extend this query by adding additional filters.
+     * Extends this query by adding additional filters or constraints.
+     *
+     * This enables fluent composition of queries by adding constraints incrementally.
+     * It returns a new query instance with the combined constraints of the original
+     * query plus the new ones.
+     *
+     * @param queryConstraints - One or more query constraints to apply
+     * @returns A new query with the additional constraints applied
+     *
+     * @example
+     * // Start with a basic query
+     * let query = usersCollection.queryDocument();
      *
-     * @param queryConstraints
+     * // Add filters conditionally
+     * if (filterByStatus) {
+     *   query = query.filter(where('status', '==', selectedStatus));
+     * }
+     *
+     * // Add more constraints and execute
+     * const result = await query
+     *   .filter(orderBy('createdAt', 'desc'))
+     *   .filter(limit(10))
+     *   .getDocs();
      */
     filter(...queryConstraints: ArrayOrValue<FirestoreQueryConstraint>[]): FirestoreCollectionExecutableDocumentQuery<T, D>;
 }
 /**
  * Creates a new FirestoreExecutableQuery from the input constraints for a FirestoreDocument.
+ *
+ * This factory function type creates document-aware queries by applying constraints and
+ * returning an executable query that handles document conversion automatically.
+ *
+ * @template T - The data type of the documents
+ * @template D - The FirestoreDocument type that wraps the data
+ *
+ * @param queryConstraints - Zero or more constraints to apply to the query
+ * @returns An executable document query configured with the specified constraints
+ *
+ * @example
+ * // Type definition of the query factory function
+ * const queryUsers: FirestoreCollectionQueryFactoryFunction<UserData, UserDocument> =
+ *   usersCollection.queryDocument;
+ *
+ * // Using the factory function to create a query
+ * const activeUsersQuery = queryUsers(where('status', '==', 'active'));
  */
 export type FirestoreCollectionQueryFactoryFunction<T, D extends FirestoreDocument<T>> = (...queryConstraints: ArrayOrValue<FirestoreQueryConstraint>[]) => FirestoreCollectionExecutableDocumentQuery<T, D>;
+/**
+ * Factory for creating document-aware Firestore queries for a collection.
+ *
+ * This interface provides access to query factory functions that create executable
+ * queries that automatically convert Firestore snapshots to typed document models.
+ *
+ * @template T - The data type of the documents
+ * @template D - The FirestoreDocument type that wraps the data
+ *
+ * @example
+ * // A collection with a query factory
+ * const usersCollection: FirestoreCollection<UserData, UserDocument> = makeFirestoreCollection({
+ *   collectionPath: 'users',
+ *   converter: userConverter
+ * });
+ *
+ * // Use the factory to create a query
+ * const activeUsersQuery = usersCollection.queryFactory.queryDocument(
+ *   where('status', '==', 'active')
+ * );
+ */
 export interface FirestoreCollectionQueryFactory<T, D extends FirestoreDocument<T>> {
+    /**
+     * Factory function for creating document queries with optional constraints.
+     * This is the primary method for creating typed queries against a collection.
+     */
     readonly queryDocument: FirestoreCollectionQueryFactoryFunction<T, D>;
 }
+/**
+ * Creates a query factory for Firestore collections that automatically handles document conversion.
+ *
+ * This factory function bridges the gap between raw Firestore queries and typed document models
+ * by wrapping standard query operations with document loading capabilities. It transforms
+ * query results from raw Firestore snapshots into fully-typed document model instances.
+ *
+ * @template T - The data type of the documents
+ * @template D - The FirestoreDocument type that wraps the data
+ * @param queryFactory - The base query factory for creating raw Firestore queries
+ * @param accessorContext - The document accessor context for loading and converting documents
+ * @returns A collection query factory for creating document-aware queries
+ *
+ * @example
+ * // Creating a collection query factory
+ * const userQueryFactory = firestoreCollectionQueryFactory(
+ *   userQueryFactory,  // Base query factory
+ *   userAccessorContext  // Document accessor context
+ * );
+ *
+ * // Using the factory to create and execute a query
+ * const activeUsers = await userQueryFactory
+ *   .queryDocument(where('status', '==', 'active'))
+ *   .getDocs();
+ */
 export declare function firestoreCollectionQueryFactory<T, D extends FirestoreDocument<T>>(queryFactory: FirestoreQueryFactory<T>, accessorContext: LimitedFirestoreDocumentAccessorContextExtension<T, D>): FirestoreCollectionQueryFactory<T, D>;

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

@@ -1,7 +1,40 @@
 import { type FirestoreDocument, type FirestoreSingleDocumentAccessor, type SingleItemFirestoreCollectionDocumentIdentifierRef } from '../accessor/document';
 import { type FirestoreCollection, type FirestoreCollectionConfig } from './collection';
+/**
+ * Configuration for creating a root-level collection that focuses on a single document.
+ *
+ * This configuration extends the standard FirestoreCollectionConfig with optional
+ * settings for specifying a single document identifier. This is used when you need
+ * to work with a specific document in a collection, such as configuration or settings.
+ *
+ * @template T - The data type of the document
+ * @template D - The FirestoreDocument type, defaults to FirestoreDocument<T>
+ */
 export interface RootSingleItemFirestoreCollectionConfig<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends FirestoreCollectionConfig<T, D>, Partial<SingleItemFirestoreCollectionDocumentIdentifierRef> {
 }
+/**
+ * A Firestore collection that provides specialized accessors for working with a single document.
+ *
+ * This interface combines the capabilities of a standard FirestoreCollection with
+ * FirestoreSingleDocumentAccessor, providing convenient methods for working directly
+ * with a single document without needing to specify its ID in each call.
+ *
+ * @template T - The data type of the document
+ * @template D - The FirestoreDocument type, defaults to FirestoreDocument<T>
+ */
 export interface RootSingleItemFirestoreCollection<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends FirestoreCollection<T, D>, FirestoreSingleDocumentAccessor<T, D> {
 }
+/**
+ * Creates a root-level Firestore collection focused on a single document.
+ *
+ * This factory function creates a specialized collection that combines standard collection
+ * functionality with convenient accessors for working with a single document. It's particularly
+ * useful for application settings, configuration, or any singleton-like data structures
+ * that are stored in Firestore.
+ *
+ * @template T - The data type of the document
+ * @template D - The FirestoreDocument type, defaults to FirestoreDocument<T>
+ * @param config - Configuration for the single document collection
+ * @returns A RootSingleItemFirestoreCollection instance configured for the specified document
+ */
 export declare function makeRootSingleItemFirestoreCollection<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: RootSingleItemFirestoreCollectionConfig<T, D>): RootSingleItemFirestoreCollection<T, D>;

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

@@ -1,25 +1,90 @@
+/**
+ * @module Firestore Subcollections
+ *
+ * This module provides utilities for working with Firestore subcollections - collections that exist
+ * within a specific document rather than at the root level. Subcollections enable hierarchical
+ * data modeling in Firestore by allowing documents to contain their own collections.
+ *
+ * Key features of subcollections:
+ * - They provide a natural way to model hierarchical relationships
+ * - They establish clear ownership boundaries (parent document owns child documents)
+ * - They enable more granular security rules (access to child documents can depend on parent)
+ * - They support efficient querying within the context of a specific parent
+ *
+ * Example hierarchy in Firestore paths:
+ * - users/{userId} (parent document)
+ * - users/{userId}/posts/{postId} (document in subcollection)
+ * - users/{userId}/posts/{postId}/comments/{commentId} (nested subcollection)
+ */
 import { type FirestoreDocument } from '../accessor/document';
 import { type FirestoreCollection, type FirestoreCollectionConfig } from './collection';
 /**
- * Used for collections that are a subcollection of a document.
+ * Configuration for a Firestore subcollection that maintains a reference to its parent document.
+ *
+ * This configuration extends the standard FirestoreCollectionConfig with a reference to the
+ * parent document, establishing a parent-child relationship between documents in different
+ * collections. This relationship is used for building proper collection paths and maintaining
+ * the document hierarchy.
+ *
+ * @template T - The data type of documents in the subcollection
+ * @template PT - The data type of the parent document
+ * @template D - The document type for documents in the subcollection, defaults to FirestoreDocument<T>
+ * @template PD - The document type for the parent document, defaults to FirestoreDocument<PT>
  */
 export interface FirestoreCollectionWithParentConfig<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>> extends FirestoreCollectionConfig<T, D> {
     /**
-     * The parent document.
+     * The parent document that contains this subcollection.
+     * This reference establishes the hierarchical relationship and is used for path construction
+     * and maintaining the document hierarchy context.
      */
     readonly parent: PD;
 }
 /**
- * A FirestoreCollection as a reference to a Subcollection.
+ * A FirestoreCollection that represents a subcollection with a reference to its parent document.
+ *
+ * This interface extends FirestoreCollection to maintain the parent-child relationship
+ * between documents. It allows access to documents within the context of their parent,
+ * enabling proper path construction and maintaining the document hierarchy.
+ *
+ * @template T - The data type of documents in the subcollection
+ * @template PT - The data type of the parent document
+ * @template D - The document type for documents in the subcollection, defaults to FirestoreDocument<T>
+ * @template PD - The document type for the parent document, defaults to FirestoreDocument<PT>
  */
 export interface FirestoreCollectionWithParent<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>> extends FirestoreCollection<T, D> {
+    /**
+     * Reference to the parent document that contains this subcollection.
+     * This allows navigation up the document hierarchy and provides context
+     * for the subcollection's position in the data model.
+     */
     readonly parent: PD;
 }
 /**
- * A FirestoreCollectionWithParent factory type.
+ * A factory function type for creating subcollection instances for a given parent document.
+ *
+ * This type defines a function that creates a subcollection instance when given a parent document.
+ * It's useful for establishing reusable patterns for accessing subcollections across different
+ * parent documents of the same type.
+ *
+ * @template T - The data type of documents in the subcollection
+ * @template PT - The data type of the parent document
+ * @template D - The document type for documents in the subcollection, defaults to FirestoreDocument<T>
+ * @template PD - The document type for the parent document, defaults to FirestoreDocument<PT>
+ * @template C - The specific subcollection type to return, defaults to FirestoreCollectionWithParent<T, PT, D, PD>
  */
 export type FirestoreCollectionWithParentFactory<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>, C extends FirestoreCollectionWithParent<T, PT, D, PD> = FirestoreCollectionWithParent<T, PT, D, PD>> = (parent: PD) => C;
 /**
- * Creates a new FirestoreCollectionWithParent from the input config.
+ * Creates a new subcollection instance with a reference to its parent document.
+ *
+ * This factory function creates a subcollection that maintains its relationship to a
+ * parent document. The subcollection inherits all the capabilities of a standard
+ * collection while also providing access to its parent document context.
+ *
+ * @template T - The data type of documents in the subcollection
+ * @template PT - The data type of the parent document
+ * @template D - The document type for documents in the subcollection, defaults to FirestoreDocument<T>
+ * @template PD - The document type for the parent document, defaults to FirestoreDocument<PT>
+ * @param config - Configuration for the subcollection, including the parent document reference
+ * @returns A subcollection instance linked to the specified parent document
  */
 export declare function makeFirestoreCollectionWithParent<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>>(config: FirestoreCollectionWithParentConfig<T, PT, D, PD>): FirestoreCollectionWithParent<T, PT, D, PD>;

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

@@ -1,7 +1,47 @@
 import { type FirestoreDocument, type FirestoreSingleDocumentAccessor, type SingleItemFirestoreCollectionDocumentIdentifierRef } from '../accessor/document';
 import { type FirestoreCollectionWithParent, type FirestoreCollectionWithParentConfig } from './subcollection';
+/**
+ * Configuration for a subcollection that focuses on a single document within a parent document.
+ *
+ * This configuration extends FirestoreCollectionWithParentConfig with an optional
+ * specification for a single document identifier. It combines the hierarchical relationship
+ * of subcollections with the focused access of single document collections.
+ *
+ * @template T - The data type of the subcollection document
+ * @template PT - The data type of the parent document
+ * @template D - The document type for the subcollection document, defaults to FirestoreDocument<T>
+ * @template PD - The document type for the parent document, defaults to FirestoreDocument<PT>
+ */
 export interface SingleItemFirestoreCollectionConfig<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>> extends FirestoreCollectionWithParentConfig<T, PT, D, PD>, Partial<SingleItemFirestoreCollectionDocumentIdentifierRef> {
 }
+/**
+ * A subcollection that provides specialized accessors for working with a single document
+ * within a parent document context.
+ *
+ * This interface combines the capabilities of FirestoreCollectionWithParent (which maintains
+ * the parent-child relationship) with FirestoreSingleDocumentAccessor (which provides
+ * convenient methods for working with a specific document). This allows for direct access
+ * to a known document within the subcollection without needing to specify its ID in each call.
+ *
+ * @template T - The data type of the subcollection document
+ * @template PT - The data type of the parent document
+ * @template D - The document type for the subcollection document, defaults to FirestoreDocument<T>
+ * @template PD - The document type for the parent document, defaults to FirestoreDocument<PT>
+ */
 export interface SingleItemFirestoreCollection<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>> extends FirestoreCollectionWithParent<T, PT, D, PD>, FirestoreSingleDocumentAccessor<T, D> {
 }
+/**
+ * Creates a subcollection that focuses on a single document within a parent document context.
+ *
+ * This factory function creates a subcollection with specialized accessors for working with
+ * a specific document. It combines the hierarchical relationship of parent-child documents
+ * with the convenience of direct access to a single, known document in the subcollection.
+ *
+ * @template T - The data type of the subcollection document
+ * @template PT - The data type of the parent document
+ * @template D - The document type for the subcollection document, defaults to FirestoreDocument<T>
+ * @template PD - The document type for the parent document, defaults to FirestoreDocument<PT>
+ * @param config - Configuration for the single document subcollection
+ * @returns A subcollection instance with specialized accessors for the single document
+ */
 export declare function makeSingleItemFirestoreCollection<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>>(config: SingleItemFirestoreCollectionConfig<T, PT, D, PD>): SingleItemFirestoreCollection<T, PT, D, PD>;

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

@@ -5,37 +5,186 @@ import { type WriteBatchFactoryReference, type RunTransactionFactoryReference }
 import { type DocumentReference, type CollectionReference, type DocumentData, type Firestore, type CollectionGroup } from './types';
 import { type QueryLikeReferenceRef } from './reference';
 /**
- * A @dereekb/firebase FirestoreContext. Wraps the main Firestore context and the drivers, as well as utility/convenience functions.
+ * A high-level context for Firestore operations that wraps the Firestore instance and its drivers.
+ *
+ * This context provides a unified interface for working with Firestore, offering convenience methods
+ * for accessing collections, creating documents, and managing transactions and batches. It serves as
+ * the main entry point for Firestore operations throughout the application.
+ *
+ * The context abstracts away the low-level Firestore implementation details, offering type-safe
+ * methods for creating various collection types (standard, group, with parent, single-item) and
+ * managing document operations within different execution contexts (standard, transaction, batch).
+ *
+ * @template F - The Firestore implementation type (defaults to standard Firestore)
  */
 export interface FirestoreContext<F extends Firestore = Firestore> extends RunTransactionFactoryReference, WriteBatchFactoryReference {
+    /**
+     * The underlying Firestore instance.
+     */
     readonly firestore: F;
+    /**
+     * The Firestore drivers used by this context.
+     * Contains implementations for queries, accessories, and other Firestore operations.
+     */
     readonly drivers: FirestoreDrivers;
+    /**
+     * Gets a reference to a collection at the specified path.
+     *
+     * @template T - The document data type in the collection
+     * @param path - The initial path segment
+     * @param pathSegments - Additional path segments
+     * @returns A reference to the specified collection
+     */
     collection<T = DocumentData>(path: string, ...pathSegments: string[]): CollectionReference<T>;
+    /**
+     * Gets a query for all documents in collections with the specified ID.
+     *
+     * @template T - The document data type in the collection group
+     * @param collectionId - The collection ID to query across all document paths
+     * @returns A query across all collections with the given ID
+     */
     collectionGroup<T = DocumentData>(collectionId: string): CollectionGroup<T>;
+    /**
+     * Gets a reference to a subcollection within a document.
+     *
+     * @template T - The document data type in the subcollection
+     * @param parent - The parent document reference
+     * @param path - The initial path segment
+     * @param pathSegments - Additional path segments
+     * @returns A reference to the specified subcollection
+     */
     subcollection<T = DocumentData>(parent: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference<T>;
+    /**
+     * Creates a FirestoreCollection for working with documents in a collection.
+     *
+     * @template T - The document data type
+     * @template D - The FirestoreDocument implementation type
+     * @param config - Configuration for the collection
+     * @returns A FirestoreCollection instance for the specified collection
+     */
     firestoreCollection<T, D extends FirestoreDocument<T>>(config: FirestoreContextFirestoreCollectionConfig<T, D>): FirestoreCollection<T, D>;
+    /**
+     * Creates a RootSingleItemFirestoreCollection for working with a single document in a collection.
+     *
+     * @template T - The document data type
+     * @template D - The FirestoreDocument implementation type
+     * @param config - Configuration for the collection
+     * @returns A RootSingleItemFirestoreCollection instance
+     */
     rootSingleItemFirestoreCollection<T, D extends FirestoreDocument<T>>(config: FirestoreContextFirestoreCollectionConfig<T, D>): RootSingleItemFirestoreCollection<T, D>;
+    /**
+     * Creates a FirestoreCollectionGroup for working with documents across collections with the same ID.
+     *
+     * @template T - The document data type
+     * @template D - The FirestoreDocument implementation type
+     * @param config - Configuration for the collection group
+     * @returns A FirestoreCollectionGroup instance for the specified collection ID
+     */
     firestoreCollectionGroup<T, D extends FirestoreDocument<T>>(config: FirestoreContextFirestoreCollectionGroupConfig<T, D>): FirestoreCollectionGroup<T, D>;
+    /**
+     * Creates a FirestoreCollectionWithParent for working with documents in a subcollection.
+     *
+     * @template T - The document data type
+     * @template PT - The parent document data type
+     * @template D - The FirestoreDocument implementation type
+     * @template PD - The parent FirestoreDocument implementation type
+     * @param config - Configuration for the collection with parent
+     * @returns A FirestoreCollectionWithParent instance for the specified subcollection
+     */
     firestoreCollectionWithParent<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>>(config: FirestoreContextFirestoreCollectionWithParentConfig<T, PT, D, PD>): FirestoreCollectionWithParent<T, PT, D, PD>;
+    /**
+     * Creates a SingleItemFirestoreCollection for working with a single document in a subcollection.
+     *
+     * @template T - The document data type
+     * @template PT - The parent document data type
+     * @template D - The FirestoreDocument implementation type
+     * @template PD - The parent FirestoreDocument implementation type
+     * @param config - Configuration for the single-item collection
+     * @returns A SingleItemFirestoreCollection instance for the specified document
+     */
     singleItemFirestoreCollection<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>>(config: FirestoreContextSingleItemFirestoreCollectionConfig<T, PT, D, PD>): SingleItemFirestoreCollection<T, PT, D, PD>;
 }
+/**
+ * Configuration for creating a FirestoreCollection through a FirestoreContext.
+ *
+ * This type omits driver-related properties from FirestoreCollectionConfig since they will be
+ * automatically provided by the FirestoreContext when creating the collection.
+ *
+ * @template T - The document data type in the collection
+ * @template D - The FirestoreDocument implementation type
+ */
 export type FirestoreContextFirestoreCollectionConfig<T, D extends FirestoreDocument<T>> = Omit<FirestoreCollectionConfig<T, D>, 'firestoreDriverIdentifier' | 'firestoreDriverType' | 'firestoreQueryDriver' | 'firestoreAccessorDriver'>;
+/**
+ * Configuration for creating a RootSingleItemFirestoreCollection through a FirestoreContext.
+ *
+ * This configuration extends the standard collection config and optionally allows specifying
+ * a custom document identifier for the single item in the collection.
+ *
+ * @template T - The document data type
+ * @template D - The FirestoreDocument implementation type
+ */
 export interface FirestoreContextRootSingleItemFirestoreCollectionConfig<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends FirestoreContextFirestoreCollectionConfig<T, D>, Partial<SingleItemFirestoreCollectionDocumentIdentifierRef> {
 }
+/**
+ * Configuration for creating a FirestoreCollectionGroup through a FirestoreContext.
+ *
+ * Unlike standard collection configurations, collection group configs use a queryLike reference
+ * instead of a collection reference since they span multiple collections with the same ID.
+ *
+ * @template T - The document data type in the collection group
+ * @template D - The FirestoreDocument implementation type
+ */
 export type FirestoreContextFirestoreCollectionGroupConfig<T, D extends FirestoreDocument<T>> = Omit<FirestoreContextFirestoreCollectionConfig<T, D>, 'collection'> & QueryLikeReferenceRef<T>;
+/**
+ * Configuration for creating a FirestoreCollectionWithParent through a FirestoreContext.
+ *
+ * This configuration extends the standard collection config but uses a parent document reference
+ * instead of a direct collection reference, enabling access to subcollections within documents.
+ *
+ * @template T - The document data type in the subcollection
+ * @template PT - The parent document data type
+ * @template D - The FirestoreDocument implementation type for subcollection documents
+ * @template PD - The FirestoreDocument implementation type for the parent document
+ */
 export interface FirestoreContextFirestoreCollectionWithParentConfig<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>> extends Omit<FirestoreContextFirestoreCollectionConfig<T, D>, 'queryLike'> {
+    /**
+     * The parent document that contains the subcollection.
+     */
     readonly parent: PD;
 }
+/**
+ * Configuration for creating a SingleItemFirestoreCollection through a FirestoreContext.
+ *
+ * This configuration extends the collection with parent config and optionally allows specifying
+ * a custom document identifier for the single item in the subcollection.
+ *
+ * @template T - The document data type in the subcollection
+ * @template PT - The parent document data type
+ * @template D - The FirestoreDocument implementation type for subcollection documents
+ * @template PD - The FirestoreDocument implementation type for the parent document
+ */
 export interface FirestoreContextSingleItemFirestoreCollectionConfig<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>> extends FirestoreContextFirestoreCollectionWithParentConfig<T, PT, D, PD>, Partial<SingleItemFirestoreCollectionDocumentIdentifierRef> {
 }
 /**
- * Factory function for generating a FirestoreContext given the input Firestore.
+ * Factory function type for creating FirestoreContext instances.
+ *
+ * Takes a Firestore instance and returns a fully configured FirestoreContext that wraps
+ * the instance and provides additional functionality through the context interface.
+ *
+ * @template F - The Firestore implementation type
+ * @param firestore - The Firestore instance to wrap
+ * @returns A FirestoreContext instance for the specified Firestore
  */
 export type FirestoreContextFactory<F extends Firestore = Firestore> = (firestore: F) => FirestoreContext;
 /**
- * Creates a new FirestoreContextFactory given the input FirestoreDrivers.
+ * Creates a factory function for generating FirestoreContext instances.
+ *
+ * This function takes a set of FirestoreDrivers and returns a factory function that can
+ * create FirestoreContext instances for specific Firestore instances. The resulting contexts
+ * will use the provided drivers for all Firestore operations.
  *
- * @param drivers
- * @returns
+ * @template F - The Firestore implementation type
+ * @param drivers - The Firestore drivers to use in created contexts
+ * @returns A factory function that creates FirestoreContext instances
  */
 export declare function firestoreContextFactory<F extends Firestore = Firestore>(drivers: FirestoreDrivers): FirestoreContextFactory<F>;