@dereekb/firebase 13.4.0 → 13.4.2

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

@@ -24,7 +24,6 @@ export type FirestoreModelType = ModelTypeString;
  * Each collection name in the app should be unique, as usage of CollectionGroups would cause collections
  * with the same name to be returned regardless of their location in the document hierarchy.
  *
- *
  * @example 'u', 'ps', 'or'
  */
 export type FirestoreCollectionName = string;
@@ -162,6 +161,7 @@ export declare function firestoreModelIdentity<P extends FirestoreModelIdentity<
 export type FirestoreModelIdentityTypeMap = Map<FirestoreModelType | FirestoreCollectionName | FirestoreCollectionType, FirestoreModelType>;
 /**
  * Creates a FirestoreModelIdentityTypeMap from the input identities.
+ *
  * @param identities
  * @returns
  */
@@ -222,7 +222,7 @@ export type FirestoreModelId = string;
 /**
  * Input for firestoreModelId()
  */
-export type FirestoreModelIdInput = FirestoreModelId | FirestoreModelKey | DocumentReferenceRef<any> | FirestoreModelKeyRef | FirestoreModelIdRef;
+export type FirestoreModelIdInput = FirestoreModelId | FirestoreModelKey | DocumentReferenceRef<object> | FirestoreModelKeyRef | FirestoreModelIdRef;
 /**
  * Reads a firestoreModelId from the input.
  *
@@ -287,7 +287,8 @@ export declare const FIRESTORE_MODEL_ID_REGEX: RegExp;
 /**
  * Returns true if the input string is a FirestoreModelId.
  *
- * @param input
+ * @param input - The string to test
+ * @returns True if the input is a valid FirestoreModelId
  */
 export declare function isFirestoreModelId(input: string | FirestoreModelId): input is FirestoreModelId;
 /**
@@ -329,13 +330,15 @@ export declare const FIRESTORE_MODEL_KEY_REGEX_STRICT: RegExp;
 /**
  * Returns true if the input string is a FirestoreModelKey.
  *
- * @param input
+ * @param input - The string to test
+ * @returns True if the input is a valid FirestoreModelKey
  */
 export declare function isFirestoreModelKey(input: string | FirestoreModelKey): input is FirestoreModelKey;
 /**
- * Returns true if the input string is a FirestoreModelId.
+ * Returns true if the input string is a FirestoreModelId or a FirestoreModelKey.
  *
- * @param input
+ * @param input - The string to test
+ * @returns True if the input is a valid FirestoreModelId or FirestoreModelKey
  */
 export declare function isFirestoreModelIdOrKey(input: string | FirestoreModelId | FirestoreModelKey): input is FirestoreModelId | FirestoreModelKey;
 /**
@@ -369,6 +372,9 @@ export declare const firestoreModelKey: <I extends RootFirestoreModelIdentity, K
 export type FirestoreModelKeyFactory<I extends RootFirestoreModelIdentity, K extends FirestoreModelId = FirestoreModelId> = (id: K) => FirestoreCollectionModelKey<I, K>;
 /**
  * Creates a FirestoreModelKeyFactory for the input root identity.
+ *
+ * @param identity - The root FirestoreModelIdentity to bind the factory to
+ * @returns A factory function that creates FirestoreModelKey values for the given identity and a provided id
  */
 export declare function firestoreModelKeyFactory<I extends RootFirestoreModelIdentity, K extends FirestoreModelId = FirestoreModelId>(identity: I): (id: K) => FirestoreCollectionModelKeyPart<I, K>;
 /**
@@ -413,6 +419,12 @@ export declare function firestoreModelKeyPath(...parts: FirestoreModelKeyPart[])
  */
 export declare function childFirestoreModelKeyPath(parent: FirestoreModelKeyPart, children: ArrayOrValue<FirestoreModelKeyPart>): FirestoreModelKey[];
 export type FirestoreModelCollectionAndIdPairObject = Record<FirestoreCollectionName, FirestoreModelId>;
+/**
+ * Converts a FirestoreModelKey or reference into a record mapping each collection name to its document id.
+ *
+ * @param input - The FirestoreModelKey, DocumentReferenceRef, or FirestoreModelKeyRef to convert
+ * @returns An object mapping collection names to document ids, or undefined if the key is unavailable
+ */
 export declare function firestoreModelKeyPairObject(input: FirestoreModelKey | DocumentReferenceRef<unknown> | FirestoreModelKeyRef): Maybe<FirestoreModelCollectionAndIdPairObject>;
 /**
  * String that is composed of the FirestoreCollectionNames derived from an input FirestoreModelKey and joined together via a separator.
@@ -420,28 +432,68 @@ export declare function firestoreModelKeyPairObject(input: FirestoreModelKey | D
  * Is equivalent to a FirestoreCollectionType if the FIRESTORE_COLLECTION_NAME_SEPARATOR is used as the separator.
  */
 export type FirestoreModelCollectionTypeArrayName = string;
