@dereekb/firebase 13.2.2 → 13.3.0

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

@@ -1,14 +1,33 @@
+/**
+ * Platform-agnostic Firestore type definitions.
+ *
+ * These types mirror the interfaces from both `@google-cloud/firestore` (Admin SDK) and
+ * `firebase/firestore` (Web SDK) so that the rest of the codebase can work with either
+ * platform without importing platform-specific packages directly. This is the foundation
+ * of the cross-platform driver abstraction.
+ *
+ * @module
+ */
 import { StringKeyPropertyKeys } from '@dereekb/util';
 import { UnionToIntersection } from 'ts-essentials';
 import { FirestoreModelKey, FirestoreModelId } from './collection';
+/**
+ * Minimal shape of the Firebase Web SDK Firestore instance.
+ */
 export type FirebaseFirestoreLikeFirestore = {
     type: string;
 };
+/**
+ * Minimal shape of the Google Cloud Admin SDK Firestore instance.
+ */
 export type GoogleCloudLikeFirestore = {
     terminate(): Promise<void>;
 };
 /**
- * Cast to the local type's firestore if direct access is needed. In most cases, direct access to this type is unncessary.
+ * Union type representing either a Web SDK or Admin SDK Firestore instance.
+ *
+ * Code that needs the concrete type should cast through the driver layer.
+ * Direct access to this type is rarely needed outside of driver implementations.
  */
 export type Firestore = FirebaseFirestoreLikeFirestore | GoogleCloudLikeFirestore;
 export type Primitive = string | number | boolean | undefined | null;
