@dereekb/firebase 11.1.8 → 12.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "11.1.8",
+  "version": "12.0.1",
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
@@ -27,13 +27,14 @@
     "@dereekb/model": "*",
     "@dereekb/date": "*",
     "rxjs": "^7.5.0",
-    "firebase": "^10.5.0",
-    "ts-essentials": "^9.1.2",
+    "firebase": "^11.0.0",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.0",
-    "date-fns": "^2.30.0"
+    "ts-essentials": "^9.1.2",
+    "date-fns": "^3.0.0"
   },
   "dependencies": {},
   "module": "./index.esm.js",
-  "main": "./index.cjs.js"
-}
+  "main": "./index.cjs.js",
+  "types": "./index.esm.d.ts"
+}

package/src/lib/common/firestore/accessor/accessor.batch.d.ts

@@ -1,3 +1,15 @@
 import { type WriteBatch } from '../types';
 import { type FirestoreDocumentDataAccessorFactory } from './accessor';
+/**
+ * Factory function type for creating document accessor factories that operate within a write batch.
+ *
+ * This is a higher-order factory that takes a Firestore WriteBatch and returns a document
+ * accessor factory. All document accessors created by the returned factory will perform
+ * their write operations as part of the specified batch, providing atomicity guarantees
+ * across multiple documents and operations.
+ *
+ * @template T - The document data type that accessors will work with
+ * @param writeBatch - The Firestore write batch to execute operations within
+ * @returns A factory for creating document accessors that operate within the specified write batch
+ */
 export type WriteBatchAccessorFactory = <T>(writeBatch: WriteBatch) => FirestoreDocumentDataAccessorFactory<T>;

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

