@dereekb/firebase 11.1.8 → 12.0.0

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

@@ -1,53 +1,162 @@
+/**
+ * @module Firestore Query
+ *
+ * This module provides core functionality for creating and executing Firestore queries,
+ * with a fluent interface for extending queries with additional constraints.
+ */
 import { type Observable } from 'rxjs';
 import { type ArrayOrValue, type Maybe } from '@dereekb/util';
 import { type QueryLikeReferenceRef } from '../reference';
 import { type Query, type QueryDocumentSnapshot, type QuerySnapshot, type Transaction } from '../types';
 import { type FirestoreQueryConstraint } from './constraint';
 import { type FirestoreQueryDriverRef } from '../driver/query';
+/**
+ * Context for executing a Firestore query.
+ *
+ * This interface allows specifying optional parameters when executing a query,
+ * such as a transaction to run the query within.
+ */
 export interface FirestoreExecutableQueryGetDocsContext {
+    /**
+     * Optional transaction to run the query within.
+     *
+     * When provided, the query will be executed as part of the transaction,
+     * ensuring consistency with other operations in the same transaction.
+     */
     readonly transaction?: Transaction;
 }
 /**
- * Immutable wrapper of a query and a way to retrieve the docs.
+ * Immutable wrapper of a Firestore query with methods to execute and extend it.
+ *
+ * This interface provides a fluent API for working with Firestore queries,
+ * allowing them to be executed in various ways (count, get, stream) and
+ * extended with additional constraints through the filter method.
+ *
+ * @template T - The document data type in the query results
  */
 export interface FirestoreExecutableQuery<T> {
+    /**
+     * The underlying Firestore query object.
+     */
     readonly query: Query<T>;
     /**
-     * Returns the number of matching documents.
+     * Returns the count of documents that match the query.
+     *
+     * This method efficiently counts matching documents without retrieving their contents.
+     *
+     * @returns A promise that resolves with the number of matching documents
      */
     countDocs(): Promise<number>;
     /**
-     * Limits the results to a single document, then returns that first/single document if it exists.
+     * Retrieves the first document matching the query, if any exists.
+     *
+     * This method optimizes the query by adding a limit(1) constraint before execution.
+     *
+     * @param transaction - Optional transaction to execute the query within
+     * @returns A promise that resolves with the first matching document snapshot, or undefined if none exist
      */
     getFirstDoc(transaction?: Transaction): Promise<Maybe<QueryDocumentSnapshot<T>>>;
     /**
-     * Returns the results in a Promise.
+     * Executes the query and returns all matching documents.
+     *
+     * @param transaction - Optional transaction to execute the query within
+     * @returns A promise that resolves with a snapshot containing all matching documents
      */
     getDocs(transaction?: Transaction): Promise<QuerySnapshot<T>>;
     /**
-     * Streams the results as an Observable.
+     * Creates an Observable that streams query results in real-time.
+     *
+     * This method establishes a listener that emits a new snapshot whenever
+     * any of the matching documents change.
+     *
+     * @returns An Observable that emits query snapshots when documents change
      */
     streamDocs(): Observable<QuerySnapshot<T>>;
     /**
-     * Extend this query by adding additional filters.
+     * Creates a new query by adding more constraints to this query.
      *
-     * @param queryConstraints
+     * This method creates a new FirestoreExecutableQuery with the additional constraints
+     * applied, preserving the immutability of the original query.
+     *
+     * @param queryConstraints - Additional constraints to apply to the query
+     * @returns A new FirestoreExecutableQuery with the combined constraints
+     *
+     * @example
+     * const baseQuery = queryFactory.query();
+     * const filteredQuery = baseQuery.filter(
+     *   where('status', '==', 'active'),
+     *   orderBy('createdAt', 'desc')
+     * );
      */
     filter(...queryConstraints: ArrayOrValue<FirestoreQueryConstraint>[]): FirestoreExecutableQuery<T>;
 }
