@dereekb/firebase 13.4.0 → 13.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.4.0",
+  "version": "13.4.2",
   "exports": {
     "./test": {
       "module": "./test/index.esm.js",
@@ -17,10 +17,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/util": "13.4.0",
-    "@dereekb/date": "13.4.0",
-    "@dereekb/model": "13.4.0",
-    "@dereekb/rxjs": "13.4.0",
+    "@dereekb/util": "13.4.2",
+    "@dereekb/date": "13.4.2",
+    "@dereekb/model": "13.4.2",
+    "@dereekb/rxjs": "13.4.2",
     "@firebase/rules-unit-testing": "5.0.0",
     "arktype": "^2.2.0",
     "date-fns": "^4.0.0",

package/src/lib/client/error/error.d.ts

@@ -20,4 +20,4 @@ import { type FirebaseError } from 'firebase/app';
  * }
  * ```
  */
-export declare function isClientFirebaseError(error: any): error is FirebaseError;
+export declare function isClientFirebaseError(error: unknown): error is FirebaseError;

package/src/lib/client/firestore/driver.accessor.batch.d.ts

@@ -22,6 +22,7 @@ export declare class WriteBatchFirestoreDocumentDataAccessor<T> extends DefaultF
  * into the same batch.
  *
  * @param writeBatch - the Firestore `WriteBatch` to queue operations into
+ * @returns a factory that creates write-batch-backed document data accessors for any document reference
  *
  * @example
  * ```ts
@@ -50,6 +51,7 @@ export declare class WriteBatchFirestoreDocumentContext<T> implements FirestoreD
  * Factory function that creates a {@link WriteBatchFirestoreDocumentContext} for the given batch.
  *
  * @param batch - the Firestore `WriteBatch` to use for all document operations
+ * @returns a new {@link WriteBatchFirestoreDocumentContext} bound to the given batch
  *
  * @example
  * ```ts

package/src/lib/client/firestore/driver.accessor.create.d.ts

@@ -7,6 +7,7 @@ import { type WithFieldValue, type WriteResult } from '../../common/firestore/ty
  * Checks for document existence first, then calls `set()` if the document is absent.
  *
  * @param accessor - the accessor to perform the existence check and set operation on
+ * @returns a function that creates the document if it does not exist, or throws if it does
  * @throws {Error} When the document already exists at the reference path
  *
  * @example

package/src/lib/client/firestore/driver.accessor.d.ts

@@ -8,6 +8,8 @@ import { type FirestoreAccessorDriver } from '../../common/firestore/driver/acce
  * - Transaction and write batch context factories for atomic operations
  * - A default (non-transactional) document context
  *
+ * @returns a {@link FirestoreAccessorDriver} backed by the `firebase/firestore` client SDK
+ *
  * @example
  * ```ts
  * const driver = firestoreClientAccessorDriver();

package/src/lib/client/firestore/driver.accessor.default.d.ts

@@ -29,6 +29,8 @@ export declare class DefaultFirestoreDocumentDataAccessor<T> implements Firestor
  * Creates a {@link FirestoreDocumentDataAccessorFactory} that produces {@link DefaultFirestoreDocumentDataAccessor} instances
  * for direct (non-batched, non-transactional) Firestore operations.
  *
+ * @returns a factory that creates default (non-transactional) document data accessors
+ *
  * @example
  * ```ts
  * const factory = defaultFirestoreAccessorFactory<MyModel>();
@@ -43,6 +45,8 @@ export declare function defaultFirestoreAccessorFactory<T>(): FirestoreDocumentD
  * The context type is {@link FirestoreDocumentContextType.NONE}, meaning operations execute immediately
  * against Firestore without transaction or batch grouping.
  *
+ * @returns a default {@link FirestoreDocumentContext} with no transaction or batch semantics
+ *
  * @example
  * ```ts
  * const context = defaultFirestoreDocumentContext<MyModel>();

package/src/lib/client/firestore/driver.accessor.transaction.d.ts

@@ -30,6 +30,7 @@ export declare class TransactionFirestoreDocumentDataAccessor<T> implements Fire
  * instances bound to the given transaction. All operations from these accessors participate in the same transaction.
  *
  * @param transaction - the Firestore `Transaction` to bind operations to
+ * @returns a factory that creates transaction-backed document data accessors for any document reference
  *
  * @example
  * ```ts
@@ -59,6 +60,7 @@ export declare class TransactionFirestoreDocumentContext<T> implements Firestore
  * Factory function that creates a {@link TransactionFirestoreDocumentContext} for the given transaction.
  *
  * @param transaction - the Firestore `Transaction` to use for all document operations
+ * @returns a new {@link TransactionFirestoreDocumentContext} bound to the given transaction
  *
  * @example
  * ```ts

package/src/lib/client/firestore/driver.d.ts

@@ -10,6 +10,8 @@ export type FirebaseFirestoreClientDrivers = FirestoreDrivers;
  * Provides accessor drivers (default, batch, transaction) and query drivers for use
  * with {@link clientFirebaseFirestoreContextFactory}.
  *
+ * @returns the client-side {@link FirebaseFirestoreClientDrivers} for the `firebase/firestore` SDK
+ *
  * @example
  * ```ts
  * const drivers = firebaseFirestoreClientDrivers();

package/src/lib/client/firestore/driver.query.d.ts

@@ -18,6 +18,7 @@ export interface FirebaseFirestoreQueryBuilder {
  *
  * @param builder - current query builder state
  * @param constraint - constraint(s) to append
+ * @returns a new {@link FirebaseFirestoreQueryBuilder} with the added constraint(s)
  */
 export declare function addConstraintToBuilder(builder: FirebaseFirestoreQueryBuilder, constraint: ArrayOrValue<QueryConstraint>): FirebaseFirestoreQueryBuilder;
 /**
@@ -31,6 +32,8 @@ export declare const FIRESTORE_CLIENT_QUERY_CONSTRAINT_HANDLER_MAPPING: FullFire
  *
  * Converts abstract query constraints into `firebase/firestore` `QueryConstraint` objects
  * and composes them into an executable `Query`.
+ *
+ * @returns a {@link FirestoreQueryConstraintFunctionsDriver} backed by the `firebase/firestore` client SDK
  */
 export declare function firebaseFirestoreQueryConstraintFunctionsDriver(): FirestoreQueryConstraintFunctionsDriver;
 /**
@@ -40,6 +43,8 @@ export declare function firebaseFirestoreQueryConstraintFunctionsDriver(): Fires
  * Note: Transactions are not supported for queries on the client; passing a `transaction` to `getDocs`
  * will throw an error.
  *
+ * @returns a {@link FirestoreQueryDriver} backed by the `firebase/firestore` client SDK
+ *
  * @example
  * ```ts
  * const queryDriver = firebaseFirestoreQueryDriver();

package/src/lib/client/function/development.function.factory.d.ts

@@ -25,6 +25,7 @@ export type DevelopmentFirebaseFunctionMapFactory<M extends DevelopmentFirebaseF
  * through a single endpoint. The function specifier and data are wrapped via {@link onCallDevelopmentParams}.
  *
  * @param configMap - maps each development function key to optional configuration
+ * @returns a factory that creates a {@link DevelopmentFirebaseFunctionMap} for a given `Functions` instance
  *
  * @example
  * ```ts

package/src/lib/client/function/error.d.ts

@@ -28,6 +28,7 @@ export declare class FirebaseServerError<T extends ServerErrorResponseData = Ser
      * structured error details from the error's `details` property if available.
      *
      * @param error - the Firebase error from an `HttpsCallable` failure
+     * @returns a new {@link FirebaseServerError} wrapping the given Firebase error with structured server error details
      */
     static fromFirebaseError(error: FirebaseError): FirebaseServerError;
     constructor(firebaseError: FirebaseError, serverError: ServerError<T>);

package/src/lib/client/function/function.callable.d.ts

@@ -9,9 +9,13 @@ import { type HttpsCallable } from 'firebase/functions';
  * @template B - the internal output type (what the callable returns)
  */
 export interface MapHttpsCallable<I, O, A, B> {
-    /** Transforms the caller's input into the format expected by the underlying callable. */
+    /**
+     * Transforms the caller's input into the format expected by the underlying callable.
+     */
     readonly mapInput?: FactoryWithInput<PromiseOrValue<A>, Maybe<I>>;
-    /** Transforms the callable's raw output into the format returned to callers. */
+    /**
+     * Transforms the callable's raw output into the format returned to callers.
+     */
     readonly mapOutput?: FactoryWithInput<PromiseOrValue<O>, Maybe<B>>;
 }
 /**
@@ -24,6 +28,7 @@ export interface MapHttpsCallable<I, O, A, B> {
  * @param callable - the underlying Firebase `HttpsCallable` to wrap
  * @param wrap - input/output mapping functions
  * @param directData - when `true`, returns the unwrapped data instead of `HttpsCallableResult`
+ * @returns a wrapped callable that applies input/output transformations and converts errors to readable forms
  *
  * @example
  * ```ts
@@ -49,6 +54,7 @@ export type DirectDataHttpsCallable<C extends HttpsCallable<any, any>> = C exten
  * Errors are converted to readable errors via {@link convertHttpsCallableErrorToReadableError}.
  *
  * @param callable - the `HttpsCallable` to wrap
+ * @returns a {@link DirectDataHttpsCallable} that resolves to the response data directly
  *
  * @example
  * ```ts
@@ -64,5 +70,6 @@ export declare function directDataHttpsCallable<I, O, C extends HttpsCallable<I,
  * to preserve server-side error context. Otherwise, converts it to a generic readable error via `toReadableError`.
  *
  * @param error - the caught error from an `HttpsCallable` invocation
+ * @returns a {@link FirebaseServerError} if the error has structured details, or a generic readable error otherwise
  */
 export declare function convertHttpsCallableErrorToReadableError(error: unknown): unknown;

package/src/lib/client/function/function.factory.d.ts

@@ -28,6 +28,7 @@ export type FirebaseFunctionMapFactory<M extends FirebaseFunctionTypeMap> = (fun
  * for direct data access. Per-key options (e.g., timeout) are applied if provided.
  *
  * @param configMap - maps function keys to their optional configuration
+ * @returns a {@link FirebaseFunctionMapFactory} that creates a typed callable function map for a given `Functions` instance
  *
  * @example
  * ```ts
@@ -91,6 +92,7 @@ export type LazyFirebaseFunctions<M extends FirebaseFunctionsMap> = {
  * so `httpsCallable` instances are only created when actually needed.
  *
  * @param configMap - maps each function group key to its `[ClassType, Factory]` tuple
+ * @returns a {@link LazyFirebaseFunctionsFactory} that creates a lazy-loaded function map for a given `Functions` instance
  *
  * @example
  * ```ts

package/src/lib/client/function/model.function.factory.d.ts

@@ -26,11 +26,17 @@ export type ModelFirebaseCrudFunction<I, O = void> = FirebaseFunction<I, O>;
  * Create function for a model. Returns {@link OnCallCreateModelResult} containing the created document's key by default.
  */
 export type ModelFirebaseCreateFunction<I, O extends OnCallCreateModelResult = OnCallCreateModelResult> = ModelFirebaseCrudFunction<I, O>;
-/** Read function for a model, returning the read data. */
+/**
+ * Read function for a model, returning the read data.
+ */
 export type ModelFirebaseReadFunction<I, O> = ModelFirebaseCrudFunction<I, O>;
-/** Update function for a model. Returns void by default. */
+/**
+ * Update function for a model. Returns void by default.
+ */
 export type ModelFirebaseUpdateFunction<I, O = void> = ModelFirebaseCrudFunction<I, O>;
-/** Delete function for a model. Returns void by default. */
+/**
+ * Delete function for a model. Returns void by default.
+ */
 export type ModelFirebaseDeleteFunction<I, O = void> = ModelFirebaseCrudFunction<I, O>;
 /**
  * Maps each model type (from a {@link FirestoreModelIdentity}) to its CRUD function type configuration.
@@ -101,7 +107,7 @@ export type ModelFirebaseCrudFunctionMapEntry<MODEL extends string, E extends Mo
 export type ModelFirebaseCrudFunctionMapEntrySpecifier<MODEL extends string, CRUD extends string, M extends unknown | ModelFirebaseCrudFunctionTypeSpecifierConfig> = {
     [SPECIFIER in keyof M as SPECIFIER extends string ? (CRUD extends string ? (SPECIFIER extends ModelFirebaseCrudFunctionSpecifierDefault ? ModelFirebaseCrudFunctionName<MODEL, CRUD> : ModelFirebaseCrudFunctionWithSpecifierName<MODEL, CRUD, SPECIFIER>) : never) : never]: ModelFirebaseCrudFunctionMapEntryFunction<M, SPECIFIER, CRUD>;
 };
-export type ModelFirebaseCrudFunctionMapEntrySpecifierShort<MODEL extends string, CRUD extends string, M extends unknown | ModelFirebaseCrudFunctionTypeSpecifierConfig> = {
+export type ModelFirebaseCrudFunctionMapEntrySpecifierShort<_MODEL extends string, CRUD extends string, M extends unknown | ModelFirebaseCrudFunctionTypeSpecifierConfig> = {
     [SPECIFIER in keyof M as SPECIFIER extends string ? (CRUD extends string ? (SPECIFIER extends ModelFirebaseCrudFunctionSpecifierDefault ? CRUD : SPECIFIER) : never) : never]: ModelFirebaseCrudFunctionMapEntryFunction<M, SPECIFIER, CRUD>;
 };
 export declare type ModelFirebaseCrudFunctionMapEntryFunction<E extends unknown | ModelFirebaseCrudFunctionTypeSpecifierConfig, K extends keyof E, CRUD extends string> = E[K] extends ModelFirebaseCrudFunctionTypeMapEntryWithReturnType<infer I, infer O> ? ModelFirebaseCrudFunction<I, O> : CRUD extends 'create' ? ModelFirebaseCreateFunction<E[K]> : ModelFirebaseCrudFunction<E[K]>;
@@ -127,6 +133,7 @@ export type ModelFirebaseFunctionMapFactory<M extends FirebaseFunctionTypeMap, U
  *
  * @param configMap - configuration for custom (non-CRUD) functions
  * @param crudConfigMap - configuration for model CRUD functions with optional specifiers
+ * @returns a {@link ModelFirebaseFunctionMapFactory} that creates a combined custom and CRUD function map for a given `Functions` instance
  *
  * @example
  * ```ts

package/src/lib/client/storage/driver.accessor.d.ts

@@ -9,6 +9,7 @@ import { type ErrorInput, type Maybe } from '@dereekb/util';
  * e.g., to silently handle deletion of already-deleted files.
  *
  * @param input - the error or error message to check
+ * @returns `true` if the error message contains `'storage/object-not-found'`, `false` otherwise
  *
  * @example
  * ```ts
@@ -27,6 +28,7 @@ export declare function isFirebaseStorageObjectNotFoundError(input: Maybe<ErrorI
  *
  * @param storage - the client Firebase Storage instance
  * @param path - abstract storage path to resolve
+ * @returns a `StorageReference` pointing to the resolved storage path
  */
 export declare function firebaseStorageRefForStorageFilePath(storage: ClientFirebaseStorage, path: StoragePath): StorageReference;
 /**
@@ -35,6 +37,7 @@ export declare function firebaseStorageRefForStorageFilePath(storage: ClientFire
  * Returns `true` if metadata is successfully retrieved, `false` for any error (including permission errors).
  *
  * @param ref - the storage reference to check
+ * @returns a promise that resolves to `true` if the file exists, `false` otherwise
  */
 export declare function firebaseStorageFileExists(ref: StorageReference): Promise<boolean>;
 /**
@@ -49,6 +52,7 @@ export type FirebaseStorageClientAccessorFile = FirebaseStorageAccessorFile<Stor
  *
  * @param storage - the client Firebase Storage instance
  * @param storagePath - the abstract storage path for the file
+ * @returns a {@link FirebaseStorageClientAccessorFile} providing CRUD and upload operations for the given path
  *
  * @example
  * ```ts
@@ -85,6 +89,7 @@ export declare const firebaseStorageClientListFilesResultFactory: import("../.."
  *
  * @param storage - the client Firebase Storage instance
  * @param storagePath - the abstract storage path for the folder
+ * @returns a {@link FirebaseStorageClientAccessorFolder} providing listing and existence operations for the given path
  *
  * @example
  * ```ts
@@ -101,6 +106,8 @@ export declare function firebaseStorageClientAccessorFolder(storage: ClientFireb
  * Provides file and folder accessor factories and default bucket resolution.
  * Used internally by {@link firebaseStorageClientDrivers}.
  *
+ * @returns a {@link FirebaseStorageAccessorDriver} backed by the `firebase/storage` client SDK
+ *
  * @example
  * ```ts
  * const driver = firebaseStorageClientAccessorDriver();

package/src/lib/client/storage/driver.d.ts

@@ -9,6 +9,8 @@ export type FirebaseStorageClientDrivers = FirebaseStorageDrivers;
  *
  * Provides file and folder accessor operations for use with {@link clientFirebaseStorageContextFactory}.
  *
+ * @returns the client-side {@link FirebaseStorageClientDrivers} for the `firebase/storage` SDK
+ *
  * @example
  * ```ts
  * const drivers = firebaseStorageClientDrivers();

package/src/lib/common/auth/auth.error.d.ts

@@ -8,14 +8,34 @@ export interface FirebaseAuthError {
     readonly name: string;
     readonly customData: unknown;
 }
-/** Error code when the user account is not found. */
+/**
+ * Error code when the user account is not found.
+ */
 export declare const FIREBASE_AUTH_USER_NOT_FOUND_ERROR = "auth/user-not-found";
-/** Error code when the password is incorrect. */
+/**
+ * Error code when the password is incorrect.
+ */
 export declare const FIREBASE_AUTH_WRONG_PASSWORD = "auth/wrong-password";
-/** Error code for a network request error (client SDK). */
+/**
+ * Error code for a network request error (client SDK).
+ */
 export declare const FIREBASE_AUTH_NETWORK_REQUEST_ERROR = "auth/network-request-error";
-/** Error code for a failed network request (client SDK). */
+/**
+ * Error code for a failed network request (client SDK).
+ */
 export declare const FIREBASE_AUTH_NETWORK_REQUEST_FAILED = "auth/network-request-failed";
+/**
+ * Error code when a phone number is already associated with another account.
+ */
+export declare const FIREBASE_AUTH_PHONE_NUMBER_ALREADY_EXISTS_ERROR = "auth/phone-number-already-exists";
+/**
+ * Error code when an email is already associated with another account.
+ */
+export declare const FIREBASE_AUTH_EMAIL_ALREADY_EXISTS_ERROR = "auth/email-already-exists";
+/**
+ * Error code when the provided phone number is not a valid E.164 string.
+ */
+export declare const FIREBASE_AUTH_INVALID_PHONE_NUMBER_ERROR = "auth/invalid-phone-number";
 /**
  * Converts a {@link FirebaseAuthError} into a user-friendly {@link ReadableError} with a human-readable message.
  *
@@ -23,6 +43,7 @@ export declare const FIREBASE_AUTH_NETWORK_REQUEST_FAILED = "auth/network-reques
  * suitable for display in the UI.
  *
  * @param inputError - the Firebase Auth error to convert
+ * @returns a {@link ReadableError} with a human-readable message suitable for display
  *
  * @example
  * ```ts

package/src/lib/common/development/function.d.ts

@@ -24,6 +24,7 @@ export interface OnCallDevelopmentParams<T = unknown> {
  *
  * @param specifier - the development function to invoke
  * @param data - the call payload
+ * @returns an {@link OnCallDevelopmentParams} envelope ready to send to the dev endpoint
  *
  * @example
  * ```ts

package/src/lib/common/development/function.schedule.d.ts

@@ -17,7 +17,9 @@ export declare enum ScheduledFunctionDevelopmentFunctionTypeEnum {
  */
 export interface ScheduledFunctionDevelopmentFirebaseFunctionParams {
     readonly type: ScheduledFunctionDevelopmentFunctionTypeEnum;
-    /** Name of the scheduled function to run (required when type is 'run'). */
+    /**
+     * Name of the scheduled function to run (required when type is 'run').
+     */
     readonly run?: string;
 }
 /**

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

@@ -65,15 +65,22 @@ 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
  */
 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
  */
 export declare function copyDocumentIdForUserRelatedModifierFunction<T extends UserRelated>(): ModifyBeforeSetModifierFunction<T>;
 /**
  * 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
  */
 export declare function copyUserRelatedDataModifierConfig<T extends UserRelated>(): ModifyBeforeSetConfig<T>;
 /**
@@ -83,5 +90,7 @@ 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
  */
 export declare function copyUserRelatedDataAccessorFactoryFunction<T extends UserRelated, D = DocumentData>(): InterceptAccessorFactoryFunction<T, D>;

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

@@ -11,11 +11,17 @@ import { type FirestoreDocumentDataAccessorFactory } from './accessor';
  * - BATCH: Operations within a Firestore write batch (atomic writes only, no reads)
  */
 export declare enum FirestoreDocumentContextType {
-    /** Standard context with no special transactional semantics */
+    /**
+     * Standard context with no special transactional semantics
+     */
     NONE = "none",
-    /** Operations within a Firestore transaction (atomic reads and writes) */
+    /**
+     * Operations within a Firestore transaction (atomic reads and writes)
+     */
     TRANSACTION = "transaction",
-    /** Operations within a Firestore write batch (atomic writes only) */
+    /**
+     * Operations within a Firestore write batch (atomic writes only)
+     */
     BATCH = "batch"
 }
 /**

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

@@ -76,23 +76,27 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
     /**
      * Retrieves a DocumentSnapshot of the document as an Observable. Streams based on the input mode.
      *
-     * @returns
+     * @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>>;
     /**
      * Retrieves the data of the DocumentSnapshot of the document as an Observable. Streams based on the input mode.
      *
-     * @param options
-     * @returns
+     * @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>>;
     /**
      * Retrieves a DocumentSnapshot of the document.
+     *
      * @returns
      */
     snapshot(): Promise<DocumentSnapshot<T>>;
     /**
      * Retrieves the data of the DocumentSnapshot of the document.
+     *
      * @param options
      * @returns
      */
@@ -118,20 +122,23 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
      *
      * Throws an exception when it does not exist.
      *
-     * @param data
-     * @returns
+     * @param data - Partial document data to update
+     * @param params - Optional update parameters
+     * @returns A Promise that resolves when the update completes
      */
     update(data: Partial<T>, params?: FirestoreDocumentUpdateParams): Promise<WriteResult | void>;
     /**
      * Updates the document using the accessor's increment functionality.
      *
-     * @param data
+     * @param data - The increment update to apply to numeric fields
+     * @returns A Promise that resolves when the increment update completes
      */
     increment(data: FirestoreAccessorIncrementUpdate<T>): Promise<WriteResult | void>;
     /**
      * Updates the document using the accessor's array field update functionality.
      *
-     * @param data
+     * @param data - The array field update to apply (union or remove elements)
+     * @returns A Promise that resolves when the array update completes
      */
     arrayUpdate(data: FirestoreAccessorArrayUpdate<T>): Promise<WriteResult | void>;
 }
@@ -254,6 +261,12 @@ export interface LimitedFirestoreDocumentAccessorFactoryConfig<T, D extends Fire
     readonly converterFactory?: InterceptFirestoreDataConverterFactory<T>;
     readonly makeDocument: FirestoreDocumentFactoryFunction<T, D>;
 }
+/**
+ * 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
+ */
 export declare function limitedFirestoreDocumentAccessorFactory<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: LimitedFirestoreDocumentAccessorFactoryConfig<T, D>): LimitedFirestoreDocumentAccessorFactoryFunction<T, D>;
 /**
  * Factory function used for creating a FirestoreDocumentAccessor.
@@ -269,6 +282,15 @@ export type FirestoreDocumentAccessorFactory<T, D extends FirestoreDocument<T> =
 export interface FirestoreDocumentAccessorFactoryConfig<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends CollectionReferenceRef<T>, LimitedFirestoreDocumentAccessorFactoryConfig<T, D> {
     readonly makeDocument: FirestoreDocumentFactoryFunction<T, D>;
 }
+/**
+ * Creates a {@link FirestoreDocumentAccessorFactoryFunction} from the provided configuration.
+ *
+ * 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
+ */
 export declare function firestoreDocumentAccessorFactory<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: FirestoreDocumentAccessorFactoryConfig<T, D>): FirestoreDocumentAccessorFactoryFunction<T, D>;
 export interface LimitedFirestoreDocumentAccessorForTransactionFactory<T, D extends FirestoreDocument<T> = FirestoreDocument<T>, A extends LimitedFirestoreDocumentAccessor<T, D> = LimitedFirestoreDocumentAccessor<T, D>> {
     /**
@@ -294,6 +316,14 @@ export interface LimitedFirestoreDocumentAccessorContextExtension<T, D extends F
 }
 export interface FirestoreDocumentAccessorContextExtension<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends FirestoreDocumentAccessorFactory<T, D>, FirestoreDocumentAccessorForTransactionFactory<T, D>, FirestoreDocumentAccessorForWriteBatchFactory<T, D> {
 }
+/**
+ * Creates a context extension object that adds transaction and write batch accessor support to a document accessor.
+ *
+ * @param config - Configuration containing the document accessor and firestore accessor driver
+ * @param config.documentAccessor - The document accessor factory function
+ * @param config.firestoreAccessorDriver - The firestore accessor driver used to create transaction and write batch contexts
+ * @returns An extension object with document accessor factory methods for default, transaction, and write batch contexts
+ */
 export declare function firestoreDocumentAccessorContextExtension<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>({ documentAccessor, firestoreAccessorDriver }: FirestoreDocumentAccessorContextExtensionConfig<T, D>): FirestoreDocumentAccessorContextExtension<T, D>;
 export declare function firestoreDocumentAccessorContextExtension<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>({ documentAccessor, firestoreAccessorDriver }: LimitedFirestoreDocumentAccessorContextExtensionConfig<T, D>): LimitedFirestoreDocumentAccessorContextExtension<T, D>;
 /**
@@ -330,6 +360,12 @@ export interface FirestoreSingleDocumentAccessorConfig<T, D extends FirestoreDoc
     readonly singleItemIdentifier: string;
     readonly accessors: FirestoreDocumentAccessorContextExtension<T, D>;
 }
+/**
+ * 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
+ */
 export declare function firestoreSingleDocumentAccessor<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: FirestoreSingleDocumentAccessorConfig<T, D>): FirestoreSingleDocumentAccessor<T, D>;
 /**
  * Default document ID used for single-document collections. The document is stored at path `<collection>/0`.
@@ -342,4 +378,10 @@ export interface SingleItemFirestoreCollectionDocumentIdentifierRef {
      */
     readonly singleItemIdentifier: SingleItemFirestoreCollectionDocumentIdentifier;
 }
+/**
+ * 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 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.utility.d.ts

@@ -79,9 +79,13 @@ export declare function getDocumentSnapshots<D extends FirestoreDocument<any>>(d
  * when you need both the document's methods (e.g. `update`, `create`) and its current data state.
  */
 export type FirestoreDocumentSnapshotPair<D extends FirestoreDocument<any>> = {
-    /** The document instance used to fetch the snapshot. */
+    /**
+     * The document instance used to fetch the snapshot.
+     */
     readonly document: D;
-    /** The fetched snapshot reflecting the document's current state in Firestore. */
+    /**
+     * The fetched snapshot reflecting the document's current state in Firestore.
+     */
     readonly snapshot: DocumentSnapshot<FirestoreDocumentData<D>>;
 };
 /**
@@ -106,11 +110,17 @@ export declare function getDocumentSnapshotPairs<D extends FirestoreDocument<any
  * in Firestore, `data` will be `undefined`.
  */
 export interface FirestoreDocumentSnapshotDataPair<D extends FirestoreDocument<any>> {
-    /** The document instance used to fetch the snapshot. */
+    /**
+     * The document instance used to fetch the snapshot.
+     */
     readonly document: D;
-    /** The fetched snapshot reflecting the document's current state in Firestore. */
+    /**
+     * The fetched snapshot reflecting the document's current state in Firestore.
+     */
     readonly snapshot: DocumentSnapshot<FirestoreDocumentData<D>>;
-    /** The snapshot's data with `id` and `key` fields injected, or `undefined` if the document does not exist. */
+    /**
+     * The snapshot's data with `id` and `key` fields injected, or `undefined` if the document does not exist.
+     */
     readonly data: Maybe<DocumentDataWithIdAndKey<FirestoreDocumentData<D>>>;
 }
 /**
@@ -119,7 +129,9 @@ export interface FirestoreDocumentSnapshotDataPair<D extends FirestoreDocument<a
  * Used by functions like {@link getDocumentSnapshotDataPairsWithData} that filter out non-existent documents.
  */
 export interface FirestoreDocumentSnapshotDataPairWithData<D extends FirestoreDocument<any>> extends Omit<FirestoreDocumentSnapshotDataPair<D>, 'data'> {
-    /** The snapshot's data with `id` and `key` fields injected (guaranteed to exist). */
+    /**
+     * The snapshot's data with `id` and `key` fields injected (guaranteed to exist).
+     */
     readonly data: DocumentDataWithIdAndKey<FirestoreDocumentData<D>>;
 }
 /**