@dereekb/firebase 13.0.5 → 13.0.7

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

@@ -3,247 +3,383 @@ import { type FirestoreModelId, type FirestoreModelIdRef, type FirestoreModelKey
 import { type QueryDocumentSnapshot, type DocumentDataWithIdAndKey, type DocumentReference, type DocumentSnapshot, type QuerySnapshot, type Transaction } from '../types';
 import { type FirestoreDocumentData, type FirestoreDocument, type FirestoreDocumentAccessor, type LimitedFirestoreDocumentAccessor, type LimitedFirestoreDocumentAccessorContextExtension } from './document';
 /**
- * Creates an array of new FirestoreDocument instances without creating them in Firestore.
+ * Creates an array of new {@link FirestoreDocument} instances without persisting them to Firestore.
  *
- * @template T - The document data type
- * @template D - The FirestoreDocument implementation type
- * @param documentAccessor - The document accessor to use for creating document instances
- * @param count - The number of document instances to create
- * @returns An array of new document instances
+ * Each document is allocated a unique auto-generated ID via {@link FirestoreDocumentAccessor.newDocument},
+ * but no data is written to the database. Useful for preparing document references in bulk before
+ * deciding what data to write.
+ *
+ * @param documentAccessor - Accessor that provides the `newDocument()` factory method
+ * @param count - Number of document instances to create
+ * @returns Array of `count` new document instances, each with a unique auto-generated ID
  */
 export declare function newDocuments<T, D extends FirestoreDocument<T>>(documentAccessor: FirestoreDocumentAccessor<T, D>, count: number): D[];
 /**
- * Parameters for creating and initializing multiple Firestore documents.
- *
- * @template T - The document data type
- * @template D - The FirestoreDocument implementation type
+ * Configuration for {@link makeDocuments} that controls how documents are created and initialized.
  */
 export interface MakeDocumentsParams<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> {
     /**
-     * The number of documents to create.
+     * Number of documents to create.
      */
     readonly count: number;
     /**
-     * Optional override to create a new document using the input accessor.
-     * If not provided, the accessor's default newDocument method will be used.
+     * Optional factory override for creating new document instances.
+     *
+     * When omitted, the accessor's default {@link FirestoreDocumentAccessor.newDocument} is used,
+     * which generates a random document ID. Provide this to customize document creation,
+     * e.g. to use specific IDs via `loadDocumentForId`.
      *
-     * @param documentAccessor - The document accessor to use for creating document instances
+     * @param documentAccessor - The accessor to create the document from
      * @returns A new document instance
      */
     readonly newDocument?: (documentAccessor: FirestoreDocumentAccessor<T, D>) => D;
     /**
-     * Initializes the document with data and/or performs tasks with the document.
+     * Called for each document to produce its initial data.
      *
-     * If this function returns a value (not null/undefined), that data will be used
-     * to create the document in Firestore. If it returns null/undefined, no document
-     * will be created in Firestore but the document instance will still be returned.
+     * If the returned value is non-nullish, the document is created in Firestore with that data
+     * via `document.accessor.create(data)`. If nullish, the document instance is still returned
+     * but nothing is written to the database.
      *
-     * @param i - The index of the document being created (0 to count-1)
-     * @param document - The document instance to initialize
-     * @returns Document data to create in Firestore, or null/undefined to skip creation
+     * @param i - Zero-based index of the current document
+     * @param document - The document instance (already has an allocated reference)
+     * @returns Data to persist, or nullish to skip Firestore creation
      */
     readonly init: (i: number, document: D) => Maybe<T> | Promise<Maybe<T>>;
 }
 /**
- * Creates multiple documents in Firestore and returns the document instances.
+ * Creates and optionally persists multiple Firestore documents in sequence.
  *
- * For each document, this function:
- * 1. Creates a new document instance using the specified or default factory
- * 2. Calls the init function with the document instance
- * 3. If init returns data, creates the document in Firestore
- * 4. Returns all document instances, whether they were created in Firestore or not
+ * Uses {@link performMakeLoop} to iterate `count` times. For each iteration:
+ * 1. A new document instance is created (via `make.newDocument` or the default factory)
+ * 2. `make.init(i, document)` is awaited to produce initial data
+ * 3. If init returns non-nullish data, `document.accessor.create(data)` persists it
+ * 4. The document instance is collected regardless of whether it was persisted
  *
- * @template T - The document data type
- * @template D - The FirestoreDocument implementation type
- * @param documentAccessor - The document accessor to use for creating document instances
- * @param make - Parameters for document creation and initialization
- * @returns A promise that resolves to an array of document instances
+ * Documents are created sequentially (not in parallel) to allow index-dependent logic.
+ *
+ * @param documentAccessor - Accessor providing the document factory and collection context
+ * @param make - Configuration controlling count, factory, and initialization
+ * @returns Promise resolving to all created document instances (length === `make.count`)
  */
 export declare function makeDocuments<T, D extends FirestoreDocument<T>>(documentAccessor: FirestoreDocumentAccessor<T, D>, make: MakeDocumentsParams<T, D>): Promise<D[]>;
 /**
- * Retrieves DocumentSnapshots for an array of documents in parallel.
+ * Fetches {@link DocumentSnapshot}s for multiple documents in parallel using {@link runAsyncTasksForValues}.
  *
- * This is useful for fetching the current state of multiple documents at once.
+ * Each document's `accessor.get()` is called concurrently. The returned array preserves
+ * the same ordering as the input `documents` array.
  *
- * @template D - The FirestoreDocument implementation type
- * @param documents - Array of document instances to get snapshots for
- * @returns Promise that resolves to an array of DocumentSnapshots in the same order as the input documents
+ * @param documents - Documents to fetch snapshots for
+ * @returns Snapshots in the same order as the input array
  */
 export declare function getDocumentSnapshots<D extends FirestoreDocument<any>>(documents: D[]): Promise<DocumentSnapshot<FirestoreDocumentData<D>>[]>;
 /**
- * A pair containing both a FirestoreDocument instance and its current DocumentSnapshot.
- *
- * This allows keeping track of both the document reference and its data.
+ * Pairs a {@link FirestoreDocument} instance with its fetched {@link DocumentSnapshot}.
  *
- * @template D - The FirestoreDocument implementation type
+ * Retains a reference to the original document alongside its snapshot, which is useful
+ * when you need both the document's methods (e.g. `update`, `create`) and its current data state.
  */
 export type FirestoreDocumentSnapshotPair<D extends FirestoreDocument<any>> = {
-    /** The original document instance */
+    /** The document instance used to fetch the snapshot. */
     readonly document: D;
-    /** The current snapshot of the document from Firestore */
+    /** The fetched snapshot reflecting the document's current state in Firestore. */
     readonly snapshot: DocumentSnapshot<FirestoreDocumentData<D>>;
 };
 /**
- * Creates a document-snapshot pair from a document instance.
+ * Fetches the current snapshot of a single document and pairs it with the document instance.
  *
- * Fetches the current snapshot of the document and returns both the original
- * document instance and the snapshot together.
- *
- * @template D - The FirestoreDocument implementation type
- * @param document - The document instance to get a snapshot for
- * @returns Promise that resolves to a document-snapshot pair
+ * @param document - The document to fetch
+ * @returns A pair containing the document and its snapshot
  */
 export declare function getDocumentSnapshotPair<D extends FirestoreDocument<any>>(document: D): Promise<FirestoreDocumentSnapshotPair<D>>;
 /**
- * Creates document-snapshot pairs for an array of documents in parallel.
- *
- * Fetches the current snapshot of each document and returns pairs containing both
- * the original document instances and their snapshots.
+ * Fetches snapshots for multiple documents in parallel and pairs each with its document instance.
  *
- * @template D - The FirestoreDocument implementation type
- * @param documents - Array of document instances to get snapshots for
- * @returns Promise that resolves to an array of document-snapshot pairs in the same order as the input documents
+ * @param documents - Documents to fetch
+ * @returns Pairs in the same order as the input array
  */
 export declare function getDocumentSnapshotPairs<D extends FirestoreDocument<any>>(documents: D[]): Promise<FirestoreDocumentSnapshotPair<D>[]>;
 /**
- * A tuple containing a document instance, its snapshot, and the extracted data.
+ * Combines a {@link FirestoreDocument}, its {@link DocumentSnapshot}, and extracted data with `id`/`key` fields.
  *
- * Provides a comprehensive view of a document with its reference, snapshot state,
- * and formatted data (including ID and key fields).
- *
- * @template D - The FirestoreDocument implementation type
+ * The `data` field is produced by {@link documentDataWithIdAndKey}, which mutates the snapshot's data object
+ * to include `id` (the document ID) and `key` (the full document path). If the document does not exist
+ * in Firestore, `data` will be `undefined`.
  */
 export interface FirestoreDocumentSnapshotDataPair<D extends FirestoreDocument<any>> {
-    /** The original document instance */
+    /** The document instance used to fetch the snapshot. */
     readonly document: D;
-    /** The current snapshot of the document from Firestore */
+    /** The fetched snapshot reflecting the document's current state in Firestore. */
     readonly snapshot: DocumentSnapshot<FirestoreDocumentData<D>>;
-    /** The document data with ID and key fields added, or undefined if the document doesn't exist */
+    /** The snapshot's data with `id` and `key` fields injected, or `undefined` if the document does not exist. */
     readonly data: Maybe<DocumentDataWithIdAndKey<FirestoreDocumentData<D>>>;
 }
 /**
- * A variant of FirestoreDocumentSnapshotDataPair that guarantees data exists.
- *
- * This interface is used when you need to ensure that only documents with existing
- * data are included in the results.
+ * Narrowed variant of {@link FirestoreDocumentSnapshotDataPair} where `data` is guaranteed non-nullish.
  *
- * @template D - The FirestoreDocument implementation type
+ * Used by functions like {@link getDocumentSnapshotDataPairsWithData} that filter out non-existent documents.
  */
 export interface FirestoreDocumentSnapshotDataPairWithData<D extends FirestoreDocument<any>> extends Omit<FirestoreDocumentSnapshotDataPair<D>, 'data'> {
-    /** The document data with ID and key fields added (guaranteed to exist) */
+    /** The snapshot's data with `id` and `key` fields injected (guaranteed to exist). */
     readonly data: DocumentDataWithIdAndKey<FirestoreDocumentData<D>>;
 }
 /**
- * Creates a document-snapshot-data triplet from a document instance.
+ * Fetches a document's snapshot, extracts its data with `id`/`key` fields, and returns all three as a triplet.
  *
- * Fetches the current snapshot of the document, extracts its data with ID and key fields,
- * and returns all three together in a single object.
- *
- * @template D - The FirestoreDocument implementation type
- * @param document - The document instance to get data for
- * @returns Promise that resolves to a document-snapshot-data triplet
+ * @param document - The document to fetch
+ * @returns A triplet of document, snapshot, and data (data may be `undefined` if the document doesn't exist)
  */
 export declare function getDocumentSnapshotDataPair<D extends FirestoreDocument<any>>(document: D): Promise<FirestoreDocumentSnapshotDataPair<D>>;
 /**
- * Creates document-snapshot-data triplets for an array of documents in parallel.
+ * Fetches snapshot-data triplets for multiple documents in parallel.
  *
- * Fetches the current snapshot of each document, extracts its data with ID and key fields,
- * and returns triplets containing all three components for each document.
+ * Processes up to 200 documents concurrently via {@link runAsyncTasksForValues}.
+ * The returned array preserves the same ordering as the input.
  *
- * @template D - The FirestoreDocument implementation type
- * @param documents - Array of document instances to get data for
- * @returns Promise that resolves to an array of document-snapshot-data triplets in the same order as the input documents
+ * @param documents - Documents to fetch
+ * @returns Triplets in the same order as the input array
  */
 export declare function getDocumentSnapshotDataPairs<D extends FirestoreDocument<any>>(documents: D[]): Promise<FirestoreDocumentSnapshotDataPair<D>[]>;
 /**
- * Creates document-snapshot-data triplets for an array of documents and filters out those without data.
+ * Fetches snapshot-data triplets for multiple documents and filters out those that don't exist in Firestore.
  *
- * This is a convenience function that fetches data for all documents and then returns
- * only the triplets for documents that actually exist in Firestore.
+ * Convenience wrapper around {@link getDocumentSnapshotDataPairs} that removes entries where `data` is nullish,
+ * returning only {@link FirestoreDocumentSnapshotDataPairWithData} results.
  *
- * @template D - The FirestoreDocument implementation type
- * @param documents - Array of document instances to get data for
- * @returns Promise that resolves to an array of document-snapshot-data triplets for existing documents only
+ * @param documents - Documents to fetch
+ * @returns Triplets for documents that exist, in their original relative order
  */
 export declare function getDocumentSnapshotDataPairsWithData<D extends FirestoreDocument<any>>(documents: D[]): Promise<FirestoreDocumentSnapshotDataPairWithData<D>[]>;
+/**
+ * A tuple of `[document, data]` where `data` is the raw snapshot data (without `id`/`key` injection)
+ * or `undefined` if the document doesn't exist.
+ */
 export type FirestoreDocumentSnapshotDataTuple<D extends FirestoreDocument<any>> = [D, Maybe<FirestoreDocumentData<D>>];
+/**
+ * Fetches raw snapshot data tuples for multiple documents in parallel.
+ *
+ * Unlike {@link getDocumentSnapshotDataPairs}, this returns a lightweight `[document, data]` tuple
+ * and does not inject `id`/`key` fields onto the data. The `data` value is the raw result of
+ * `snapshot.data()` and may be `undefined` for non-existent documents.
+ *
+ * @param documents - Documents to fetch
+ * @returns Tuples in the same order as the input array
+ */
 export declare function getDocumentSnapshotDataTuples<D extends FirestoreDocument<any>>(documents: D[]): Promise<FirestoreDocumentSnapshotDataTuple<D>[]>;
+/**
+ * Fetches the data from a single document's snapshot.
+ *
+ * By default (`withId=true`), the returned data has `id` and `key` fields injected via
+ * {@link documentDataWithIdAndKey}. Pass `withId=false` to get the raw snapshot data instead.
+ *
+ * Returns `undefined` if the document does not exist.
+ *
+ * @param document - The document to fetch data for
+ * @param withId - Whether to inject `id` and `key` fields onto the data (default: `true`)
+ * @returns The document's data, or `undefined` if it doesn't exist
+ */
 export declare function getDocumentSnapshotData<D extends FirestoreDocument<any>>(document: D): Promise<Maybe<DocumentDataWithIdAndKey<FirestoreDocumentData<D>>>>;
 export declare function getDocumentSnapshotData<D extends FirestoreDocument<any>>(document: D, withId: true): Promise<Maybe<DocumentDataWithIdAndKey<FirestoreDocumentData<D>>>>;
 export declare function getDocumentSnapshotData<D extends FirestoreDocument<any>>(document: D, withId: false): Promise<Maybe<FirestoreDocumentData<D>>>;
 export declare function getDocumentSnapshotData<D extends FirestoreDocument<any>>(document: D, withId?: boolean): Promise<Maybe<DocumentDataWithIdAndKey<FirestoreDocumentData<D>> | FirestoreDocumentData<D>>>;
+/**
+ * Fetches data for multiple documents in parallel, filtering out non-existent documents.
+ *
+ * By default (`withId=true`), each data object has `id` and `key` fields injected.
+ * Documents that don't exist in Firestore are excluded from the results (the returned
+ * array may be shorter than the input).
+ *
+ * @param documents - Documents to fetch data for
+ * @param withId - Whether to inject `id` and `key` fields onto each data object (default: `true`)
+ * @returns Data objects for existing documents only
+ */
 export declare function getDocumentSnapshotsData<D extends FirestoreDocument<any>>(documents: D[]): Promise<DocumentDataWithIdAndKey<FirestoreDocumentData<D>>[]>;
 export declare function getDocumentSnapshotsData<D extends FirestoreDocument<any>>(documents: D[], withId: true): Promise<DocumentDataWithIdAndKey<FirestoreDocumentData<D>>[]>;
 export declare function getDocumentSnapshotsData<D extends FirestoreDocument<any>>(documents: D[], withId: false): Promise<FirestoreDocumentData<D>[]>;
 export declare function getDocumentSnapshotsData<D extends FirestoreDocument<any>>(documents: D[], withId?: boolean): Promise<DocumentDataWithIdAndKey<FirestoreDocumentData<D>>[] | FirestoreDocumentData<D>[]>;
 /**
- * Returns the data from all input snapshots. Snapshots without data are filtered out.
+ * Extracts data from an array of {@link DocumentSnapshot}s, filtering out snapshots for non-existent documents.
  *
- * @param snapshots
+ * By default (`withId=true`), each data object has `id` and `key` fields injected via {@link documentDataWithIdAndKey}.
+ * Snapshots where `data()` returns `undefined` are removed from the output via {@link filterMaybeArrayValues}.
+ *
+ * @param snapshots - Snapshots to extract data from
+ * @param withId - Whether to inject `id` and `key` fields onto each data object (default: `true`)
+ * @returns Data objects for existing documents only (may be shorter than input)
  */
 export declare function getDataFromDocumentSnapshots<T>(snapshots: DocumentSnapshot<T>[]): DocumentDataWithIdAndKey<T>[];
 export declare function getDataFromDocumentSnapshots<T>(snapshots: DocumentSnapshot<T>[], withId: true): DocumentDataWithIdAndKey<T>[];
 export declare function getDataFromDocumentSnapshots<T>(snapshots: DocumentSnapshot<T>[], withId: false): T[];
 export declare function getDataFromDocumentSnapshots<T>(snapshots: DocumentSnapshot<T>[], withId?: boolean): DocumentDataWithIdAndKey<T>[] | T[];
+/**
+ * Creates {@link FirestoreDocument} instances for all documents in a {@link QuerySnapshot}.
+ *
+ * Maps each document in `snapshots.docs` to a loaded document via `accessor.loadDocument(ref)`.
+ * No additional data fetching occurs; the documents are loaded from their existing references.
+ *
+ * @param accessor - Accessor to load documents with
+ * @param snapshots - Query snapshot containing the document references
+ * @returns Document instances in the same order as the query results
+ */
 export declare function loadDocumentsForSnapshots<T, D extends FirestoreDocument<T>>(accessor: LimitedFirestoreDocumentAccessor<T, D>, snapshots: QuerySnapshot<T>): D[];
+/**
+ * Extracts {@link DocumentReference}s from arbitrary values and loads them as {@link FirestoreDocument} instances.
+ *
+ * Convenience function that maps values through `getRef` then delegates to {@link loadDocumentsForDocumentReferences}.
+ *
+ * @param accessor - Accessor to load documents with
+ * @param values - Source values to extract references from
+ * @param getRef - Extracts a document reference from each value
+ * @returns Document instances in the same order as the input values
+ */
 export declare function loadDocumentsForDocumentReferencesFromValues<I, T, D extends FirestoreDocument<T>>(accessor: LimitedFirestoreDocumentAccessor<T, D>, values: I[], getRef: (value: I) => DocumentReference<T>): D[];
+/**
+ * Alias for {@link loadDocumentsForDocumentReferencesFromValues}.
+ */
 export declare const loadDocumentsForValues: typeof loadDocumentsForDocumentReferencesFromValues;
+/**
+ * Loads {@link FirestoreDocument} instances from an array of {@link DocumentReference}s.
+ *
+ * Each reference is passed to `accessor.loadDocument()` to create a document wrapper.
+ * No network calls are made; this only creates in-memory document instances bound to the given references.
+ *
+ * @param accessor - Accessor to load documents with
+ * @param refs - Document references to load
+ * @returns Document instances in the same order as the input references
+ */
 export declare function loadDocumentsForDocumentReferences<T, D extends FirestoreDocument<T>>(accessor: LimitedFirestoreDocumentAccessor<T, D>, refs: DocumentReference<T>[]): D[];
+/**
+ * Extracts {@link FirestoreModelKey}s from arbitrary values and loads them as {@link FirestoreDocument} instances.
+ *
+ * Convenience function that maps values through `getKey` then delegates to {@link loadDocumentsForKeys}.
+ *
+ * @param accessor - Accessor to load documents with
+ * @param values - Source values to extract keys from
+ * @param getKey - Extracts a model key (full Firestore path) from each value
+ * @returns Document instances in the same order as the input values
+ */
 export declare function loadDocumentsForKeysFromValues<I, T, D extends FirestoreDocument<T>>(accessor: LimitedFirestoreDocumentAccessor<T, D>, values: I[], getKey: (value: I) => FirestoreModelKey): D[];
+/**
+ * Loads {@link FirestoreDocument} instances from an array of full Firestore document paths (keys).
+ *
+ * Each key is passed to `accessor.loadDocumentForKey()`. No network calls are made.
+ *
+ * @param accessor - Accessor to load documents with
+ * @param keys - Full Firestore document paths (e.g. `'users/abc123'`)
+ * @returns Document instances in the same order as the input keys
+ */
 export declare function loadDocumentsForKeys<T, D extends FirestoreDocument<T>>(accessor: LimitedFirestoreDocumentAccessor<T, D>, keys: FirestoreModelKey[]): D[];
+/**
+ * Extracts {@link FirestoreModelId}s from arbitrary values and loads them as {@link FirestoreDocument} instances.
+ *
+ * Convenience function that maps values through `getId` then delegates to {@link loadDocumentsForIds}.
+ * Requires a full {@link FirestoreDocumentAccessor} (not limited) because loading by ID requires collection context.
+ *
+ * @param accessor - Accessor to load documents with (must have collection context for ID resolution)
+ * @param values - Source values to extract IDs from
+ * @param getId - Extracts a model ID from each value
+ * @returns Document instances in the same order as the input values
+ */
 export declare function loadDocumentsForIdsFromValues<I, T, D extends FirestoreDocument<T>>(accessor: FirestoreDocumentAccessor<T, D>, values: I[], getId: (value: I) => FirestoreModelId): D[];
+/**
+ * Loads {@link FirestoreDocument} instances from an array of document IDs relative to the accessor's collection.
+ *
+ * Each ID is passed to `accessor.loadDocumentForId()`. Requires a full {@link FirestoreDocumentAccessor}
+ * because ID-based loading needs the collection reference to resolve the full path. No network calls are made.
+ *
+ * @param accessor - Accessor to load documents with (must have collection context)
+ * @param ids - Document IDs within the accessor's collection
+ * @returns Document instances in the same order as the input IDs
+ */
 export declare function loadDocumentsForIds<T, D extends FirestoreDocument<T>>(accessor: FirestoreDocumentAccessor<T, D>, ids: FirestoreModelId[]): D[];
 /**
- * Used for loading documents for the input references.
+ * Function type that loads {@link FirestoreDocument} instances from {@link DocumentReference}s.
+ *
+ * When a {@link Transaction} is provided, the returned documents are bound to that transaction's accessor,
+ * ensuring reads/writes participate in the transaction. Otherwise, the default accessor is used.
  */
 export type FirestoreDocumentLoader<T, D extends FirestoreDocument<T>> = (references: DocumentReference<T>[], transaction?: Transaction) => D[];
 /**
- * Used to make a FirestoreDocumentLoader.
+ * Creates a {@link FirestoreDocumentLoader} from a {@link LimitedFirestoreDocumentAccessorContextExtension}.
  *
- * @param accessorContext
- * @returns
+ * The returned loader resolves the appropriate accessor based on whether a transaction is provided,
+ * then delegates to {@link loadDocumentsForDocumentReferences}.
+ *
+ * @param accessorContext - Context that provides accessors for both default and transactional use
+ * @returns A loader function that converts document references to document instances
  */
 export declare function firestoreDocumentLoader<T, D extends FirestoreDocument<T>>(accessorContext: LimitedFirestoreDocumentAccessorContextExtension<T, D>): FirestoreDocumentLoader<T, D>;
 /**
- * Used for loading documents for the input snapshots.
+ * Function type that converts {@link DocumentSnapshot}s into {@link FirestoreDocumentSnapshotDataPair}s.
+ *
+ * Loads a document for each snapshot's reference and extracts data with `id`/`key` fields.
+ * When a {@link Transaction} is provided, documents are bound to that transaction's accessor.
  */
 export type FirestoreDocumentSnapshotPairsLoader<T, D extends FirestoreDocument<T>> = (snapshots: DocumentSnapshot<T>[], transaction?: Transaction) => FirestoreDocumentSnapshotDataPair<D>[];
 /**
- * Used for loading documents for the input query snapshots. Query snapshots always contain data.
+ * Variant of {@link FirestoreDocumentSnapshotPairsLoader} for {@link QueryDocumentSnapshot}s.
+ *
+ * Since query snapshots always contain data, the returned pairs use
+ * {@link FirestoreDocumentSnapshotDataPairWithData} where `data` is guaranteed non-nullish.
  */
 export type FirestoreQueryDocumentSnapshotPairsLoader<T, D extends FirestoreDocument<T>> = (snapshots: QueryDocumentSnapshot<T>[], transaction?: Transaction) => FirestoreDocumentSnapshotDataPairWithData<D>[];
 /**
- * Used to make a FirestoreDocumentSnapshotPairsLoader.
+ * Creates a {@link FirestoreDocumentSnapshotPairsLoader} from a {@link LimitedFirestoreDocumentAccessorContextExtension}.
+ *
+ * The returned loader resolves the appropriate accessor based on whether a transaction is provided,
+ * then maps each snapshot to a {@link FirestoreDocumentSnapshotDataPair} using {@link firestoreDocumentSnapshotPairsLoaderInstance}.
  *
- * @param accessorContext
- * @returns
+ * Also satisfies the {@link FirestoreQueryDocumentSnapshotPairsLoader} type since the implementation
+ * handles both {@link DocumentSnapshot} and {@link QueryDocumentSnapshot} inputs.
+ *
+ * @param accessorContext - Context that provides accessors for both default and transactional use
+ * @returns A loader function that converts snapshots to document-snapshot-data pairs
  */
 export declare function firestoreDocumentSnapshotPairsLoader<T, D extends FirestoreDocument<T>>(accessorContext: LimitedFirestoreDocumentAccessorContextExtension<T, D>): FirestoreDocumentSnapshotPairsLoader<T, D> & FirestoreQueryDocumentSnapshotPairsLoader<T, D>;
 /**
- * Used for loading a FirestoreDocumentSnapshotDataPair for the input snapshot. The accessor is already available given the context.
+ * A callable that converts a single snapshot into a {@link FirestoreDocumentSnapshotDataPair},
+ * with the accessor already bound.
+ *
+ * Overloaded: when given a {@link QueryDocumentSnapshot} (which always has data), returns
+ * {@link FirestoreDocumentSnapshotDataPairWithData}. When given a {@link DocumentSnapshot},
+ * returns the base {@link FirestoreDocumentSnapshotDataPair} where `data` may be `undefined`.
+ *
+ * Exposes `_accessor` for inspection of the bound accessor.
  */
 export type FirestoreDocumentSnapshotPairsLoaderInstance<T, D extends FirestoreDocument<T>> = (((snapshot: QueryDocumentSnapshot<T>) => FirestoreDocumentSnapshotDataPairWithData<D>) & ((snapshots: DocumentSnapshot<T>) => FirestoreDocumentSnapshotDataPair<D>)) & {
     readonly _accessor: LimitedFirestoreDocumentAccessor<T, D>;
 };
 /**
- * Used to make a FirestoreDocumentSnapshotPairsLoader.
+ * Creates a {@link FirestoreDocumentSnapshotPairsLoaderInstance} bound to a specific accessor.
+ *
+ * The returned function converts a snapshot into a {@link FirestoreDocumentSnapshotDataPair} by:
+ * 1. Extracting data with `id`/`key` fields via {@link documentDataWithIdAndKey}
+ * 2. Loading the document from the snapshot's reference via `accessor.loadDocument()`
+ * 3. Combining all three into a single pair object
  *
- * @param accessorContext
- * @returns
+ * @param accessor - The accessor to bind for document loading
+ * @returns A reusable function that converts snapshots to pairs using the bound accessor
  */
 export declare function firestoreDocumentSnapshotPairsLoaderInstance<T, D extends FirestoreDocument<T>>(accessor: LimitedFirestoreDocumentAccessor<T, D>): FirestoreDocumentSnapshotPairsLoaderInstance<T, D>;
 /**
- * Used to make a FirestoreQueryDocumentSnapshotPairsLoader.
+ * Alias for {@link firestoreDocumentSnapshotPairsLoader}, typed specifically as a {@link FirestoreQueryDocumentSnapshotPairsLoader}.
  *
- * @param accessorContext
- * @returns
+ * Use this when you know all input snapshots are from a query and want the stronger return type
+ * that guarantees `data` is non-nullish.
  */
 export declare const firestoreQueryDocumentSnapshotPairsLoader: <T, D extends FirestoreDocument<T>>(accessorContext: LimitedFirestoreDocumentAccessorContextExtension<T, D>) => FirestoreQueryDocumentSnapshotPairsLoader<T, D>;
 /**
- * Creates the document data from the snapshot.
+ * Extracts data from a {@link DocumentSnapshot}, optionally injecting `id` and `key` fields.
  *
- * @param snapshot
- * @returns
+ * When `withId` is `true` (default is `false`), delegates to {@link documentDataWithIdAndKey} to mutate
+ * the data object with `id` (document ID) and `key` (full document path). When `false`, returns the
+ * raw result of `snapshot.data()`.
+ *
+ * For {@link QueryDocumentSnapshot} inputs, the return value is guaranteed non-nullish.
+ * For {@link DocumentSnapshot} inputs, may return `undefined` if the document doesn't exist.
+ *
+ * @param snapshot - The snapshot to extract data from
+ * @param withId - Whether to inject `id` and `key` fields (default: `false`)
+ * @returns The snapshot data, or `undefined` for non-existent documents
  */
 export declare function documentData<T>(snapshot: QueryDocumentSnapshot<T>): DocumentDataWithIdAndKey<T>;
 export declare function documentData<T>(snapshot: QueryDocumentSnapshot<T>, withId: true): DocumentDataWithIdAndKey<T>;
@@ -251,51 +387,226 @@ export declare function documentData<T>(snapshot: QueryDocumentSnapshot<T>, with
 export declare function documentData<T>(snapshot: DocumentSnapshot<T>): Maybe<DocumentDataWithIdAndKey<T>>;
 export declare function documentData<T>(snapshot: DocumentSnapshot<T>, withId: true): Maybe<DocumentDataWithIdAndKey<T>>;
 export declare function documentData<T>(snapshot: DocumentSnapshot<T>, withId: false): Maybe<T>;
+/**
+ * Function type that extracts raw data from a snapshot. Returns `undefined` for non-existent documents.
+ */
 export type DocumentDataFunction<T> = ((snapshot: QueryDocumentSnapshot<T>) => T) & ((snapshot: DocumentSnapshot<T>) => Maybe<T>);
+/**
+ * Function type that extracts data from a snapshot with `id` and `key` fields injected.
+ * Returns `undefined` for non-existent documents.
+ */
 export type DocumentDataWithIdAndKeyFunction<T> = ((snapshot: QueryDocumentSnapshot<T>) => DocumentDataWithIdAndKey<T>) & ((snapshot: DocumentSnapshot<T>) => Maybe<DocumentDataWithIdAndKey<T>>);
+/**
+ * Returns a data extraction function based on whether `id`/`key` injection is desired.
+ *
+ * When `withId` is `true`, returns {@link documentDataWithIdAndKey} (a {@link DocumentDataWithIdAndKeyFunction}).
+ * When `false`, returns a simple `snapshot.data()` wrapper (a {@link DocumentDataFunction}).
+ *
+ * Useful for creating reusable mappers when processing arrays of snapshots.
+ *
+ * @param withId - Whether the returned function should inject `id` and `key` fields
+ * @returns A snapshot-to-data extraction function
+ */
 export declare function documentDataFunction<T>(withId: true): DocumentDataWithIdAndKeyFunction<T>;
 export declare function documentDataFunction<T>(withId: false): DocumentDataFunction<T>;
 export declare function documentDataFunction<T>(withId: boolean): DocumentDataWithIdAndKeyFunction<T> | DocumentDataFunction<T>;
 /**
- * Creates a DocumentDataWithId from the input DocumentSnapshot. If the data does not exist, returns undefined.
+ * Extracts data from a {@link DocumentSnapshot} and mutates it to include `id` and `key` fields.
+ *
+ * The `id` is set to `snapshot.id` (the document's ID within its collection) and `key` is set
+ * to `snapshot.ref.path` (the full Firestore document path). The mutation is performed in-place
+ * on the data object returned by `snapshot.data()`.
  *
- * @param snapshot
- * @returns
+ * For {@link QueryDocumentSnapshot} inputs, the return value is guaranteed non-nullish.
+ * Returns `undefined` if the document does not exist (i.e. `snapshot.data()` returns falsy).
+ *
+ * @param snapshot - The snapshot to extract and augment data from
+ * @returns The data object with `id` and `key` fields, or `undefined` if the document doesn't exist
  */
 export declare function documentDataWithIdAndKey<T>(snapshot: QueryDocumentSnapshot<T>): DocumentDataWithIdAndKey<T>;
 export declare function documentDataWithIdAndKey<T>(snapshot: DocumentSnapshot<T>): Maybe<DocumentDataWithIdAndKey<T>>;
 /**
- * Sets the id and key values from the snapshot onto the input data.
+ * Mutates the input data object to include `id` and `key` fields from a {@link DocumentSnapshot}.
+ *
+ * Sets `data.id` to `snapshot.id` and `data.key` to `snapshot.ref.path`. The data object
+ * is modified in-place and also returned for chaining convenience.
  *
- * @param data
- * @param snapshot
- * @returns
+ * @param data - The data object to augment (mutated in-place)
+ * @param snapshot - Source of the `id` and `key` values
+ * @returns The same data object, now typed as {@link DocumentDataWithIdAndKey}
  */
 export declare function setIdAndKeyFromSnapshotOnDocumentData<T>(data: T, snapshot: DocumentSnapshot<T>): DocumentDataWithIdAndKey<T>;
 /**
- * Sets the id and key values from the snapshot onto the input data.
+ * Mutates the input data object to include `id` and `key` fields from a model reference.
  *
- * @param data
- * @param snapshot
- * @returns
+ * Similar to {@link setIdAndKeyFromSnapshotOnDocumentData}, but sources the values from a
+ * {@link FirestoreModelKeyRef} & {@link FirestoreModelIdRef} instead of a snapshot.
+ * The data object is modified in-place and also returned for chaining convenience.
+ *
+ * @param data - The data object to augment (mutated in-place)
+ * @param modelRef - Source of the `id` and `key` values
+ * @returns The same data object, now typed as {@link DocumentDataWithIdAndKey}
  */
 export declare function setIdAndKeyFromKeyIdRefOnDocumentData<T>(data: T, modelRef: FirestoreModelKeyRef & FirestoreModelIdRef): DocumentDataWithIdAndKey<T>;
 /**
- * MappedUseAsyncFunction to load a snapshot from the input document and use it.
+ * Fetches a document's snapshot and passes it to a `use` callback, following the {@link UseAsync} pattern.
+ *
+ * If `document` is nullish, the `use` callback is not invoked and `defaultValue` is returned instead.
+ * If `document` exists but the snapshot is nullish (shouldn't happen in practice), `defaultValue` is also used.
  *
- * @param document
- * @param use
- * @param defaultValue
- * @returns
+ * @param document - The document to fetch, or nullish to skip
+ * @param use - Callback that receives the fetched snapshot and returns a result
+ * @param defaultValue - Fallback value when `document` is nullish or the snapshot is unavailable
+ * @returns The result of `use`, or the default value
  */
 export declare function useDocumentSnapshot<D extends FirestoreDocument<any>, O = void>(document: Maybe<D>, use: UseAsync<DocumentSnapshot<FirestoreDocumentData<D>>, O>, defaultValue?: Maybe<AsyncGetterOrValue<O>>): Promise<Maybe<O>>;
 /**
- * MappedUseAsyncFunction to load snapshot data from the input document and use it.
+ * Fetches a document's snapshot data (via `snapshot.data()`) and passes it to a `use` callback.
+ *
+ * Wraps {@link useDocumentSnapshot} with a mapping step that extracts raw data from the snapshot.
+ * If the document doesn't exist (data is `undefined`), the `use` callback is not invoked
+ * and `defaultValue` is returned instead.
+ *
+ * @param document - The document to fetch, or nullish to skip
+ * @param use - Callback that receives the snapshot data and returns a result
+ * @param defaultValue - Fallback value when the document is nullish or doesn't exist
+ * @returns The result of `use`, or the default value
  */
 export declare const useDocumentSnapshotData: <D extends FirestoreDocument<any>, O = void>(document: Maybe<D>, use: UseAsync<FirestoreDocumentData<D>, O>, defaultValue?: Maybe<AsyncGetterOrValue<O>>) => Promise<Maybe<O>>;
+/**
+ * Extracts the document ID ({@link FirestoreModelId}) from a {@link FirestoreDocument}.
+ *
+ * Useful as a mapper function, e.g. `documents.map(firestoreModelIdFromDocument)`.
+ *
+ * @param document - The document to extract the ID from
+ * @returns The document's ID (the last segment of its Firestore path)
+ */
 export declare function firestoreModelIdFromDocument<T, D extends FirestoreDocument<T>>(document: D): FirestoreModelId;
+/**
+ * Extracts document IDs from an array of {@link FirestoreDocument}s.
+ *
+ * @param documents - Documents to extract IDs from
+ * @returns Array of document IDs in the same order as the input
+ */
 export declare function firestoreModelIdsFromDocuments<T, D extends FirestoreDocument<T>>(documents: D[]): FirestoreModelId[];
+/**
+ * Extracts the full Firestore path ({@link FirestoreModelKey}) from a {@link FirestoreDocument}.
+ *
+ * Useful as a mapper function, e.g. `documents.map(firestoreModelKeyFromDocument)`.
+ *
+ * @param document - The document to extract the key from
+ * @returns The document's full Firestore path (e.g. `'users/abc123'`)
+ */
 export declare function firestoreModelKeyFromDocument<T, D extends FirestoreDocument<T>>(document: D): FirestoreModelKey;
+/**
+ * Extracts full Firestore paths from an array of {@link FirestoreDocument}s.
+ *
+ * @param documents - Documents to extract keys from
+ * @returns Array of full Firestore paths in the same order as the input
+ */
 export declare function firestoreModelKeysFromDocuments<T, D extends FirestoreDocument<T>>(documents: D[]): FirestoreModelKey[];
+/**
+ * Extracts the {@link DocumentReference} from a {@link FirestoreDocument}.
+ *
+ * Useful as a mapper function, e.g. `documents.map(documentReferenceFromDocument)`.
+ *
+ * @param document - The document to extract the reference from
+ * @returns The underlying Firestore document reference
+ */
 export declare function documentReferenceFromDocument<T, D extends FirestoreDocument<T>>(document: D): DocumentReference<T>;
+/**
+ * Extracts {@link DocumentReference}s from an array of {@link FirestoreDocument}s.
+ *
+ * @param documents - Documents to extract references from
+ * @returns Array of document references in the same order as the input
+ */
 export declare function documentReferencesFromDocuments<T, D extends FirestoreDocument<T>>(documents: D[]): DocumentReference<T>[];
+/**
+ * An in-memory snapshot cache backed by a {@link LimitedFirestoreDocumentAccessor} that deduplicates
+ * Firestore reads for the same document key within a single operation scope.
+ *
+ * The cache is keyed by {@link FirestoreModelKey} (full Firestore path) and stores the in-flight or
+ * resolved {@link FirestoreDocumentSnapshotDataPair} promises. This ensures that concurrent or repeated
+ * requests for the same document reuse a single Firestore read.
+ *
+ * Does not implement {@link LimitedFirestoreDocumentAccessor} itself — it is a higher-level abstraction
+ * that wraps an accessor to provide cached snapshot reads. The underlying accessor is exposed via
+ * the {@link accessor} property for direct use when needed.
+ *
+ * Useful in batch processing or fan-out scenarios where multiple code paths may reference the same
+ * documents and you want to avoid redundant reads without manual deduplication.
+ *
+ * @example
+ * ```typescript
+ * const cache = limitedFirestoreDocumentAccessorSnapshotCache(accessor);
+ *
+ * // Both calls resolve from a single Firestore read
+ * const [pair1, pair2] = await Promise.all([
+ *   cache.getDocumentSnapshotDataPairForKey('users/abc123'),
+ *   cache.getDocumentSnapshotDataPairForKey('users/abc123')
+ * ]);
+ * ```
+ */
+export interface LimitedFirestoreDocumentAccessorSnapshotCache<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> {
+    /**
+     * The underlying accessor used to load documents and fetch snapshots.
+     */
+    readonly accessor: LimitedFirestoreDocumentAccessor<T, D>;
+    /**
+     * Fetches or returns the cached {@link FirestoreDocumentSnapshotDataPair} for the given key.
+     *
+     * @param key - Full Firestore document path (e.g. `'users/abc123'`)
+     * @returns The document, its snapshot, and extracted data (data may be `undefined` if the document doesn't exist)
+     */
+    getDocumentSnapshotDataPairForKey(key: FirestoreModelKey): Promise<FirestoreDocumentSnapshotDataPair<D>>;
+    /**
+     * Fetches or returns cached {@link FirestoreDocumentSnapshotDataPair}s for multiple keys.
+     *
+     * Each key is resolved independently through the cache, so previously fetched documents are not re-read.
+     *
+     * @param keys - Full Firestore document paths
+     * @returns Pairs in the same order as the input keys
+     */
+    getDocumentSnapshotDataPairsForKeys(keys: FirestoreModelKey[]): Promise<FirestoreDocumentSnapshotDataPair<D>[]>;
+    /**
+     * Fetches or returns cached pairs for multiple keys, filtering out non-existent documents.
+     *
+     * Convenience method that delegates to {@link getDocumentSnapshotDataPairsForKeys} and removes entries
+     * where `data` is nullish, returning only {@link FirestoreDocumentSnapshotDataPairWithData} results.
+     *
+     * @param keys - Full Firestore document paths
+     * @returns Pairs for existing documents only, in their original relative order
+     */
+    getDocumentSnapshotDataPairsWithDataForKeys(keys: FirestoreModelKey[]): Promise<FirestoreDocumentSnapshotDataPairWithData<D>[]>;
+}
+/**
+ * Creates a {@link LimitedFirestoreDocumentAccessorSnapshotCache} that wraps the given accessor
+ * with an in-memory {@link Map} cache so that repeated loads for the same key return the cached
+ * promise instead of re-reading from Firestore.
+ *
+ * The cache stores the promise itself (not the resolved value), which means concurrent requests
+ * for the same key that arrive before the first read completes will also be deduplicated.
+ *
+ * The cache lives for the lifetime of the returned object and is never invalidated, so this is
+ * best suited for short-lived scopes (e.g. a single request or batch operation) where stale reads
+ * are acceptable.
+ *
+ * @param accessor - The accessor to wrap with caching behavior
+ * @returns A {@link LimitedFirestoreDocumentAccessorSnapshotCache} backed by the given accessor
+ *
+ * @example
+ * ```typescript
+ * const cache = limitedFirestoreDocumentAccessorSnapshotCache(accessor);
+ *
+ * // First call reads from Firestore; second call returns cached result
+ * const pair = await cache.getDocumentSnapshotDataPairForKey('users/abc123');
+ * const samePair = await cache.getDocumentSnapshotDataPairForKey('users/abc123');
+ *
+ * // Batch fetch with automatic deduplication
+ * const pairs = await cache.getDocumentSnapshotDataPairsWithDataForKeys(['users/abc', 'users/def']);
+ *
+ * // Access the underlying accessor directly
+ * const doc = cache.accessor.loadDocumentForKey('users/xyz');
+ * ```
+ */
+export declare function limitedFirestoreDocumentAccessorSnapshotCache<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(accessor: LimitedFirestoreDocumentAccessor<T, D>): LimitedFirestoreDocumentAccessorSnapshotCache<T, D>;