@dereekb/firebase 11.1.8 → 12.0.1

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

@@ -1,24 +1,91 @@
+/**
+ * @module Firestore Query Utilities
+ *
+ * This module provides utility functions for working with Firestore queries and documents,
+ * including reactive stream helpers and document reference utilities.
+ */
 import { type FirestoreModelKey } from '../collection';
 import { type DocumentReference, type QuerySnapshot, type DocumentSnapshot } from './../types';
 import { Observable } from 'rxjs';
+/**
+ * Parameters for the Firestore onSnapshot callback handler.
+ *
+ * This interface mirrors the standard Observer pattern with next, error, and complete
+ * callbacks used in RxJS, allowing for easy conversion of Firestore snapshot events to
+ * Observable streams.
+ *
+ * @template O - The type of output value to emit in the stream
+ */
 export interface StreamDocsWithOnSnapshotFunctionParams<O> {
-    readonly next: (value?: O | undefined) => void;
+    /**
+     * Handler for new values in the stream.
+     *
+     * @param value - The new value to emit
+     */
+    readonly next: (value: O) => void;
+    /**
+     * Handler for errors in the stream.
+     *
+     * @param err - The error that occurred, if any
+     */
     readonly error: (err?: unknown) => void;
+    /**
+     * Handler for stream completion.
+     */
     readonly complete: () => void;
 }
+/**
+ * Function to unsubscribe from a Firestore snapshot listener.
+ *
+ * This function is returned when setting up a snapshot listener and can be called
+ * to stop receiving updates and clean up resources.
+ */
 export type StreamDocsUnsubscribeFunction = () => void;
 /**
- * Use to build an Observable that reacts to OnSnapshot events from queries.
+ * Creates an Observable that wraps a Firestore onSnapshot listener.
+ *
+ * This utility function bridges the gap between Firestore's callback-based API
+ * and RxJS's reactive streams, allowing for seamless integration of Firestore
+ * query results into reactive applications.
  *
- * @param callOnSnapshot
- * @returns
+ * @template O - The type of output value to emit in the Observable
+ * @param callOnSnapshot - Function that sets up the Firestore snapshot listener
+ *                          and returns an unsubscribe function
+ * @returns An Observable that emits values from the Firestore snapshot listener
+ *
+ * @example
+ * // Create a reactive stream from a Firestore query
+ * const usersStream = streamFromOnSnapshot(params => {
+ *   return collection(firestore, 'users')
+ *     .where('status', '==', 'active')
+ *     .onSnapshot(
+ *       snapshot => params.next(snapshot),
+ *       error => params.error(error),
+ *       () => params.complete()
+ *     );
+ * });
  */
 export declare function streamFromOnSnapshot<O>(callOnSnapshot: (params: StreamDocsWithOnSnapshotFunctionParams<O>) => StreamDocsUnsubscribeFunction): Observable<O>;
+/**
+ * Extracts document references from a query snapshot.
+ *
+ * This utility function converts a Firestore QuerySnapshot into an array of
+ * DocumentReference objects, making it easier to work with the references
+ * to the documents that matched a query.
+ *
+ * @template T - The document data type
+ * @param snapshots - The query snapshot containing document snapshots
+ * @returns Array of document references extracted from the snapshot
+ */
 export declare function documentReferencesFromSnapshot<T>(snapshots: QuerySnapshot<T>): DocumentReference<T>[];
 /**
- * Reads the FirestoreModelKey from the query document snapshot.
+ * Extracts the Firestore model key (document path) from a document snapshot.
+ *
+ * This function returns the full path of the document as the model key,
+ * which uniquely identifies the document within Firestore. This is useful
+ * for tracking documents across queries and preventing duplicate processing.
  *
- * @param snapshot
- * @returns
+ * @param snapshot - The document snapshot to extract the key from
+ * @returns The document's full path as a FirestoreModelKey
  */
 export declare function readFirestoreModelKeyFromDocumentSnapshot(snapshot: DocumentSnapshot<any>): FirestoreModelKey;

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