+/**
+ * Returns the FirestoreCollectionType derived from the input FirestoreModelKey.
+ *
+ * @param input - The key or reference to extract the collection type from
+ * @returns The FirestoreCollectionType string, or undefined if the key is unavailable
+ */
 export declare function firestoreModelKeyCollectionType<T = unknown>(input: ReadFirestoreModelKeyInput<T>): Maybe<FirestoreCollectionType>;
+/**
+ * Returns the collection type array name string derived from the input key, joined by the given separator.
+ *
+ * @param input - The key or reference to extract collection names from
+ * @param separator - The separator to join collection names with; defaults to the Firestore collection name separator
+ * @returns The joined collection type array name string, or undefined if the key is unavailable
+ */
 export declare function firestoreModelKeyCollectionTypeArrayName<T = unknown>(input: ReadFirestoreModelKeyInput<T>, separator?: string): Maybe<FirestoreModelCollectionTypeArrayName>;
+/**
+ * Returns the collection type array name string derived from a FirestoreModelIdentity, joined by the given separator.
+ *
+ * @param input - The FirestoreModelIdentity to derive collection names from
+ * @param separator - The separator to join collection names with; defaults to the Firestore collection name separator
+ * @returns The joined collection type array name string
+ */
 export declare function firestoreIdentityTypeArrayName(input: FirestoreModelIdentity, separator?: string): FirestoreModelCollectionTypeArrayName;
 export type FirestoreModelCollectionTypeArray = FirestoreCollectionName[];
+/**
+ * Returns an ordered array of collection names derived from a FirestoreModelIdentity, from root to leaf.
+ *
+ * @param input - The FirestoreModelIdentity to traverse
+ * @returns An array of FirestoreCollectionName values ordered from root to leaf
+ */
 export declare function firestoreIdentityTypeArray(input: FirestoreModelIdentity): FirestoreModelCollectionTypeArray;
+/**
+ * Returns an ordered array of collection names derived from the input FirestoreModelKey.
+ *
+ * @param input - The key or reference to extract collection names from
+ * @returns An array of FirestoreCollectionName values, or undefined if the key is unavailable
+ */
 export declare function firestoreModelKeyCollectionTypeArray<T = unknown>(input: ReadFirestoreModelKeyInput<T>): Maybe<FirestoreModelCollectionTypeArray>;
 export interface FirestoreModelCollectionAndIdPair extends FirestoreModelIdRef, FirestoreCollectionNameRef {
 }
 /**
  * Returns the collection name of the input key.
  *
- * @param input
- * @returns
+ * @param input - The key or reference to extract the collection name from
+ * @returns The FirestoreCollectionName from the deepest key pair, or undefined if unavailable
  */
 export declare function firestoreModelKeyCollectionName<T = unknown>(input: ReadFirestoreModelKeyInput<T>): Maybe<FirestoreCollectionName>;
 /**
  * Returns the parent model key from up the specified amount of levels.
  *
- * @param input
- * @param maxLevelsUp
+ * @param input - The key or reference to extract the parent key from
+ * @param maxLevelsUp - The number of levels to traverse up the key hierarchy; defaults to 1
+ * @returns The parent FirestoreModelKey, or undefined if no parent exists
  */
 export declare function firestoreModelKeyParentKey<T = unknown>(input: ReadFirestoreModelKeyInput<T>, maxLevelsUp?: number): Maybe<FirestoreModelKey>;
+/**
+ * Returns the collection/id pair array truncated by the specified number of levels from the end.
+ *
+ * @param input - The key or reference to extract pairs from
+ * @param maxLevelsUp - The number of levels to remove from the end; defaults to 1
+ * @returns An array of FirestoreModelCollectionAndIdPair values up to the parent level, or undefined if unavailable
+ */
 export declare function firestoreModelKeyParentKeyPartPairs<T = unknown>(input: ReadFirestoreModelKeyInput<T>, maxLevelsUp?: number): Maybe<FirestoreModelCollectionAndIdPair[]>;
 /**
  * Returns the last pair type from all generated pairs from the input.
@@ -450,6 +502,12 @@ export declare function firestoreModelKeyParentKeyPartPairs<T = unknown>(input:
  * @returns
  */
 export declare function firestoreModelKeyTypePair<T = unknown>(input: ReadFirestoreModelKeyInput<T>): Maybe<FirestoreModelCollectionAndIdPair>;