@@ -34,9 +53,28 @@ export type UpdateData<T> = T extends Primitive ? T : T extends {} ? {
 export interface FieldPath {
     isEqual(other: FieldPath): boolean;
 }
+/**
+ * A field path expressed as either a dot-separated string or a {@link FieldPath} object.
+ */
 export type FieldPathOrStringPath = string | FieldPath;
+/**
+ * A type-safe field path that restricts string keys to those present on `T`.
+ */
 export type FieldPathOrStringPathOf<T = object> = StringKeyPropertyKeys<T> | FieldPath;
+/**
+ * Extracts the top-level field name from each path, discarding nested segments.
+ *
+ * @param input - Array of field paths (strings or FieldPath objects)
+ * @returns Array of top-level field name strings
+ */
 export declare function asTopLevelFieldPaths(input: (string | FieldPath)[]): string[];
+/**
+ * Extracts the top-level field name from a path, discarding nested segments.
+ * For example, `'address.city'` returns `'address'`.
+ *
+ * @param input - A field path (string or FieldPath object)
+ * @returns The top-level field name
+ */
 export declare function asTopLevelFieldPath(input: string | FieldPath): string;
 export interface Timestamp {
     readonly seconds: number;

package/src/lib/common/firestore/util/id.batch.d.ts

@@ -2,24 +2,76 @@ import { type ArrayOrValue, type FactoryWithRequiredInput, type IdBatchVerifier,
 import { type FirestoreCollectionLike } from '../collection';
 import { type FirestoreQueryConstraint } from '../query/constraint';
 import { type DocumentSnapshot } from '../types';
+/**
+ * Base configuration for creating a Firestore-backed {@link IdBatchVerifier}.
+ *
+ * @template T - The Firestore document data type
+ * @template I - The identifier/key type (must be a primitive key)
+ */
 export type FirestoreIdBatchVerifierFactoryBaseConfig<T, I extends PrimativeKey> = {
     /**
-     * Reads the existing identifier(s) from the queried model.
+     * Extracts the identifier(s) from a queried document snapshot.
+     * Used to determine which keys from a batch already exist in Firestore.
      */
     readKeys: ReadMultipleKeysFunction<DocumentSnapshot<T>, I>;
 };
+/**
+ * Configuration that queries a specific document field for existence checks.
+ * Use `'_id'` as the field value to query by document ID instead of a data field.
+ *
+ * @template T - The Firestore document data type
+ * @template I - The identifier/key type
+ */
 export type FirestoreIdBatchVerifierFactoryFieldsQueryConfig<T, I extends PrimativeKey> = FirestoreIdBatchVerifierFactoryBaseConfig<T, I> & {
     /**
-     * Uses the keys in a query that checks for existence in this field.
+     * The document field to query with an `in` filter, or `'_id'` to query by document ID.
      */
     fieldToQuery: keyof T | '_id';
 };
+/**
+ * Configuration that provides custom query constraints for existence checks.
+ *
+ * @template T - The Firestore document data type
+ * @template I - The identifier/key type
+ */
 export type FirestoreIdBatchVerifierFactoryMakeQueryConfig<T, I extends PrimativeKey> = FirestoreIdBatchVerifierFactoryBaseConfig<T, I> & {
     /**
-     * Used to create query constraints for looking for models with the key.
+     * Creates query constraints to find documents matching the given keys.
      */
     makeQueryConstraints: FactoryWithRequiredInput<ArrayOrValue<FirestoreQueryConstraint>, I[]>;
 };
+/**
+ * Union config type: either specify a field to query or provide custom query constraints.
+ */
 export type FirestoreIdBatchVerifierFactoryConfig<T, I extends PrimativeKey> = FirestoreIdBatchVerifierFactoryMakeQueryConfig<T, I> | FirestoreIdBatchVerifierFactoryFieldsQueryConfig<T, I>;
+/**
+ * Factory that creates an {@link IdBatchVerifier} bound to a specific Firestore collection.
+ *
+ * @template T - The Firestore document data type
+ * @template I - The identifier/key type
+ */
 export type FirestoreIdBatchVerifierFactory<T, I extends PrimativeKey> = FactoryWithRequiredInput<IdBatchVerifier<I, I>, FirestoreCollectionLike<T>>;
+/**
+ * Creates a factory for Firestore-backed {@link IdBatchVerifier} instances.
+ *
+ * The verifier checks which keys from a batch do **not** already exist in a Firestore
+ * collection, respecting Firestore's `where('in')` limit of {@link FIRESTORE_MAX_WHERE_IN_FILTER_ARGS_COUNT}
+ * items per query. This is used for batch ID generation to ensure uniqueness.
+ *
+ * @template T - The Firestore document data type
+ * @template I - The identifier/key type
+ * @param config - Specifies how to query for existing keys (by field or custom constraints)
+ * @returns A factory that produces verifiers bound to a specific collection
+ *
+ * @example
+ * ```ts
+ * const factory = firestoreIdBatchVerifierFactory<MyDoc, string>({
+ *   fieldToQuery: '_id',
+ *   readKeys: (snapshot) => [snapshot.id]
+ * });
+ *
+ * const verifier = factory(myCollection);
+ * // verifier can now check batches of IDs for uniqueness
+ * ```
+ */
 export declare function firestoreIdBatchVerifierFactory<T, I extends PrimativeKey>(config: FirestoreIdBatchVerifierFactoryConfig<T, I>): FirestoreIdBatchVerifierFactory<T, I>;

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

@@ -1,9 +1,44 @@
 import { type TransformAndValidateFunctionResult } from '@dereekb/model';
+/**
+ * A validated create action for a Firebase function.
+ *
+ * Wraps a {@link TransformAndValidateFunctionResult} that validates parameters `P` then executes a create operation
+ * returning `T`. Optionally accepts an input `I`.
+ *
+ * @template P - the validated parameters type
+ * @template T - the created entity type
+ * @template I - optional input for the create operation
+ */
 export type FirebaseFunctionCreateAction<P extends object, T, I = void> = I extends void ? TransformAndValidateFunctionResult<P, () => Promise<T>> : TransformAndValidateFunctionResult<P, (input: I) => Promise<T>>;
+/**
+ * Async variant of {@link FirebaseFunctionCreateAction} — the action itself is produced asynchronously.
+ */
 export type AsyncFirebaseFunctionCreateAction<P extends object, T, I = void> = Promise<FirebaseFunctionCreateAction<P, T, I>>;
+/**
+ * A validated read action for a Firebase function. Structurally identical to {@link FirebaseFunctionCreateAction}.
+ */
 export type FirebaseFunctionReadAction<P extends object, T, I = void> = FirebaseFunctionCreateAction<P, T, I>;
+/**
+ * Async variant of {@link FirebaseFunctionReadAction}.
+ */
 export type AsyncFirebaseFunctionReadAction<P extends object, T, I = void> = Promise<FirebaseFunctionReadAction<P, T, I>>;
+/**
+ * A validated update action for a Firebase function.
+ *
+ * Takes the entity `T` as input and returns the updated entity.
+ */
 export type FirebaseFunctionUpdateAction<P extends object, T> = TransformAndValidateFunctionResult<P, (input: T) => Promise<T>>;
+/**
+ * Async variant of {@link FirebaseFunctionUpdateAction}.
+ */
 export type AsyncFirebaseFunctionUpdateAction<P extends object, T> = Promise<FirebaseFunctionUpdateAction<P, T>>;
+/**
+ * A validated delete action for a Firebase function.
+ *
+ * Takes the entity `T` as input and returns void on successful deletion.
+ */
 export type FirebaseFunctionDeleteAction<P extends object, T> = TransformAndValidateFunctionResult<P, (input: T) => Promise<void>>;
+/**
+ * Async variant of {@link FirebaseFunctionDeleteAction}.
+ */
 export type AsyncFirebaseFunctionDeleteAction<P extends object, T> = Promise<FirebaseFunctionDeleteAction<P, T>>;

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

@@ -1,10 +1,20 @@
 import { type FirebaseAuthContext } from '../auth/auth.context';
 import { type FirebasePermissionContext, type FirebasePermissionErrorContext } from './permission';
 /**
- * A base model context that contains info about what is current occuring.
+ * Base context for Firebase model operations, combining authentication, permission checks, and error handling.
+ *
+ * Passed to model services, permission evaluators, and action handlers to provide
+ * information about the current caller and their authorization state.
+ *
+ * See {@link FirebaseAuthContext} for auth details and {@link FirebasePermissionContext} for transaction access.
  */
 export interface FirebaseModelContext extends FirebasePermissionContext, FirebasePermissionErrorContext, FirebaseAuthContext {
 }
+/**
+ * Extends {@link FirebaseModelContext} with an application-specific context (e.g., Firestore collections).
+ *
+ * @template C - the application context type (typically the Firestore collections container)
+ */
 export interface FirebaseAppModelContext<C> extends FirebaseModelContext {
     readonly app: C;
 }

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

@@ -2,36 +2,53 @@ import { type ArrayOrValue, type Maybe } from '@dereekb/util';
 import { type DocumentReferenceRef } from '../firestore/reference';
 import { type FirestoreModelKey, type FirestoreModelType, type FirestoreModelTypeRef } from '../firestore/collection/collection';
 /**
- * Set of known call types. The basic CRUD functions.
+ * Standard CRUD call types used by the `callModel` Firebase function pattern.
  */
 export type KnownOnCallFunctionType = 'create' | 'read' | 'update' | 'delete';
 /**
- * A call function type specifier.
+ * Call type identifier — one of the standard CRUD types or a custom string.
  */
 export type OnCallFunctionType = KnownOnCallFunctionType | string;
+/**
+ * Parameters for a typed model call through the `callModel` Firebase function.
+ *
+ * Combines the target model type, CRUD call type, optional specifier for sub-operations,
+ * and the call payload. This is the standard envelope format for all model API calls.
+ *
+ * @template T - the call data payload type
+ */
 export interface OnCallTypedModelParams<T = unknown> extends FirestoreModelTypeRef {
     /**
-     * Call type. Should typically be defined.
+     * CRUD call type (create, read, update, delete) or a custom action type.
      */
     readonly call?: Maybe<OnCallFunctionType>;
     /**
-     * Call sub-function specifier.
+     * Sub-function specifier for distinguishing different operations within the same call type.
      */
     readonly specifier?: string;
     /**
-     * Call data
+     * The call payload data.
      */
     readonly data: T;
 }
 /**
- *
+ * Function that creates {@link OnCallTypedModelParams} for a given model type, pre-configured with a call type.
  */
 export type OnCallTypeModelParamsFunction = <T>(modelTypeInput: FirestoreModelType | FirestoreModelTypeRef, data: T, specifier?: string) => OnCallTypedModelParams<T>;
 /**
- * Creates a OnCallTypedModelParamsFunction
+ * Creates an {@link OnCallTypeModelParamsFunction} pre-configured with the given call type.
  *
- * @param call
- * @returns
+ * The returned function builds {@link OnCallTypedModelParams} for any model type.
+ *
+ * @param call - the CRUD call type to embed in generated params
+ * @throws {Error} When `modelType` is not provided or empty.
+ *
+ * @example
+ * ```ts
+ * const createParams = onCallTypedModelParamsFunction('create');
+ * const params = createParams('notification', { title: 'Hello' });
+ * // params === { call: 'create', modelType: 'notification', data: { title: 'Hello' } }
+ * ```
  */
 export declare function onCallTypedModelParamsFunction(call?: Maybe<OnCallFunctionType>): OnCallTypeModelParamsFunction;
 /**
@@ -82,11 +99,30 @@ export type OnCallUpdateModelParams<T = unknown> = OnCallTypedModelParams<T>;
  * OnCallTypedModelParams for Delete calls.
  */
 export type OnCallDeleteModelParams<T = unknown> = OnCallTypedModelParams<T>;
+/**
+ * Standard result returned by model create operations, containing the key(s) of the created document(s).
+ */
 export interface OnCallCreateModelResult {
     /**
      * Key(s)/Paths of the created object(s)
      */
     readonly modelKeys: ArrayOrValue<FirestoreModelKey>;
 }
+/**
+ * Creates an {@link OnCallCreateModelResult} from document references by extracting their paths as model keys.
+ *
+ * @param result - document reference(s) from a create operation
+ *
+ * @example
+ * ```ts
+ * const result = onCallCreateModelResultWithDocs(createdDocs);
+ * // result.modelKeys === ['notifications/abc123']
+ * ```
+ */
 export declare function onCallCreateModelResultWithDocs(result: ArrayOrValue<DocumentReferenceRef<unknown>>): OnCallCreateModelResult;
+/**
+ * Creates an {@link OnCallCreateModelResult} from model key(s), normalizing to an array.
+ *
+ * @param modelKeys - the model key(s) of the created document(s)
+ */
 export declare function onCallCreateModelResult(modelKeys: ArrayOrValue<FirestoreModelKey>): OnCallCreateModelResult;

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

@@ -1,11 +1,26 @@
 import { type FirebaseTransactionContext, type FirestoreCollectionLike, type FirestoreDocument, type FirestoreModelKey } from '../../firestore';
 import { type InContextModelLoader, type ModelLoader } from '@dereekb/model';
 import { type Getter } from '@dereekb/util';
+/**
+ * Context type for model loading operations — requires optional transaction support.
+ */
 export type FirebaseModelLoaderContext = FirebaseTransactionContext;
+/**
+ * Function that retrieves a {@link FirestoreCollectionLike} from a context, used by loaders to access the correct collection.
+ */
 export type FirebaseModelGetFirestoreCollectionFunction<C extends FirebaseModelLoaderContext, T, D extends FirestoreDocument<T>> = (context: C) => FirestoreCollectionLike<T, D>;
+/**
+ * Provides access to a Firestore collection for a specific model type within a given context.
+ */
 export interface FirebaseModelCollectionLoader<C extends FirebaseModelLoaderContext, T, D extends FirestoreDocument<T>> {
     readonly getFirestoreCollection: FirebaseModelGetFirestoreCollectionFunction<C, T, D>;
 }
+/**
+ * Loads a {@link FirestoreDocument} wrapper for a given model key and context.
+ *
+ * Does not verify that the document actually exists in Firestore — it creates a document reference
+ * that can then be used for reads, writes, or permission checks.
+ */
 export interface FirebaseModelLoader<C extends FirebaseModelLoaderContext, T, D extends FirestoreDocument<T>> extends ModelLoader<C, D> {
     /**
      * Loads a FirestoreDocument for the input key.
@@ -17,10 +32,29 @@ export interface FirebaseModelLoader<C extends FirebaseModelLoaderContext, T, D
      */
     loadModelForKey(key: FirestoreModelKey, context: C): D;
 }
+/**
+ * Creates a {@link FirebaseModelLoader} that loads document wrappers from the given collection function.
+ *
+ * Automatically uses a transaction accessor when the context has an active transaction.
+ *
+ * @param getFirestoreCollection - function to retrieve the Firestore collection from context
+ *
+ * @example
+ * ```ts
+ * const loader = firebaseModelLoader((ctx) => ctx.app.notifications);
+ * const doc = loader.loadModelForKey('notifications/abc123', context);
+ * ```
+ */
 export declare function firebaseModelLoader<C extends FirebaseModelLoaderContext, T, D extends FirestoreDocument<T>>(getFirestoreCollection: FirebaseModelGetFirestoreCollectionFunction<C, T, D>): FirebaseModelLoader<C, T, D>;
+/**
+ * Context-bound variant of {@link FirebaseModelCollectionLoader} — the context is already captured.
+ */
 export interface InContextFirebaseModelCollectionLoader<T, D extends FirestoreDocument<T>> {
     readonly getFirestoreCollection: Getter<FirestoreCollectionLike<T, D>>;
 }
+/**
+ * Context-bound variant of {@link FirebaseModelLoader} — the context is already captured.
+ */
 export interface InContextFirebaseModelLoader<T, D extends FirestoreDocument<T>> extends InContextModelLoader<D> {
     loadModelForKey(key: FirestoreModelKey): D;
 }
@@ -28,6 +62,9 @@ export interface InContextFirebaseModelLoader<T, D extends FirestoreDocument<T>>
  * Type used to convert a FirebaseModelLoader into an InContextFirebaseModelLoader
  */
 export type AsInContextFirebaseModelLoader<X> = X extends FirebaseModelLoader<infer C, infer T, infer D> ? InContextFirebaseModelLoader<T, D> : never;
+/**
+ * A loader that is already bound to a specific model document instance.
+ */
 export interface InModelContextFirebaseModelLoader<T, D extends FirestoreDocument<T>> {
     readonly model: D;
 }

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

@@ -1,24 +1,46 @@
 import { type Type } from 'arktype';
 import { type FirestoreModelKey, type FirestoreModelKeyRef } from '../../firestore/collection/collection';
 /**
- * Simple params that implements FirestoreModelKeyRef.
+ * API parameter type that targets a specific Firestore model by its full key path (e.g., `"collection/id"`).
+ *
+ * Used in `callModel` function parameter validation.
  */
 export interface TargetModelParams extends FirestoreModelKeyRef {
     readonly key: FirestoreModelKey;
 }
+/**
+ * ArkType validator for {@link TargetModelParams} — requires a valid full model key.
+ */
 export declare const targetModelParamsType: Type<TargetModelParams>;
+/**
+ * Variant of {@link TargetModelParams} where the key is optional, allowing the server to infer it from context.
+ */
 export interface InferredTargetModelParams extends Partial<FirestoreModelKeyRef> {
     readonly key?: FirestoreModelKey;
 }
+/**
+ * ArkType validator for {@link InferredTargetModelParams}.
+ */
 export declare const inferredTargetModelParamsType: Type<InferredTargetModelParams>;
 /**
- * Simple params that implements FirestoreModelKeyRef but key is a FirestoreModelId.
+ * API parameter type that targets a specific Firestore model by its document ID only (not the full path).
+ *
+ * Used when the collection is already known from the call context.
  */
 export interface TargetModelIdParams extends FirestoreModelKeyRef {
     readonly key: FirestoreModelKey;
 }
+/**
+ * ArkType validator for {@link TargetModelIdParams} — requires a valid document ID.
+ */
 export declare const targetModelIdParamsType: Type<TargetModelIdParams>;
+/**
+ * Variant of {@link TargetModelIdParams} where the key is optional.
+ */
 export interface InferredTargetModelIdParams extends Partial<FirestoreModelKeyRef> {
     readonly key?: FirestoreModelKey;
 }
+/**
+ * ArkType validator for {@link InferredTargetModelIdParams}.
+ */
 export declare const inferredTargetModelIdParamsType: Type<InferredTargetModelIdParams>;

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

@@ -5,21 +5,88 @@ import { type FirestoreModelIdentity, type FirestoreModelKey, type FirestoreMode
 import { type FirebaseModelCollectionLoader, type FirebaseModelLoader, type InContextFirebaseModelCollectionLoader, type InContextFirebaseModelLoader } from './model/model.loader';
 import { type InContextFirebaseModelPermissionService, type FirebasePermissionContext, type FirebaseModelPermissionService, type FirebasePermissionServiceInstanceDelegate, type InModelContextFirebaseModelPermissionService, type FirebasePermissionErrorContext } from './permission';
 import { type ContextGrantedModelRolesReader } from './permission/permission.service.role';
+/**
+ * Context type required by the model service layer — combines permission and error handling contexts.
+ */
 export type FirebaseModelServiceContext = FirebasePermissionContext & FirebasePermissionErrorContext;
+/**
+ * Unified service for a single Firestore model type that combines permission checking, model loading, and collection access.
+ *
+ * Each model type in the application (e.g., Notification, StorageFile) gets its own {@link FirebaseModelService}.
+ * The service is the central point for CRUD operations that need permission-aware model access.
+ *
+ * @template C - the model context type
+ * @template T - the Firestore document data type
+ * @template D - the FirestoreDocument wrapper type
+ * @template R - the granted role type for this model
+ */
 export interface FirebaseModelService<C extends FirebaseModelServiceContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> extends FirebaseModelPermissionService<C, T, D, R>, FirebaseModelLoader<C, T, D>, FirebaseModelCollectionLoader<any, T, D> {
 }
+/**
+ * Lazy getter for a {@link FirebaseModelService}, typically used in the service factory map.
+ */
 export type FirebaseModelServiceGetter<C extends FirebaseModelServiceContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> = Getter<FirebaseModelService<C, T, D, R>>;
+/**
+ * Configuration for creating a {@link FirebaseModelService} via {@link firebaseModelService}.
+ *
+ * Provides the collection loader and the role-mapping delegate. Model loading is derived automatically
+ * from the collection loader.
+ */
 export interface FirebaseModelServiceConfig<C extends FirebaseModelServiceContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> extends Omit<FirebasePermissionServiceInstanceDelegate<C, T, D, R>, 'loadModelForKey'>, FirebaseModelCollectionLoader<C, T, D> {
 }
+/**
+ * Creates a {@link FirebaseModelService} that wires together model loading and permission evaluation.
+ *
+ * @param config - collection loader and role mapping functions
+ *
+ * @example
+ * ```ts
+ * const notificationService = firebaseModelService({
+ *   getFirestoreCollection: (context) => context.app.notification,
+ *   roleMapForModel: (output, context, model) => computeRoles(output, context)
+ * });
+ * ```
+ */
 export declare function firebaseModelService<C extends FirebaseModelServiceContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole>(config: FirebaseModelServiceConfig<C, T, D, R>): FirebaseModelService<C, T, D, R>;
+/**
+ * Cached getter that lazily creates and memoizes a {@link FirebaseModelService}.
+ */
 export type FirebaseModelServiceFactory<C extends FirebaseModelServiceContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> = Getter<FirebaseModelService<C, T, D, R>>;
+/**
+ * Creates a {@link FirebaseModelServiceFactory} that lazily instantiates and caches the service.
+ *
+ * @param config - the service configuration
+ */
 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>;
+/**
+ * A context-bound model service with permission checking, model loading, and collection access.
+ *
+ * Does not include the `forKey` method — use {@link InContextFirebaseModelService} for the full interface.
+ */
 export type LimitedInContextFirebaseModelService<C extends FirebasePermissionErrorContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> = InContextFirebaseModelPermissionService<C, T, D, R> & InContextFirebaseModelLoader<T, D> & InContextFirebaseModelCollectionLoader<T, D> & {
     forKey: (key: FirestoreModelKey) => InModelContextFirebaseModelService<C, T, D, R>;
 };
+/**
+ * Full context-bound model service that can also be called directly with a model/key to get a model-bound service.
+ *
+ * Calling `service(modelOrKey)` returns an {@link InModelContextFirebaseModelService} with role checking and assertions.
+ * Also provides `forKey(key)` for key-based lookup.
+ */
 export type InContextFirebaseModelService<C extends FirebasePermissionErrorContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> = InModelContextFirebaseModelServiceFactory<C, T, D, R> & LimitedInContextFirebaseModelService<C, T, D, R>;
+/**
+ * Factory that binds a {@link FirebaseModelService} to a specific context, producing an {@link InContextFirebaseModelService}.
+ */
 export type InContextFirebaseModelServiceFactory<C extends FirebasePermissionErrorContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> = (context: C) => InContextFirebaseModelService<C, T, D, R>;
+/**
+ * Factory that binds a context-aware model service to a specific model document or key.
+ */
 export type InModelContextFirebaseModelServiceFactory<C extends FirebasePermissionErrorContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> = (modelOrKey: D | FirestoreModelKey) => InModelContextFirebaseModelService<C, T, D, R>;
+/**
+ * A model service bound to both a context and a specific model document.
+ *
+ * Provides role-based access control via `roleReader()`, `requireRole()`, and `use()`.
+ * Can be called as a function with roles to get a {@link UsePromiseFunction} for the role reader.
+ */
 export type InModelContextFirebaseModelService<C extends FirebasePermissionErrorContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> = InModelContextFirebaseModelPermissionService<C, T, D, R> & InModelContextFirebaseModelServiceUseFunction<C, T, D, R> & InContextFirebaseModelCollectionLoader<T, D> & {
     roleReader: () => Promise<ContextGrantedModelRolesReader<C, T, D, R>>;
     requireRole: (roles: ArrayOrValue<R>, setIncludes?: SetIncludesMode) => Promise<ContextGrantedModelRolesReader<C, T, D, R>>;
@@ -27,17 +94,39 @@ export type InModelContextFirebaseModelService<C extends FirebasePermissionError
     use: UsePromiseFunction<ContextGrantedModelRolesReader<C, T, D, R>>;
 };
 export type InModelContextFirebaseModelServiceUseFunction<C extends FirebasePermissionErrorContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> = (roles: ArrayOrValue<R>, setIncludes?: SetIncludesMode) => UsePromiseFunction<ContextGrantedModelRolesReader<C, T, D, R>>;
+/**
+ * Creates an {@link InContextFirebaseModelServiceFactory} from a service getter.
+ *
+ * The returned factory, when given a context, produces a callable service that can be invoked
+ * with a model or key to perform permission-checked operations.
+ *
+ * @param factory - lazy getter for the underlying model 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>;
+/**
+ * Map of model type identifiers to their corresponding {@link FirebaseModelServiceGetter} factories.
+ *
+ * Defines the full set of model services available in the application.
+ */
 export type FirebaseModelsServiceFactory<C extends FirebaseModelServiceContext, I extends FirestoreModelIdentity = FirestoreModelIdentity> = {
     [J in FirestoreModelTypes<I>]: FirebaseModelServiceGetter<C, any>;
 };
+/**
+ * Provides access to the list of all registered model types.
+ */
 export type FirebaseModelsServiceTypesAccessor = {
     allTypes(): FirestoreModelType[];
 };
 /**
- * Function that returns a configured service corresponding with the requested function, and for that context.
+ * Multi-model service function that returns a context-bound service for any registered model type.
+ *
+ * Call with a model type key and context to get an {@link InContextFirebaseModelService} for that model.
+ * This is the top-level entry point for permission-checked model operations in server-side code.
  */
 export type FirebaseModelsService<X extends FirebaseModelsServiceFactory<C>, C extends FirebaseModelServiceContext> = (<K extends keyof X>(type: K, context: C) => X[K] extends FirebaseModelServiceGetter<C, infer T, infer D, infer R> ? InContextFirebaseModelService<C, T, D, R> : never) & FirebaseModelsServiceTypesAccessor;
+/**
+ * Extracts the union of model type keys from a {@link FirebaseModelsService}.
+ */
 export type FirebaseModelsServiceTypes<S extends FirebaseModelsService<any, any>> = S extends FirebaseModelsService<infer X, any> ? keyof X : never;
 /**
  * Creates a new FirebaseModelsService.
@@ -55,15 +144,25 @@ export type FirebaseModelsServiceTypes<S extends FirebaseModelsService<any, any>
  * @returns
  */
 export declare function firebaseModelsService<X extends FirebaseModelsServiceFactory<C, I>, C extends FirebaseModelServiceContext, I extends FirestoreModelIdentity = FirestoreModelIdentity>(services: X): FirebaseModelsService<X, C>;
+/**
+ * A context-bound multi-model service — call with a model type to get the context-bound single-model service.
+ */
 export type InContextFirebaseModelsService<Y> = FirebaseModelsServiceTypesAccessor & (Y extends FirebaseModelsService<infer X, infer C> ? <K extends keyof X>(type: K) => X[K] extends FirebaseModelServiceGetter<C, infer T, infer D, infer R> ? InContextFirebaseModelService<C, T, D, R> : never : never);
+/**
+ * Factory that creates an {@link InContextFirebaseModelsService} from a context.
+ */
 export type InContextFirebaseModelsServiceFactory<Y> = FirebaseModelsServiceTypesAccessor & (Y extends FirebaseModelsService<infer X, infer C> ? (context: C) => InContextFirebaseModelsService<Y> : never);
 /**
- * Creates a InContextFirebaseModelsServiceFactory for a particular service.
+ * Creates an {@link InContextFirebaseModelsServiceFactory} from a {@link FirebaseModelsService}.
  *
- * @param service
- * @returns
+ * The returned factory binds a context, so callers can then select individual model services by type.
+ *
+ * @param service - the multi-model service to wrap
  */
 export declare function inContextFirebaseModelsServiceFactory<X extends FirebaseModelsServiceFactory<C, I>, C extends FirebaseModelServiceContext, I extends FirestoreModelIdentity = FirestoreModelIdentity>(service: FirebaseModelsService<X, C>): InContextFirebaseModelsServiceFactory<FirebaseModelsService<X, C>>;
+/**
+ * Selection parameters for accessing a specific model by type and key (without role requirements).
+ */
 export type FirebaseModelsServiceSelection<Y extends FirebaseModelsService<any, any>, T extends FirebaseModelsServiceTypes<Y>> = Omit<UseFirebaseModelsServiceSelection<Y, T>, 'roles' | 'rolesSetIncludes'>;
 export type FirebaseModelsServiceSelectionResult<Y extends FirebaseModelsService<any, any>, T extends FirebaseModelsServiceTypes<Y>> = Y extends FirebaseModelsService<infer X, infer C> ? (T extends keyof X ? (X[T] extends FirebaseModelServiceGetter<C, infer T, infer D, infer R> ? InModelContextFirebaseModelService<C, T, D, R> : never) : never) : never;
 export type FirebaseModelsServiceSelectionResultRolesReader<Y extends FirebaseModelsService<any, any>, T extends FirebaseModelsServiceTypes<Y>> = Y extends FirebaseModelsService<infer X, infer C> ? (T extends keyof X ? (X[T] extends FirebaseModelServiceGetter<C, infer T, infer D, infer R> ? ContextGrantedModelRolesReader<C, T, D, R> : never) : never) : never;
@@ -76,6 +175,29 @@ export type UseFirebaseModelsServiceSelection<Y extends FirebaseModelsService<an
 } : never : never;
 export type UseFirebaseModelsServiceSelectionResult<Y extends FirebaseModelsService<any, any>, T extends FirebaseModelsServiceTypes<Y>> = Y extends FirebaseModelsService<infer X, infer C> ? (T extends keyof X ? (X[T] extends FirebaseModelServiceGetter<C, infer T, infer D, infer R> ? UsePromiseFunction<ContextGrantedModelRolesReader<C, T, D, R>> : never) : never) : never;
 export type UseFirebaseModelsServiceSelectionUseFunction<Y extends FirebaseModelsService<any, any>, T extends FirebaseModelsServiceTypes<Y>, O> = Y extends FirebaseModelsService<infer X, infer C> ? (T extends keyof X ? (X[T] extends FirebaseModelServiceGetter<C, infer T, infer D, infer R> ? UseAsync<ContextGrantedModelRolesReader<C, T, D, R>, O> : never) : never) : never;
+/**
+ * Selects a model-bound service instance from a multi-model service by type and key.
+ *
+ * @param service - the multi-model service
+ * @param type - the model type to select
+ * @param select - selection params including context and key
+ */
 export declare function selectFromFirebaseModelsService<Y extends FirebaseModelsService<any, any>, T extends FirebaseModelsServiceTypes<Y>>(service: Y, type: T, select: FirebaseModelsServiceSelection<Y, T>): FirebaseModelsServiceSelectionResult<Y, T>;
+/**
+ * Selects a model-bound service and returns a {@link UsePromiseFunction} that lazily evaluates roles on use.
+ *
+ * If roles are provided, uses `requireUse` to assert them. Otherwise, returns the basic `use` function.
+ *
+ * @param service - the multi-model service
+ * @param type - the model type to select
+ * @param select - selection params including context, key, and optional role requirements
+ */
 export declare function useFirebaseModelsService<Y extends FirebaseModelsService<any, any>, T extends FirebaseModelsServiceTypes<Y>>(service: Y, type: T, select: UseFirebaseModelsServiceSelection<Y, T>): UseFirebaseModelsServiceSelectionResult<Y, T>;
+/**
+ * Builds a type map from collection type to {@link FirestoreModelIdentity} for all registered models.
+ *
+ * Useful for routing incoming requests to the correct model service by collection path.
+ *
+ * @param inContextFirebaseModelsService - context-bound multi-model service
+ */
 export declare function buildFirebaseCollectionTypeModelTypeMap<Y extends FirebaseModelsService<any, any>>(inContextFirebaseModelsService: InContextFirebaseModelsService<Y>): import("..").FirestoreModelIdentityTypeMap;

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

@@ -2,9 +2,24 @@ import { type GrantedRole } from '@dereekb/model';
 import { type ArrayOrValue } from '@dereekb/util';
 import { type FirebaseTransactionContext } from '../../firestore/reference';
 import { type FirebaseContextGrantedModelRoles } from './permission';
+/**
+ * Context type for permission operations — provides optional Firestore transaction access.
+ */
 export type FirebasePermissionContext = FirebaseTransactionContext;
+/**
+ * Factory function for creating permission-denied errors, given the model roles and the required role(s).
+ */
 export type FirebasePermissionErrorContextErrorFunction = (firebaseContextGrantedModelRoles: FirebaseContextGrantedModelRoles<FirebasePermissionErrorContext, unknown>, role?: ArrayOrValue<GrantedRole>) => Error;
+/**
+ * Factory function for creating "does not exist" errors when a model document is not found.
+ */
 export type FirebaseDoesNotExistErrorContextErrorFunction = (firebaseContextGrantedModelRoles: FirebaseContextGrantedModelRoles<FirebasePermissionErrorContext, unknown>) => Error;
+/**
+ * Context that provides custom error factories for permission and existence checks.
+ *
+ * When these factories are not provided, the system falls back to generic error messages.
+ * Applications typically supply these to produce HTTP-appropriate errors (e.g., 403, 404).
+ */
 export interface FirebasePermissionErrorContext {
     makePermissionError?: FirebasePermissionErrorContextErrorFunction;
     makeDoesNotExistError?: FirebasePermissionErrorContextErrorFunction;