@dereekb/firebase 11.1.8 → 12.0.1

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

@@ -2,9 +2,24 @@ import { type WebsiteLink, type GrantedRole, type WebsiteFileLink } from '@deree
 import { type DateCellRange, type DateCellSchedule } from '@dereekb/date';
 import { type ModelFieldMapFunctionsConfig, type GetterOrValue, type Maybe, type ModelFieldMapConvertFunction, type PrimativeKey, type ReadKeyFunction, type ModelFieldMapFunctionsWithDefaultsConfig, type FilterUniqueStringsTransformConfig, type MapFunction, type FilterKeyValueTuplesInput, type ModelKey, type ToModelMapFunctionsInput, type ModelMapFunctionsRef, type LatLngPrecision, type LatLngString, type TimezoneString, type PrimativeKeyStringDencoderFunction, type PrimativeKeyDencoderFunction, type UnitedStatesAddress, type ZoomLevel, type FilterUniqueFunction, type BitwiseEncodedSet, type BitwiseObjectDencoder, type SortCompareFunctionRef, type TransformNumberFunctionConfigInput, type TransformStringFunctionConfigInput, type DecisionFunction, type ISO8601DateString, type FilterFunction } from '@dereekb/util';
 import { type FirestoreModelData } from './snapshot.type';
+/**
+ * Base configuration for Firestore field mapping.
+ *
+ * @template V - Value type for the field in the model
+ * @template D - Data type for the field in Firestore (defaults to unknown)
+ */
 export interface BaseFirestoreFieldConfig<V, D = unknown> {
+    /**
+     * Function to convert from Firestore data (D) to model value (V)
+     */
     fromData: ModelFieldMapConvertFunction<D, V>;
+    /**
+     * Function to convert from model value (V) to Firestore data (D)
+     */
     toData: ModelFieldMapConvertFunction<V, D>;
+    /**
+     * Optional default value to use before saving if the value is null/undefined
+     */
     defaultBeforeSave?: GetterOrValue<D | null>;
 }
 /**
@@ -29,19 +44,67 @@ export interface FirestoreFieldDefaultData<D = unknown> {
      */
     defaultData: GetterOrValue<D>;
 }
+/**
+ * Configuration for Firestore field with a default value for the model.
+ *
+ * @template V - Value type for the field in the model
+ * @template D - Data type for the field in Firestore (defaults to unknown)
+ */
 export interface FirestoreFieldConfigWithDefault<V, D = unknown> extends BaseFirestoreFieldConfig<V, D>, FirestoreFieldDefault<V> {
 }
+/**
+ * Configuration for Firestore field with a default value for the Firestore data.
+ *
+ * @template V - Value type for the field in the model
+ * @template D - Data type for the field in Firestore (defaults to unknown)
+ */
 export interface FirestoreFieldConfigWithDefaultData<V, D = unknown> extends BaseFirestoreFieldConfig<V, D>, FirestoreFieldDefaultData<D> {
 }
+/**
+ * Configuration for Firestore field that can have either a default value for the model
+ * or a default value for the Firestore data.
+ *
+ * @template V - Value type for the field in the model
+ * @template D - Data type for the field in Firestore (defaults to unknown)
+ */
 export type FirestoreFieldConfig<V, D = unknown> = FirestoreFieldConfigWithDefault<V, D> | FirestoreFieldConfigWithDefaultData<V, D>;
 /**
  * All firebase ModelFieldMapFunctionsConfig are configured to handle the read field value as null/undefined. This implies that
  * by design, the firebase database documents do not need to be fully intact for the system to handle them properly.
  */
 export type FirestoreModelFieldMapFunctionsConfig<V, D> = ModelFieldMapFunctionsWithDefaultsConfig<V, Maybe<D>>;
+/**
+ * Creates a Firestore field mapping configuration.
+ *
+ * This function generates the necessary mapping functions for converting between
+ * model values and Firestore data. It handles defaults and conversions in both directions.
+ *
+ * @template V - Value type for the field in the model
+ * @template D - Data type for the field in Firestore (defaults to unknown)
+ * @param config - Configuration for the Firestore field
+ * @returns A configured mapping between model and Firestore data
+ */
 export declare function firestoreField<V, D = unknown>(config: FirestoreFieldConfig<V, D>): FirestoreModelFieldMapFunctionsConfig<V, D>;
 export declare const FIRESTORE_PASSTHROUGH_FIELD: FirestoreModelFieldMapFunctionsConfig<unknown, unknown>;
+/**
+ * Creates a pass-through field mapping configuration that doesn't transform the data.
+ *
+ * This is useful when the model field and Firestore field are the same type and
+ * no transformation is needed in either direction.
+ *
+ * @template T - Type for both the model field and Firestore field
+ * @returns A field mapping configuration that passes values through unchanged
+ */
 export declare function firestorePassThroughField<T>(): ModelFieldMapFunctionsConfig<T, T>;