+/**
+ * Parses a FirestoreModelKey into an ordered array of collection/id pair objects.
+ *
+ * @param input - The key or reference to parse
+ * @returns An array of FirestoreModelCollectionAndIdPair values, or undefined if the key is unavailable
+ */
 export declare function firestoreModelKeyPartPairs<T = unknown>(input: ReadFirestoreModelKeyInput<T>): Maybe<FirestoreModelCollectionAndIdPair[]>;
 /**
  * Creates a FirestoreModelKey from the input pairs.
@@ -466,6 +524,13 @@ export declare function firestoreModelKeyPartPairsKeyPath(input: FirestoreModelC
  */
 export declare function firestoreModelKeyPartPairsPaths(input: FirestoreModelCollectionAndIdPair[]): FirestoreModelKeyPart[];
 export type ReadFirestoreModelKeyInput<T = unknown> = FirestoreModelKey | FirestoreModelKeyRef | DocumentReferenceRef<T>;
+/**
+ * Reads a FirestoreModelKey from the input, which may be a raw key string, a key ref, or a document reference ref.
+ *
+ * @param input - The key, key ref, or document reference ref to read
+ * @param required - Whether to throw if the key is not available; defaults to false
+ * @returns The FirestoreModelKey string, or undefined if unavailable and not required
+ */
 export declare function readFirestoreModelKey<T = unknown>(input: ReadFirestoreModelKeyInput<T>, required: true): FirestoreModelKey;
 export declare function readFirestoreModelKey<T = unknown>(input: ReadFirestoreModelKeyInput<T>, required: false): Maybe<FirestoreModelKey>;
 export declare function readFirestoreModelKey<T = unknown>(input: ReadFirestoreModelKeyInput<T>, required?: boolean): Maybe<FirestoreModelKey>;
@@ -548,7 +613,7 @@ export interface FirestoreCollectionRef<T, D extends FirestoreDocument<T> = Fire
  *
  * @template T - The data type of documents in the collection
  * @template D - The FirestoreDocument type that wraps the data
- * @param config - Configuration for the collection
+ * @param inputConfig - Configuration for the collection
  * @returns A fully configured FirestoreCollection instance
  */
 export declare function makeFirestoreCollection<T, D extends FirestoreDocument<T>>(inputConfig: FirestoreCollectionConfig<T, D>): FirestoreCollection<T, D>;

package/src/lib/common/firestore/driver/query.handler.d.ts

@@ -9,11 +9,17 @@ import { type FirestoreQueryConstraintFunctionsDriver } from './query';
  * @template B - The platform-specific query builder type (e.g., the Firestore Query itself)
  */
 export interface MakeFirestoreQueryConstraintFunctionsDriver<B> extends Omit<FirestoreQueryConstraintFunctionsDriver, 'query' | 'availableConstraintTypes'> {
-    /** Maps constraint type names to handler functions that apply them to the builder. */
+    /**
+     * Maps constraint type names to handler functions that apply them to the builder.
+     */
     mapping: FirestoreQueryConstraintHandlerMap<B>;
-    /** Initializes a builder from a base query. */
+    /**
+     * Initializes a builder from a base query.
+     */
     init: <T>(query: Query<T>) => B;
-    /** Converts the finalized builder back to a query. */
+    /**
+     * Converts the finalized builder back to a query.
+     */
     build: <T>(builder: B) => Query<T>;
 }
 /**

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

@@ -852,6 +852,8 @@ export declare function firestoreMap<T, K extends string = string>(config?: Fire
  * FirestoreField configuration for a map of granted roles, keyed by model keys.
  *
  * Filters out models with no/null roles by default.
+ *
+ * @returns A field mapping configuration for a map of granted roles keyed by FirestoreModelKey
  */
 export declare function firestoreModelKeyGrantedRoleMap<R extends GrantedRole>(): FirestoreModelFieldMapFunctionsConfig<FirestoreMapFieldType<R, string>, FirestoreMapFieldType<R, string>>;
 /**
@@ -917,6 +919,9 @@ export declare function firestoreDencoderMap<D extends PrimativeKey, E extends P
  * FirestoreField configuration for a map of encoded granted roles, keyed by model keys.
  *
  * Filters out models with empty/no roles by default.
+ *
+ * @param dencoder - The dencoder function used to encode and decode the role values
+ * @returns A field mapping configuration for an encoded granted role map keyed by FirestoreModelKey
  */
 export declare function firestoreModelKeyEncodedGrantedRoleMap<D extends GrantedRole, E extends string>(dencoder: PrimativeKeyStringDencoderFunction<D, E>): FirestoreModelFieldMapFunctionsConfig<FirestoreEncodedObjectMapFieldValueType<D[], string>, FirestoreMapFieldType<E, string>>;
 /**
@@ -939,6 +944,8 @@ export declare function firestoreArrayMap<T, K extends string = string>(config?:
  * FirestoreField configuration for a map of granted roles, keyed by models keys.
  *
  * Filters empty roles/arrays by default.
+ *
+ * @returns A field mapping configuration for a map of granted role arrays keyed by FirestoreModelKey
  */
 export declare function firestoreModelKeyGrantedRoleArrayMap<R extends GrantedRole>(): FirestoreModelFieldMapFunctionsConfig<FirestoreMapFieldType<R[], string>, FirestoreMapFieldType<R[], string>>;
 /**
@@ -977,6 +984,9 @@ export type FirestoreObjectArrayFieldConfigFirestoreFieldInput<T extends object,
  *
  * Used internally by {@link firestoreObjectArray} to adapt field configs into the map functions
  * format needed for array element conversion.
+ *
+ * @param config - The FirestoreModelFieldMapFunctionsConfig to convert
+ * @returns A ModelMapFunctionsRef wrapping the derived map functions
  */
 export declare function firestoreFieldConfigToModelMapFunctionsRef<T extends object, O extends object = FirestoreModelData<T>>(config: FirestoreModelFieldMapFunctionsConfig<T, O>): ModelMapFunctionsRef<T, O>;
 /**
@@ -1065,7 +1075,10 @@ export type FirestoreTimezoneStringConfig = DefaultMapConfiguredFirestoreFieldCo
 /**
  * Default configuration for a TimezoneString.
  *
- * The value defaults to UTC
+ * The value defaults to UTC.
+ *
+ * @param config - Optional configuration for the timezone string field, including default value and pre-save default.
+ * @returns A configured Firestore field that stores a TimezoneString value.
  */
 export declare function firestoreTimezoneString(config?: FirestoreTimezoneStringConfig): FirestoreModelFieldMapFunctionsConfig<string, string>;
 export declare const DEFAULT_WEBSITE_LINK: WebsiteLink;