+/**
+ * Function that creates a FirestoreExecutableQuery with the specified constraints.
+ *
+ * This type represents a factory function that creates query instances with a consistent
+ * base query (typically a collection or collection group query) and applies the provided
+ * constraints.
+ *
+ * @template T - The document data type in the query results
+ */
 export type FirestoreQueryFactoryFunction<T> = (...queryConstraints: ArrayOrValue<FirestoreQueryConstraint>[]) => FirestoreExecutableQuery<T>;
+/**
+ * Factory for creating Firestore queries with consistent base configuration.
+ *
+ * This interface provides a method for creating executable queries against a specific
+ * collection or query reference, with various constraints applied.
+ *
+ * @template T - The document data type in the query results
+ */
 export interface FirestoreQueryFactory<T> {
     /**
-     * Creates a new FirestoreExecutableQuery from the input constraints.
+     * Creates a new FirestoreExecutableQuery with the specified constraints.
+     *
+     * This function creates a query against the factory's base query reference
+     * (typically a collection or collection group) with the provided constraints applied.
      */
     readonly query: FirestoreQueryFactoryFunction<T>;
 }
+/**
+ * Configuration for creating a FirestoreQueryFactory.
+ *
+ * This interface combines the necessary components for creating a query factory:
+ * - A query-like reference (collection, collection group, etc.)
+ * - A query driver to handle the Firestore operations
+ *
+ * @template T - The document data type in the query results
+ */
 export interface FirestoreQueryConfig<T> extends FirestoreQueryDriverRef, QueryLikeReferenceRef<T> {
 }
 /**
- * Creates a FirestoreCollectionQuery.
+ * Creates a factory for building and executing Firestore queries against a specific collection.
+ *
+ * This function creates a query factory that allows building queries with various constraints
+ * and executing them in different ways (getting documents, counting, streaming). The factory
+ * maintains the base query reference (typically a collection or collection group) and provides
+ * a fluent API for working with it.
+ *
+ * @template T - The document data type in the query results
+ * @param config - Configuration for the query factory, including the base query reference and driver
+ * @returns A factory for creating and executing queries against the specified collection
+ *
+ * @example
+ * // Create a query factory for the 'users' collection
+ * const usersQuery = firestoreQueryFactory({
+ *   queryLike: collection(firestore, 'users'),
+ *   firestoreQueryDriver: driver
+ * });
+ *
+ * // Use the factory to create and execute queries
+ * const activeUsers = await usersQuery.query(
+ *   where('status', '==', 'active'),
+ *   orderBy('lastLogin', 'desc'),
+ *   limit(10)
+ * ).getDocs();
  *
- * @param config
- * @returns
+ * // Queries can be extended with additional constraints
+ * const adminUsers = activeUsers.filter(
+ *   where('role', '==', 'admin')
+ * ).getDocs();
  */
 export declare function firestoreQueryFactory<T>(config: FirestoreQueryConfig<T>): FirestoreQueryFactory<T>;

package/src/lib/common/firestore/query/query.iterate.array.d.ts