@@ -3,20 +3,43 @@ import { type WriteResult, type SnapshotOptions, type DocumentReference, type Do
 import { type Observable, type OperatorFunction } from 'rxjs';
 import { type DocumentReferenceRef } from '../reference';
 import { type PickProperties } from 'ts-essentials';
+/**
+ * Parameters for document deletion operations.
+ */
 export interface FirestoreDocumentDeleteParams {
+    /**
+     * Precondition that must be met for the operation to succeed.
+     * Can be used to check document exists or has a specific update time.
+     */
     readonly precondition?: Precondition;
 }
+/**
+ * Parameters for document update operations.
+ */
 export interface FirestoreDocumentUpdateParams {
+    /**
+     * Precondition that must be met for the operation to succeed.
+     * Can be used to check document exists or has a specific update time.
+     */
     readonly precondition?: Precondition;
 }
 /**
- * Used for performing increment updates.
+ * Used for performing increment operations on numeric fields.
+ *
+ * Represents a partial object where keys correspond to numeric fields in the document
+ * and values represent the amount to increment each field by.
  *
- * Is an object that contains the amount to increment.
+ * @template T - The document type containing numeric fields to increment
  */
 export type FirestoreAccessorIncrementUpdate<T> = Partial<KeyValueTransformMap<PickProperties<T, Maybe<number> | number>, number>>;
 /**
- * Firestore database accessor instance used to retrieve and make changes to items in the database.
+ * Interface for accessing and modifying a Firestore document.
+ *
+ * Provides methods for reading, creating, updating, and deleting document data,
+ * as well as streaming document snapshots for real-time updates.
+ *
+ * @template T - The document data type that this accessor will work with
+ * @template D - The raw document data type in Firestore (defaults to DocumentData)
  */
 export interface FirestoreDocumentDataAccessor<T, D = DocumentData> extends DocumentReferenceRef<T> {
     /**
@@ -72,10 +95,26 @@ export interface FirestoreDocumentDataAccessor<T, D = DocumentData> extends Docu
      */
     increment(data: FirestoreAccessorIncrementUpdate<T>, params?: FirestoreDocumentUpdateParams): Promise<WriteResult | void>;
 }
+/**
+ * Function signature for creating a document.
+ *
+ * @template T - The document data type
+ */
 export type FirestoreDocumentDataAccessorCreateFunction<T> = (data: WithFieldValue<T>) => Promise<void | WriteResult>;
+/**
+ * Function signature for setting document data with optional merge settings.
+ *
+ * @template T - The document data type
+ */
 export type FirestoreDocumentDataAccessorSetFunction<T> = (data: PartialWithFieldValue<T> | WithFieldValue<T>, options?: SetOptions) => Promise<void | WriteResult>;
 /**
- * Contextual interface used for making a FirestoreDocumentModifier for a specific document.
+ * Factory interface for creating document accessors for specific document references.
+ *
+ * Provides a mechanism to create data accessors tailored to specific document references,
+ * enabling consistent access patterns across multiple documents.
+ *
+ * @template T - The document data type that accessors will work with
+ * @template D - The raw document data type in Firestore (defaults to DocumentData)
  */
 export interface FirestoreDocumentDataAccessorFactory<T, D = DocumentData> {
     /**
@@ -85,64 +124,85 @@ export interface FirestoreDocumentDataAccessorFactory<T, D = DocumentData> {
      */
     accessorFor(ref: DocumentReference<T>): FirestoreDocumentDataAccessor<T, D>;
 }
+/**
+ * Enumeration of methods for retrieving document data.
+ */
 export declare enum FirestoreAccessorStreamMode {
     /**
-     *
+     * Continuous stream of document snapshots that updates in real-time.
      */
     STREAM = 0,
     /**
-     *
+     * One-time retrieval of the current document snapshot.
      */
     GET = 1
 }
 /**
- * Retrieves a DocumentSnapshot's data observable using the input stream mode.
+ * Creates an Observable that emits the document data from snapshots based on the specified stream mode.
  *
- * @param accessor
- * @param mode
- * @returns
+ * @template T - The document data type
+ * @param accessor - The document accessor to retrieve snapshots from
+ * @param mode - Whether to use a one-time GET or continuous STREAM mode
+ * @param options - Options for how to format the document data
+ * @returns An Observable that emits the document data or undefined if the document doesn't exist
  */
 export declare function snapshotStreamDataForAccessor<T>(accessor: FirestoreDocumentDataAccessor<T>, mode: FirestoreAccessorStreamMode, options?: SnapshotOptions): Observable<T | undefined>;
 /**
- * Retrieves a DocumentSnapshot observable using the input stream mode.
+ * Creates an Observable that emits DocumentSnapshots based on the specified stream mode.
  *
- * @param accessor
- * @param mode
- * @returns
+ * @template T - The document data type
+ * @param accessor - The document accessor to retrieve snapshots from
+ * @param mode - Whether to use a one-time GET or continuous STREAM mode
+ * @returns An Observable that emits DocumentSnapshots
  */
 export declare function snapshotStreamForAccessor<T>(accessor: FirestoreDocumentDataAccessor<T>, mode: FirestoreAccessorStreamMode): Observable<DocumentSnapshot<T>>;
 /**
- * Maps data from the given snapshot stream.
+ * Creates an Observable that emits document data from a stream of DocumentSnapshots.
  *
- * Maybe values are filtered from the stream until data is provided.
+ * Filters out null/undefined values from the stream (documents that don't exist).
  *
- * @param stream
- * @param options
- * @returns
+ * @template T - The document data type
+ * @param stream - Observable that emits DocumentSnapshots
+ * @param options - Options for how to format the document data
+ * @returns An Observable that emits document data, filtering out non-existent documents
  */
 export declare function dataFromSnapshotStream<T>(stream: Observable<DocumentSnapshot<T>>, options?: SnapshotOptions): Observable<T>;
 /**
- * OperatorFunction to map data from the snapshot.
+ * Creates an RxJS operator that transforms DocumentSnapshots into their data.
  *
- * @param options
- * @returns
+ * @template T - The document data type
+ * @param options - Options for how to format the document data
+ * @returns An operator that transforms DocumentSnapshots into document data (or undefined if the document doesn't exist)
  */
 export declare function mapDataFromSnapshot<T>(options?: SnapshotOptions): OperatorFunction<DocumentSnapshot<T>, Maybe<T>>;
 /**
- * Updates the target object using the input data that uses the input converter to build data suitable for the update function.
+ * Function that updates a document using a data converter to transform the input data.
  *
- * If the input data after conversion is empty then returns void.
+ * The function handles:
+ * - Converting the input data to Firestore format
+ * - Skipping updates if the converted data is empty
+ * - Applying preconditions to the update operation
  *
- * If the target object does not exist, this will fail.
+ * Note: If the target document doesn't exist, the update will fail.
  *
- * @param data
+ * @template T - The document data type
+ * @param data - The partial data to update in the document
+ * @param params - Optional parameters for the update operation
+ * @returns A promise that resolves with the WriteResult or void
  */
 export type UpdateWithAccessorUpdateAndConverterFunction<T> = (data: Partial<T>, params?: FirestoreDocumentUpdateParams) => Promise<WriteResult | void>;
 /**
- * Creates an UpdateWithAccessorUpdateAndConverterFunction.
+ * Creates a function that updates a document using a data converter.
+ *
+ * The created function:
+ * - Filters out undefined values from the input data
+ * - Uses the converter to transform data to Firestore format
+ * - Skips the update if the resulting data is empty
+ * - Applies any provided preconditions to the update
  *
- * @param accessor
- * @param converter
- * @returns
+ * @template T - The document data type
+ * @param accessor - The document accessor to use for updates
+ * @param converter - The data converter to transform input data to Firestore format
+ * @returns A function that updates the document with converted data
  */
 export declare function updateWithAccessorUpdateAndConverterFunction<T>(accessor: FirestoreDocumentDataAccessor<T>, converter: FirestoreDataConverter<T>): UpdateWithAccessorUpdateAndConverterFunction<T>;

package/src/lib/common/firestore/accessor/accessor.default.d.ts

@@ -1,2 +1,16 @@
 import { type FirestoreDocumentDataAccessorFactory } from './accessor';
+/**
+ * Factory function type for creating standard document accessor factories.
+ *
+ * This is a parameterless factory that creates a document accessor factory for standard
+ * (non-transactional) operations. The returned factory can then be used to create document
+ * accessors for specific document references.
+ *
+ * Document accessors created through this factory chain will perform operations with
+ * standard Firestore semantics - individual operations with no transactional guarantees
+ * across multiple operations.
+ *
+ * @template T - The document data type that accessors will work with
+ * @returns A factory for creating standard document accessors
+ */
 export type DefaultFirestoreAccessorFactory<T> = () => FirestoreDocumentDataAccessorFactory<T>;

package/src/lib/common/firestore/accessor/accessor.transaction.d.ts

@@ -1,3 +1,18 @@
 import { type Transaction } from '../types';
 import { type FirestoreDocumentDataAccessorFactory } from './accessor';
+/**
+ * Factory function type for creating document accessor factories that operate within a transaction.
+ *
+ * This is a higher-order factory that takes a Firestore Transaction and returns a document
+ * accessor factory. All document accessors created by the returned factory will perform
+ * their read and write operations as part of the specified transaction, providing atomicity
+ * and consistency guarantees across multiple documents and operations.
+ *
+ * Unlike write batches, transactions support both read and write operations and ensure
+ * that reads reflect a consistent snapshot of the database.
+ *
+ * @template T - The document data type that accessors will work with
+ * @param transaction - The Firestore transaction to execute operations within
+ * @returns A factory for creating document accessors that operate within the specified transaction
+ */
 export type TransactionAccessorFactory<T = unknown> = (transaction: Transaction) => FirestoreDocumentDataAccessorFactory<T>;

package/src/lib/common/firestore/accessor/accessor.wrap.d.ts

@@ -2,26 +2,131 @@ import { type Observable } from 'rxjs';
 import { type DocumentData, type DocumentReference, type DocumentSnapshot, type FirestoreDataConverter, type PartialWithFieldValue, type SetOptions, type UpdateData, type WithFieldValue, type WriteResult } from '../types';
 import { type FirestoreAccessorIncrementUpdate, type FirestoreDocumentDataAccessor, type FirestoreDocumentDataAccessorFactory, type FirestoreDocumentDeleteParams, type FirestoreDocumentUpdateParams } from './accessor';
 /**
- * Abstract wrapper for a FirestoreDocumentDataAccessor.
+ * Abstract wrapper for a FirestoreDocumentDataAccessor that delegates operations.
  *
- * Forwards all non-overridden accessor functions to the wrapped accessor by default.
+ * Provides a base implementation that forwards all accessor operations to the wrapped
+ * accessor instance. Subclasses can override specific methods to modify or intercept
+ * the behavior while inheriting the rest of the implementation.
+ *
+ * @template T - The document data type
+ * @template D - The raw document data type in Firestore (defaults to DocumentData)
  */
 export declare abstract class AbstractFirestoreDocumentDataAccessorWrapper<T, D = DocumentData> implements FirestoreDocumentDataAccessor<T, D> {
     private readonly _accessor;
+    /**
+     * Creates a new accessor wrapper.
+     *
+     * @param accessor - The accessor instance to wrap
+     */
     constructor(accessor: FirestoreDocumentDataAccessor<T, D>);
+    /**
+     * Gets the wrapped accessor instance.
+     *
+     * @returns The wrapped FirestoreDocumentDataAccessor instance
+     */
     get accessor(): FirestoreDocumentDataAccessor<T, D>;
+    /**
+     * Gets the document reference from the wrapped accessor.
+     *
+     * @returns The DocumentReference for the current document
+     */
     get documentRef(): DocumentReference<T>;
+    /**
+     * Streams document snapshots from the wrapped accessor.
+     *
+     * @returns An Observable that emits DocumentSnapshots when the document changes
+     */
     stream(): Observable<DocumentSnapshot<T>>;
+    /**
+     * Creates a new document with the provided data.
+     *
+     * @param data - The data to create the document with
+     * @returns A Promise that resolves when the create operation completes
+     */
     create(data: WithFieldValue<T>): Promise<WriteResult | void>;
+    /**
+     * Gets the current document snapshot.
+     *
+     * @returns A Promise that resolves with the current DocumentSnapshot
+     */
     get(): Promise<DocumentSnapshot<T>>;
+    /**
+     * Gets the document snapshot with a specific data converter.
+     *
+     * @template U - The converted data type
+     * @param converter - The data converter to use, or null for raw data
+     * @returns A Promise that resolves with the DocumentSnapshot with converted data
+     */
     getWithConverter<U = DocumentData>(converter: null | FirestoreDataConverter<U>): Promise<DocumentSnapshot<U>>;
+    /**
+     * Checks if the document exists.
+     *
+     * @returns A Promise that resolves with true if the document exists, false otherwise
+     */
     exists(): Promise<boolean>;
+    /**
+     * Deletes the document.
+     *
+     * @param params - Optional parameters for the delete operation
+     * @returns A Promise that resolves when the delete operation completes
+     */
     delete(params?: FirestoreDocumentDeleteParams): Promise<void | WriteResult>;
+    /**
+     * Sets document data with merge options.
+     *
+     * @param data - The partial data to set with merge
+     * @param options - The set options (e.g., merge settings)
+     * @returns A Promise that resolves when the set operation completes
+     */
     set(data: PartialWithFieldValue<T>, options: SetOptions): Promise<WriteResult | void>;
+    /**
+     * Sets document data, replacing any existing data.
+     *
+     * @param data - The complete data to set
+     * @returns A Promise that resolves when the set operation completes
+     */
     set(data: WithFieldValue<T>): Promise<WriteResult | void>;
+    /**
+     * Updates specific fields of the document.
+     *
+     * @param data - The fields to update and their new values
+     * @param params - Optional parameters for the update operation
+     * @returns A Promise that resolves when the update operation completes
+     */
     update(data: UpdateData<D>, params?: FirestoreDocumentUpdateParams): Promise<void | WriteResult>;
+    /**
+     * Increments numeric fields in the document.
+     *
+     * @param data - Mapping of fields to increment and the amount to increment by
+     * @param params - Optional parameters for the increment operation
+     * @returns A Promise that resolves when the increment operation completes
+     */
     increment(data: FirestoreAccessorIncrementUpdate<T>, params?: FirestoreDocumentUpdateParams): Promise<WriteResult | void>;
 }
+/**
+ * Function type for wrapping a document accessor with additional functionality.
+ *
+ * @template T - The document data type
+ * @template D - The raw document data type in Firestore
+ */
 export type WrapFirestoreDocumentDataAccessorFunction<T, D = DocumentData> = (input: FirestoreDocumentDataAccessor<T, D>) => FirestoreDocumentDataAccessor<T, D>;
+/**
+ * Function type for intercepting an accessor factory to modify all created accessors.
+ *
+ * @template T - The document data type
+ * @template D - The raw document data type in Firestore
+ */
 export type InterceptAccessorFactoryFunction<T, D = DocumentData> = (input: FirestoreDocumentDataAccessorFactory<T, D>) => FirestoreDocumentDataAccessorFactory<T, D>;
+/**
+ * Creates a function that intercepts an accessor factory to wrap all created accessors.
+ *
+ * This function creates a higher-order factory that wraps each accessor created by the
+ * original factory with the provided wrapper function, allowing for consistent modification
+ * of all accessors created through the factory.
+ *
+ * @template T - The document data type
+ * @template D - The raw document data type in Firestore
+ * @param wrap - Function to wrap each created accessor
+ * @returns A function that transforms accessor factories to use the wrapper
+ */
 export declare function interceptAccessorFactoryFunction<T, D = DocumentData>(wrap: WrapFirestoreDocumentDataAccessorFunction<T, D>): InterceptAccessorFactoryFunction<T, D>;

package/src/lib/common/firestore/accessor/context.batch.d.ts

@@ -1,7 +1,38 @@
 import { type WriteBatch } from '../types';
 import { type FirestoreDocumentContext, type FirestoreDocumentContextType } from './context';
+/**
+ * Factory function type for creating write batch document contexts.
+ *
+ * This factory creates contexts that execute write operations within a Firestore batch,
+ * providing atomicity guarantees across multiple write operations.
+ *
+ * @template T - The document data type that accessors from this context will work with
+ * @param writeBatch - The Firestore write batch to execute operations within
+ * @returns A FirestoreDocumentContext with batch execution semantics
+ */
 export type WriteBatchFirestoreDocumentContextFactory = <T>(writeBatch: WriteBatch) => WriteBatchFirestoreDocumentContext<T>;
+/**
+ * Document context for operations executed within a Firestore write batch.
+ *
+ * This context ensures that document write operations are performed as part of a batch,
+ * providing atomicity guarantees. Multiple write operations performed through accessors
+ * from this context will either all succeed or all fail together.
+ *
+ * Unlike transactions, batches in Firestore only support write operations (create, update,
+ * delete) and cannot read documents. This makes them more performant for write-only
+ * operations that don't depend on reading the current state.
+ *
+ * @template T - The document data type that accessors from this context will work with
+ */
 export interface WriteBatchFirestoreDocumentContext<T> extends FirestoreDocumentContext<T> {
+    /**
+     * The context type is always BATCH, indicating batch execution.
+     */
     readonly contextType: FirestoreDocumentContextType.BATCH;
+    /**
+     * The Firestore write batch that operations will be executed within.
+     *
+     * All write operations performed through accessors from this context will be part of this batch.
+     */
     readonly batch: WriteBatch;
 }

package/src/lib/common/firestore/accessor/context.d.ts

@@ -1,24 +1,47 @@
 import { type FirestoreDocumentDataAccessorFactory } from './accessor';
 /**
- * A specific document context type.
+ * Enumeration of possible contexts for document operations.
  *
- * Used by a FirestoreDocumentContext to communicate which kind of context it was created in.
+ * Used by FirestoreDocumentContext to indicate the execution environment of document operations,
+ * which affects how reads and writes are processed (e.g., atomicity, consistency).
+ *
+ * @remarks
+ * - NONE: Standard individual operations without transaction or batch guarantees
+ * - TRANSACTION: Operations within a Firestore transaction (atomic, with reads and writes)
+ * - BATCH: Operations within a Firestore write batch (atomic writes only, no reads)
  */
 export declare enum FirestoreDocumentContextType {
+    /** Standard context with no special transactional semantics */
     NONE = "none",
+    /** Operations within a Firestore transaction (atomic reads and writes) */
     TRANSACTION = "transaction",
+    /** Operations within a Firestore write batch (atomic writes only) */
     BATCH = "batch"
 }
 /**
- * Firebase database context used for accessing and modifying documents in a specific context, such as a transaction.
+ * Container for document operations within a specific execution context.
+ *
+ * Provides an accessor factory that creates document accessors appropriate for the current
+ * context (standard, transaction, or batch). When operations are performed using accessors
+ * from this context, they inherit the guarantees of the context type (e.g., transaction atomicity).
+ *
+ * This interface is used throughout the accessor system to propagate context information
+ * through the document access chain, ensuring consistent behavior.
+ *
+ * @template T - The document data type that accessors will work with
  */
 export interface FirestoreDocumentContext<T> {
     /**
-     * Context type
+     * The type of execution context (none, transaction, or batch).
+     *
+     * Determines how operations will be executed and what guarantees they provide.
      */
     readonly contextType: FirestoreDocumentContextType;
     /**
-     * Database accessor
+     * Factory for creating document accessors appropriate for this context.
+     *
+     * The returned accessors will execute operations in a manner consistent with
+     * the current context type (e.g., using transaction references for transactions).
      */
     readonly accessorFactory: FirestoreDocumentDataAccessorFactory<T>;
 }

package/src/lib/common/firestore/accessor/context.default.d.ts

@@ -1,5 +1,26 @@
 import { type FirestoreDocumentContext, type FirestoreDocumentContextType } from './context';
+/**
+ * Factory function type for creating default (non-transactional) document contexts.
+ *
+ * This factory creates contexts with the standard execution semantics where
+ * operations are executed individually without transaction or batch guarantees.
+ *
+ * @template T - The document data type that accessors from this context will work with
+ * @returns A FirestoreDocumentContext with standard execution semantics
+ */
 export type DefaultFirestoreDocumentContextFactory = <T>() => FirestoreDocumentContext<T>;
+/**
+ * The standard document context with no special transactional semantics.
+ *
+ * This context is used for regular document operations outside of transactions or batches.
+ * Operations performed through accessors from this context will be executed individually
+ * with standard Firestore guarantees but no atomicity across multiple operations.
+ *
+ * @template T - The document data type that accessors from this context will work with
+ */
 export interface DefaultFirestoreDocumentContext<T> extends FirestoreDocumentContext<T> {
+    /**
+     * The context type is always NONE, indicating standard non-transactional execution.
+     */
     readonly contextType: FirestoreDocumentContextType.NONE;
 }

package/src/lib/common/firestore/accessor/context.transaction.d.ts

@@ -1,7 +1,38 @@
 import { type Transaction } from '../types';
 import { type FirestoreDocumentContext, type FirestoreDocumentContextType } from './context';
+/**
+ * Factory function type for creating transaction document contexts.
+ *
+ * This factory creates contexts that execute operations within a Firestore transaction,
+ * providing atomicity guarantees across multiple read and write operations.
+ *
+ * @template T - The document data type that accessors from this context will work with
+ * @param transaction - The Firestore transaction to execute operations within
+ * @returns A FirestoreDocumentContext with transaction execution semantics
+ */
 export type TransactionFirestoreDocumentContextFactory = <T>(transaction: Transaction) => TransactionFirestoreDocumentContext<T>;
+/**
+ * Document context for operations executed within a Firestore transaction.
+ *
+ * This context ensures that document operations are performed as part of a transaction,
+ * providing atomicity guarantees. Multiple operations performed through accessors from
+ * this context will either all succeed or all fail together.
+ *
+ * Transactions in Firestore allow both reading and writing documents, and ensure that
+ * reads reflect a consistent snapshot of the database that isn't affected by other
+ * transactions until the current transaction completes.
+ *
+ * @template T - The document data type that accessors from this context will work with
+ */
 export interface TransactionFirestoreDocumentContext<T> extends FirestoreDocumentContext<T> {
+    /**
+     * The context type is always TRANSACTION, indicating transactional execution.
+     */
     readonly contextType: FirestoreDocumentContextType.TRANSACTION;
+    /**
+     * The Firestore transaction that operations will be executed within.
+     *
+     * All operations performed through accessors from this context will be part of this transaction.
+     */
     readonly transaction: Transaction;
 }

package/src/lib/common/firestore/accessor/converter.d.ts

@@ -1,16 +1,41 @@
 import { type FactoryWithInput, type FactoryWithRequiredInput, type Maybe } from '@dereekb/util';
 import { type DocumentReference, type FirestoreDataConverter } from '../types';
 /**
- * Factory used to provide an FirestoreDataConverter based on the input reference.
+ * Factory that creates a FirestoreDataConverter for a specific document reference.
+ *
+ * This factory allows dynamic creation of data converters based on the specific document
+ * reference being accessed. This enables different document references to have different
+ * conversion logic even within the same collection.
+ *
+ * @template T - The document data type that the converter will transform to/from Firestore
  */
 export type FirestoreDataConverterFactory<T> = FactoryWithInput<FirestoreDataConverter<T>, DocumentReference<T>>;
 /**
- * Ref to a FirestoreDataConverterFactory.
+ * Interface that provides access to a FirestoreDataConverterFactory.
+ *
+ * This interface is typically implemented by classes or objects that need to
+ * reference a converter factory without directly containing the creation logic.
+ * It enables separation between components that use converters and those that
+ * define how conversion should happen.
+ *
+ * @template T - The document data type that the converter will transform to/from Firestore
  */
 export interface FirestoreDataConverterFactoryRef<T> {
+    /**
+     * Factory function that creates a FirestoreDataConverter for a specific document reference.
+     */
     readonly converterFactory: FirestoreDataConverterFactory<T>;
 }
 /**
- * Factory used to provide an optional custom FirestoreDataConverter based on the input reference.
+ * Factory that optionally intercepts and provides a custom FirestoreDataConverter.
+ *
+ * Unlike FirestoreDataConverterFactory which always returns a converter, this factory
+ * may return null/undefined to indicate that no custom converter should be used.
+ * This allows for selective interception of converter creation based on specific criteria.
+ *
+ * This pattern is useful for middleware-like components that need to optionally modify
+ * or replace converters without affecting the entire conversion pipeline.
+ *
+ * @template T - The document data type that the converter will transform to/from Firestore
  */
 export type InterceptFirestoreDataConverterFactory<T> = FactoryWithRequiredInput<Maybe<FirestoreDataConverter<T>>, DocumentReference<T>>;

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

@@ -1,6 +1,43 @@
 import { type Observable, type OperatorFunction } from 'rxjs';
 import { type DocumentDataWithIdAndKey, type DocumentSnapshot } from '../types';
 import { type FirestoreDocument, type FirestoreDocumentData } from './document';
+/**
+ * Creates an Observable that emits arrays of document snapshots for multiple documents.
+ *
+ * This function streams the latest snapshots for each document in the provided array.
+ * Each time any document in the array changes, a new array containing the latest snapshots
+ * of all documents is emitted. Results are shared with multiple subscribers through shareReplay.
+ *
+ * If the input array is empty, an Observable that emits an empty array is returned.
+ *
+ * @template D - The FirestoreDocument implementation type
+ * @param documents - Array of document instances to stream snapshots for
+ * @returns Observable that emits arrays of DocumentSnapshots whenever any document changes
+ */
 export declare function latestSnapshotsFromDocuments<D extends FirestoreDocument<any>>(documents: D[]): Observable<DocumentSnapshot<FirestoreDocumentData<D>>[]>;
+/**
+ * Creates an Observable that emits arrays of document data for multiple documents.
+ *
+ * This function streams the latest data for each document in the provided array.
+ * Each time any document in the array changes, a new array containing the latest data
+ * of all documents is emitted. Document data includes both the document content and
+ * metadata like document ID and key. Results are shared with multiple subscribers.
+ *
+ * Non-existent documents are filtered out of the results automatically.
+ *
+ * @template D - The FirestoreDocument implementation type
+ * @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>>[]>;
+/**
+ * Creates an RxJS operator that transforms arrays of DocumentSnapshots into arrays of document data.
+ *
+ * This operator extracts the data from each document snapshot, adds ID and key information,
+ * and filters out non-existent documents. It's designed to be used in a pipe after
+ * operations that produce arrays of snapshots.
+ *
+ * @template T - The document data type
+ * @returns An operator that transforms arrays of DocumentSnapshots into arrays of document data
+ */
 export declare function dataFromDocumentSnapshots<T>(): OperatorFunction<DocumentSnapshot<T>[], DocumentDataWithIdAndKey<T>[]>;