@@ -1077,6 +1090,11 @@ export declare const firestoreWebsiteLinkAssignFn: MapFunction<WebsiteLink, Webs
  * @returns A field mapping configuration for website link values
  */
 export declare function firestoreWebsiteLink(): FirestoreModelFieldMapFunctionsConfig<WebsiteLink, WebsiteLink>;
+/**
+ * Creates a field mapping configuration for Firestore arrays of WebsiteLink values.
+ *
+ * @returns A field mapping configuration for WebsiteLink array values
+ */
 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>;
@@ -1089,10 +1107,14 @@ export declare const firestoreWebsiteFileLinkAssignFn: MapFunction<WebsiteFileLi
 export declare function firestoreWebsiteFileLink(): FirestoreModelFieldMapFunctionsConfig<WebsiteFileLink, WebsiteFileLink>;
 /**
  * Stores the array of WebsiteFileLink values as an array of objects.
+ *
+ * @returns A field mapping configuration for WebsiteFileLink array values stored as objects
  */
 export declare function firestoreWebsiteFileLinkObjectArray(): FirestoreModelFieldMapFunctionsConfig<WebsiteFileLink[], WebsiteFileLink[]>;
 /**
  * Stores the array of WebsiteFileLink values as an array of EncodedWebsiteFileLink values.
+ *
+ * @returns A field mapping configuration for WebsiteFileLink array values stored in encoded form
  */
 export declare function firestoreWebsiteFileLinkEncodedArray(): FirestoreModelFieldMapFunctionsConfig<WebsiteFileLink[], string[]>;
 export declare const DEFAULT_DATE_CELL_RANGE_VALUE: DateCellRange;
@@ -1104,6 +1126,12 @@ export declare const firestoreDateCellRangeAssignFn: MapFunction<DateCellRange,
  * @returns A field mapping configuration for date cell range values
  */
 export declare function firestoreDateCellRange(): FirestoreModelFieldMapFunctionsConfig<DateCellRange, DateCellRange>;
+/**
+ * Creates a field mapping configuration for Firestore arrays of DateCellRange values.
+ *
+ * @param sort - Whether to sort the array by index number; defaults to true
+ * @returns A field mapping configuration for DateCellRange array values
+ */
 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>;