@@ -3,37 +3,141 @@ import { type IterateFirestoreDocumentSnapshotCheckpointsConfig, type IterateFir
 import { type FirestoreDocument } from '../accessor/document';
 import { type FirestoreDocumentSnapshotDataPairWithData } from '../accessor/document.utility';
 /**
- * Configuration for loadAllFirestoreDocumentSnapshot()
+ * Configuration for loading all document snapshots with their associated data as pairs.
+ *
+ * This interface defines the options for retrieving all document snapshots that match
+ * specific criteria, along with their associated data, in a single batch operation.
+ * It supports pagination via the checkpoint system for efficient handling of large result sets.
+ *
+ * @template T - The document data type
+ * @template D - The FirestoreDocument implementation type (defaults to FirestoreDocument<T>)
  */
 export interface LoadAllFirestoreDocumentSnapshotPairsConfig<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends Pick<IterateFirestoreDocumentSnapshotPairBatchesConfig<T, unknown, D>, 'documentAccessor' | 'queryFactory' | 'constraintsFactory' | 'dynamicConstraints' | 'totalSnapshotsLimit' | 'handleRepeatCursor' | 'filterCheckpointSnapshots' | 'limitPerCheckpoint'> {
     /**
-     * Optional iterate function. Returns no value.
+     * Optional callback function to process each batch of snapshot pairs as they are loaded.
+     *
+     * This function is called once for each batch (checkpoint) of results, allowing for
+     * batch processing of documents without waiting for all results to be collected.
+     *
+     * @param snapshotDataPairs - Array of document snapshots with their associated data
+     * @param batchIndex - Zero-based index of the current batch
+     * @returns A promise that resolves when batch processing is complete
      */
     iterateSnapshotPairsBatch?(snapshotDataPairs: FirestoreDocumentSnapshotDataPairWithData<D>[], batchIndex: number): Promise<void>;
 }
+/**
+ * Result of loading all document snapshots with their associated data as pairs.
+ *
+ * Contains the complete array of document snapshot pairs and metadata about the
+ * query execution, such as the number of checkpoints processed and whether any
+ * limits were reached.
+ *
+ * @template T - The document data type
+ * @template D - The FirestoreDocument implementation type (defaults to FirestoreDocument<T>)
+ */
 export interface LoadAllFirestoreDocumentSnapshotPairsResult<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends Pick<IterateFirestoreDocumentSnapshotCheckpointsResult, 'totalCheckpoints' | 'totalSnapshotsVisited' | 'totalSnapshotsLimitReached'> {
+    /**
+     * Array of all document snapshots with their associated data.
+     *
+     * Each item in the array contains both the Firestore document snapshot and
+     * the data extracted from it, along with additional metadata.
+     */
     readonly snapshotPairs: FirestoreDocumentSnapshotDataPairWithData<D>[];
 }
+/**
+ * Loads all document snapshots that match the specified criteria, along with their associated data,
+ * into a single array.
+ *
+ * This function uses the paginated checkpoint system to efficiently retrieve potentially large
+ * result sets in batches, then combines them into a single result array. It supports optional
+ * batch processing while loading.
+ *
+ * @template T - The document data type
+ * @template D - The FirestoreDocument implementation type (defaults to FirestoreDocument<T>)
+ * @param config - Configuration options for the loading operation
+ * @returns Promise resolving to the result containing all matching document snapshot pairs
+ *
+ * @example
+ * // Load all active user documents with their data
+ * const result = await loadAllFirestoreDocumentSnapshotPairs({
+ *   queryFactory: () => collection(firestore, 'users'),
+ *   constraintsFactory: () => [where('status', '==', 'active')],
+ *   documentAccessor: userAccessorFactory,
+ *   // Process batches as they load
+ *   iterateSnapshotPairsBatch: async (pairs, index) => {
+ *     console.log(`Processing batch ${index} with ${pairs.length} users`);
+ *   }
+ * });
+ *
+ * console.log(`Loaded ${result.snapshotPairs.length} user documents`);
+ */
 export declare function loadAllFirestoreDocumentSnapshotPairs<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: LoadAllFirestoreDocumentSnapshotPairsConfig<T, D>): Promise<LoadAllFirestoreDocumentSnapshotPairsResult<T, D>>;
 /**
- * Configuration for loadAllFirestoreDocumentSnapshot()
+ * Configuration for loading all document snapshots that match specific criteria.
+ *
+ * This interface defines the options for retrieving all document snapshots in a single batch
+ * operation, without their associated data. It supports pagination via the checkpoint system
+ * for efficient handling of large result sets.
+ *
+ * @template T - The document data type
  */
 export interface LoadAllFirestoreDocumentSnapshotsConfig<T> extends Pick<IterateFirestoreDocumentSnapshotCheckpointsConfig<T, unknown>, 'queryFactory' | 'constraintsFactory' | 'dynamicConstraints' | 'totalSnapshotsLimit' | 'handleRepeatCursor' | 'filterCheckpointSnapshots' | 'limitPerCheckpoint'> {
     /**
-     * Optional iterate function. Returns no value.
+     * Optional callback function to process each batch of snapshots as they are loaded.
+     *
+     * This function is called once for each batch (checkpoint) of results, allowing for
+     * batch processing of documents without waiting for all results to be collected.
      *
-     * @param snapshots
-     * @param query
+     * @param snapshots - Array of document snapshots in the current batch
+     * @param query - The complete query snapshot for the current batch
+     * @returns A promise that resolves when batch processing is complete
      */
     iterateSnapshotsForCheckpoint?(snapshots: QueryDocumentSnapshot<T>[], query: QuerySnapshot<T>): Promise<void>;
 }