+/**
+ * Configuration for optional Firestore fields with conditional storage.
+ *
+ * This interface provides options for determining when fields should not be stored
+ * in Firestore and default values for reading.
+ *
+ * @template V - Value type for the field in the model
+ * @template D - Data type for the field in Firestore
+ */
 export interface OptionalFirestoreFieldConfig<V, D> {
     /**
      * Removes the value from the object if the decision returns true.
@@ -60,6 +123,11 @@ export interface OptionalFirestoreFieldConfig<V, D> {
      */
     readonly defaultReadValue?: GetterOrValue<D>;
 }
+/**
+ * Configuration for optional Firestore fields with the same type for model and Firestore.
+ *
+ * @template T - Type for both the model field and Firestore field
+ */
 export interface OptionalOneTypeFirestoreFieldConfig<T> extends OptionalFirestoreFieldConfig<T, T> {
     /**
      * Defaults the dontStoreIfValue value to this value.
@@ -74,6 +142,12 @@ export interface OptionalOneTypeFirestoreFieldConfig<T> extends OptionalFirestor
      */
     readonly dontStoreIfValue?: T;
 }
+/**
+ * Configuration for optional Firestore fields with different types and transformations.
+ *
+ * @template V - Value type for the field in the model
+ * @template D - Data type for the field in Firestore
+ */
 export interface OptionalFirestoreFieldConfigWithTwoTypeTransform<V, D> extends OptionalFirestoreFieldConfig<V, D> {
     /**
      * (Optional) Function to transform the data after it is read from Firestore.
@@ -92,6 +166,11 @@ export interface OptionalFirestoreFieldConfigWithTwoTypeTransform<V, D> extends
      */
     readonly transformToData?: MapFunction<V, D | null>;
 }
+/**
+ * Configuration for optional Firestore fields with single type and transformation function.
+ *
+ * @template T - Type for both the model field and Firestore field
+ */
 export interface OptionalFirestoreFieldConfigWithOneTypeTransform<T> extends OptionalFirestoreFieldConfigWithTwoTypeTransform<T, T>, OptionalOneTypeFirestoreFieldConfig<T> {
     /**
      * (Optional) Function to transform the data before it is stored and after it is read.
@@ -100,47 +179,253 @@ export interface OptionalFirestoreFieldConfigWithOneTypeTransform<T> extends Opt
      */
     readonly transformData?: MapFunction<T, T>;
 }
+/**
+ * Creates a field mapping configuration for optional Firestore fields.
+ *
+ * Handles transformation and conditional storage of values with different types.
+ *
+ * @template V - Value type for the field in the model
+ * @template D - Data type for the field in Firestore
+ * @param config - Configuration for the optional Firestore field
+ * @returns A field mapping configuration for optional values
+ */
 export declare function optionalFirestoreField<V, D>(config?: OptionalFirestoreFieldConfigWithTwoTypeTransform<V, D>): ModelFieldMapFunctionsConfig<Maybe<V>, Maybe<D>>;
+/**
+ * Creates a field mapping configuration for optional Firestore fields with same type.
+ *
+ * Handles transformation and conditional storage of values of the same type.
+ *
+ * @template T - Type for both the model field and Firestore field
+ * @param config - Configuration for the optional Firestore field
+ * @returns A field mapping configuration for optional values
+ */
 export declare function optionalFirestoreField<T>(config?: OptionalFirestoreFieldConfigWithOneTypeTransform<T>): ModelFieldMapFunctionsConfig<Maybe<T>, Maybe<T>>;
+/**
+ * Configuration for a Firestore field with default model value but without conversion functions.
+ *
+ * @template V - Value type for the field in the model
+ * @template D - Data type for the field in Firestore (defaults to unknown)
+ */
 export type MapConfiguredFirestoreFieldConfigWithDefault<V, D = unknown> = Omit<FirestoreFieldConfigWithDefault<V, D>, 'fromData' | 'toData'>;
+/**
+ * Configuration for a Firestore field with default data value but without conversion functions.
+ *
+ * @template V - Value type for the field in the model
+ * @template D - Data type for the field in Firestore (defaults to unknown)
+ */
 export type MapConfiguredFirestoreFieldConfigWithDefaultData<V, D = unknown> = Omit<FirestoreFieldConfigWithDefaultData<V, D>, 'fromData' | 'toData'>;
+/**
+ * Configuration for a Firestore field with default values but without conversion functions.
+ *
+ * @template V - Value type for the field in the model
+ * @template D - Data type for the field in Firestore (defaults to unknown)
+ */
 export type MapConfiguredFirestoreFieldConfig<V, D = unknown> = MapConfiguredFirestoreFieldConfigWithDefault<V, D> | MapConfiguredFirestoreFieldConfigWithDefaultData<V, D>;