@@ -1121,6 +1149,9 @@ export declare const DEFAULT_FIRESTORE_UNITED_STATES_ADDRESS_VALUE: UnitedStates
 export declare const assignUnitedStatesAddressFunction: import("@dereekb/util").AssignValuesToPOJOFunction<UnitedStatesAddress>;
 /**
  * Function to assign values from an input UnitedStatesAddress to a default UnitedStatesAddress.
+ *
+ * @param input - The source UnitedStatesAddress to copy values from
+ * @returns A new UnitedStatesAddress with values assigned from the input
  */
 export declare const firestoreUnitedStatesAddressAssignFn: MapFunction<UnitedStatesAddress, UnitedStatesAddress>;
 /**

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

@@ -41,6 +41,7 @@ export type OnCallTypeModelParamsFunction = <T>(modelTypeInput: FirestoreModelTy
  * The returned function builds {@link OnCallTypedModelParams} for any model type.
  *
  * @param call - the CRUD call type to embed in generated params
+ * @returns an {@link OnCallTypeModelParamsFunction} pre-configured with the given call type
  * @throws {Error} When `modelType` is not provided or empty.
  *
  * @example
@@ -58,9 +59,11 @@ export declare function onCallTypedModelParamsFunction(call?: Maybe<OnCallFuncti
  *
  * @deprecated Move towards using onCallTypedModelParamsFunction directly with the call type instead of using this function. Will not be removed in the future.
  *
- * @param modelType
- * @param data
- * @returns
+ * @param modelTypeInput - the model type string or ref
+ * @param data - the call payload
+ * @param specifier - optional sub-function specifier
+ * @param call - the CRUD call type
+ * @returns the constructed {@link OnCallTypedModelParams}
  */
 export declare function onCallTypedModelParams<T>(modelTypeInput: FirestoreModelType | FirestoreModelTypeRef, data: T, specifier?: string, call?: OnCallFunctionType): OnCallTypedModelParams<T>;
 /**
@@ -112,6 +115,7 @@ export interface OnCallCreateModelResult {
  * Creates an {@link OnCallCreateModelResult} from document references by extracting their paths as model keys.
  *
  * @param result - document reference(s) from a create operation
+ * @returns an {@link OnCallCreateModelResult} with model keys extracted from document paths
  *
  * @example
  * ```ts
@@ -124,5 +128,6 @@ export declare function onCallCreateModelResultWithDocs(result: ArrayOrValue<Doc
  * Creates an {@link OnCallCreateModelResult} from model key(s), normalizing to an array.
  *
  * @param modelKeys - the model key(s) of the created document(s)
+ * @returns an {@link OnCallCreateModelResult} containing the keys as an array
  */
 export declare function onCallCreateModelResult(modelKeys: ArrayOrValue<FirestoreModelKey>): OnCallCreateModelResult;

package/src/lib/common/model/model/model.loader.d.ts

@@ -38,6 +38,7 @@ export interface FirebaseModelLoader<C extends FirebaseModelLoaderContext, T, D
  * Automatically uses a transaction accessor when the context has an active transaction.
  *
  * @param getFirestoreCollection - function to retrieve the Firestore collection from context
+ * @returns a {@link FirebaseModelLoader} that loads document wrappers for given keys
  *
  * @example
  * ```ts

package/src/lib/common/model/model.service.d.ts

@@ -38,6 +38,7 @@ export interface FirebaseModelServiceConfig<C extends FirebaseModelServiceContex
  * Creates a {@link FirebaseModelService} that wires together model loading and permission evaluation.
  *
  * @param config - collection loader and role mapping functions
+ * @returns a {@link FirebaseModelService} combining model loading and permission evaluation
  *
  * @example
  * ```ts
@@ -56,6 +57,7 @@ export type FirebaseModelServiceFactory<C extends FirebaseModelServiceContext, T
  * Creates a {@link FirebaseModelServiceFactory} that lazily instantiates and caches the service.
  *
  * @param config - the service configuration