+/**
+ * Result of loading all document snapshots that match specific criteria.
+ *
+ * Contains the complete array of document snapshots and metadata about the
+ * query execution, such as the number of checkpoints processed and whether any
+ * limits were reached.
+ *
+ * @template T - The document data type
+ */
 export interface LoadAllFirestoreDocumentSnapshotsResult<T> extends Pick<IterateFirestoreDocumentSnapshotCheckpointsResult, 'totalCheckpoints' | 'totalSnapshotsVisited' | 'totalSnapshotsLimitReached'> {
+    /**
+     * Array of all document snapshots that matched the query criteria.
+     *
+     * These snapshots can be used to access document data, IDs, and references.
+     */
     readonly snapshots: QueryDocumentSnapshot<T>[];
 }
 /**
- * Iterates all documents that match the configuration and puts them into an array.
+ * Loads all document snapshots that match the specified criteria into a single array.
+ *
+ * This function uses the paginated checkpoint system to efficiently retrieve potentially large
+ * result sets in batches, then combines them into a single result array. It supports optional
+ * batch processing while loading.
+ *
+ * Unlike loadAllFirestoreDocumentSnapshotPairs, this function only retrieves the document
+ * snapshots without automatically loading their associated data.
+ *
+ * @template T - The document data type
+ * @param config - Configuration options for the loading operation
+ * @returns Promise resolving to the result containing all matching document snapshots
+ *
+ * @example
+ * // Load all documents created in the last 24 hours
+ * const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000);
+ * const result = await loadAllFirestoreDocumentSnapshot({
+ *   queryFactory: () => collection(firestore, 'events'),
+ *   constraintsFactory: () => [where('createdAt', '>=', yesterday), orderBy('createdAt')],
+ *   totalSnapshotsLimit: 1000, // Stop after 1000 documents
+ *   // Process batches as they load
+ *   iterateSnapshotsForCheckpoint: async (snapshots, query) => {
+ *     console.log(`Processing batch with ${snapshots.length} events`);
+ *   }
+ * });
  *
- * @param config
- * @returns
+ * console.log(`Loaded ${result.snapshots.length} event documents`);
  */
 export declare function loadAllFirestoreDocumentSnapshot<T>(config: LoadAllFirestoreDocumentSnapshotsConfig<T>): Promise<LoadAllFirestoreDocumentSnapshotsResult<T>>;

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

@@ -1,3 +1,11 @@
+/**
+ * @module Firestore Query Iteration
+ *
+ * This module provides a comprehensive system for iterating through Firestore query results
+ * with support for pagination, batching, and parallelism. It enables efficient processing of
+ * large result sets by using cursor-based pagination (via "checkpoints") and various iteration
+ * strategies.
+ */
 import { type GetterOrValue, type PromiseOrValue, type IndexRef, type Maybe, type PerformAsyncTasksConfig, type IndexNumber, type PerformAsyncTasksResult, type FactoryWithRequiredInput, type Milliseconds, type AllowValueOnceFilter, type ReadKeyFunction } from '@dereekb/util';
 import { type FirestoreDocument, type LimitedFirestoreDocumentAccessor, type FirestoreDocumentSnapshotDataPairWithData } from '../accessor';
 import { type QueryDocumentSnapshot, type QuerySnapshot, type DocumentSnapshot } from '../types';