+/**
+ * Configuration for a Firestore field with optional default model value but without conversion functions.
+ *
+ * @template V - Value type for the field in the model
+ * @template D - Data type for the field in Firestore (defaults to unknown)
+ */
 export type DefaultMapConfiguredFirestoreFieldConfig<V, D = unknown> = Omit<FirestoreFieldConfigWithDefault<V, D>, 'fromData' | 'toData' | 'default'> & Partial<Pick<FirestoreFieldConfigWithDefault<V, D>, 'default'>>;
+/**
+ * Configuration for an optional Firestore field without conversion functions or defaults.
+ *
+ * @template V - Value type for the field in the model
+ * @template D - Data type for the field in Firestore (defaults to unknown)
+ */
 export type OptionalMapConfiguredFirestoreFieldConfig<V, D = unknown> = Omit<BaseFirestoreFieldConfig<V, D>, 'fromData' | 'toData' | 'defaultBeforeSave'>;
+/**
+ * Configuration for a Firestore string field with optional transformation.
+ *
+ * @template S - String type for the field (defaults to string)
+ */
 export interface FirestoreStringConfig<S extends string = string> extends DefaultMapConfiguredFirestoreFieldConfig<S, S> {
+    /**
+     * Optional transformation to apply to the string value
+     */
     readonly transform?: TransformStringFunctionConfigInput<S>;
 }
 export declare const DEFAULT_FIRESTORE_STRING_FIELD_VALUE = "";
+/**
+ * Creates a field mapping configuration for Firestore string fields.
+ *
+ * @template S - String type for the field (defaults to string)
+ * @param config - Configuration for the string field
+ * @returns A field mapping configuration for string values
+ */
 export declare function firestoreString<S extends string = string>(config?: FirestoreStringConfig<S>): FirestoreModelFieldMapFunctionsConfig<S, S>;
+/**
+ * Configuration for an optional Firestore string field with transformation.
+ *
+ * @template S - String type for the field (defaults to string)
+ */
 export type OptionalFirestoreString<S extends string = string> = OptionalOneTypeFirestoreFieldConfig<S> & Pick<FirestoreStringConfig<S>, 'transform'>;
+/**
+ * Creates a field mapping configuration for optional Firestore string fields.
+ *
+ * @template S - String type for the field (defaults to string)
+ * @param config - Configuration for the optional string field
+ * @returns A field mapping configuration for optional string values
+ */
 export declare function optionalFirestoreString<S extends string = string>(config?: OptionalFirestoreString<S>): ModelFieldMapFunctionsConfig<Maybe<S>, Maybe<S>>;
+/**
+ * Configuration for a Firestore enum field.
+ *
+ * @template S - Enum type (string or number)
+ */
 export type FirestoreEnumConfig<S extends string | number> = MapConfiguredFirestoreFieldConfigWithDefault<S, S>;
+/**
+ * Creates a field mapping configuration for Firestore enum fields.
+ *
+ * @template S - Enum type (string or number)
+ * @param config - Configuration for the enum field
+ * @returns A field mapping configuration for enum values
+ */
 export declare function firestoreEnum<S extends string | number>(config: FirestoreEnumConfig<S>): FirestoreModelFieldMapFunctionsConfig<S, S>;
+/**
+ * Configuration for an optional Firestore enum field.
+ *
+ * @template S - Enum type (string or number)
+ */
 export type OptionalFirestoreEnumConfig<S extends string | number> = OptionalOneTypeFirestoreFieldConfig<S>;
+/**
+ * Creates a field mapping configuration for optional Firestore enum fields.
+ *
+ * @template S - Enum type (string or number)
+ * @param config - Configuration for the optional enum field
+ * @returns A field mapping configuration for optional enum values
+ */
 export declare function optionalFirestoreEnum<S extends string | number>(config?: OptionalFirestoreEnumConfig<S>): ModelFieldMapFunctionsConfig<Maybe<S>, Maybe<S>>;
+/**
+ * Creates a field mapping configuration for Firestore UID fields.
+ *
+ * @returns A field mapping configuration for Firebase Auth user IDs
+ */
 export declare function firestoreUID(): FirestoreModelFieldMapFunctionsConfig<string, string>;
+/**
+ * Creates a field mapping configuration for optional Firestore UID fields.
+ *
+ * @returns A field mapping configuration for optional Firebase Auth user IDs
+ */
 export declare function optionalFirestoreUID(): ModelFieldMapFunctionsConfig<Maybe<string>, Maybe<string>>;
 export declare const firestoreModelKeyString: FirestoreModelFieldMapFunctionsConfig<string, string>;
 export declare const firestoreModelIdString: FirestoreModelFieldMapFunctionsConfig<string, string>;
+/**
+ * Configuration for a Firestore date field.
+ *
+ * @template Date - JavaScript Date object type
+ * @template string - ISO8601 date string format in Firestore
+ */
 export type FirestoreDateFieldConfig = DefaultMapConfiguredFirestoreFieldConfig<Date, string> & {
+    /**
+     * Whether to save the default date as the current timestamp
+     */
     readonly saveDefaultAsNow?: boolean;
 };