@@ -1,34 +1,165 @@
 import { type Observable } from 'rxjs';
 import { type DocumentChange, type QuerySnapshot } from '../types';
 import { type FirestoreItemPageIterationInstance } from './iterator';
+/**
+ * Default delay in milliseconds before a query change watcher begins processing events.
+ *
+ * A value of 0 means the watcher will start immediately after the first successful page result.
+ */
 export declare const DEFAULT_QUERY_CHANGE_WATCHER_DELAY = 0;
+/**
+ * Configuration for creating a query document change watcher.
+ *
+ * @template T - The document data type
+ */
 export interface IterationQueryDocChangeWatcherConfig<T = unknown> {
+    /**
+     * The iteration instance that will be watched for changes.
+     *
+     * This instance provides access to the underlying Firestore query and its results,
+     * which the watcher will monitor for document changes.
+     */
     readonly instance: FirestoreItemPageIterationInstance<T>;
+    /**
+     * Optional delay in milliseconds before the watcher begins processing events.
+     *
+     * This delay is applied after the first successful page result is received.
+     * Default is 0 (start immediately).
+     */
     readonly delay?: number;
 }
 /**
  * Interface for watching query result changes events.
+ *
+ * Provides observables for monitoring changes to Firestore query results over time,
+ * including document additions, modifications, and removals.
+ *
+ * @template T - The document data type
  */
 export interface IterationQueryDocChangeWatcher<T = unknown> {
     /**
-     * Streams all subsequent query changes.
+     * Streams all subsequent query snapshots after the initial result.
+     *
+     * This observable emits the raw QuerySnapshot objects from Firestore,
+     * allowing direct access to all query results and their changes.
      */
     readonly stream$: Observable<QuerySnapshot<T>>;
     /**
-     * Event stream
+     * Streams processed change events derived from the query snapshots.
+     *
+     * This observable transforms the raw query snapshots into structured event
+     * objects that categorize document changes into added, removed, and modified
+     * groups, making it easier to respond to specific types of changes.
      */
     readonly event$: Observable<IterationQueryDocChangeWatcherEvent<T>>;
 }
+/**
+ * Event representing a set of changes to a Firestore query result.
+ *
+ * This event captures all document changes that occurred in a single update,
+ * categorized by their type (added, removed, modified) along with metadata
+ * about when the changes occurred and an overall classification of the event.
+ *
+ * @template T - The document data type
+ */
 export interface IterationQueryDocChangeWatcherEvent<T = unknown> extends IterationQueryDocChangeWatcherChangeGroup<T> {
+    /**
+     * Timestamp when this change event was processed.
+     */
     readonly time: Date;
+    /**
+     * Array of all document changes in this event.
+     *
+     * Contains the complete set of changes, regardless of their type.
+     */
     readonly changes: DocumentChange<T>[];
+    /**
+     * Classification of this change event based on the types of changes it contains.
+     *
+     * This provides a quick way to determine the nature of the changes without
+     * examining the individual document changes.
+     */
     readonly type: IterationQueryDocChangeWatcherChangeType;
 }
+/**
+ * Group of document changes categorized by their change type.
+ *
+ * This interface organizes document changes into three distinct categories:
+ * added, removed, and modified, making it easier to process changes based
+ * on their type.
+ *
+ * @template T - The document data type
+ */
 export interface IterationQueryDocChangeWatcherChangeGroup<T = unknown> {
+    /**
+     * Documents that were newly added to the query results.
+     */
     readonly added: DocumentChange<T>[];
+    /**
+     * Documents that were removed from the query results.
+     */
     readonly removed: DocumentChange<T>[];
+    /**
+     * Documents that remained in the query results but had their data modified.
+     */
     readonly modified: DocumentChange<T>[];
 }