@@ -5,7 +13,11 @@ import { type FirestoreQueryConstraint } from './constraint';
 import { type FirestoreQueryFactory } from './query';
 import { type FirestoreModelKey } from '../collection/collection';
 /**
- * Config for iterateFirestoreDocumentSnapshots().
+ * Configuration for iterating through Firestore document snapshots with their associated data as pairs.
+ *
+ * @template T - The document data type
+ * @template R - The result type of processing each snapshot pair
+ * @template D - The FirestoreDocument implementation type (defaults to FirestoreDocument<T>)
  */
 export interface IterateFirestoreDocumentSnapshotPairsConfig<T, R, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends Omit<IterateFirestoreDocumentSnapshotsConfig<T, R>, 'iterateSnapshot'> {
     /**
@@ -20,33 +32,78 @@ export interface IterateFirestoreDocumentSnapshotPairsConfig<T, R, D extends Fir
 /**
  * Iterates through the results of a Firestore query by each FirestoreDocumentSnapshotDataPairWithData.
  *
- * @param config
- * @returns
+ * This function efficiently handles pagination through potentially large result sets by using
+ * the checkpoint system to load documents in batches. For each document snapshot, it loads the
+ * associated data using the provided document accessor, then passes the combined pair to the
+ * processing function.
+ *
+ * @template T - The document data type
+ * @template R - The result type of processing each snapshot pair
+ * @template D - The FirestoreDocument implementation type (defaults to FirestoreDocument<T>)
+ * @param config - Configuration for the iteration, including the document accessor and processing function
+ * @returns A promise that resolves to the result of the iteration, including statistics about checkpoints and snapshots processed
  */
 export declare function iterateFirestoreDocumentSnapshotPairs<T, R, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: IterateFirestoreDocumentSnapshotPairsConfig<T, R, D>): Promise<IterateFirestoreDocumentSnapshotCheckpointsResult>;
 /**
- * Config for iterateFirestoreDocumentSnapshots().
+ * Configuration for iterating through Firestore document snapshots individually.
+ *
+ * This interface provides settings for processing each document snapshot one by one,
+ * rather than in batches.
+ *
+ * @template T - The document data type
+ * @template R - The result type of processing each snapshot
  */
 export interface IterateFirestoreDocumentSnapshotsConfig<T, R> extends Omit<IterateFirestoreDocumentSnapshotBatchesConfig<T, IterateFirestoreDocumentSnapshotsResult<T, R>>, 'iterateSnapshotBatch' | 'maxParallelCheckpoints'> {
     /**
-     * The iterate function per each snapshot individually
+     * The iterate function per each snapshot individually.
+     *
+     * This function is called once for each document snapshot encountered during iteration.
+     *
+     * @param snapshot - The document snapshot to process
+     * @returns A promise resolving to the result of processing this snapshot
      */
     iterateSnapshot(snapshot: QueryDocumentSnapshot<T>): Promise<R>;
     /**
-     * (Optional) Additional config for the snapshot's PerformAsyncTasks call. By default user the performTasksConfig value.
+     * (Optional) Additional config for the snapshot's PerformAsyncTasks call. By default uses the performTasksConfig value.
+     *
+     * This allows fine-tuning the parallelism, batching, and error handling when
+     * processing the individual snapshots within a checkpoint batch.
      */
     readonly snapshotsPerformTasksConfig?: Partial<PerformAsyncTasksConfig<QueryDocumentSnapshot<T>>>;
 }