+/**
+ * Creates a field mapping configuration for Firestore date fields.
+ *
+ * Handles conversion between JavaScript Date objects and ISO8601 strings stored in Firestore.
+ *
+ * @param config - Configuration for the date field
+ * @returns A field mapping configuration for Date values
+ */
 export declare function firestoreDate(config?: FirestoreDateFieldConfig): FirestoreModelFieldMapFunctionsConfig<Date, string>;
+/**
+ * Configuration for an optional Firestore date field.
+ *
+ * @template Date - JavaScript Date object type
+ * @template ISO8601DateString - ISO8601 date string format in Firestore
+ */
 export type OptionalFirestoreDateFieldConfig = OptionalFirestoreFieldConfig<Date, ISO8601DateString>;
+/**
+ * Creates a field mapping configuration for optional Firestore date fields.
+ *
+ * Handles conversion between JavaScript Date objects and ISO8601 strings stored in Firestore.
+ *
+ * @param config - Configuration for the optional date field
+ * @returns A field mapping configuration for optional Date values
+ */
 export declare function optionalFirestoreDate(config?: OptionalFirestoreDateFieldConfig): ModelFieldMapFunctionsConfig<Maybe<Date>, Maybe<string>>;
+/**
+ * Configuration for a Firestore boolean field.
+ */
 export type FirestoreBooleanFieldConfig = MapConfiguredFirestoreFieldConfigWithDefault<boolean, boolean>;
+/**
+ * Creates a field mapping configuration for Firestore boolean fields.
+ *
+ * @param config - Configuration for the boolean field
+ * @returns A field mapping configuration for boolean values
+ */
 export declare function firestoreBoolean(config: FirestoreBooleanFieldConfig): FirestoreModelFieldMapFunctionsConfig<boolean, boolean>;
+/**
+ * Configuration for an optional Firestore boolean field.
+ */
 export type OptionalFirestoreBooleanFieldConfig = OptionalOneTypeFirestoreFieldConfig<boolean>;
+/**
+ * Creates a field mapping configuration for optional Firestore boolean fields.
+ *
+ * @param config - Configuration for the optional boolean field
+ * @returns A field mapping configuration for optional boolean values
+ */
 export declare function optionalFirestoreBoolean(config?: OptionalFirestoreBooleanFieldConfig): ModelFieldMapFunctionsConfig<Maybe<boolean>, Maybe<boolean>>;
+/**
+ * Configuration for a Firestore number field with optional transformation.
+ *
+ * @template N - Number type for the field (defaults to number)
+ */
 export interface FirestoreNumberConfig<N extends number = number> extends MapConfiguredFirestoreFieldConfigWithDefault<N, N> {
+    /**
+     * Whether to save the default value if no value is provided
+     */
     readonly saveDefault?: Maybe<boolean>;
+    /**
+     * Optional transformation to apply to the number value
+     */
     readonly transform?: TransformNumberFunctionConfigInput<N>;
 }
+/**
+ * Creates a field mapping configuration for Firestore number fields.
+ *
+ * @template N - Number type for the field (defaults to number)
+ * @param config - Configuration for the number field
+ * @returns A field mapping configuration for number values
+ */
 export declare function firestoreNumber<N extends number = number>(config: FirestoreNumberConfig<N>): FirestoreModelFieldMapFunctionsConfig<N, N>;
+/**
+ * Configuration for an optional Firestore number field with transformation.
+ *
+ * @template N - Number type for the field (defaults to number)
+ */
 export type OptionalFirestoreNumberFieldConfig<N extends number = number> = OptionalOneTypeFirestoreFieldConfig<N> & Pick<FirestoreNumberConfig<N>, 'transform'>;
+/**
+ * Creates a field mapping configuration for optional Firestore number fields.
+ *
+ * @template N - Number type for the field (defaults to number)
+ * @param config - Configuration for the optional number field
+ * @returns A field mapping configuration for optional number values
+ */
 export declare function optionalFirestoreNumber<N extends number = number>(config?: OptionalFirestoreNumberFieldConfig<N>): ModelFieldMapFunctionsConfig<Maybe<N>, Maybe<N>>;
+/**
+ * Configuration for a Firestore array field with optional sorting.
+ *
+ * @template T - Type of elements in the array
+ */
 export type FirestoreArrayFieldConfig<T> = DefaultMapConfiguredFirestoreFieldConfig<T[], T[]> & Partial<SortCompareFunctionRef<T>> & Partial<FirestoreFieldDefault<T[]>>;
+/**
+ * Creates a field mapping configuration for Firestore array fields.
+ *
+ * @template T - Type of elements in the array
+ * @param config - Configuration for the array field
+ * @returns A field mapping configuration for array values
+ */
 export declare function firestoreArray<T>(config: FirestoreArrayFieldConfig<T>): FirestoreModelFieldMapFunctionsConfig<T[], T[]>;
