@dereekb/firebase 13.11.13 → 13.11.15

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

@@ -38,8 +38,9 @@ export interface FirestoreQueryConstraint<T = unknown> {
  * {@link limit}, {@link orderBy}). Most callers should use those typed builders instead.
  *
  * @param type - The constraint type identifier (e.g., 'where', 'limit')
- * @param data - The constraint-specific configuration data
- * @returns A typed constraint object
+ * @param data - The constraint-specific configuration data.
+ * @returns A typed constraint object.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreQueryConstraint<T = unknown>(type: string, data: T): FirestoreQueryConstraint<T>;
@@ -50,16 +51,18 @@ export declare function firestoreQueryConstraint<T = unknown>(type: string, data
  * for a particular constraint type, making it easier to create multiple constraints
  * of the same type with different data.
  *
- * @param type - The constraint type identifier
- * @returns A function that creates constraints of the specified type
+ * @param type - Identifier registered for the constraint variant.
+ * @returns Factory bound to that constraint type.
  *
  * @example
+ * ```ts
  * // Create a factory for 'where' constraints
  * const whereFactory = firestoreQueryConstraintFactory('where');
- *
  * // Use the factory to create constraints
  * const nameConstraint = whereFactory({ field: 'name', op: '==', value: 'John' });
  * const ageConstraint = whereFactory({ field: 'age', op: '>', value: 21 });
+ * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreQueryConstraintFactory(type: string): <T = unknown>(data: T) => FirestoreQueryConstraint<T>;
@@ -84,12 +87,14 @@ export interface LimitQueryConstraintData {
  * This constraint restricts the number of documents returned by a query to at most
  * the specified limit. This is useful for pagination and reducing query result size.
  *
- * @param limit - Maximum number of documents to return
- * @returns A Firestore query constraint for limiting results
+ * @param limit - Maximum number of documents to return.
+ * @returns A Firestore query constraint for limiting results.
  *
  * @example
+ * ```ts
  * // Limit results to 10 documents
  * const query = applyConstraints(baseQuery, [limit(10)]);
+ * ```
  */
 export declare function limit(limit: number): FirestoreQueryConstraint<LimitQueryConstraintData>;
 /**
@@ -117,15 +122,17 @@ export interface LimitToLastQueryConstraintData {
  *
  * Important: Does not work with queries that use streaming results.
  *
- * @param limit - Maximum number of documents to return from the end of the results
- * @returns A Firestore query constraint for limiting results to the last N documents
+ * @param limit - Maximum number of documents to return from the end of the results.
+ * @returns A Firestore query constraint for limiting results to the last N documents.
  *
  * @example
+ * ```ts
  * // Get the 5 most recent documents when ordered by timestamp
  * const query = applyConstraints(baseQuery, [
  *   orderBy('timestamp', 'desc'),
  *   limitToLast(5)
  * ]);
+ * ```
  */
 export declare function limitToLast(limit: number): FirestoreQueryConstraint<LimitToLastQueryConstraintData>;
 /**
@@ -151,15 +158,17 @@ export interface OffsetQueryConstraintData {
  * constraint. Note that performance can degrade with large offset values as Firestore
  * still needs to read all skipped documents.
  *
- * @param offset - Number of documents to skip
- * @returns A Firestore query constraint for offsetting results
+ * @param offset - Number of documents to skip.
+ * @returns A Firestore query constraint for offsetting results.
  *
  * @example
+ * ```ts
  * // Skip the first 20 documents and take the next 10 (for page 3 with page size 10)
  * const query = applyConstraints(baseQuery, [
  *   offset(20),
  *   limit(10)
  * ]);
+ * ```
  */
 export declare function offset(offset: number): FirestoreQueryConstraint<OffsetQueryConstraintData>;
 /**
@@ -224,9 +233,9 @@ export type WhereDocumentIdQueryConstraintData = Omit<WhereQueryConstraintData,
 /**
  * Creates a constraint that filters documents by their document ID.
  *
- * @param opStr - Filter operator
- * @param value - Document ID value to compare against
- * @returns A Firestore query constraint for filtering documents by ID
+ * @param opStr - Filter operator.
+ * @param value - Document ID value to compare against.
+ * @returns A Firestore query constraint for filtering documents by ID.
  */
 export declare function whereDocumentId(opStr: WhereFilterOp, value: unknown): FirestoreQueryConstraint<WhereDocumentIdQueryConstraintData>;
 /**
@@ -280,7 +289,7 @@ export type OrderByDocumentIdQueryConstraintData = Pick<OrderByQueryConstraintDa
  * Creates a constraint that orders documents by their document ID.
  *
  * @param directionStr - Direction to order results (defaults to ascending)
- * @returns A Firestore query constraint for ordering documents by ID
+ * @returns A Firestore query constraint for ordering documents by ID.
  */
 export declare function orderByDocumentId(directionStr?: OrderByDirection): FirestoreQueryConstraint<OrderByDocumentIdQueryConstraintData>;
 /**
@@ -301,9 +310,10 @@ export interface StartAtQueryConstraintData<T = DocumentData> {
 /**
  * Creates a constraint that starts returning results at the document referenced by the snapshot.
  *
+ * @param snapshot - Document snapshot to start at.
+ * @returns A Firestore query constraint for starting at a document.
+ *
  * @template T - Type of document data
- * @param snapshot - Document snapshot to start at
- * @returns A Firestore query constraint for starting at a document
  */
 export declare function startAt<T = DocumentData>(snapshot: DocumentSnapshot<T>): FirestoreQueryConstraint<StartAtQueryConstraintData<T>>;
 /**
@@ -323,7 +333,7 @@ export interface StartAtValueQueryConstraintData {
  * Creates a constraint that starts returning results at the specified field values.
  *
  * @param fieldValues - Field values to start at (must match the orderBy fields)
- * @returns A Firestore query constraint for starting at field values
+ * @returns A Firestore query constraint for starting at field values.
  */
 export declare function startAtValue(...fieldValues: unknown[]): FirestoreQueryConstraint<StartAtValueQueryConstraintData>;
 /**
@@ -344,9 +354,10 @@ export interface StartAfterQueryConstraintData<T = DocumentData> {
 /**
  * Creates a constraint that starts returning results after the document referenced by the snapshot.
  *
+ * @param snapshot - Document snapshot to start after.
+ * @returns A Firestore query constraint for starting after a document.
+ *
  * @template T - Type of document data
- * @param snapshot - Document snapshot to start after
- * @returns A Firestore query constraint for starting after a document
  */
 export declare function startAfter<T = DocumentData>(snapshot: DocumentSnapshot<T>): FirestoreQueryConstraint<StartAfterQueryConstraintData<T>>;
 /**
@@ -381,15 +392,16 @@ export interface EndAtValueQueryConstraintData {
  * Creates a constraint that ends results at the specified field values.
  *
  * @param fieldValues - Field values to end at (must match the orderBy fields)
- * @returns A Firestore query constraint for ending at field values
+ * @returns A Firestore query constraint for ending at field values.
  */
 export declare function endAtValue(...fieldValues: unknown[]): FirestoreQueryConstraint<EndAtValueQueryConstraintData>;
 /**
  * Creates a constraint that ends returning results at the document referenced by the snapshot.
  *
+ * @param snapshot - Document snapshot to end at.
+ * @returns A Firestore query constraint for ending at a document.
+ *
  * @template T - Type of document data
- * @param snapshot - Document snapshot to end at
- * @returns A Firestore query constraint for ending at a document
  */
 export declare function endAt<T = DocumentData>(snapshot: DocumentSnapshot<T>): FirestoreQueryConstraint<EndAtQueryConstraintData<T>>;
 /**
@@ -410,9 +422,10 @@ export interface EndBeforeQueryConstraintData<T = DocumentData> {
 /**
  * Creates a constraint that ends returning results before the document referenced by the snapshot.
  *
+ * @param snapshot - Document snapshot to end before.
+ * @returns A Firestore query constraint for ending before a document.
+ *
  * @template T - Type of document data
- * @param snapshot - Document snapshot to end before
- * @returns A Firestore query constraint for ending before a document
  */
 export declare function endBefore<T = DocumentData>(snapshot: DocumentSnapshot<T>): FirestoreQueryConstraint<EndBeforeQueryConstraintData<T>>;
 /**
@@ -482,18 +495,19 @@ export type FullFirestoreQueryConstraintHandlersMapping<B> = {
  *
  * It preserves the existing limit type (regular limit vs limitToLast) if one exists.
  *
- * @param limit - Maximum number of documents to return
- * @param addedLimitType - Type of limit constraint to add (default: regular limit)
- * @returns A function that adds or replaces limit constraints
+ * @param limit - Maximum number of documents to return.
+ * @param addedLimitType - Variant of limit constraint used when none already exists (default: regular limit).
+ * @returns Constraint transformer that adds or replaces the limit constraint.
  *
  * @example
+ * ```ts
  * // Replace any existing limit with a limit of 25
  * const withLimit25 = addOrReplaceLimitInConstraints(25);
  * const newConstraints = withLimit25(existingConstraints);
- *
  * // Replace any existing limit with a limitToLast of 10
  * const withLastLimit10 = addOrReplaceLimitInConstraints(10, FIRESTORE_LIMIT_TO_LAST_QUERY_CONSTRAINT_TYPE);
  * const newConstraints = withLastLimit10(existingConstraints);
+ * ```
  */
 export declare function addOrReplaceLimitInConstraints(limit: number, addedLimitType?: typeof FIRESTORE_LIMIT_QUERY_CONSTRAINT_TYPE | typeof FIRESTORE_LIMIT_TO_LAST_QUERY_CONSTRAINT_TYPE): (constraints: FirestoreQueryConstraint[]) => FirestoreQueryConstraint[];
 /**
@@ -510,13 +524,15 @@ export type FirestoreQueryConstraintMapFunction = (constraints: FirestoreQueryCo
  * This is useful when you want to remove certain constraint types from a query,
  * for example removing existing limit or where constraints before adding new ones.
  *
- * @param types - Constraint types to filter out
- * @returns A function that filters constraints by type
+ * @param types - Constraint types to drop from the list.
+ * @returns Mapper that yields the input constraints minus those matching `types`.
  *
  * @example
+ * ```ts
  * // Remove all limit and offset constraints from the query
  * const withoutPagination = filterConstraintsOfType('limit', 'offset');
  * const newConstraints = withoutPagination(existingConstraints);
+ * ```
  */
 export declare function filterConstraintsOfType(...types: FirestoreQueryConstraintType[]): FirestoreQueryConstraintMapFunction;
 /**
@@ -526,17 +542,19 @@ export declare function filterConstraintsOfType(...types: FirestoreQueryConstrai
  * preserving all other constraints. It's useful for updating pagination settings,
  * changing filters, or modifying sorting without rebuilding the entire constraint list.
  *
- * @param replaceFn - Function that generates replacement constraints based on the filtered constraints
- * @param types - Constraint types to replace
- * @returns A function that replaces constraints of specified types
+ * @param replaceFn - Produces the replacement constraint(s) from the excluded ones.
+ * @param types - Constraint types whose entries are replaced.
+ * @returns Mapper that swaps matching constraints for the generated replacements.
  *
  * @example
+ * ```ts
  * // Replace any existing limit constraint with a new limit of 20
  * const replaceLimit = replaceConstraints(
  *   () => limit(20),
  *   [FIRESTORE_LIMIT_QUERY_CONSTRAINT_TYPE]
  * );
  * const newConstraints = replaceLimit(existingConstraints);
+ * ```
  */
 export declare function replaceConstraints(replaceFn: (constraints: FirestoreQueryConstraint[]) => Maybe<ArrayOrValue<FirestoreQueryConstraint>>, types: FirestoreQueryConstraintType[]): (constraints: FirestoreQueryConstraint[]) => FirestoreQueryConstraint[];
 /**
@@ -546,14 +564,16 @@ export declare function replaceConstraints(replaceFn: (constraints: FirestoreQue
  * the specified types and those that don't. This is used internally by other constraint
  * manipulation functions and can be useful for custom constraint processing.
  *
- * @param types - Constraint types to separate
- * @returns A function that separates constraints into included and excluded groups
+ * @param types - Constraint types collected into the excluded group.
+ * @returns Mapper producing `{ included, excluded }` partitions.
  *
  * @example
+ * ```ts
  * // Separate pagination constraints from filtering constraints
  * const separatePagination = separateConstraints('limit', 'offset');
  * const { included, excluded } = separatePagination(allConstraints);
  * // included contains constraints that aren't limit or offset
  * // excluded contains only the limit and offset constraints
+ * ```
  */
 export declare function separateConstraints(...types: FirestoreQueryConstraintType[]): (constraints: FirestoreQueryConstraint[]) => SeparateResult<FirestoreQueryConstraint>;

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

@@ -30,15 +30,18 @@ export type FirestoreQueryOrderByAndRangeWhereTuple = [FirestoreQueryConstraint<
  * include documents that are descendants of the specified parent. It's useful for hierarchical data
  * structures where you need to retrieve all documents of a certain type that belong to a specific parent.
  *
+ * @param parentRef - The parent document reference.
+ * @returns Array of query constraints to filter by parent document.
+ *
  * @template P - The parent document data type
- * @param parentRef - The parent document reference
- * @returns Array of query constraints to filter by parent document
  *
  * @example
+ * ```ts
  * // Get all 'comments' documents under a specific 'post'
  * const postRef = doc(firestore, 'posts', postId);
  * const query = collectionGroup(firestore, 'comments')
  *   .where(...allChildDocumentsUnderParent(postRef));
+ * ```
  */
 export declare function allChildDocumentsUnderParent<P>(parentRef: DocumentReference<P>): FirestoreQueryOrderByDocumentIdRangeBoundsTuple;
 /**
@@ -49,12 +52,14 @@ export declare function allChildDocumentsUnderParent<P>(parentRef: DocumentRefer
  * Uses a range query on document IDs to efficiently filter for descendants.
  *
  * @param parentPath - The full path to the parent document (e.g., 'users/123')
- * @returns Array of query constraints to filter by parent path
+ * @returns Array of query constraints to filter by parent path.
  *
  * @example
+ * ```ts
  * // Get all 'comments' under a specific post without creating a reference
  * const query = collectionGroup(firestore, 'comments')
  *   .where(...allChildDocumentsUnderParentPath('posts/abc123'));
+ * ```
  */
 export declare function allChildDocumentsUnderParentPath(parentPath: string): FirestoreQueryOrderByDocumentIdRangeBoundsTuple;
 /**
@@ -87,16 +92,19 @@ export declare function allChildDocumentsUnderRelativePath(orderByFieldPath: Fie
  * It's useful when you're storing references to other models as strings in the format
  * 'collectionType/id'.
  *
- * @template T - The document data type
- * @param orderByFieldPath - The field containing model references
- * @param value - The root model identity containing the collection type to search for
+ * @param orderByFieldPath - The field containing model references.
+ * @param value - The root model identity containing the collection type to search for.
  * @param sortDirection - Optional direction to sort results (default: 'asc')
- * @returns Array of query constraints to filter by model type
+ * @returns Array of query constraints to filter by model type.
+ *
+ * @template T - The document data type
  *
  * @example
+ * ```ts
  * // Find all documents where the 'reference' field contains a reference to a 'users' model
  * const query = collection(firestore, 'documents')
  *   .where(...whereStringHasRootIdentityModelKey('reference', { collectionType: 'users' }));
+ * ```
  */
 export declare function whereStringHasRootIdentityModelKey<T = object>(orderByFieldPath: FieldPathOrStringPathOf<T> | FieldPathOrStringPath, value: RootFirestoreModelIdentity, sortDirection?: OrderByDirection): FirestoreQueryOrderByRangeBoundsTuple;
 /**

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

@@ -157,8 +157,8 @@ export type InternalFirestoreItemPageIterationInstance<T> = ItemPageIterationIns
  * This utility function removes constraints that would conflict with the pagination
  * mechanics, such as 'limit' constraints which are automatically added by the paginator.
  *
- * @param constraints - Array of query constraints to filter
- * @returns Filtered array with disallowed constraints removed
+ * @param constraints - Array of query constraints to filter.
+ * @returns Filtered array with disallowed constraints removed.
  */
 export declare function filterDisallowedFirestoreItemPageIteratorInputConstraints(constraints: FirestoreQueryConstraint[]): FirestoreQueryConstraint[];
 /**
@@ -240,11 +240,13 @@ export type FirestoreItemPageIterationFactoryFunction<T> = (filter?: FirestoreIt
  * that can create properly configured pagination instances. This is useful when you need to create
  * multiple pagination instances for the same collection but with different filters.
  *
+ * @param baseConfig - The base configuration shared by all created pagination instances.
+ * @returns A factory function that creates pagination instances with the specified base configuration.
+ *
  * @template T - The document data type in the query results
- * @param baseConfig - The base configuration shared by all created pagination instances
- * @returns A factory function that creates pagination instances with the specified base configuration
  *
  * @example
+ * ```ts
  * // Create a factory for paginating users collection
  * const usersQuery = collection(firestore, 'users');
  * const usersPaginator = firestoreItemPageIterationFactory({
@@ -252,7 +254,6 @@ export type FirestoreItemPageIterationFactoryFunction<T> = (filter?: FirestoreIt
  *   itemsPerPage: 20,
  *   firestoreQueryDriver: driver
  * });
- *
  * // Create specific pagination instances with different filters
  * const activePaginator = usersPaginator({
  *   constraints: [where('status', '==', 'active')]
@@ -260,6 +261,8 @@ export type FirestoreItemPageIterationFactoryFunction<T> = (filter?: FirestoreIt
  * const adminPaginator = usersPaginator({
  *   constraints: [where('role', '==', 'admin')]
  * });
+ * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreItemPageIterationFactory<T>(baseConfig: FirestoreItemPageIterationBaseConfig<T>): FirestoreItemPageIterationFactoryFunction<T>;
@@ -285,11 +288,13 @@ export declare const FIRESTORE_ITEM_PAGE_ITERATOR: ItemPageIterator<FirestoreIte
  * that directly provides document arrays while also exposing access to the underlying
  * snapshot iteration.
  *
+ * @param config - The configuration for the pagination.
+ * @returns A Firestore pagination instance that loads documents in pages.
+ *
  * @template T - The document data type in the query results
- * @param config - The configuration for the pagination
- * @returns A Firestore pagination instance that loads documents in pages
  *
  * @example
+ * ```ts
  * // Create a pagination instance for a users collection
  * const usersPagination = firestoreItemPageIteration({
  *   queryLike: collection(firestore, 'users'),
@@ -299,14 +304,14 @@ export declare const FIRESTORE_ITEM_PAGE_ITERATOR: ItemPageIterator<FirestoreIte
  *     constraints: [where('status', '==', 'active'), orderBy('createdAt', 'desc')]
  *   }
  * });
- *
  * // Load the first page of results
  * const firstPage = await usersPagination.loadNextPage().toPromise();
  * console.log('First 10 users:', firstPage);
- *
  * // Load the next page when needed
  * const secondPage = await usersPagination.loadNextPage().toPromise();
  * console.log('Next 10 users:', secondPage);
+ * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreItemPageIteration<T>(config: FirestoreItemPageIterationConfig<T>): FirestoreItemPageIterationInstance<T>;
@@ -327,8 +332,9 @@ export type FirestoreFixedItemPageIterationFactoryFunction<T> = (items: Document
  * producing a pagination instance that iterates over those specific documents in pages.
  *
  * @param baseConfig - Base pagination configuration (query reference, driver, page size)
- * @param documentAccessor - Accessor used to load document snapshots from the references
- * @returns A factory function that creates fixed-set pagination instances
+ * @param documentAccessor - Accessor used to load document snapshots from the references.
+ * @returns A factory function that creates fixed-set pagination instances.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreFixedItemPageIterationFactory<T>(baseConfig: FirestoreItemPageIterationConfig<T>, documentAccessor: LimitedFirestoreDocumentAccessor<T>): FirestoreFixedItemPageIterationFactoryFunction<T>;
@@ -361,8 +367,9 @@ export interface FirestoreFixedItemPageIterationConfig<T> extends FirestoreItemP
  * This is useful for paginating over known document sets (e.g., from a pre-computed list
  * of references) without executing Firestore queries.
  *
- * @param config - Configuration including the document references, accessor, and pagination settings
- * @returns A pagination instance that pages through the fixed reference set
+ * @param config - Configuration including the document references, accessor, and pagination settings.
+ * @returns A pagination instance that pages through the fixed reference set.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreFixedItemPageIteration<T>(config: FirestoreFixedItemPageIterationConfig<T>): FirestoreItemPageIterationInstance<T>;

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

@@ -136,28 +136,30 @@ export interface FirestoreQueryConfig<T> extends FirestoreQueryDriverRef, QueryL
  * maintains the base query reference (typically a collection or collection group) and provides
  * a fluent API for working with it.
  *
+ * @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.
+ *
  * @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
+ * ```ts
  * // 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();
- *
  * // Queries can be extended with additional constraints
  * const adminUsers = activeUsers.filter(
  *   where('role', '==', 'admin')
  * ).getDocs();
+ * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreQueryFactory<T>(config: FirestoreQueryConfig<T>): FirestoreQueryFactory<T>;

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

@@ -52,12 +52,14 @@ export interface LoadAllFirestoreDocumentSnapshotPairsResult<T, D extends Firest
  * result sets in batches, then combines them into a single result array. It supports optional
  * batch processing while loading.
  *
+ * @param config - Configuration options for the loading operation.
+ * @returns Promise resolving to the result containing all matching document snapshot pairs.
+ *
  * @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
+ * ```ts
  * // Load all active user documents with their data
  * const result = await loadAllFirestoreDocumentSnapshotPairs({
  *   queryFactory: () => collection(firestore, 'users'),
@@ -68,8 +70,8 @@ export interface LoadAllFirestoreDocumentSnapshotPairsResult<T, D extends Firest
  *     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>>;
 /**
@@ -121,11 +123,13 @@ export interface LoadAllFirestoreDocumentSnapshotsResult<T> extends Pick<Iterate
  * Unlike loadAllFirestoreDocumentSnapshotPairs, this function only retrieves the document
  * snapshots without automatically loading their associated data.
  *
+ * @param config - Configuration options for the loading operation.
+ * @returns Promise resolving to the result containing all matching document snapshots.
+ *
  * @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
+ * ```ts
  * // Load all documents created in the last 24 hours
  * const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000);
  * const result = await loadAllFirestoreDocumentSnapshot({
@@ -137,7 +141,7 @@ export interface LoadAllFirestoreDocumentSnapshotsResult<T> extends Pick<Iterate
  *     console.log(`Processing batch with ${snapshots.length} events`);
  *   }
  * });
- *
  * 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

@@ -56,7 +56,7 @@ export interface IterateFirestoreDocumentSnapshotPairsConfig<T, R, D extends Fir
  * This is the highest-level iteration function — use it when your callback needs
  * document-level operations (updates, deletes) alongside the snapshot data.
  *
- * @param config - Iteration config including the document accessor and per-pair callback
+ * @param config - Iteration config including the document accessor and per-pair callback.
  * @returns Checkpoint-level statistics (total checkpoints, snapshots visited, limit status)
  *
  * @example
@@ -121,7 +121,7 @@ export type IterateFirestoreDocumentSnapshotsResult<T, R> = PerformAsyncTasksRes
  * For document-level operations (needing the typed {@link FirestoreDocument} wrapper),
  * use {@link iterateFirestoreDocumentSnapshotPairs} instead.
  *
- * @param config - Iteration config including the per-snapshot callback
+ * @param config - Iteration config including the per-snapshot callback.
  * @returns Checkpoint-level statistics (total checkpoints, snapshots visited, limit status)
  *
  * @example
@@ -170,7 +170,7 @@ export interface IterateFirestoreDocumentSnapshotPairBatchesConfig<T, R, D exten
  * typed document-snapshot pairs. Use this when you need batch-level operations with
  * typed document access (e.g., bulk updates, batch writes).
  *
- * @param config - Iteration config including the document accessor and per-batch callback
+ * @param config - Iteration config including the document accessor and per-batch callback.
  * @returns Checkpoint-level statistics (total checkpoints, snapshots visited, limit status)
  *
  * @example
@@ -236,7 +236,7 @@ export interface IterateFirestoreDocumentSnapshotBatchesConfig<T, R> extends Omi
      * Called once per checkpoint with all snapshots from that checkpoint. If it returns `null`,
      * all snapshots are processed in a single batch. Takes precedence over `batchSize` when provided.
      */
-    readonly batchSizeForSnapshots?: Maybe<FactoryWithRequiredInput<number | null, QueryDocumentSnapshot<T>[]>>;
+    readonly batchSizeForSnapshots?: Maybe<FactoryWithRequiredInput<Maybe<number>, QueryDocumentSnapshot<T>[]>>;
     /**
      * Callback invoked for each batch of document snapshots within a checkpoint.
      *
@@ -275,7 +275,7 @@ export declare const DEFAULT_ITERATE_FIRESTORE_DOCUMENT_SNAPSHOT_BATCHES_BATCH_S
  * For per-snapshot processing, use {@link iterateFirestoreDocumentSnapshots}.
  * For batch processing with typed document pairs, use {@link iterateFirestoreDocumentSnapshotPairBatches}.
  *
- * @param config - Iteration config including batch size and per-batch callback
+ * @param config - Iteration config including batch size and per-batch callback.
  * @returns Checkpoint-level statistics (total checkpoints, snapshots visited, limit status)
  *
  * @example
@@ -544,8 +544,8 @@ export interface IterateFirestoreDocumentSnapshotCheckpointsResult {
  * - {@link iterateFirestoreDocumentSnapshots} — processes one snapshot at a time
  * - {@link iterateFirestoreDocumentSnapshotPairs} — loads typed document wrappers per snapshot
  *
- * @param config - Complete configuration for pagination, processing, and termination behavior
- * @returns Statistics including total checkpoints executed, snapshots visited, and whether the limit was hit
+ * @param config - Complete configuration for pagination, processing, and termination behavior.
+ * @returns Statistics including total checkpoints executed, snapshots visited, and whether the limit was hit.
  *
  * @example
  * ```typescript
@@ -573,7 +573,7 @@ export declare function iterateFirestoreDocumentSnapshotCheckpoints<T, R>(config
  * this filter uses the full document path ({@link readFirestoreModelKeyFromDocumentSnapshot}),
  * making it suitable for cross-collection iteration where document IDs alone may collide.
  *
- * @returns A reusable filter function that passes each unique document path exactly once
+ * @returns A reusable filter function that passes each unique document path exactly once.
  *
  * @example
  * ```typescript

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

@@ -48,12 +48,14 @@ export type StreamDocsUnsubscribeFunction = () => void;
  * and RxJS's reactive streams, allowing for seamless integration of Firestore
  * query results into reactive applications.
  *
- * @template O - The type of output value to emit in the Observable
  * @param callOnSnapshot - Function that sets up the Firestore snapshot listener
- *                          and returns an unsubscribe function
- * @returns An Observable that emits values from the Firestore snapshot listener
+ *                          and returns an unsubscribe function.
+ * @returns An Observable that emits values from the Firestore snapshot listener.
+ *
+ * @template O - The type of output value to emit in the Observable
  *
  * @example
+ * ```ts
  * // Create a reactive stream from a Firestore query
  * const usersStream = streamFromOnSnapshot(params => {
  *   return collection(firestore, 'users')
@@ -64,6 +66,7 @@ export type StreamDocsUnsubscribeFunction = () => void;
  *       () => params.complete()
  *     );
  * });
+ * ```
  */
 export declare function streamFromOnSnapshot<O>(callOnSnapshot: (params: StreamDocsWithOnSnapshotFunctionParams<O>) => StreamDocsUnsubscribeFunction): Observable<O>;
 /**
@@ -73,9 +76,10 @@ export declare function streamFromOnSnapshot<O>(callOnSnapshot: (params: StreamD
  * DocumentReference objects, making it easier to work with the references
  * to the documents that matched a query.
  *
+ * @param snapshots - The query snapshot containing document snapshots.
+ * @returns Array of document references extracted from the snapshot.
+ *
  * @template T - The document data type
- * @param snapshots - The query snapshot containing document snapshots
- * @returns Array of document references extracted from the snapshot
  */
 export declare function documentReferencesFromSnapshot<T>(snapshots: QuerySnapshot<T>): DocumentReference<T>[];
 /**
@@ -85,7 +89,7 @@ export declare function documentReferencesFromSnapshot<T>(snapshots: QuerySnapsh
  * which uniquely identifies the document within Firestore. This is useful
  * for tracking documents across queries and preventing duplicate processing.
  *
- * @param snapshot - The document snapshot to extract the key from
- * @returns The document's full path as a FirestoreModelKey
+ * @param snapshot - The document snapshot to extract the key from.
+ * @returns The document's full path as a FirestoreModelKey.
  */
 export declare function readFirestoreModelKeyFromDocumentSnapshot(snapshot: DocumentSnapshot<any>): FirestoreModelKey;