+ * @returns a {@link FirebaseModelServiceFactory} that lazily creates and caches the service
  */
 export declare function firebaseModelServiceFactory<C extends FirebaseModelServiceContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole>(config: FirebaseModelServiceConfig<C, T, D, R>): FirebaseModelServiceFactory<C, T, D, R>;
 /**
@@ -101,6 +103,7 @@ export type InModelContextFirebaseModelServiceUseFunction<C extends FirebasePerm
  * with a model or key to perform permission-checked operations.
  *
  * @param factory - lazy getter for the underlying model service
+ * @returns an {@link InContextFirebaseModelServiceFactory} that binds contexts to the service
  */
 export declare function inContextFirebaseModelServiceFactory<C extends FirebaseModelServiceContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole>(factory: FirebaseModelServiceGetter<C, T, D, R>): InContextFirebaseModelServiceFactory<C, T, D, R>;
 /**
@@ -140,8 +143,8 @@ export type FirebaseModelsServiceTypes<S extends FirebaseModelsService<any, any>
  * export const demoFirebaseModelServices = firebaseModelsService<typeof DEMO_FIREBASE_MODEL_SERVICE_FACTORIES, DemoFirebaseBaseContext, DemoFirebaseModelTypes>(DEMO_FIREBASE_MODEL_SERVICE_FACTORIES);
  * export type DemoFirebaseContext = DemoFirebaseBaseContext & { service: typeof demoFirebaseModelServices };
  *
- * @param services
- * @returns
+ * @param services - the map of model service getter factories
+ * @returns a {@link FirebaseModelsService} that dispatches to the appropriate model service by type
  */
 export declare function firebaseModelsService<X extends FirebaseModelsServiceFactory<C, I>, C extends FirebaseModelServiceContext, I extends FirestoreModelIdentity = FirestoreModelIdentity>(services: X): FirebaseModelsService<X, C>;
 /**
@@ -158,6 +161,7 @@ export type InContextFirebaseModelsServiceFactory<Y> = FirebaseModelsServiceType
  * The returned factory binds a context, so callers can then select individual model services by type.
  *
  * @param service - the multi-model service to wrap
+ * @returns an {@link InContextFirebaseModelsServiceFactory} that binds a context to the service
  */
 export declare function inContextFirebaseModelsServiceFactory<X extends FirebaseModelsServiceFactory<C, I>, C extends FirebaseModelServiceContext, I extends FirestoreModelIdentity = FirestoreModelIdentity>(service: FirebaseModelsService<X, C>): InContextFirebaseModelsServiceFactory<FirebaseModelsService<X, C>>;
 /**
@@ -181,6 +185,7 @@ export type UseFirebaseModelsServiceSelectionUseFunction<Y extends FirebaseModel
  * @param service - the multi-model service
  * @param type - the model type to select
  * @param select - selection params including context and key
+ * @returns the {@link FirebaseModelsServiceSelectionResult} bound to the specified model
  */
 export declare function selectFromFirebaseModelsService<Y extends FirebaseModelsService<any, any>, T extends FirebaseModelsServiceTypes<Y>>(service: Y, type: T, select: FirebaseModelsServiceSelection<Y, T>): FirebaseModelsServiceSelectionResult<Y, T>;
 /**
@@ -191,6 +196,7 @@ export declare function selectFromFirebaseModelsService<Y extends FirebaseModels
  * @param service - the multi-model service
  * @param type - the model type to select
  * @param select - selection params including context, key, and optional role requirements
+ * @returns a {@link UsePromiseFunction} for the resolved roles reader
  */
 export declare function useFirebaseModelsService<Y extends FirebaseModelsService<any, any>, T extends FirebaseModelsServiceTypes<Y>>(service: Y, type: T, select: UseFirebaseModelsServiceSelection<Y, T>): UseFirebaseModelsServiceSelectionResult<Y, T>;
 /**
@@ -199,5 +205,6 @@ export declare function useFirebaseModelsService<Y extends FirebaseModelsService
  * Useful for routing incoming requests to the correct model service by collection path.
  *
  * @param inContextFirebaseModelsService - context-bound multi-model service
+ * @returns a map of collection type strings to their {@link FirestoreModelIdentity} objects
  */
 export declare function buildFirebaseCollectionTypeModelTypeMap<Y extends FirebaseModelsService<any, any>>(inContextFirebaseModelsService: InContextFirebaseModelsService<Y>): import("..").FirestoreModelIdentityTypeMap;

package/src/lib/common/model/permission/permission.d.ts