+/**
+ * Configuration for an optional Firestore array field with filtering and sorting options.
+ *
+ * @template T - Type of elements in the array
+ */
 export type OptionalFirestoreArrayFieldConfig<T> = Omit<OptionalFirestoreFieldConfigWithOneTypeTransform<T[]>, 'dontStoreIf' | 'dontStoreIfValue' | 'transformFromData' | 'transformToData'> & Pick<FirestoreArrayFieldConfig<T>, 'sortWith'> & {
     /**
      * Filters the function uniquely. If true uses the unique function.
@@ -157,15 +442,63 @@ export type OptionalFirestoreArrayFieldConfig<T> = Omit<OptionalFirestoreFieldCo
      */
     readonly dontStoreIfEmpty?: boolean;
 };
+/**
+ * Creates a field mapping configuration for optional Firestore array fields.
+ *
+ * Supports unique filtering and conditional storage based on array content.
+ *
+ * @template T - Type of elements in the array
+ * @param config - Configuration for the optional array field
+ * @returns A field mapping configuration for optional array values
+ */
 export declare function optionalFirestoreArray<T>(config?: OptionalFirestoreArrayFieldConfig<T>): ModelFieldMapFunctionsConfig<Maybe<T[]>, Maybe<T[]>>;
+/**
+ * Configuration for a Firestore array field with unique filtering.
+ *
+ * @template T - Type of elements in the array
+ * @template K - Key type for filtering uniqueness (defaults to T if it's a primative key)
+ */
 export type FirestoreUniqueArrayFieldConfig<T, K extends PrimativeKey = T extends PrimativeKey ? T : PrimativeKey> = FirestoreArrayFieldConfig<T> & Partial<SortCompareFunctionRef<T>> & {
+    /**
+     * Function to filter array elements for uniqueness
+     */
     readonly filterUnique: FilterUniqueFunction<T, K> | true;
 };
+/**
+ * Creates a field mapping configuration for Firestore array fields with unique filtering.
+ *
+ * @template T - Type of elements in the array
+ * @template K - Key type for filtering uniqueness
+ * @param config - Configuration for the unique array field
+ * @returns A field mapping configuration for unique array values
+ */
 export declare function firestoreUniqueArray<T, K extends PrimativeKey = T extends PrimativeKey ? T : PrimativeKey>(config: FirestoreUniqueArrayFieldConfig<T, K>): FirestoreModelFieldMapFunctionsConfig<T[], T[]>;
+/**
+ * Configuration for a Firestore array field with unique filtering based on a key function.
+ *
+ * @template T - Type of elements in the array
+ * @template K - Type of the key used for uniqueness (defaults to PrimativeKey)
+ */
 export type FirestoreUniqueKeyedArrayFieldConfig<T, K extends PrimativeKey = PrimativeKey> = FirestoreArrayFieldConfig<T> & {
+    /**
+     * Function to extract the key from an array element for uniqueness checking
+     */
     readonly readKey: ReadKeyFunction<T, K>;
 };
+/**
+ * Creates a field mapping configuration for Firestore array fields with unique filtering based on a key function.
+ *
+ * @template T - Type of elements in the array
+ * @template K - Type of the key used for uniqueness
+ * @param config - Configuration for the keyed unique array field
+ * @returns A field mapping configuration for keyed unique array values
+ */
 export declare function firestoreUniqueKeyedArray<T, K extends PrimativeKey = PrimativeKey>(config: FirestoreUniqueKeyedArrayFieldConfig<T, K>): FirestoreModelFieldMapFunctionsConfig<T[], T[]>;
+/**
+ * Configuration for a Firestore array field of enum values.
+ *
+ * @template S - Enum type (string or number)
+ */
 export type FirestoreEnumArrayFieldConfig<S extends string | number> = Omit<FirestoreUniqueArrayFieldConfig<S>, 'filterUnique'>;
 /**
  * FirestoreField configuration for an array of unique enum values.
@@ -173,16 +506,62 @@ export type FirestoreEnumArrayFieldConfig<S extends string | number> = Omit<Fire
  * @param config
  * @returns
  */
+/**
+ * Creates a field mapping configuration for Firestore array fields of enum values.
+ *
+ * @template S - Enum type (string or number)
+ * @param config - Configuration for the enum array field
+ * @returns A field mapping configuration for enum array values
+ */
 export declare function firestoreEnumArray<S extends string | number>(config?: FirestoreEnumArrayFieldConfig<S>): FirestoreModelFieldMapFunctionsConfig<S[], S[]>;
+/**
+ * Configuration for a Firestore array field of unique string values.
+ *
+ * @template S - String type (defaults to string)
+ */
 export type FirestoreUniqueStringArrayFieldConfig<S extends string = string> = Omit<FirestoreUniqueArrayFieldConfig<S>, 'filterUnique'> & FilterUniqueStringsTransformConfig;
