@dereekb/firebase 13.0.6 → 13.0.7

package/index.cjs.js

@@ -1093,6 +1093,61 @@ function documentReferenceFromDocument(document) {
 function documentReferencesFromDocuments(documents) {
     return documents.map(documentReferenceFromDocument);
 }
+/**
+ * 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');
+ * ```
+ */
+function limitedFirestoreDocumentAccessorSnapshotCache(accessor) {
+    const cache = new Map();
+    function getDocumentSnapshotDataPairForKey(key) {
+        let cached = cache.get(key);
+        if (!cached) {
+            const document = accessor.loadDocumentForKey(key);
+            cached = getDocumentSnapshotDataPair(document);
+            cache.set(key, cached);
+        }
+        return cached;
+    }
+    async function getDocumentSnapshotDataPairsForKeys(keys) {
+        return Promise.all(keys.map((key) => getDocumentSnapshotDataPairForKey(key)));
+    }
+    async function getDocumentSnapshotDataPairsWithDataForKeys(keys) {
+        const pairs = await getDocumentSnapshotDataPairsForKeys(keys);
+        return util.filterMaybeArrayValues(pairs.map((pair) => (pair.data != null ? pair : undefined)));
+    }
+    return {
+        accessor,
+        getDocumentSnapshotDataPairForKey,
+        getDocumentSnapshotDataPairsForKeys,
+        getDocumentSnapshotDataPairsWithDataForKeys
+    };
+}
 
 /**
  * Creates an Observable that emits arrays of document snapshots for multiple documents.
@@ -1142,7 +1197,7 @@ function mapLatestSnapshotsFromDocuments(documents, operator) {
  * @param documents - Array of document instances to stream data for
  * @returns Observable that emits arrays of document data whenever any document changes
  */
-function latestDataFromDocuments(documents) {
+function streamDocumentSnapshotsData(documents) {
     return latestSnapshotsFromDocuments(documents).pipe(dataFromDocumentSnapshots());
 }
 /**
@@ -1200,6 +1255,11 @@ function streamDocumentSnapshotDataPairs(documents) {
 function streamDocumentSnapshotDataPairsWithData(documents) {
     return streamDocumentSnapshotDataPairs(documents).pipe(rxjs$1.map((pairs) => pairs.filter((pair) => pair.data != null)));
 }
+// MARK: Compat
+/**
+ * @deprecated Use {@link streamDocumentSnapshotsData} instead.
+ */
+const latestDataFromDocuments = streamDocumentSnapshotsData;
 
 // A set of copied types from @google-cloud/firestore and firebase/firestore to allow cross-compatability.
 /* eslint-disable */
@@ -2355,20 +2415,14 @@ function firebaseQueryItemAccumulator(iteration, mapItem) {
 }
 
 /**
- * Creates a Firestore query constraint.
+ * Creates a {@link FirestoreQueryConstraint} with the given type identifier and data.
  *
- * @template T - Type of data stored in the constraint
- * @param type - The constraint type identifier
- * @param data - The constraint data
- * @returns A Firestore query constraint object
- */
-/**
- * Creates a Firestore query constraint.
+ * This is the low-level factory used by all constraint builder functions (e.g., {@link where},
+ * {@link limit}, {@link orderBy}). Most callers should use those typed builders instead.
  *
- * @template T - Type of data stored in the constraint
- * @param type - The constraint type identifier
- * @param data - The constraint data
- * @returns A Firestore query constraint object
+ * @param type - The constraint type identifier (e.g., 'where', 'limit')
+ * @param data - The constraint-specific configuration data
+ * @returns A typed constraint object
  */
 function firestoreQueryConstraint(type, data) {
     return {
@@ -2868,6 +2922,17 @@ function filterDisallowedFirestoreItemPageIteratorInputConstraints(constraints)
  * This value is used when no itemsPerPage is explicitly specified in the configuration.
  */
 const DEFAULT_FIRESTORE_ITEM_PAGE_ITERATOR_ITEMS_PER_PAGE = 50;
+/**
+ * Creates a {@link FirestoreItemPageIteratorDelegate} that handles cursor-based Firestore pagination.
+ *
+ * The delegate implements `loadItemsForPage` by:
+ * 1. Retrieving the cursor document from the previous page's results
+ * 2. Building a query with the configured constraints, `startAfter` cursor, and `limit`
+ * 3. Executing the query and wrapping the results in a {@link FirestoreItemPageQueryResult}
+ *    with `reload()` and `stream()` capabilities
+ *
+ * @returns A delegate instance for use with {@link ItemPageIterator}
+ */
 function makeFirestoreItemPageIteratorDelegate() {
     return {
         loadItemsForPage: (request) => {
@@ -3025,7 +3090,14 @@ function _firestoreItemPageIterationWithSnapshotIteration(snapshotIteration) {
     return result;
 }
 /**
- * Creates a FirestoreFixedItemPageIterationFactoryFunction.
+ * Creates a factory function for generating fixed-set Firestore pagination instances.
+ *
+ * The returned factory takes an array of document references and an optional filter,
+ * 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
  */
 function firestoreFixedItemPageIterationFactory(baseConfig, documentAccessor) {
     return (items, filter) => {
@@ -3042,7 +3114,17 @@ function firestoreFixedItemPageIterationFactory(baseConfig, documentAccessor) {
     };
 }
 /**
- * Creates a FirestoreItemPageIterationInstance that iterates over the fixed
+ * Creates a pagination instance that iterates over a fixed set of document references.
+ *
+ * Unlike {@link firestoreItemPageIteration} which queries Firestore dynamically, this function
+ * paginates through a pre-determined list of document references. Each page loads the next
+ * slice of references via the document accessor and produces a synthetic {@link QuerySnapshot}.
+ *
+ * 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
  */
 function firestoreFixedItemPageIteration(config) {
     const { items, documentAccessor } = config;
@@ -3259,24 +3341,47 @@ function readFirestoreModelKeyFromDocumentSnapshot(snapshot) {
 /**
  * @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.
+ * Provides a layered system for iterating through Firestore query results using
+ * cursor-based pagination ("checkpoints"). Each layer adds convenience on top of the
+ * one below:
+ *
+ * 1. **Checkpoints** ({@link iterateFirestoreDocumentSnapshotCheckpoints}) — core pagination engine
+ * 2. **Batches** ({@link iterateFirestoreDocumentSnapshotBatches}) — subdivides checkpoints into fixed-size batches
+ * 3. **Snapshots** ({@link iterateFirestoreDocumentSnapshots}) — processes individual snapshots
+ * 4. **Pairs** ({@link iterateFirestoreDocumentSnapshotPairs}) — loads typed document wrappers per snapshot
+ *
+ * Batch variants with document pairs are also available:
+ * - {@link iterateFirestoreDocumentSnapshotPairBatches} — batch processing with typed document access
+ *
+ * All functions support configurable limits (`limitPerCheckpoint`, `totalSnapshotsLimit`),
+ * concurrency (`maxParallelCheckpoints`), rate limiting (`waitBetweenCheckpoints`),
+ * snapshot filtering, and repeat cursor detection.
  */
 /**
- * Iterates through the results of a Firestore query by each FirestoreDocumentSnapshotDataPairWithData.
+ * Iterates through Firestore query results, loading each snapshot as a
+ * {@link FirestoreDocumentSnapshotDataPairWithData} before processing.
  *
- * 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.
+ * Built on {@link iterateFirestoreDocumentSnapshots}, this adds an automatic document
+ * loading step: each raw snapshot is resolved through the `documentAccessor` to produce
+ * a pair containing both the typed {@link FirestoreDocument} and its snapshot data.
+ * This is the highest-level iteration function — use it when your callback needs
+ * document-level operations (updates, deletes) alongside the snapshot data.
  *
- * @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
+ * @param config - Iteration config including the document accessor and per-pair callback
+ * @returns Checkpoint-level statistics (total checkpoints, snapshots visited, limit status)
+ *
+ * @example
+ * ```typescript
+ * const result = await iterateFirestoreDocumentSnapshotPairs({
+ *   queryFactory,
+ *   constraintsFactory: [where('status', '==', 'pending')],
+ *   limitPerCheckpoint: 100,
+ *   documentAccessor: collection.documentAccessor(),
+ *   iterateSnapshotPair: async (pair) => {
+ *     await pair.document.accessor.set({ ...pair.data, status: 'processed' });
+ *   }
+ * });
+ * ```
  */
 async function iterateFirestoreDocumentSnapshotPairs(config) {
     const { iterateSnapshotPair, documentAccessor } = config;
@@ -3290,16 +3395,32 @@ async function iterateFirestoreDocumentSnapshotPairs(config) {
     });
 }
 /**
- * Iterates through the results of a Firestore query by each document snapshot by itself.
+ * Iterates through Firestore query results, processing each document snapshot individually.
  *
- * 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.
+ * Built on {@link iterateFirestoreDocumentSnapshotBatches} with `maxParallelCheckpoints: 1`,
+ * this unwraps each checkpoint's snapshots and processes them one-by-one via
+ * {@link performAsyncTasks} (sequential by default). Use `snapshotsPerformTasksConfig`
+ * to enable parallel snapshot processing within each checkpoint.
  *
- * @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
+ * For document-level operations (needing the typed {@link FirestoreDocument} wrapper),
+ * use {@link iterateFirestoreDocumentSnapshotPairs} instead.
+ *
+ * @param config - Iteration config including the per-snapshot callback
+ * @returns Checkpoint-level statistics (total checkpoints, snapshots visited, limit status)
+ *
+ * @example
+ * ```typescript
+ * const result = await iterateFirestoreDocumentSnapshots({
+ *   queryFactory,
+ *   constraintsFactory: [where('active', '==', true)],
+ *   limitPerCheckpoint: 200,
+ *   totalSnapshotsLimit: 1000,
+ *   iterateSnapshot: async (snapshot) => {
+ *     const data = snapshot.data();
+ *     await externalApi.sync(data);
+ *   }
+ * });
+ * ```
  */
 async function iterateFirestoreDocumentSnapshots(config) {
     const { iterateSnapshot, performTasksConfig, snapshotsPerformTasksConfig } = config;
@@ -3316,10 +3437,32 @@ async function iterateFirestoreDocumentSnapshots(config) {
     });
 }
 /**
- * Iterates through the results of a Firestore query by each FirestoreDocumentSnapshotDataPair.
+ * Iterates through Firestore query results in batches, loading each batch as
+ * {@link FirestoreDocumentSnapshotDataPairWithData} instances before processing.
  *
- * @param config
- * @returns
+ * Built on {@link iterateFirestoreDocumentSnapshotBatches} with `maxParallelCheckpoints: 1`.
+ * Each batch of raw snapshots is resolved through the `documentAccessor` to produce
+ * 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
+ * @returns Checkpoint-level statistics (total checkpoints, snapshots visited, limit status)
+ *
+ * @example
+ * ```typescript
+ * const result = await iterateFirestoreDocumentSnapshotPairBatches({
+ *   queryFactory,
+ *   constraintsFactory: [where('needsMigration', '==', true)],
+ *   limitPerCheckpoint: 500,
+ *   batchSize: 50,
+ *   documentAccessor: collection.documentAccessor(),
+ *   iterateSnapshotPairsBatch: async (pairs, batchIndex) => {
+ *     const writeBatch = firestore.batch();
+ *     pairs.forEach((pair) => writeBatch.update(pair.document.documentRef, { migrated: true }));
+ *     await writeBatch.commit();
+ *   }
+ * });
+ * ```
  */
 async function iterateFirestoreDocumentSnapshotPairBatches(config) {
     const { iterateSnapshotPairsBatch, documentAccessor } = config;
@@ -3340,10 +3483,32 @@ async function iterateFirestoreDocumentSnapshotPairBatches(config) {
  */
 const DEFAULT_ITERATE_FIRESTORE_DOCUMENT_SNAPSHOT_BATCHES_BATCH_SIZE = 25;
 /**
- * Iterates through the results of a Firestore query by each document snapshot.
+ * Iterates through Firestore query results by subdividing each checkpoint into smaller batches.
  *
- * @param config
- * @returns
+ * Built on {@link iterateFirestoreDocumentSnapshotCheckpoints}, this function takes each
+ * checkpoint's snapshots and splits them into batches (default size: 25). Batches are
+ * processed via {@link performAsyncTasks}, sequential by default. Use this when operations
+ * have size limits (e.g., Firestore batch writes) or benefit from controlled chunk sizes.
+ *
+ * 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
+ * @returns Checkpoint-level statistics (total checkpoints, snapshots visited, limit status)
+ *
+ * @example
+ * ```typescript
+ * const result = await iterateFirestoreDocumentSnapshotBatches({
+ *   queryFactory,
+ *   constraintsFactory: [where('type', '==', 'order')],
+ *   limitPerCheckpoint: 500,
+ *   batchSize: 100,
+ *   iterateSnapshotBatch: async (snapshots, batchIndex) => {
+ *     const data = snapshots.map((s) => s.data());
+ *     await analytics.trackBatch(data);
+ *   }
+ * });
+ * ```
  */
 async function iterateFirestoreDocumentSnapshotBatches(config) {
     const { iterateSnapshotBatch, batchSizeForSnapshots: inputBatchSizeForSnapshots, performTasksConfig, batchSize: inputBatchSize } = config;
@@ -3369,29 +3534,75 @@ async function iterateFirestoreDocumentSnapshotBatches(config) {
     });
 }
 /**
- * Creates a IterateFirestoreDocumentSnapshotCheckpointsFilterCheckpointSnapshotsFunction that filters out any repeat documents.
+ * Creates a checkpoint filter that deduplicates documents across checkpoints.
  *
- * 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.
+ * Repeat documents can appear when a document is updated during iteration and
+ * re-matches the query in a subsequent checkpoint. This factory returns a stateful
+ * filter that tracks seen document keys and removes duplicates.
  *
- * @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
+ * The filter maintains state across checkpoints — use a single instance for the
+ * entire iteration run. Pair with `handleRepeatCursor: false` to also terminate
+ * iteration when cursor-level repeats are detected.
+ *
+ * @param readKeyFunction - Extracts a unique key from each snapshot; defaults to `snapshot.id`
+ * @returns A stateful filter function suitable for `filterCheckpointSnapshots`
+ *
+ * @example
+ * ```typescript
+ * const result = await iterateFirestoreDocumentSnapshotCheckpoints({
+ *   queryFactory,
+ *   constraintsFactory: [orderBy('updatedAt')],
+ *   limitPerCheckpoint: 100,
+ *   filterCheckpointSnapshots: filterRepeatCheckpointSnapshots(),
+ *   handleRepeatCursor: false,
+ *   iterateCheckpoint: async (snapshots) => {
+ *     return snapshots.map((s) => s.data());
+ *   }
+ * });
+ * ```
  */
 function filterRepeatCheckpointSnapshots(readKeyFunction = (x) => x.id) {
     const allowOnceFilter = util.allowValueOnceFilter(readKeyFunction);
     return async (snapshots) => snapshots.filter(allowOnceFilter);
 }
 /**
- * Iterates through the results of a Firestore query in several batches.
+ * Core cursor-based pagination engine for iterating through Firestore query results.
  *
- * 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.
+ * This is the foundational function in the Firestore iteration hierarchy. It drives
+ * sequential cursor-based pagination: each "checkpoint" executes a Firestore query,
+ * uses the last document as a `startAfter` cursor for the next query, and passes
+ * results to the `iterateCheckpoint` callback.
  *
- * @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
+ * The iteration loop continues until one of these conditions is met:
+ * - A query returns no results (no more matching documents)
+ * - The `totalSnapshotsLimit` is reached
+ * - A repeat cursor is detected and `handleRepeatCursor` returns `false`
+ * - The effective `limitPerCheckpoint` calculates to 0 remaining
+ *
+ * Higher-level functions build on this:
+ * - {@link iterateFirestoreDocumentSnapshotBatches} — subdivides checkpoints into smaller batches
+ * - {@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
+ *
+ * @example
+ * ```typescript
+ * const result = await iterateFirestoreDocumentSnapshotCheckpoints({
+ *   queryFactory,
+ *   constraintsFactory: [where('createdAt', '<=', cutoffDate), orderBy('createdAt')],
+ *   limitPerCheckpoint: 200,
+ *   totalSnapshotsLimit: 5000,
+ *   handleRepeatCursor: false,
+ *   iterateCheckpoint: async (snapshots, querySnapshot) => {
+ *     return snapshots.map((s) => ({ id: s.id, data: s.data() }));
+ *   },
+ *   useCheckpointResult: (result) => {
+ *     console.log(`Checkpoint ${result.i}: processed ${result.docSnapshots.length} docs`);
+ *   }
+ * });
+ * ```
  */
 async function iterateFirestoreDocumentSnapshotCheckpoints(config) {
     const { iterateCheckpoint, filterCheckpointSnapshots: inputFilterCheckpointSnapshot, handleRepeatCursor: inputHandleRepeatCursor, waitBetweenCheckpoints, useCheckpointResult, constraintsFactory: inputConstraintsFactory, dynamicConstraints: inputDynamicConstraints, queryFactory, maxParallelCheckpoints = 1, limitPerCheckpoint: inputLimitPerCheckpoint, totalSnapshotsLimit: inputTotalSnapshotsLimit } = config;
@@ -3494,13 +3705,20 @@ async function iterateFirestoreDocumentSnapshotCheckpoints(config) {
 }
 // MARK: Utility
 /**
- * Creates a filter that allows each document snapshot to be processed only once based on its path.
+ * Creates a stateful filter that allows each document snapshot through only once,
+ * keyed by its full Firestore model path.
  *
- * This utility helps prevent duplicate processing of documents by tracking which ones have
- * already been seen based on their path.
+ * Unlike {@link filterRepeatCheckpointSnapshots} which uses document ID by default,
+ * this filter uses the full document path ({@link readFirestoreModelKeyFromDocumentSnapshot}),
+ * making it suitable for cross-collection iteration where document IDs alone may collide.
  *
- * @template T - The document snapshot type
- * @returns A filter function that only allows each unique document to pass once
+ * @returns A reusable filter function that passes each unique document path exactly once
+ *
+ * @example
+ * ```typescript
+ * const onceFilter = allowDocumentSnapshotWithPathOnceFilter();
+ * const uniqueSnapshots = allSnapshots.filter(onceFilter);
+ * ```
  */
 function allowDocumentSnapshotWithPathOnceFilter() {
     return util.allowValueOnceFilter(readFirestoreModelKeyFromDocumentSnapshot);
@@ -9907,6 +10125,7 @@ exports.limit = limit;
 exports.limitToLast = limitToLast;
 exports.limitUploadFileTypeDeterminer = limitUploadFileTypeDeterminer;
 exports.limitedFirestoreDocumentAccessorFactory = limitedFirestoreDocumentAccessorFactory;
+exports.limitedFirestoreDocumentAccessorSnapshotCache = limitedFirestoreDocumentAccessorSnapshotCache;
 exports.loadAllFirestoreDocumentSnapshot = loadAllFirestoreDocumentSnapshot;
 exports.loadAllFirestoreDocumentSnapshotPairs = loadAllFirestoreDocumentSnapshotPairs;
 exports.loadDocumentsForDocumentReferences = loadDocumentsForDocumentReferences;
@@ -10064,6 +10283,7 @@ exports.storagePathFactory = storagePathFactory;
 exports.storedFileReaderFactory = storedFileReaderFactory;
 exports.streamDocumentSnapshotDataPairs = streamDocumentSnapshotDataPairs;
 exports.streamDocumentSnapshotDataPairsWithData = streamDocumentSnapshotDataPairsWithData;
+exports.streamDocumentSnapshotsData = streamDocumentSnapshotsData;
 exports.streamFromOnSnapshot = streamFromOnSnapshot;
 exports.systemStateCollectionReference = systemStateCollectionReference;
 exports.systemStateConverter = systemStateConverter;