@dereekb/firebase 13.11.13 → 13.11.15

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

@@ -1,4 +1,5 @@
 import { type Observable } from 'rxjs';
+import type { Maybe } from '@dereekb/util';
 import { type DocumentData, type DocumentReference, type DocumentSnapshot, type FirestoreDataConverter, type PartialWithFieldValue, type SetOptions, type UpdateData, type WithFieldValue, type WriteResult } from '../types';
 import { type FirestoreAccessorArrayUpdate, type FirestoreAccessorIncrementUpdate, type FirestoreDocumentDataAccessor, type FirestoreDocumentDataAccessorFactory, type FirestoreDocumentDeleteParams, type FirestoreDocumentUpdateParams } from './accessor';
 /**
@@ -16,98 +17,99 @@ export declare abstract class AbstractFirestoreDocumentDataAccessorWrapper<T, D
     /**
      * Creates a new accessor wrapper.
      *
-     * @param accessor - The accessor instance to wrap
+     * @param accessor - The accessor instance to wrap.
      */
     constructor(accessor: FirestoreDocumentDataAccessor<T, D>);
     /**
      * Gets the wrapped accessor instance.
      *
-     * @returns The wrapped FirestoreDocumentDataAccessor 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
+     * @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
+     * @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
+     * @param data - Initial document contents.
+     * @returns 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
+     * @returns Resolves with the latest snapshot read for this document.
      */
     get(): Promise<DocumentSnapshot<T>>;
     /**
      * Gets the document snapshot with a specific data converter.
      *
+     * @param converter - Converter applied to the raw snapshot, or null to skip conversion.
+     * @returns Resolves with the converted snapshot.
+     *
      * @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>>;
+    getWithConverter<U = DocumentData>(converter: Maybe<FirestoreDataConverter<U>>): Promise<DocumentSnapshot<U>>;
     /**
      * Checks if the document exists.
      *
-     * @returns A Promise that resolves with true if the document exists, false otherwise
+     * @returns Resolves with true when the document is present, otherwise false.
      */
     exists(): Promise<boolean>;
     /**
      * Deletes the document.
      *
-     * @param params - Optional parameters for the delete operation
-     * @returns A Promise that resolves when the delete operation completes
+     * @param params - Overrides applied to the delete operation, if any.
+     * @returns 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
+     * @param data - Partial fields written to the document.
+     * @param options - Controls merge behavior (e.g., merge or mergeFields).
+     * @returns 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
+     * @param data - Full replacement contents for the document.
+     * @returns 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
+     * @param data - Field paths mapped to their new values.
+     * @param params - Overrides applied to the update operation, if any.
+     * @returns 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
+     * @param data - Field paths mapped to their increment amounts.
+     * @param params - Overrides applied to the increment operation, if any.
+     * @returns Resolves when the increment operation completes.
      */
     increment(data: FirestoreAccessorIncrementUpdate<T>, params?: FirestoreDocumentUpdateParams): Promise<WriteResult | void>;
     /**
      * Updates array fields in the document.
      *
-     * @param data - The array update to apply
-     * @param params - Optional parameters for the update operation
-     * @returns A Promise that resolves when the update operation completes
+     * @param data - Array operations (union/remove) to apply per field.
+     * @param params - Overrides applied to the update operation, if any.
+     * @returns Resolves when the update operation completes.
      */
     arrayUpdate(data: FirestoreAccessorArrayUpdate<T>, params?: FirestoreDocumentUpdateParams): Promise<WriteResult | void>;
 }