+/**
+ * Creates a field mapping configuration for Firestore array fields of unique string values.
+ *
+ * @template S - String type (defaults to string)
+ * @param config - Configuration for the unique string array field
+ * @returns A field mapping configuration for unique string array values
+ */
 export declare function firestoreUniqueStringArray<S extends string = string>(config?: FirestoreUniqueStringArrayFieldConfig<S>): FirestoreModelFieldMapFunctionsConfig<S[], S[]>;
 export declare const firestoreModelKeyArrayField: FirestoreModelFieldMapFunctionsConfig<string[], string[]>;
 export declare const firestoreModelIdArrayField: FirestoreModelFieldMapFunctionsConfig<string[], string[]>;
+/**
+ * Configuration for a Firestore array field of unique number values.
+ *
+ * @template S - Number type (defaults to number)
+ */
 export type FirestoreUniqueNumberArrayFieldConfig<S extends number = number> = Omit<FirestoreUniqueArrayFieldConfig<S>, 'filterUnique'>;
+/**
+ * Creates a field mapping configuration for Firestore array fields of unique number values.
+ *
+ * @template S - Number type (defaults to number)
+ * @param config - Configuration for the unique number array field
+ * @returns A field mapping configuration for unique number array values
+ */
 export declare function firestoreUniqueNumberArray<S extends number = number>(config?: FirestoreUniqueNumberArrayFieldConfig<S>): FirestoreModelFieldMapFunctionsConfig<S[], S[]>;
+/**
+ * Configuration for a Firestore array field with custom encoding/decoding of values.
+ *
+ * @template T - Type of elements in the model array
+ * @template E - Type of encoded elements in Firestore (string or number)
+ */
 export type FirestoreEncodedArrayFieldConfig<T, E extends string | number> = DefaultMapConfiguredFirestoreFieldConfig<T[], E[]> & Partial<SortCompareFunctionRef<T>> & {
+    /**
+     * Conversion functions for encoding/decoding array elements
+     */
     readonly convert: {
+        /**
+         * Function to convert from Firestore data to model value
+         */
         fromData: MapFunction<E, T>;
+        /**
+         * Function to convert from model value to Firestore data
+         */
         toData: MapFunction<T, E>;
     };
 };
@@ -192,8 +571,27 @@ export type FirestoreEncodedArrayFieldConfig<T, E extends string | number> = Def
  * @param config
  * @returns
  */
+/**
+ * Creates a field mapping configuration for Firestore array fields with custom encoding.
+ *
+ * A Firestore array that encodes values to either string or number values using another FirestoreModelField config for encoding/decoding.
+ *
+ * @template T - Type of elements in the model array
+ * @template E - Type of encoded elements in Firestore (string or number)
+ * @param config - Configuration for the encoded array field
+ * @returns A field mapping configuration for encoded array values
+ */
 export declare function firestoreEncodedArray<T, E extends string | number>(config: FirestoreEncodedArrayFieldConfig<T, E>): FirestoreModelFieldMapFunctionsConfig<T[], E[]>;
+/**
+ * Configuration for a Firestore array field with primative key encoding/decoding.
+ *
+ * @template D - Type of decoded elements in the model array
+ * @template E - Type of encoded elements in Firestore
+ */
 export type FirestoreDencoderArrayFieldConfig<D extends PrimativeKey, E extends PrimativeKey> = DefaultMapConfiguredFirestoreFieldConfig<D[], E[]> & {
+    /**
+     * Function that handles both encoding and decoding of array elements
+     */
     readonly dencoder: PrimativeKeyDencoderFunction<D, E>;
 };
 /**
@@ -202,15 +600,40 @@ export type FirestoreDencoderArrayFieldConfig<D extends PrimativeKey, E extends
  * @param config
  * @returns
  */
+/**
+ * Creates a field mapping configuration for Firestore array fields with primative key encoding/decoding.
+ *
+ * An array that is stored as an array of encoded values using a PrimativeKeyDencoderFunction.
+ *
+ * @template D - Type of decoded elements in the model array
+ * @template E - Type of encoded elements in Firestore
+ * @param config - Configuration for the decoder array field
+ * @returns A field mapping configuration for encoded primative key array values
+ */
 export declare function firestoreDencoderArray<D extends PrimativeKey, E extends PrimativeKey>(config: FirestoreDencoderArrayFieldConfig<D, E>): FirestoreModelFieldMapFunctionsConfig<D[], E[]>;