@@ -9,13 +9,21 @@ import { type FirebasePermissionErrorContext } from './permission.context';
  * Passed to role-mapping functions so they can inspect the model's state to determine permissions.
  */
 export interface FirebasePermissionServiceModel<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> {
-    /** The {@link FirestoreDocument} wrapper. */
+    /**
+     * The {@link FirestoreDocument} wrapper.
+     */
     readonly document: D;
-    /** The raw Firestore document snapshot. */
+    /**
+     * The raw Firestore document snapshot.
+     */
     readonly snapshot: DocumentSnapshot<T>;
-    /** Whether the document exists in Firestore. */
+    /**
+     * Whether the document exists in Firestore.
+     */
     readonly exists: boolean;
-    /** The deserialized document data, or `undefined` if it doesn't exist. */
+    /**
+     * The deserialized document data, or `undefined` if it doesn't exist.
+     */
     readonly data: Maybe<T>;
 }
 /**

package/src/lib/common/model/permission/permission.service.d.ts

@@ -35,6 +35,7 @@ export declare class FirebaseModelPermissionServiceInstance<C extends FirebaseMo
  * Creates a {@link FirebaseModelPermissionServiceInstance} from a delegate.
  *
  * @param delegate - provides model loading and role computation
+ * @returns a {@link FirebaseModelPermissionServiceInstance} configured with the given delegate
  */
 export declare function firebaseModelPermissionService<C extends FirebaseModelContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends string = string>(delegate: FirebasePermissionServiceInstanceDelegate<C, T, D, R>): FirebaseModelPermissionServiceInstance<C, T, D, R>;
 /**

package/src/lib/common/model/permission/permission.service.grant.d.ts

@@ -7,12 +7,16 @@ import { type UserRelated } from '../../../model/user';
  * Decision function that checks if the current user is an admin in the given context.
  *
  * Returns `false` if no auth is present.
+ *
+ * @param context - the Firebase model context to evaluate
+ * @returns a promise resolving to `true` if the user is an admin, `false` otherwise
  */
 export declare const isAdminInFirebaseModelContext: AsyncDecisionFunction<FirebaseModelContext>;
 /**
  * Creates a {@link GrantRolesIfFunction} that grants the specified roles when the user is an admin.
  *
  * @param rolesToGrantToAdmin - roles to grant if the user is an admin
+ * @returns a {@link GrantRolesIfFunction} that grants the given roles when the user is an admin
  *
  * @example
  * ```ts
@@ -31,6 +35,7 @@ export declare const grantFullAccessIfAdmin: GeneralGrantRolesIfFunction<Firebas
  * @param context - the model context to check
  * @param rolesToGrantToAdmin - roles to grant if admin
  * @param otherwise - fallback role computation when not admin
+ * @returns a promise or value resolving to the granted role map
  */
 export declare function grantModelRolesIfAdmin<R extends string = string>(context: FirebaseModelContext, rolesToGrantToAdmin: GetterOrValue<GrantedRoleMap<R>>, otherwise?: GrantRolesOtherwiseFunction<R>): PromiseOrValue<GrantedRoleMap<R>>;
 /**
@@ -38,6 +43,7 @@ export declare function grantModelRolesIfAdmin<R extends string = string>(contex
  *
  * @param authRoles - the auth roles the user must have
  * @param rolesToGrantToAdmin - the model roles to grant if the auth roles are present
+ * @returns a {@link GrantRolesIfFunction} that grants the given roles when the user has the required auth roles
  */
 export declare function grantModelRolesIfHasAuthRolesFunction<R extends string = string>(authRoles: AuthRole[], rolesToGrantToAdmin: GetterOrValue<GrantedRoleMap<R>>): GrantRolesIfFunction<FirebaseModelContext, R>;
 /**
@@ -48,6 +54,7 @@ export type GrantModelRolesIfHasAuthRolesFactory = <R extends string = string>(c
  * Creates a reusable factory pre-configured with specific auth roles to check for.
  *
  * @param authRoles - the auth roles the user must have
+ * @returns a {@link GrantModelRolesIfHasAuthRolesFactory} pre-configured to check the given auth roles
  */
 export declare function grantModelRolesIfHasAuthRolesFactory(authRoles: IterableOrValue<AuthRole>): GrantModelRolesIfHasAuthRolesFactory;
 /**
@@ -80,6 +87,7 @@ export declare const isOwnerOfUserRelatedModelInFirebaseModelContext: AsyncDecis
  * Creates a {@link GrantRolesIfFunction} that grants roles when the authenticated user's UID matches the model's `uid` field.
  *
  * @param rolesToGrant - the roles to grant if the user owns the model
+ * @returns a {@link GrantRolesIfFunction} that grants roles when the authenticated user is the model owner
  *
  * @example
  * ```ts
@@ -107,6 +115,7 @@ export type GeneralGrantRolesOnlyIfFunction<C> = <R extends string = string>(con
  *
  * @param grantIf - decision function to evaluate
  * @param grantedRoles - roles to grant if the decision is `true`
+ * @returns a {@link GrantRolesOnlyIfFunction} that grants roles or returns no-access with no fallback
  */
 export declare function grantModelRolesOnlyIfFunction<C, R extends string = string>(grantIf: AsyncDecisionFunction<C>, grantedRoles: GetterOrValue<GrantedRoleMap<R>>): GrantRolesOnlyIfFunction<C, R>;
 /**
@@ -132,6 +141,7 @@ export type GrantRolesOtherwiseFunction<R extends string = string> = Getter<Gran
  *
  * @param grantIf - async decision function to evaluate
  * @param grantedRoles - roles to grant if the decision is `true`
+ * @returns a {@link GrantRolesIfFunction} that evaluates the condition and grants roles or falls back
  * @throws {Error} When `grantIf` is not provided.
  *
  * @example

package/src/lib/common/model/permission/permission.service.role.d.ts

@@ -39,7 +39,7 @@ export declare class ContextGrantedModelRolesReaderInstance<C extends FirebasePe
     get snapshot(): import("../..").DocumentSnapshot<T>;
     get exists(): boolean;
     get roleMap(): GrantedRoleMap<R>;
-    truthMap<M extends GrantedRoleTruthMapObject<any, R>>(input: M): GrantedRoleTruthMap<M>;
+    truthMap<M extends GrantedRoleTruthMapObject<unknown, R>>(input: M): GrantedRoleTruthMap<M>;
     hasNoAccess(): boolean;
     hasRole(role: R): boolean;
     hasRoles(setIncludes: SetIncludesMode, roles: ArrayOrValue<R>): boolean;
@@ -53,21 +53,23 @@ export declare class ContextGrantedModelRolesReaderInstance<C extends FirebasePe
 }
 /**
  * Creates a new ContextGrantedModelRolesReader for the input model.
+ *
+ * @param service - the in-model-context permission service to read roles from
+ * @returns a promise resolving to a {@link ContextGrantedModelRolesReader} for the model
  */
 export declare function contextGrantedModelRolesReader<C extends FirebasePermissionErrorContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole>(service: InModelContextFirebaseModelPermissionService<C, T, D, R>): Promise<ContextGrantedModelRolesReader<C, T, D, R>>;
 /**
  * Creates the default permission error message.
  *
- * @param contextGrantedModelRoles
- * @param role
- * @returns
+ * @param contextGrantedModelRoles - the granted model roles context to generate the message from
+ * @param roles - the required role(s) that were not satisfied
+ * @returns a human-readable permission error message string
  */
 export declare function contextGrantedModelRolesReaderPermissionErrorMessage(contextGrantedModelRoles: FirebaseContextGrantedModelRoles<FirebasePermissionErrorContext, unknown>, roles?: ArrayOrValue<GrantedRole>): string;
 /**
  * Creates the default does not exist error message.
  *
- * @param contextGrantedModelRoles
- * @param role
- * @returns
+ * @param contextGrantedModelRoles - the granted model roles context to generate the message from
+ * @returns a human-readable does-not-exist error message string
  */
 export declare function contextGrantedModelRolesReaderDoesNotExistErrorMessage(contextGrantedModelRoles: FirebaseContextGrantedModelRoles<FirebasePermissionErrorContext, unknown>): string;

