@dereekb/firebase 13.0.6 → 13.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.0.6",
+  "version": "13.0.7",
   "exports": {
     "./test": {
       "module": "./test/index.esm.js",
@@ -17,10 +17,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.0.6",
-    "@dereekb/model": "13.0.6",
-    "@dereekb/rxjs": "13.0.6",
-    "@dereekb/util": "13.0.6",
+    "@dereekb/date": "13.0.7",
+    "@dereekb/model": "13.0.7",
+    "@dereekb/rxjs": "13.0.7",
+    "@dereekb/util": "13.0.7",
     "@firebase/rules-unit-testing": "5.0.0",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.15.1",

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

@@ -46,7 +46,7 @@ export declare function mapLatestSnapshotsFromDocuments<D extends FirestoreDocum
  * @param documents - Array of document instances to stream data for
  * @returns Observable that emits arrays of document data whenever any document changes
  */
-export declare function latestDataFromDocuments<D extends FirestoreDocument<any>>(documents: D[]): Observable<DocumentDataWithIdAndKey<FirestoreDocumentData<D>>[]>;
+export declare function streamDocumentSnapshotsData<D extends FirestoreDocument<any>>(documents: D[]): Observable<DocumentDataWithIdAndKey<FirestoreDocumentData<D>>[]>;
 /**
  * Creates an RxJS operator that transforms arrays of DocumentSnapshots into arrays of document data.
  *
@@ -89,3 +89,7 @@ export declare function streamDocumentSnapshotDataPairs<D extends FirestoreDocum
  * @returns Observable emitting snapshot-data pairs for existing documents only, whenever any document changes
  */
 export declare function streamDocumentSnapshotDataPairsWithData<D extends FirestoreDocument<any>>(documents: D[]): Observable<FirestoreDocumentSnapshotDataPairWithData<D>[]>;
+/**
+ * @deprecated Use {@link streamDocumentSnapshotsData} instead.
+ */
+export declare const latestDataFromDocuments: typeof streamDocumentSnapshotsData;

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

@@ -521,3 +521,92 @@ export declare function documentReferenceFromDocument<T, D extends FirestoreDocu
  * @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>;

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

@@ -27,20 +27,14 @@ export interface FirestoreQueryConstraint<T = unknown> {
     readonly data: T;
 }
 /**
- * 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
  */
 export declare function firestoreQueryConstraint<T = unknown>(type: string, data: T): FirestoreQueryConstraint<T>;
 /**
@@ -67,12 +61,9 @@ export declare function firestoreQueryConstraintFactory(type: string): <T = unkn
  */
 export declare const FIRESTORE_LIMIT_QUERY_CONSTRAINT_TYPE = "limit";
 /**
- * Configuration data for a limit constraint.
- */
-/**
- * Configuration data for a limit constraint.
+ * Configuration data for a {@link limit} constraint.
  *
- * Used to specify the maximum number of documents to return in a query.
+ * Specifies the maximum number of documents to return from a query.
  */
 export interface LimitQueryConstraintData {
     /**
@@ -418,19 +409,33 @@ export interface EndBeforeQueryConstraintData<T = DocumentData> {
  */
 export declare function endBefore<T = DocumentData>(snapshot: DocumentSnapshot<T>): FirestoreQueryConstraint<EndBeforeQueryConstraintData<T>>;
 /**
- * Updates the input builder with the passed constraint value.
+ * Handler function that applies a single constraint to a query builder.
+ *
+ * Used by Firestore driver implementations to translate abstract constraints into
+ * native Firestore query operations. Each handler receives the current builder state,
+ * the constraint's data, and the full constraint object, and returns the updated builder.
+ *
+ * @param builder - The current query builder state
+ * @param data - The constraint-specific data to apply
+ * @param constraint - The full constraint object (for access to the type identifier)
+ * @returns The updated query builder with the constraint applied
  */
 export type FirestoreQueryConstraintHandlerFunction<B, D = unknown> = (builder: B, data: D, constraint: FirestoreQueryConstraint<D>) => B;
 /**
- * Map of constraint type identifiers to handler functions.
+ * Registry mapping constraint type identifiers to their handler functions.
  *
- * @template B - Type of query builder
+ * Driver implementations populate this map to define how each constraint type
+ * is translated into native Firestore query operations. Missing entries (undefined/null)
+ * indicate unsupported constraint types.
  */
 export type FirestoreQueryConstraintHandlerMap<B> = {
     readonly [key: string]: Maybe<FirestoreQueryConstraintHandlerFunction<B, any>>;
 };
 /**
- * The full list of known firestore query constraints, and the data associated with it.
+ * Exhaustive mapping of all known constraint type identifiers to their data types.
+ *
+ * Used for type-safe handler registration in {@link FullFirestoreQueryConstraintHandlersMapping}
+ * and for compile-time verification that all constraint types are handled.
  */
 export type FullFirestoreQueryConstraintDataMapping = {
     [FIRESTORE_LIMIT_QUERY_CONSTRAINT_TYPE]: LimitQueryConstraintData;
@@ -448,7 +453,7 @@ export type FullFirestoreQueryConstraintDataMapping = {
     [FIRESTORE_END_BEFORE_QUERY_CONSTRAINT_TYPE]: EndBeforeQueryConstraintData;
 };
 /**
- * Mapping of all constraint types to their constraint objects.
+ * Mapping of all constraint type identifiers to their fully typed {@link FirestoreQueryConstraint} objects.
  */
 export type FullFirestoreQueryConstraintMapping = {
     [K in keyof FullFirestoreQueryConstraintDataMapping]: FirestoreQueryConstraint<FullFirestoreQueryConstraintDataMapping[K]>;

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

@@ -141,13 +141,15 @@ export declare function filterWithDateRange(field: FieldPathOrStringPath, dateRa
 export declare function whereDateIsInRange<T>(field: StringKeyPropertyKeys<T>, rangeInput: DateRangeInput, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 export declare function whereDateIsInRange(field: FieldPathOrStringPath, rangeInput: DateRangeInput, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 /**
- * Searches dates that follow between the input DateRange. Excludes the end date.
+ * Creates constraints to filter documents where a date field falls within a half-open range `[start, end)`.
  *
- * Sorts in ascending order by default.
+ * The start date is inclusive and the end date is exclusive. Results are sorted by the
+ * date field in ascending order by default.
  *
- * @param field
- * @param range
- * @param sortDirection
+ * @param field - The date field to filter on (stored as ISO string in Firestore)
+ * @param range - Date range with `start` (inclusive) and `end` (exclusive) boundaries
+ * @param sortDirection - Direction to sort results (default: 'asc')
+ * @returns Array of query constraints for the date range filter and sort
  */
 export declare function whereDateIsBetween<T>(field: StringKeyPropertyKeys<T>, range: DateRange, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 export declare function whereDateIsBetween(field: FieldPathOrStringPath, range: DateRange, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
@@ -195,62 +197,76 @@ export declare function whereDateIsOnOrAfter(field: FieldPathOrStringPath, date?
 export declare function whereDateIsOnOrAfterWithSort<T>(field: StringKeyPropertyKeys<T>, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 export declare function whereDateIsOnOrAfterWithSort(field: FieldPathOrStringPath, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 /**
- * Searches dates that are on or before the input date. If no date is input, uses now.
+ * Creates a constraint to filter documents where a date field is less than or equal to a specified date.
  *
- * @param field
- * @param date
- * @param sortDirection
+ * If no date is provided, defaults to the current date and time (`new Date()`).
+ *
+ * @param field - The date field to filter on (stored as ISO string in Firestore)
+ * @param date - The maximum date to include (default: current date/time)
+ * @returns A query constraint for dates on or before the specified date
  */
 export declare function whereDateIsOnOrBefore<T>(field: StringKeyPropertyKeys<T>, date?: Date): FirestoreQueryConstraint;
 export declare function whereDateIsOnOrBefore(field: FieldPathOrStringPath, date?: Date): FirestoreQueryConstraint;
 /**
- * Searches dates that are on or before the input date. If no date is input, uses now.
+ * Creates constraints to filter documents where a date field is on or before a specified date, with sorting.
  *
- * Sorts in descending order by default.
+ * Combines a `<=` date comparison with an `orderBy` on the same field.
+ * Sorts in descending order by default (most recent first).
+ * If no date is provided, defaults to the current date and time.
  *
- * @param field
- * @param date
- * @param sortDirection
+ * @param field - The date field to filter and sort on (stored as ISO string in Firestore)
+ * @param date - The maximum date to include (default: current date/time)
+ * @param sortDirection - Direction to sort results (default: 'desc')
+ * @returns Array of query constraints for filtering and sorting
  */
 export declare function whereDateIsOnOrBeforeWithSort<T>(field: StringKeyPropertyKeys<T>, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 export declare function whereDateIsOnOrBeforeWithSort(field: FieldPathOrStringPath, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 /**
- * Searches dates that are on or after the input date. If no date is input, uses now.
+ * Creates a constraint to filter documents where a date field is strictly after a specified date.
  *
- * @param field
- * @param date
- * @param sortDirection
+ * Uses a `>` comparison (exclusive). If no date is provided, defaults to the current date and time.
+ *
+ * @param field - The date field to filter on (stored as ISO string in Firestore)
+ * @param date - The exclusive lower bound date (default: current date/time)
+ * @returns A query constraint for dates strictly after the specified date
  */
 export declare function whereDateIsAfter<T>(field: StringKeyPropertyKeys<T>, date?: Date): FirestoreQueryConstraint;
 export declare function whereDateIsAfter(field: FieldPathOrStringPath, date?: Date): FirestoreQueryConstraint;
 /**
- * Searches dates that are on or after the input date. If no date is input, uses now.
+ * Creates constraints to filter documents where a date field is strictly after a specified date, with sorting.
  *
- * Sorts in ascending order by default.
+ * Combines a `>` date comparison with an `orderBy` on the same field.
+ * Sorts in ascending order by default. If no date is provided, defaults to the current date and time.
  *
- * @param field
- * @param date
- * @param sortDirection
+ * @param field - The date field to filter and sort on (stored as ISO string in Firestore)
+ * @param date - The exclusive lower bound date (default: current date/time)
+ * @param sortDirection - Direction to sort results (default: 'asc')
+ * @returns Array of query constraints for filtering and sorting
  */
 export declare function whereDateIsAfterWithSort<T>(field: StringKeyPropertyKeys<T>, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 export declare function whereDateIsAfterWithSort(field: FieldPathOrStringPath, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 /**
- * Searches dates that are on or after the input date. If no date is input, uses now.
+ * Creates a constraint to filter documents where a date field is strictly before a specified date.
+ *
+ * Uses a `<` comparison (exclusive). If no date is provided, defaults to the current date and time.
  *
- * @param field
- * @param date
- * @param sortDirection
+ * @param field - The date field to filter on (stored as ISO string in Firestore)
+ * @param date - The exclusive upper bound date (default: current date/time)
+ * @returns A query constraint for dates strictly before the specified date
  */
 export declare function whereDateIsBefore<T>(field: StringKeyPropertyKeys<T>, date?: Date): FirestoreQueryConstraint;
 export declare function whereDateIsBefore(field: FieldPathOrStringPath, date?: Date): FirestoreQueryConstraint;
 /**
- * Searches dates that are on or after the input date. If no date is input, uses now.
+ * Creates constraints to filter documents where a date field is strictly before a specified date, with sorting.
  *
- * Sorts in descending order by default.
+ * Combines a `<` date comparison with an `orderBy` on the same field.
+ * Sorts in descending order by default (most recent first).
+ * If no date is provided, defaults to the current date and time.
  *
- * @param field
- * @param date
- * @param sortDirection
+ * @param field - The date field to filter and sort on (stored as ISO string in Firestore)
+ * @param date - The exclusive upper bound date (default: current date/time)
+ * @param sortDirection - Direction to sort results (default: 'desc')
+ * @returns Array of query constraints for filtering and sorting
  */
 export declare function whereDateIsBeforeWithSort<T>(field: StringKeyPropertyKeys<T>, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 export declare function whereDateIsBeforeWithSort(field: FieldPathOrStringPath, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];

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

@@ -125,7 +125,20 @@ export interface FirestoreItemPageQueryResultStreamOptions {
      */
     readonly options?: Maybe<SnapshotListenOptions>;
 }
+/**
+ * Delegate that implements the page loading logic for Firestore pagination.
+ *
+ * Responsible for translating pagination requests into Firestore queries,
+ * managing cursors between pages, and producing {@link FirestoreItemPageQueryResult} values.
+ */
 export type FirestoreItemPageIteratorDelegate<T> = ItemPageIteratorDelegate<FirestoreItemPageQueryResult<T>, FirestoreItemPageIteratorFilter, FirestoreItemPageIterationConfig<T>>;
+/**
+ * Internal pagination instance that works directly with {@link FirestoreItemPageQueryResult}.
+ *
+ * This is the raw iteration instance before mapping to document arrays. It provides
+ * access to snapshot-level data and metadata. Exposed via
+ * {@link FirestoreItemPageIteration.snapshotIteration} for advanced use cases.
+ */
 export type InternalFirestoreItemPageIterationInstance<T> = ItemPageIterationInstance<FirestoreItemPageQueryResult<T>, FirestoreItemPageIteratorFilter, FirestoreItemPageIterationConfig<T>>;
 /**
  * Filters out constraints that should not be directly specified in pagination queries.
@@ -143,6 +156,17 @@ export declare function filterDisallowedFirestoreItemPageIteratorInputConstraint
  * This value is used when no itemsPerPage is explicitly specified in the configuration.
  */
 export declare 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}
+ */
 export declare function makeFirestoreItemPageIteratorDelegate<T>(): FirestoreItemPageIteratorDelegate<T>;
 export interface FirestoreItemPageIteration<T> extends MappedPageItemIterationInstance<QueryDocumentSnapshotArray<T>, FirestoreItemPageQueryResult<T>, PageLoadingState<QueryDocumentSnapshotArray<T>>, PageLoadingState<FirestoreItemPageQueryResult<T>>, InternalFirestoreItemPageIterationInstance<T>> {
     /**
@@ -283,14 +307,46 @@ export declare function firestoreItemPageIteration<T>(config: FirestoreItemPageI
  */
 export type FirestoreFixedItemPageIterationFactoryFunction<T> = (items: DocumentReference<T>[], filter?: FirestoreItemPageIteratorFilter) => FirestoreItemPageIterationInstance<T>;
 /**
- * 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
  */
 export declare function firestoreFixedItemPageIterationFactory<T>(baseConfig: FirestoreItemPageIterationConfig<T>, documentAccessor: LimitedFirestoreDocumentAccessor<T>): FirestoreFixedItemPageIterationFactoryFunction<T>;
+/**
+ * Configuration for {@link firestoreFixedItemPageIteration}.
+ *
+ * Extends the standard pagination config with a fixed set of document references
+ * and a document accessor to load their snapshots. Instead of querying Firestore,
+ * pagination is simulated by slicing through the provided references array.
+ */
 export interface FirestoreFixedItemPageIterationConfig<T> extends FirestoreItemPageIterationConfig<T> {
+    /**
+     * The fixed set of document references to paginate through.
+     *
+     * Documents are loaded in order, sliced into pages of `itemsPerPage` size.
+     */
     readonly items: DocumentReference<T>[];
+    /**
+     * Accessor used to load document snapshots from the references.
+     */
     readonly documentAccessor: LimitedFirestoreDocumentAccessor<T>;
 }
 /**
- * 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
  */
 export declare function firestoreFixedItemPageIteration<T>(config: FirestoreFixedItemPageIterationConfig<T>): FirestoreItemPageIterationInstance<T>;