+/**
+ * Configuration for a Firestore array field that encodes primative keys to a string representation.
+ *
+ * @template D - Type of decoded elements in the model array
+ * @template E - Type of encoded elements (intermediate representation)
+ * @template S - String type for storage in Firestore
+ */
 export type FirestoreDencoderStringArrayFieldConfig<D extends PrimativeKey, E extends PrimativeKey, S extends string = string> = DefaultMapConfiguredFirestoreFieldConfig<D[], S> & {
-    readonly dencoder: PrimativeKeyStringDencoderFunction<D, E>;
+    /**
+     * Function that handles both encoding and decoding of array elements to/from string
+     */
+    readonly dencoder: PrimativeKeyStringDencoderFunction<D, E, S>;
 };
 /**
+ * Creates a field mapping configuration for Firestore array fields that encode primative keys to a string representation.
+ *
  * An array that is stored as an encoded string using a PrimativeKeyDencoderString configuration.
  *
- * @param config
- * @returns
+ * @template D - Type of decoded elements in the model array
+ * @template E - Type of encoded elements (intermediate representation)
+ * @template S - String type for storage in Firestore
+ * @param config - Configuration for the string decoder array field
+ * @returns A field mapping configuration for string-encoded primative key array values
  */
 export declare function firestoreDencoderStringArray<D extends PrimativeKey, E extends PrimativeKey, S extends string = string>(config: FirestoreDencoderStringArrayFieldConfig<D, E, S>): FirestoreModelFieldMapFunctionsConfig<D[], S>;
 /**
@@ -398,11 +821,21 @@ export declare function firestoreTimezoneString(config?: FirestoreTimezoneString
 export declare const DEFAULT_WEBSITE_LINK: WebsiteLink;
 export declare const assignWebsiteLinkFunction: import("@dereekb/util").AssignValuesToPOJOFunction<WebsiteLink>;
 export declare const firestoreWebsiteLinkAssignFn: MapFunction<WebsiteLink, WebsiteLink>;
+/**
+ * Creates a field mapping configuration for Firestore website link fields.
+ *
+ * @returns A field mapping configuration for website link values
+ */
 export declare function firestoreWebsiteLink(): FirestoreModelFieldMapFunctionsConfig<WebsiteLink, WebsiteLink>;
 export declare function firestoreWebsiteLinkArray(): FirestoreModelFieldMapFunctionsConfig<WebsiteLink[], WebsiteLink[]>;
 export declare const DEFAULT_FIRESTORE_WEBSITE_FILE_LINK_VALUE: WebsiteFileLink;
 export declare const assignWebsiteFileLinkFunction: import("@dereekb/util").AssignValuesToPOJOFunction<WebsiteFileLink>;
 export declare const firestoreWebsiteFileLinkAssignFn: MapFunction<WebsiteFileLink, WebsiteFileLink>;
+/**
+ * Creates a field mapping configuration for Firestore website file link fields.
+ *
+ * @returns A field mapping configuration for website file link values
+ */
 export declare function firestoreWebsiteFileLink(): FirestoreModelFieldMapFunctionsConfig<WebsiteFileLink, WebsiteFileLink>;
 /**
  * Stores the array of WebsiteFileLink values as an array of objects.
@@ -415,32 +848,109 @@ export declare function firestoreWebsiteFileLinkEncodedArray(): FirestoreModelFi
 export declare const DEFAULT_DATE_CELL_RANGE_VALUE: DateCellRange;
 export declare const assignDateCellRangeFunction: import("@dereekb/util").AssignValuesToPOJOFunction<DateCellRange>;
 export declare const firestoreDateCellRangeAssignFn: MapFunction<DateCellRange, DateCellRange>;
+/**
+ * Creates a field mapping configuration for Firestore date cell range fields.
+ *
+ * @returns A field mapping configuration for date cell range values
+ */
 export declare function firestoreDateCellRange(): FirestoreModelFieldMapFunctionsConfig<DateCellRange, DateCellRange>;
 export declare function firestoreDateCellRangeArray(sort?: boolean): FirestoreModelFieldMapFunctionsConfig<DateCellRange[], DateCellRange[]>;
 export declare const DEFAULT_FIRESTORE_DATE_CELL_SCHEDULE_VALUE: DateCellSchedule;
 export declare const assignDateCellScheduleFunction: import("@dereekb/util").AssignValuesToPOJOFunction<DateCellSchedule>;
 export declare const firestoreDateCellScheduleAssignFn: MapFunction<DateCellSchedule, DateCellSchedule>;
+/**
+ * Creates a field mapping configuration for Firestore date cell schedule fields.
+ *
+ * @returns A field mapping configuration for date cell schedule values
+ */
 export declare function firestoreDateCellSchedule(): FirestoreModelFieldMapFunctionsConfig<DateCellSchedule, DateCellSchedule>;
 export declare const DEFAULT_FIRESTORE_UNITED_STATES_ADDRESS_VALUE: UnitedStatesAddress;
+/**
+ * Function to assign values to a UnitedStatesAddress object while filtering specific keys and empty values.
+ */
 export declare const assignUnitedStatesAddressFunction: import("@dereekb/util").AssignValuesToPOJOFunction<UnitedStatesAddress>;