package/src/lib/common/storage/accessor/path.model.d.ts

@@ -34,6 +34,7 @@ export type ModelStorageSlashPathFactory<T extends object = object> = (input: Re
  * The generated paths follow the convention `/model/[basePath/]<modelKey>/[path]`.
  *
  * @param config - optional base path to nest under
+ * @returns a {@link ModelStorageSlashPathFactory} that maps Firestore model keys to storage paths
  *
  * @example
  * ```ts

package/src/lib/common/storage/context.d.ts

@@ -40,6 +40,7 @@ export interface FirebaseStorageContextFactoryConfig {
  * a {@link StoragePathFactory} to normalize all path inputs.
  *
  * @param drivers - the storage driver implementations to use
+ * @returns a {@link FirebaseStorageContextFactory} that creates storage contexts for a given storage instance
  * @throws {Error} When a default bucket ID cannot be resolved from the driver or config.
  *
  * @example

package/src/lib/common/storage/driver/accessor.iterate.d.ts

@@ -25,6 +25,7 @@ export type IterateStorageListFilesFactory = FetchPageFactory<IterateStorageList
  * Wraps the folder's `list()` API with cursor-based pagination via {@link fetchPageFactory}.
  *
  * @param config - default listing options (e.g., maxResults)
+ * @returns an {@link IterateStorageListFilesFactory} for paginated file listing
  *
  * @example
  * ```ts
@@ -41,6 +42,9 @@ export type IterateStorageListFilesByEachFileConfig<T, R> = Omit<IterateFetchPag
  * Iterates through every file in a storage folder, invoking a callback for each individual file result.
  *
  * Convenience wrapper around {@link iterateFetchPagesByEachItem} pre-configured for storage listing.
+ *
+ * @param input - iteration configuration including folder, listing options, and per-item callback
+ * @returns the result of the paginated per-item iteration
  */
 export declare function iterateStorageListFilesByEachFile<T, R>(input: IterateStorageListFilesByEachFileConfig<T, R>): Promise<{
     totalItemsLoaded: number;
@@ -57,5 +61,8 @@ export type IterateStorageListFilesConfig<R> = Omit<IterateFetchPagesConfigWithF
  * Iterates through pages of file results in a storage folder, invoking a callback for each page.
  *
  * Convenience wrapper around {@link iterateFetchPages} pre-configured for storage listing.
+ *
+ * @param input - iteration configuration including folder, listing options, and per-page callback
+ * @returns the result of the paginated page-level iteration
  */
 export declare function iterateStorageListFiles<R>(input: IterateStorageListFilesConfig<R>): Promise<import("@dereekb/util/fetch").IterateFetchPagesResult>;

package/src/lib/common/storage/driver/accessor.util.d.ts

@@ -9,6 +9,7 @@ import { type FirebaseStorageAccessorFile } from './accessor';
  * @param file - the target file accessor to upload to
  * @param readableStream - the source stream to pipe
  * @param options - optional upload configuration (content type, metadata, etc.)
+ * @returns a promise that resolves when the upload stream has finished
  * @throws {StorageFileUploadStreamUnsupportedError} When the file accessor does not support stream uploads.
  *
  * @example

package/src/lib/common/storage/driver/error.d.ts

@@ -6,11 +6,14 @@ import { BaseError } from 'make-error';
  * Required when the upload input is a string, since the format (raw, base64, etc.) must be explicit.
  *
  * @param options - the upload options to extract from
+ * @returns the {@link StorageDataStringType} extracted from the options
  * @throws {Error} When `stringFormat` is not set in the options.
  */
 export declare function assertStorageUploadOptionsStringFormat(options?: StorageUploadOptions): StorageDataStringType;
 /**
  * Creates an error indicating that `stringFormat` was missing from upload options.
+ *
+ * @returns an {@link Error} describing the missing `stringFormat` in upload options
  */
 export declare function noStringFormatInStorageUploadOptionsError(): Error;
 /**