+/**
+ * Result of processing individual document snapshots during iteration.
+ *
+ * Contains the combined results of all processed snapshots, including successful results,
+ * error information, and statistics about the processing operation.
+ *
+ * @template T - The document data type
+ * @template R - The result type of processing each snapshot
+ */
 export type IterateFirestoreDocumentSnapshotsResult<T, R> = PerformAsyncTasksResult<QueryDocumentSnapshot<T>, R>;
 /**
  * Iterates through the results of a Firestore query by each document snapshot by itself.
  *
- * @param config
- * @returns
+ * This function efficiently handles pagination through potentially large result sets by using
+ * the checkpoint system to load documents in batches. Each document snapshot is then processed
+ * individually using the provided processing function.
+ *
+ * @template T - The document data type
+ * @template R - The result type of processing each snapshot
+ * @param config - Configuration for the iteration, including the snapshot processing function
+ * @returns A promise that resolves to the result of the iteration, including statistics about checkpoints and snapshots processed
  */
 export declare function iterateFirestoreDocumentSnapshots<T, R>(config: IterateFirestoreDocumentSnapshotsConfig<T, R>): Promise<IterateFirestoreDocumentSnapshotCheckpointsResult>;
 /**
  * Config for iterateFirestoreDocumentSnapshots().
+ *
+ * This interface defines the configuration for processing batches of document snapshots
+ * with their associated data. It supports efficient batch processing operations on related
+ * documents.
+ *
+ * @template T - The document data type
+ * @template R - The result type of processing each batch
+ * @template D - The FirestoreDocument implementation type
  */
 export interface IterateFirestoreDocumentSnapshotPairBatchesConfig<T, R, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends Omit<IterateFirestoreDocumentSnapshotBatchesConfig<T, R>, 'iterateSnapshotBatch'> {
     /**
@@ -69,6 +126,11 @@ export declare function iterateFirestoreDocumentSnapshotPairBatches<T, R, D exte
  * Single batch result from iterateFirestoreDocumentSnapshotBatches().
  *
  * Contains the batch index, the snapshots, and the final result for this batch.
+ * Used to track the processing results for each batch of documents processed
+ * during iteration.
+ *
+ * @template T - The document data type
+ * @template R - The result type from processing the batch
  */
 export interface IterateFirestoreDocumentSnapshotBatchesResult<T, R> extends IndexRef {
     /***
@@ -197,61 +259,122 @@ export interface IterateFirestoreDocumentSnapshotCheckpointsConfig<T, R> {
 /**
  * Filter function used to filter out snapshots.
  *
- * @param snapshot
- * @returns
+ * This type defines a function that can filter document snapshots during iteration,
+ * allowing for custom filtering logic to be applied to checkpoints beyond what
+ * Firestore query constraints can achieve.
+ *
+ * @param snapshot - Array of document snapshots to filter
+ * @returns Filtered array of document snapshots
  */
 export type IterateFirestoreDocumentSnapshotCheckpointsFilterCheckpointSnapshotsFunction<T> = (snapshot: QueryDocumentSnapshot<T>[]) => PromiseOrValue<QueryDocumentSnapshot<T>[]>;
 /**
  * Creates a IterateFirestoreDocumentSnapshotCheckpointsFilterCheckpointSnapshotsFunction that filters out any repeat documents.
  *
  * Repeat documents can occur in cases where the document is updated and the query matches it again for a different reason.
+ * This utility function creates a filter that prevents processing the same document multiple times.
  *
- * @param readKeyFunction
+ * @param readKeyFunction - Function that extracts a unique key from a document snapshot, defaults to document ID
+ * @returns A filter function that prevents duplicate document processing
  */
 export declare function filterRepeatCheckpointSnapshots<T>(readKeyFunction?: ReadKeyFunction<QueryDocumentSnapshot<T>>): IterateFirestoreDocumentSnapshotCheckpointsFilterCheckpointSnapshotsFunction<T>;
+/**
+ * Result of processing a single pagination checkpoint during the iteration process.
+ *
+ * This interface contains all data related to one checkpoint/batch in the pagination
+ * sequence, including the documents retrieved, the cursor position, and processing results.
+ *
+ * @template T - The document data type
+ * @template R - The result type from processing this checkpoint
+ */
 export interface IterateFirestoreDocumentSnapshotCheckpointsIterationResult<T, R> extends IndexRef {
     /***
      * Checkpoint index number
+     *
+     * Zero-based index of this checkpoint within the iteration sequence.
      */
     readonly i: IndexNumber;
     /**
      * The cursor document used in this query.
+     *
+     * This is typically the last document in the current batch, which will be used
+     * as the starting point for the next query. May be undefined for the last batch
+     * or if the batch is empty.
      */
     readonly cursorDocument?: Maybe<QueryDocumentSnapshot<T>>;
     /**
      * Results returned from each checkpoint.
+     *
+     * These are the values returned by the checkpoint processing function for
+     * this specific batch of documents.
      */
     readonly results: R[];
     /**
      * All non-filtered document snapshots in this checkpoint.
      *
      * If filterCheckpointSnapshot is configured, this does not include the filtered snapshots.
+     * These are the raw document snapshots as retrieved from Firestore that passed any
+     * configured filtering.
      */
     readonly docSnapshots: QueryDocumentSnapshot<T>[];
     /**
      * The query snapshot for this checkpoint.
+     *
+     * Contains the raw query result, including metadata like query time and
+     * whether the query includes data from local cache.
      */
     readonly docQuerySnapshot: QuerySnapshot<T>;
 }
+/**
+ * Summary results of a complete paginated iteration through Firestore query results.
+ *
+ * This interface provides statistics about the query execution, including the number
+ * of pagination checkpoints processed and the total number of documents visited.
+ */
 export interface IterateFirestoreDocumentSnapshotCheckpointsResult {
     /**
      * The total number of batches visited.
+     *
+     * Each checkpoint represents one Firestore query execution as part of the
+     * paginated iteration process. The number of checkpoints depends on the
+     * number of documents matching the query and the limit per checkpoint.
      */
     readonly totalCheckpoints: number;
     /**
      * The total number of snapshots that were visited.
+     *
+     * This represents the total number of documents that matched the query constraints
+     * and were processed during the iteration, subject to any total limit applied.
      */
     readonly totalSnapshotsVisited: number;
     /**
      * Whether or not the total snapshots limit was reached.
+     *
+     * When true, this indicates that the query potentially had more matching documents
+     * than were processed, but the iteration stopped after reaching the configured limit.
+     * When false, all matching documents were processed.
      */
     readonly totalSnapshotsLimitReached: boolean;
 }
 /**
  * Iterates through the results of a Firestore query in several batches.
  *
- * @param config
- * @returns
+ * This is the core pagination function that handles cursor-based iteration through
+ * potentially large Firestore query results. It manages cursor documents, checkpoint
+ * processing, parallel execution, and various limit controls.
+ *
+ * @template T - The document data type
+ * @template R - The result type of the iteration
+ * @param config - Complete configuration for the pagination and processing behavior
+ * @returns Promise resolving to statistics about the iteration
  */
 export declare function iterateFirestoreDocumentSnapshotCheckpoints<T, R>(config: IterateFirestoreDocumentSnapshotCheckpointsConfig<T, R>): Promise<IterateFirestoreDocumentSnapshotCheckpointsResult>;
+/**
+ * Creates a filter that allows each document snapshot to be processed only once based on its path.
+ *
+ * This utility helps prevent duplicate processing of documents by tracking which ones have
+ * already been seen based on their path.
+ *
+ * @template T - The document snapshot type
+ * @returns A filter function that only allows each unique document to pass once
+ */
 export declare function allowDocumentSnapshotWithPathOnceFilter<T extends DocumentSnapshot>(): AllowValueOnceFilter<T, FirestoreModelKey>;