+/**
+ * Classification of a change event based on the types of document changes it contains.
+ *
+ * - 'addedAndRemoved': Both additions and removals occurred
+ * - 'added': Only additions occurred
+ * - 'removed': Only removals occurred
+ * - 'modified': Only modifications occurred
+ * - 'none': No changes occurred
+ */
 export type IterationQueryDocChangeWatcherChangeType = 'addedAndRemoved' | 'added' | 'removed' | 'modified' | 'none';
+/**
+ * Creates a watcher for monitoring changes to Firestore query results.
+ *
+ * This function sets up observables that track document changes (additions, removals,
+ * and modifications) in the results of a Firestore query over time. It provides both
+ * raw query snapshots and processed change events, making it easier to react to
+ * specific types of changes.
+ *
+ * @template T - The document data type
+ * @param config - Configuration for the watcher, including the iteration instance to watch
+ *                and an optional delay before starting to monitor changes
+ * @returns A watcher object with observables for streaming changes
+ *
+ * @example
+ * // Create a watcher for changes to active users
+ * const usersIterator = firestoreItemPageIterator({
+ *   queryFactory: () => collection(firestore, 'users').where('status', '==', 'active'),
+ *   pageSize: 10
+ * });
+ *
+ * const watcher = iterationQueryDocChangeWatcher({
+ *   instance: usersIterator,
+ *   delay: 1000 // wait 1 second after first results before watching for changes
+ * });
+ *
+ * // React to specific change types
+ * watcher.event$.subscribe(event => {
+ *   if (event.type === 'added') {
+ *     console.log('New users added:', event.added.map(change => change.doc.data()));
+ *   }
+ * });
+ */
 export declare function iterationQueryDocChangeWatcher<T = unknown>(config: IterationQueryDocChangeWatcherConfig<T>): IterationQueryDocChangeWatcher<T>;
+/**
+ * Determines the overall change type for a group of document changes.
+ *
+ * This function analyzes a change group to classify it based on the types of changes
+ * it contains. It follows a priority order for classification:
+ * 1. If both additions and removals are present, classify as 'addedAndRemoved'.
+ * 2. If only additions are present, classify as 'added'.
+ * 3. If only removals are present, classify as 'removed'.
+ * 4. If only modifications are present, classify as 'modified'.
+ * 5. If no changes are present, classify as 'none'.
+ *
+ * @template T - The document data type
+ * @param group - The change group to classify
+ * @returns The overall change type classification
+ */
 export declare function iterationQueryDocChangeWatcherChangeTypeForGroup<T = unknown>(group: IterationQueryDocChangeWatcherChangeGroup<T>): IterationQueryDocChangeWatcherChangeType;

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

@@ -1,2 +1,28 @@
 import { type FirestoreModelData, type SnapshotConverterConfig, type SnapshotConverterFunctions } from './snapshot.type';
+/**
+ * Creates converter functions for transforming between Firestore document snapshots and application model objects.
+ *
+ * This function generates a set of utility functions that handle the conversion between your application's
+ * typed model objects and the data format stored in Firestore. It supports field-level conversions,
+ * custom modifiers, and handles Firestore's merge options appropriately.
+ *
+ * @template T - The application model type that will be used in your application code
+ * @template O - The data type that will be stored in Firestore (defaults to FirestoreModelData<T>)
+ * @param config - Configuration for the converter, including field mappings and modifiers
+ * @returns A set of functions for converting between Firestore data and application models
+ *
+ * @example
+ * // Create a converter for a User model
+ * const userConverter = snapshotConverterFunctions<User, UserData>({
+ *   fields: {
+ *     createdAt: {
+ *       from: (date: string) => new Date(date),
+ *       to: (date: Date) => date.toISOString()
+ *     }
+ *   }
+ * });
+ *
+ * // Use with a collection reference
+ * const usersCollection = firestore.collection('users').withConverter(userConverter);
+ */
 export declare function snapshotConverterFunctions<T extends object, O extends object = FirestoreModelData<T>>(config: SnapshotConverterConfig<T, O>): SnapshotConverterFunctions<T, O>;