+/**
+ * Function to assign values from an input UnitedStatesAddress to a default UnitedStatesAddress.
+ */
 export declare const firestoreUnitedStatesAddressAssignFn: MapFunction<UnitedStatesAddress, UnitedStatesAddress>;
+/**
+ * Creates a field mapping configuration for Firestore United States address fields.
+ *
+ * @returns A field mapping configuration for United States address values
+ */
 export declare function firestoreUnitedStatesAddress(): FirestoreModelFieldMapFunctionsConfig<UnitedStatesAddress, UnitedStatesAddress>;
+/**
+ * Creates a field mapping configuration for optional Firestore United States address fields.
+ *
+ * @returns A field mapping configuration for optional United States address values
+ */
 export declare function optionalFirestoreUnitedStatesAddress(): FirestoreModelFieldMapFunctionsConfig<Maybe<UnitedStatesAddress>, Maybe<UnitedStatesAddress>>;
 export declare const MIN_FIRESTORE_MAP_ZOOM_LEVEL_VALUE: ZoomLevel;
 export declare const MAX_FIRESTORE_MAP_ZOOM_LEVEL_VALUE: ZoomLevel;
 /**
+ * Field mapping configuration for Firestore map zoom level fields.
+ *
  * Convenience function for firestoreNumber() for storing an integer ZoomLevel value.
  */
 export declare const firestoreMapZoomLevel: FirestoreModelFieldMapFunctionsConfig<number, number>;
+/**
+ * Configuration for a Firestore field that stores a set of numbers as a bitwise-encoded value.
+ *
+ * @template D - Type of number elements in the set (defaults to number)
+ */
 export interface FirestoreBitwiseSetConfig<D extends number = number> extends DefaultMapConfiguredFirestoreFieldConfig<Set<D>, BitwiseEncodedSet> {
+    /**
+     * Maximum index value to support in the bitwise encoding
+     */
     readonly maxIndex?: number;
 }
+/**
+ * Creates a field mapping configuration for Firestore fields that store sets of numbers as bitwise-encoded values.
+ *
+ * @template D - Type of number elements in the set (defaults to number)
+ * @param config - Configuration for the bitwise set field
+ * @returns A field mapping configuration for bitwise-encoded set values
+ */
 export declare function firestoreBitwiseSet<D extends number = number>(config: FirestoreBitwiseSetConfig<D>): FirestoreModelFieldMapFunctionsConfig<Set<D>, number>;
+/**
+ * Configuration for a Firestore field that maps objects with bitwise-encoded set values.
+ *
+ * @template D - Type of number elements in the sets (defaults to number)
+ * @template K - Type of keys in the object (string)
+ */
 export interface FirestoreBitwiseSetMapConfig<D extends number = number, K extends string = string> extends Omit<FirestoreEncodedObjectMapFieldConfig<Set<D>, BitwiseEncodedSet, K>, 'encoder' | 'decoder'> {
+    /**
+     * Maximum index value to support in the bitwise encoding
+     */
     readonly maxIndex?: number;
 }
+/**
+ * Creates a field mapping configuration for Firestore fields that map objects with bitwise-encoded set values.
+ *
+ * @template D - Type of number elements in the sets (defaults to number)
+ * @template K - Type of keys in the object (string)
+ * @param config - Configuration for the bitwise set map field
+ * @returns A field mapping configuration for object maps with bitwise-encoded set values
+ */
 export declare function firestoreBitwiseSetMap<D extends number = number, K extends string = string>(config: FirestoreBitwiseSetMapConfig<D, K>): FirestoreModelFieldMapFunctionsConfig<FirestoreEncodedObjectMapFieldValueType<Set<D>, K>, FirestoreMapFieldType<number, K>>;
+/**
+ * Configuration for a Firestore field that maps objects with bitwise-encoded object values.
+ *
+ * @template T - Type of object values in the map
+ * @template K - Type of keys in the object (string)
+ */
 export interface FirestoreBitwiseObjectMapConfig<T extends object, K extends string = string> extends Omit<FirestoreEncodedObjectMapFieldConfig<T, BitwiseEncodedSet, K>, 'encoder' | 'decoder'> {
+    /**
+     * Function that handles both encoding and decoding of object values to/from bitwise values
+     */
     readonly dencoder: BitwiseObjectDencoder<T>;
 }
+/**
+ * Creates a field mapping configuration for Firestore fields that map objects with bitwise-encoded object values.
+ *
+ * @template T - Type of object values in the map
+ * @template K - Type of keys in the object (string)
+ * @param config - Configuration for the bitwise object map field
+ * @returns A field mapping configuration for object maps with bitwise-encoded object values
+ */
 export declare function firestoreBitwiseObjectMap<T extends object, K extends string = string>(config: FirestoreBitwiseObjectMapConfig<T, K>): FirestoreModelFieldMapFunctionsConfig<FirestoreEncodedObjectMapFieldValueType<T, K>, FirestoreMapFieldType<number, K>>;