@@ -132,10 +134,12 @@ export type InterceptAccessorFactoryFunction<T, D = DocumentData> = (input: Fire
  * original factory with the provided wrapper function, allowing for consistent modification
  * of all accessors created through the factory.
  *
+ * @param wrap - Wraps each accessor produced by the original factory.
+ * @returns Factory transformer that pipes accessors through the wrapper.
+ *
  * @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
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function interceptAccessorFactoryFunction<T, D = DocumentData>(wrap: WrapFirestoreDocumentDataAccessorFunction<T, D>): InterceptAccessorFactoryFunction<T, D>;

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

@@ -58,8 +58,9 @@ export declare class ModifyBeforeSetFirestoreDocumentDataAccessorWrapper<T exten
  *
  * Useful for models that need to store their own document ID as a field (e.g., `uid` on {@link UserRelated} models).
  *
- * @param fieldName - The field to copy the document ID into
- * @returns A modifier function that sets the field to the document's ID
+ * @param fieldName - The field to copy the document ID into.
+ * @returns A modifier function that sets the field to the document's ID.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function copyDocumentIdToFieldModifierFunction<T extends object>(fieldName: keyof T): ModifyBeforeSetModifierFunction<T>;
@@ -67,15 +68,17 @@ export declare function copyDocumentIdToFieldModifierFunction<T extends object>(
  * Creates an {@link InterceptAccessorFactoryFunction} that wraps all created accessors with
  * {@link ModifyBeforeSetFirestoreDocumentDataAccessorWrapper} using the provided config.
  *
- * @param config - The ModifyBeforeSetConfig defining when and how to modify documents
- * @returns An InterceptAccessorFactoryFunction that wraps accessors with the modify-before-set behavior
+ * @param config - The ModifyBeforeSetConfig defining when and how to modify documents.
+ * @returns An InterceptAccessorFactoryFunction that wraps accessors with the modify-before-set behavior.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function modifyBeforeSetInterceptAccessorFactoryFunction<T extends object, D = DocumentData>(config: ModifyBeforeSetConfig<T>): InterceptAccessorFactoryFunction<T, D>;
 /**
  * Creates a modifier that copies the document ID to the `uid` field for {@link UserRelated} models.
  *
- * @returns A ModifyBeforeSetModifierFunction that sets the `uid` field to the document's ID
+ * @returns A ModifyBeforeSetModifierFunction that sets the `uid` field to the document's ID.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function copyDocumentIdForUserRelatedModifierFunction<T extends UserRelated>(): ModifyBeforeSetModifierFunction<T>;
@@ -83,7 +86,7 @@ export declare function copyDocumentIdForUserRelatedModifierFunction<T extends U
  * Returns a pre-configured {@link ModifyBeforeSetConfig} for {@link UserRelated} models
  * that copies the document ID to the `uid` field on set operations (new document creation).
  *
- * @returns A ModifyBeforeSetConfig configured to copy the document ID to the `uid` field on set
+ * @returns A ModifyBeforeSetConfig configured to copy the document ID to the `uid` field on set.
  */
 export declare function copyUserRelatedDataModifierConfig<T extends UserRelated>(): ModifyBeforeSetConfig<T>;
 /**
@@ -94,7 +97,8 @@ export declare const COPY_USER_RELATED_DATA_ACCESSOR_FACTORY_FUNCTION: import("@
  * Returns a typed {@link InterceptAccessorFactoryFunction} that applies the UserRelated
  * document ID copy modifier to all accessors created by the factory.
  *
- * @returns A typed InterceptAccessorFactoryFunction with the UserRelated document ID copy modifier applied
+ * @returns A typed InterceptAccessorFactoryFunction with the UserRelated document ID copy modifier applied.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function copyUserRelatedDataAccessorFactoryFunction<T extends UserRelated, D = DocumentData>(): InterceptAccessorFactoryFunction<T, D>;

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

@@ -13,10 +13,11 @@ export type ArrayFieldUpdateWithAccessorFunction<T> = (data: FirestoreAccessorAr
  * the operation entirely if no valid fields remain. Uses Firestore's built-in `arrayUnion`
  * and `arrayRemove` operations, which are safe for concurrent updates.
  *
- * @param accessor - The document accessor to perform the array update on
- * @returns A function that applies array updates to the document
+ * @param accessor - Accessor used to apply the array update.
+ * @returns Update function that runs the supplied array operations.
  *
  * @see https://firebase.google.com/docs/firestore/manage-data/add-data#update_elements_in_an_array
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function arrayUpdateWithAccessorFunction<T>(accessor: FirestoreDocumentDataAccessor<T>): ArrayFieldUpdateWithAccessorFunction<T>;

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

@@ -82,8 +82,8 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
      *
      * Passively populates the cache with each emitted snapshot.
      *
-     * @param mode - The stream mode controlling how the Observable emits snapshot updates
-     * @returns An Observable that emits DocumentSnapshot values based on the given mode
+     * @param mode - The stream mode controlling how the Observable emits snapshot updates.
+     * @returns An Observable that emits DocumentSnapshot values based on the given mode.
      */
     snapshotStream(mode: FirestoreAccessorStreamMode): Observable<DocumentSnapshot<T>>;
     /**
@@ -91,9 +91,9 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
      *
      * Passively populates the cache via {@link snapshotStream}.
      *
-     * @param mode - The stream mode controlling how the Observable emits snapshot data updates
-     * @param options - Optional SnapshotOptions for reading the document data
-     * @returns An Observable that emits the document data or undefined based on the given mode
+     * @param mode - The stream mode controlling how the Observable emits snapshot data updates.
+     * @param options - Optional SnapshotOptions for reading the document data.
+     * @returns An Observable that emits the document data or undefined based on the given mode.
      */
     snapshotDataStream(mode: FirestoreAccessorStreamMode, options?: SnapshotOptions): Observable<Maybe<T>>;
     /**
@@ -101,7 +101,7 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
      *
      * Passively populates the cache with the fetched snapshot.
      *
-     * @returns A Promise resolving to the document snapshot
+     * @returns Resolves with the freshly fetched snapshot.
      */
     snapshot(): Promise<DocumentSnapshot<T>>;
     /**
@@ -110,8 +110,8 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
      * If a fresh cache entry exists, returns it without hitting Firestore.
      * Otherwise falls through to {@link snapshot} which populates the cache.
      *
-     * @param options - Optional SnapshotOptions for reading the document data
-     * @returns A Promise resolving to the document data, or undefined if the document does not exist
+     * @param options - Overrides forwarded to `DocumentSnapshot.data()`, if any.
+     * @returns Resolves with the document data, or undefined when the document does not exist.
      */
     snapshotData(options?: SnapshotOptions): Promise<Maybe<T>>;
     /**
@@ -126,8 +126,8 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
      *
      * Populates the cache with the written data after a successful create.
      *
-     * @param data - The document data to create
-     * @returns A Promise that resolves when the create completes
+     * @param data - Initial document contents.
+     * @returns Resolves when the create completes.
      */
     create(data: T): Promise<WriteResult | void>;
     /**
@@ -138,9 +138,9 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
      * Invalidates the cache entry since partial updates don't provide the full document.
      * Throws an exception when the document does not exist.
      *
-     * @param data - Partial document data to update
-     * @param params - Optional update parameters
-     * @returns A Promise that resolves when the update completes
+     * @param data - Partial field values written to the existing document.
+     * @param params - Overrides applied to the update operation, if any.
+     * @returns Resolves when the update completes.
      */
     update(data: Partial<T>, params?: FirestoreDocumentUpdateParams): Promise<WriteResult | void>;
     /**
@@ -148,8 +148,8 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
      *
      * Invalidates the cache entry since increment updates don't provide the full document.
      *
-     * @param data - The increment update to apply to numeric fields
-     * @returns A Promise that resolves when the increment update completes
+     * @param data - Field paths mapped to their increment amounts.
+     * @returns Resolves when the increment update completes.
      */
     increment(data: FirestoreAccessorIncrementUpdate<T>): Promise<WriteResult | void>;
     /**
@@ -157,8 +157,8 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
      *
      * Invalidates the cache entry since array updates don't provide the full document.
      *
-     * @param data - The array field update to apply (union or remove elements)
-     * @returns A Promise that resolves when the array update completes
+     * @param data - Array operations (union/remove) to apply per field.
+     * @returns Resolves when the array update completes.
      */
     arrayUpdate(data: FirestoreAccessorArrayUpdate<T>): Promise<WriteResult | void>;
 }
@@ -298,8 +298,9 @@ export interface LimitedFirestoreDocumentAccessorFactoryConfig<T, D extends Fire
 /**
  * Creates a {@link LimitedFirestoreDocumentAccessorFactoryFunction} from the provided configuration.
  *
- * @param config - Configuration including converter, accessor factory, and document factory
- * @returns A factory function for creating LimitedFirestoreDocumentAccessor instances
+ * @param config - Configuration including converter, accessor factory, and document factory.
+ * @returns A factory function for creating LimitedFirestoreDocumentAccessor instances.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function limitedFirestoreDocumentAccessorFactory<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: LimitedFirestoreDocumentAccessorFactoryConfig<T, D>): LimitedFirestoreDocumentAccessorFactoryFunction<T, D>;
@@ -323,8 +324,9 @@ export interface FirestoreDocumentAccessorFactoryConfig<T, D extends FirestoreDo
  * Extends the limited accessor factory with collection-level operations such as creating new documents
  * and loading documents by ID.
  *
- * @param config - Configuration including the collection reference and document factory
- * @returns A factory function for creating FirestoreDocumentAccessor instances
+ * @param config - Configuration including the collection reference and document factory.
+ * @returns A factory function for creating FirestoreDocumentAccessor instances.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreDocumentAccessorFactory<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: FirestoreDocumentAccessorFactoryConfig<T, D>): FirestoreDocumentAccessorFactoryFunction<T, D>;
@@ -400,8 +402,9 @@ export interface FirestoreSingleDocumentAccessorConfig<T, D extends FirestoreDoc
 /**
  * Creates a {@link FirestoreSingleDocumentAccessor} for a collection that contains a single known document.
  *
- * @param config - Configuration specifying the single item identifier and the document accessor context extension
- * @returns A FirestoreSingleDocumentAccessor providing convenient access to the single document
+ * @param config - Configuration specifying the single item identifier and the document accessor context extension.
+ * @returns A FirestoreSingleDocumentAccessor providing convenient access to the single document.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreSingleDocumentAccessor<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: FirestoreSingleDocumentAccessorConfig<T, D>): FirestoreSingleDocumentAccessor<T, D>;
@@ -427,7 +430,7 @@ export interface SingleItemFirestoreCollectionDocumentIdentifierRef {
 /**
  * Extends a Firestore collection object in-place with single-document accessor methods.
  *
- * @param x - The collection object to extend with single-document accessor methods
+ * @param x - The collection object to extend with single-document accessor methods.
  * @param singleItemIdentifier - Optional identifier for the single document; defaults to {@link DEFAULT_SINGLE_ITEM_FIRESTORE_COLLECTION_DOCUMENT_IDENTIFIER}
  */
 export declare function extendFirestoreCollectionWithSingleDocumentAccessor<X extends FirestoreSingleDocumentAccessor<T, D> & FirestoreDocumentAccessorContextExtension<T, D>, T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(x: Building<X>, singleItemIdentifier?: SingleItemFirestoreCollectionDocumentIdentifier): void;

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

@@ -128,7 +128,7 @@ export interface PagedItemAccessorExtensionConfig<T> {
  * {@link FirestoreContextReference} from its base — both are provided by
  * {@link makeFirestoreCollectionWithParent}.
  *
- * @param x - The collection object to extend
- * @param config - Paged accessor configuration
+ * @param x - The collection object to extend.
+ * @param config - Paged accessor configuration.
  */
 export declare function extendFirestoreCollectionWithPagedItemAccessor<X extends FirestorePagedItemAccessor<T> & CollectionReferenceRef<unknown> & FirestoreContextReference, T>(x: Building<X>, config: PagedItemAccessorExtensionConfig<T>): void;

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

@@ -11,9 +11,10 @@ import { type FirestoreDocumentSnapshotDataPair, type FirestoreDocumentSnapshotD
  *
  * If the input array is empty, an Observable that emits an empty array is returned.
  *
+ * @param documents - Array of document instances to stream snapshots for.
+ * @returns Observable that emits arrays of DocumentSnapshots whenever any document changes.
+ *
  * @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>>[]>;
 /**
@@ -27,9 +28,9 @@ export declare function latestSnapshotsFromDocuments<D extends FirestoreDocument
  *
  * Returns `of([])` for an empty input array.
  *
- * @param documents - Documents to stream from
- * @param operator - RxJS operator applied to each document's snapshot stream individually
- * @returns Observable emitting an array of transformed values whenever any document changes
+ * @param documents - Documents to stream from.
+ * @param operator - RxJS operator applied to each document's snapshot stream individually.
+ * @returns Observable emitting an array of transformed values whenever any document changes.
  */
 export declare function mapLatestSnapshotsFromDocuments<D extends FirestoreDocument<any>, O>(documents: D[], operator: OperatorFunction<DocumentSnapshot<FirestoreDocumentData<D>>, O>): Observable<O[]>;
 /**
@@ -42,9 +43,10 @@ export declare function mapLatestSnapshotsFromDocuments<D extends FirestoreDocum
  *
  * Non-existent documents are filtered out of the results automatically.
  *
+ * @param documents - Array of document instances to stream data for.
+ * @returns Observable that emits arrays of document data whenever any document changes.
+ *
  * @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 streamDocumentSnapshotsData<D extends FirestoreDocument<any>>(documents: D[]): Observable<DocumentDataWithIdAndKey<FirestoreDocumentData<D>>[]>;
 /**
@@ -54,8 +56,9 @@ export declare function streamDocumentSnapshotsData<D extends FirestoreDocument<
  * and filters out non-existent documents. It's designed to be used in a pipe after
  * operations that produce arrays of snapshots.
  *
+ * @returns An operator that transforms arrays of DocumentSnapshots into arrays of document data.
+ *
  * @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>[]>;
 /**
@@ -70,8 +73,8 @@ export declare function dataFromDocumentSnapshots<T>(): OperatorFunction<Documen
  *
  * This is the streaming equivalent of {@link import('./document.utility').getDocumentSnapshotDataPairs}.
  *
- * @param documents - Documents to stream snapshot-data pairs for
- * @returns Observable emitting snapshot-data pairs whenever any document changes
+ * @param documents - Documents to stream snapshot-data pairs for.
+ * @returns Observable emitting snapshot-data pairs whenever any document changes.
  */
 export declare function streamDocumentSnapshotDataPairs<D extends FirestoreDocument<any>>(documents: D[]): Observable<FirestoreDocumentSnapshotDataPair<D>[]>;
 /**
@@ -85,8 +88,8 @@ export declare function streamDocumentSnapshotDataPairs<D extends FirestoreDocum
  *
  * This is the streaming equivalent of {@link import('./document.utility').getDocumentSnapshotDataPairsWithData}.
  *
- * @param documents - Documents to stream snapshot-data pairs for
- * @returns Observable emitting snapshot-data pairs for existing documents only, whenever any document changes
+ * @param documents - Documents to stream snapshot-data pairs for.
+ * @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>[]>;
 /**