@dereekb/firebase 13.2.2 → 13.3.0

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

@@ -2,10 +2,26 @@ import { type Maybe } from '@dereekb/util';
 import { type GrantedRole, type ContextGrantedModelRoles } from '@dereekb/model';
 import { type DocumentSnapshot, type FirestoreDocument } from '../../firestore';
 import { type FirebasePermissionErrorContext } from './permission.context';
+/**
+ * Snapshot of a Firestore model as loaded by the permission service for role evaluation.
+ *
+ * Contains the document wrapper, its snapshot, existence status, and deserialized data.
+ * 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. */
     readonly document: D;
+    /** The raw Firestore document snapshot. */
     readonly snapshot: DocumentSnapshot<T>;
+    /** Whether the document exists in Firestore. */
     readonly exists: boolean;
+    /** The deserialized document data, or `undefined` if it doesn't exist. */
     readonly data: Maybe<T>;
 }
+/**
+ * The result of evaluating permissions for a Firebase model — contains the model data,
+ * context, and the computed role map.
+ *
+ * Used by {@link ContextGrantedModelRolesReader} to make role-based access control decisions.
+ */
 export type FirebaseContextGrantedModelRoles<C extends FirebasePermissionErrorContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> = ContextGrantedModelRoles<FirebasePermissionServiceModel<T, D>, C, R>;

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

@@ -4,12 +4,24 @@ import { type Maybe, type PromiseOrValue } from '@dereekb/util';
 import { type FirebaseModelLoader, type InModelContextFirebaseModelLoader } from '../model/model.loader';
 import { type FirebaseModelContext } from '../context';
 import { type FirebasePermissionServiceModel } from './permission';
+/**
+ * Permission service interface for a single Firebase model type, specialized from {@link ModelPermissionService}.
+ */
 export type FirebaseModelPermissionService<C extends FirebaseModelContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends string = string> = ModelPermissionService<C, D, R, FirebasePermissionServiceModel<T, D>>;
+/**
+ * Delegate that provides model loading and role mapping for a {@link FirebaseModelPermissionServiceInstance}.
+ *
+ * The `roleMapForModel` function is the core of the permission system — it examines the loaded model data
+ * and context to produce a {@link GrantedRoleMap} of what the current user can do.
+ */
 export interface FirebasePermissionServiceInstanceDelegate<C extends FirebaseModelContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends string = string> extends FirebaseModelLoader<C, T, D> {
     roleMapForModel(output: FirebasePermissionServiceModel<T, D>, context: C, model: D): PromiseOrValue<GrantedRoleMap<R>>;
 }
 /**
- * Abstract AbstractModelPermissionService implementation for FirebaseModelsPermissionService.
+ * Concrete permission service implementation for Firebase models.
+ *
+ * Loads the document snapshot, checks existence, and delegates role computation to the configured delegate.
+ * Used internally by {@link firebaseModelPermissionService}.
  */
 export declare class FirebaseModelPermissionServiceInstance<C extends FirebaseModelContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends string = string> extends AbstractModelPermissionService<C, D, R, FirebasePermissionServiceModel<T, D>> implements FirebaseModelPermissionService<C, T, D, R> {
     private readonly _delegate;
@@ -19,6 +31,17 @@ export declare class FirebaseModelPermissionServiceInstance<C extends FirebaseMo
     protected outputForModel(document: D): Promise<Maybe<FirebasePermissionServiceModel<T, D>>>;
     protected isUsableOutputForRoles(output: FirebasePermissionServiceModel<T, D>): boolean;
 }
+/**
+ * Creates a {@link FirebaseModelPermissionServiceInstance} from a delegate.
+ *
+ * @param delegate - provides model loading and role computation
+ */
 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>;
+/**
+ * Context-bound permission service — evaluates roles for any model by key or document.
+ */
 export type InContextFirebaseModelPermissionService<C, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends string = string> = InContextModelPermissionService<C, D, R, FirebasePermissionServiceModel<T, D>>;
+/**
+ * Fully bound permission service for a specific model and context — provides the computed role map.
+ */
 export type InModelContextFirebaseModelPermissionService<C, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends string = string> = InModelContextModelPermissionService<C, D, R, FirebasePermissionServiceModel<T, D>> & InModelContextFirebaseModelLoader<T, D>;

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

@@ -4,42 +4,67 @@ import { type AsyncDecisionFunction, type AuthRole, type Getter, type GetterOrVa
 import { type FirebaseModelContext } from '../context';
 import { type UserRelated } from '../../../model/user';
 /**
- * DecisionFunction for a FirebaseModelContext that checks if the current user is an admin.
+ * Decision function that checks if the current user is an admin in the given context.
  *
- * @param context
- * @returns
+ * Returns `false` if no auth is present.
  */
 export declare const isAdminInFirebaseModelContext: AsyncDecisionFunction<FirebaseModelContext>;
 /**
- * Convenience function that checks the input context if the user is an admin or not and grants pre-set admin roles if they are.
+ * Creates a {@link GrantRolesIfFunction} that grants the specified roles when the user is an admin.
  *
- * @param context
- * @param rolesToGrantToAdmin
- * @param otherwise
- * @returns
+ * @param rolesToGrantToAdmin - roles to grant if the user is an admin
+ *
+ * @example
+ * ```ts
+ * const grantIfAdmin = grantModelRolesIfAdminFunction(fullAccessRoleMap);
+ * const roles = await grantIfAdmin(context);
+ * ```
  */
 export declare function grantModelRolesIfAdminFunction<R extends string = string>(rolesToGrantToAdmin: GetterOrValue<GrantedRoleMap<R>>): GrantRolesIfFunction<FirebaseModelContext, R>;
 /**
- * Convenience function that checks the input context if the user is an admin or grants all roles.
+ * Pre-built grant function that gives full access (all roles) when the user is an admin.
  */
 export declare const grantFullAccessIfAdmin: GeneralGrantRolesIfFunction<FirebaseModelContext>;
+/**
+ * Convenience function that evaluates admin status and grants roles in a single call.
+ *
+ * @param context - the model context to check
+ * @param rolesToGrantToAdmin - roles to grant if admin
+ * @param otherwise - fallback role computation when not admin
+ */
 export declare function grantModelRolesIfAdmin<R extends string = string>(context: FirebaseModelContext, rolesToGrantToAdmin: GetterOrValue<GrantedRoleMap<R>>, otherwise?: GrantRolesOtherwiseFunction<R>): PromiseOrValue<GrantedRoleMap<R>>;
 /**
- * Convenience function that checks the input context if the user is an admin or not and grants pre-set admin roles if they are.
+ * Creates a {@link GrantRolesIfFunction} that grants roles when the user has all specified auth roles in their token.
  *
- * @param context
- * @param rolesToGrantToAdmin
- * @param otherwise
- * @returns
+ * @param authRoles - the auth roles the user must have
+ * @param rolesToGrantToAdmin - the model roles to grant if the auth roles are present
  */
 export declare function grantModelRolesIfHasAuthRolesFunction<R extends string = string>(authRoles: AuthRole[], rolesToGrantToAdmin: GetterOrValue<GrantedRoleMap<R>>): GrantRolesIfFunction<FirebaseModelContext, R>;
+/**
+ * Factory function type for auth-role-based role granting.
+ */
 export type GrantModelRolesIfHasAuthRolesFactory = <R extends string = string>(context: FirebaseModelContext, rolesToGrantToAdmin: GetterOrValue<GrantedRoleMap<R>>, otherwise?: GrantRolesOtherwiseFunction<R>) => PromiseOrValue<GrantedRoleMap<R>>;
+/**
+ * Creates a reusable factory pre-configured with specific auth roles to check for.
+ *
+ * @param authRoles - the auth roles the user must have
+ */
 export declare function grantModelRolesIfHasAuthRolesFactory(authRoles: IterableOrValue<AuthRole>): GrantModelRolesIfHasAuthRolesFactory;
+/**
+ * Context for evaluating ownership of a {@link UserRelated} model. Accepts either the model data directly
+ * or a document reference that will be loaded to check ownership.
+ */
 export type UserRelatedModelFirebaseModelContext<T extends UserRelated = UserRelated> = UserRelatedModelFirebaseModelContextModelInput<T> | UserRelatedModelFirebaseModelContextDocumentInput<T>;
+/**
+ * Input variant that provides the model data directly (avoids an extra Firestore read).
+ */
 export type UserRelatedModelFirebaseModelContextModelInput<T extends UserRelated = UserRelated> = {
     model: T;
     context: FirebaseModelContext;
 };
+/**
+ * Input variant that provides a document reference — the model data will be loaded to check ownership.
+ */
 export type UserRelatedModelFirebaseModelContextDocumentInput<T extends UserRelated = UserRelated> = {
     document: FirestoreDocument<T>;
     context: FirebaseModelContext;
@@ -52,12 +77,15 @@ export type UserRelatedModelFirebaseModelContextDocumentInput<T extends UserRela
  */
 export declare const isOwnerOfUserRelatedModelInFirebaseModelContext: AsyncDecisionFunction<UserRelatedModelFirebaseModelContext<UserRelated>>;
 /**
- * Creates a GrantRolesIfFunction that grants roles if the user is related to the model by uid.
+ * Creates a {@link GrantRolesIfFunction} that grants roles when the authenticated user's UID matches the model's `uid` field.
  *
- * @param context
- * @param rolesToGrant
- * @param otherwise
- * @returns
+ * @param rolesToGrant - the roles to grant if the user owns the model
+ *
+ * @example
+ * ```ts
+ * const grantIfOwner = grantModelRolesIfAuthUserRelatedModelFunction<User>(fullAccessRoleMap);
+ * const roles = await grantIfOwner({ model: userData, context });
+ * ```
  */
 export declare function grantModelRolesIfAuthUserRelatedModelFunction<T extends UserRelated, R extends string = string>(rolesToGrant: GetterOrValue<GrantedRoleMap<R>>): GrantRolesIfFunction<UserRelatedModelFirebaseModelContext<T>, R>;
 /**
@@ -65,16 +93,20 @@ export declare function grantModelRolesIfAuthUserRelatedModelFunction<T extends
  */
 export declare const grantFullAccessIfAuthUserRelated: GeneralGrantRolesIfFunction<UserRelatedModelFirebaseModelContext<UserRelated>>;
 /**
- * Grants the configured roles if the decision is made about the context. Otherwise, returns a NoAccessRoleMap.
+ * Grants the configured roles if the decision function returns `true`. Otherwise returns a no-access role map.
+ *
+ * Unlike {@link GrantRolesIfFunction}, this does not accept an `otherwise` fallback.
  */
 export type GrantRolesOnlyIfFunction<C, R extends string = string> = (context: C) => Promise<GrantedRoleMap<R>>;
+/**
+ * Generic variant of {@link GrantRolesOnlyIfFunction} that works with any role type.
+ */
 export type GeneralGrantRolesOnlyIfFunction<C> = <R extends string = string>(context: C) => Promise<GrantedRoleMap<R>>;
 /**
- * Creates a GrantRolesOnlyIfFunction
+ * Creates a {@link GrantRolesOnlyIfFunction} with no fallback — returns no-access if the condition is false.
  *
- * @param grantIf
- * @param grantedRoles
- * @returns
+ * @param grantIf - decision function to evaluate
+ * @param grantedRoles - roles to grant if the decision is `true`
  */
 export declare function grantModelRolesOnlyIfFunction<C, R extends string = string>(grantIf: AsyncDecisionFunction<C>, grantedRoles: GetterOrValue<GrantedRoleMap<R>>): GrantRolesOnlyIfFunction<C, R>;
 /**
@@ -93,10 +125,22 @@ export type GrantedRolesOtherwiseFunctionResult<R extends string = string> = Pro
  */
 export type GrantRolesOtherwiseFunction<R extends string = string> = Getter<GrantedRolesOtherwiseFunctionResult<R>>;
 /**
- * Creates a GrantRolesIfFunction.
+ * Creates a {@link GrantRolesIfFunction} that evaluates a decision function and grants roles if `true`,
+ * or falls back to the `otherwise` function (defaulting to no-access).
  *
- * @param grantIf
- * @param grantedRoles
- * @returns
+ * This is the core building block for composing permission logic.
+ *
+ * @param grantIf - async decision function to evaluate
+ * @param grantedRoles - roles to grant if the decision is `true`
+ * @throws {Error} When `grantIf` is not provided.
+ *
+ * @example
+ * ```ts
+ * const grantIfOwner = grantModelRolesIfFunction(
+ *   isOwnerOfUserRelatedModelInFirebaseModelContext,
+ *   fullAccessRoleMap
+ * );
+ * const roles = await grantIfOwner(context, () => noAccessRoleMap());
+ * ```
  */
 export declare function grantModelRolesIfFunction<C, R extends string = string>(grantIf: AsyncDecisionFunction<C>, grantedRoles: GetterOrValue<GrantedRoleMap<R>>): GrantRolesIfFunction<C, R>;

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

@@ -4,6 +4,15 @@ import { type InModelContextFirebaseModelPermissionService } from './permission.
 import { type SetIncludesMode, type ArrayOrValue } from '@dereekb/util';
 import { type FirebasePermissionErrorContext } from './permission.context';
 import { type FirebaseContextGrantedModelRoles, type FirebasePermissionServiceModel } from './permission';
+/**
+ * Reads and asserts granted roles for a specific model in a given context.
+ *
+ * Combines the computed {@link GrantedRoleMap} with the model's data and provides methods to
+ * check and assert roles. Used as the primary interface for permission-guarded operations.
+ *
+ * Chainable assertion methods (`assertExists`, `assertHasRole`, `assertHasRoles`) return `this`
+ * for fluent usage.
+ */
 export interface ContextGrantedModelRolesReader<C extends FirebasePermissionErrorContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> extends GrantedRoleMapReader<R>, FirebasePermissionServiceModel<T, D> {
     readonly roleMap: GrantedRoleMap<R>;
     readonly contextGrantedModelRoles: FirebaseContextGrantedModelRoles<C, T, D, R>;
@@ -13,6 +22,12 @@ export interface ContextGrantedModelRolesReader<C extends FirebasePermissionErro
     assertContainsRoles(setIncludes: SetIncludesMode, roles: ArrayOrValue<R>): this;
     throwPermissionError(role?: R): never;
 }
+/**
+ * Default implementation of {@link ContextGrantedModelRolesReader}.
+ *
+ * Wraps a {@link FirebaseContextGrantedModelRoles} result and delegates role reading
+ * to a {@link GrantedRoleMapReader}. Throws context-specific errors via the permission error context.
+ */
 export declare class ContextGrantedModelRolesReaderInstance<C extends FirebasePermissionErrorContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> implements ContextGrantedModelRolesReader<C, T, D, R> {
     private readonly _contextGrantedModelRoles;
     private readonly _roleReader;

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

@@ -1,28 +1,45 @@
 import { type SlashPath, type SlashPathFolder } from '@dereekb/util';
 import { type ReadFirestoreModelKeyInput } from '../../firestore/collection/collection';
+/**
+ * Base storage path prefix for all model-related files.
+ *
+ * All model storage files are nested under `/model/` in the storage bucket.
+ */
 export declare const BASE_MODEL_STORAGE_FILE_PATH: SlashPathFolder;
 /**
- * Shared and configured slashPathFactory configuration for the model storage file path.
+ * Pre-configured {@link slashPathFactory} that produces absolute paths under {@link BASE_MODEL_STORAGE_FILE_PATH}.
  */
 export declare const MODEL_STORAGE_FILE_SLASH_PATH_FACTORY: import("@dereekb/util").SlashPathFactory;
+/**
+ * Configuration for {@link modelStorageSlashPathFactory}.
+ */
 export interface ModelStorageSlashPathFactoryConfig {
     /**
-     * Additional base path to provide.
+     * Additional base path segment appended after `/model/`.
      *
-     * This value is merged with the BASE_MODEL_STORAGE_FILE_PATH (/model/) base path configured for all ModelStorageSlashPathFactory values
+     * For example, `'uploads'` produces paths like `/model/uploads/<modelKey>/...`.
      */
     readonly basePath?: string;
 }
 /**
- * Factory for SlashPath values using input ReadFirestoreModelKeyInput values.
+ * Factory that generates storage {@link SlashPath} values for Firestore model documents.
  *
- * Can optionally specify an additional path to append.
+ * Takes a model document or key as input and returns a storage path rooted under `/model/<modelKey>/`.
+ * An optional additional path can be appended.
  */
 export type ModelStorageSlashPathFactory<T extends object = object> = (input: ReadFirestoreModelKeyInput<T>, path?: SlashPath) => SlashPath;
 /**
- * Creates a ModelStorageSlashPathFactory.
+ * Creates a {@link ModelStorageSlashPathFactory} that maps Firestore model keys to storage paths.
+ *
+ * The generated paths follow the convention `/model/[basePath/]<modelKey>/[path]`.
+ *
+ * @param config - optional base path to nest under
  *
- * @param config
- * @returns
+ * @example
+ * ```ts
+ * const pathFactory = modelStorageSlashPathFactory({ basePath: 'avatars' });
+ * const path = pathFactory(userDocument, 'profile.png');
+ * // path === '/model/avatars/users/abc123/profile.png'
+ * ```
  */
 export declare function modelStorageSlashPathFactory<T extends object = object>(config?: ModelStorageSlashPathFactoryConfig): ModelStorageSlashPathFactory<T>;

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

@@ -3,18 +3,25 @@ import { type FirebaseStorageDrivers } from './driver/driver';
 import { type StorageBucketId } from './storage';
 import { type FirebaseStorage } from './types';
 /**
- * A @dereekb/firebase FirebaseStorageContext. Wraps the main FirebaseStorage context and the drivers, as well as utility/convenience functions.
+ * Central context for Firebase Cloud Storage operations within `@dereekb/firebase`.
+ *
+ * Wraps the underlying {@link FirebaseStorage} instance and its {@link FirebaseStorageDrivers},
+ * while exposing convenience methods for file/folder access via {@link FirebaseStorageAccessor}.
+ *
+ * Created by {@link firebaseStorageContextFactory}.
  */
 export interface FirebaseStorageContext<F extends FirebaseStorage = FirebaseStorage> extends FirebaseStorageAccessor {
     readonly storage: F;
     readonly drivers: FirebaseStorageDrivers;
 }
 /**
- * Factory function for generating a FirebaseStorageContext given the input FirebaseStorage.
+ * Factory that creates a {@link FirebaseStorageContext} from a {@link FirebaseStorage} instance and optional configuration.
+ *
+ * Produced by {@link firebaseStorageContextFactory}.
  */
 export type FirebaseStorageContextFactory<F extends FirebaseStorage = FirebaseStorage> = (firebaseStorage: F, config?: FirebaseStorageContextFactoryConfig) => FirebaseStorageContext;
 /**
- * firebaseStorageContextFactory() configuration
+ * Configuration for {@link firebaseStorageContextFactory}.
  */
 export interface FirebaseStorageContextFactoryConfig {
     /**
@@ -27,9 +34,19 @@ export interface FirebaseStorageContextFactoryConfig {
     readonly forceBucket?: boolean;
 }
 /**
- * Creates a new FirebaseStorageContextFactory given the input FirebaseStorageDrivers.
+ * Creates a {@link FirebaseStorageContextFactory} that produces storage contexts using the given drivers.
+ *
+ * The returned factory resolves a default bucket (from driver, config, or error) and builds
+ * a {@link StoragePathFactory} to normalize all path inputs.
+ *
+ * @param drivers - the storage driver implementations to use
+ * @throws {Error} When a default bucket ID cannot be resolved from the driver or config.
  *
- * @param drivers
- * @returns
+ * @example
+ * ```ts
+ * const factory = firebaseStorageContextFactory(myDrivers);
+ * const storageContext = factory(firebaseStorage, { defaultBucketId: 'my-bucket' });
+ * const file = storageContext.file('uploads/doc.pdf');
+ * ```
  */
 export declare function firebaseStorageContextFactory<F extends FirebaseStorage = FirebaseStorage>(drivers: FirebaseStorageDrivers): FirebaseStorageContextFactory<F>;

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

@@ -3,7 +3,10 @@ import { type ConfigurableStorageMetadata, type StorageAccessControlObject, type
 import { type ArrayOrValue, type Maybe } from '@dereekb/util';
 import { type Readable } from 'stream';
 /**
- * Used for accessing files and folders in the storage.
+ * Core interface for accessing files and folders in Firebase Cloud Storage.
+ *
+ * Provides a bucket-aware entry point to obtain {@link FirebaseStorageAccessorFile} and
+ * {@link FirebaseStorageAccessorFolder} handles. Typically obtained from a {@link FirebaseStorageContext}.
  */
 export interface FirebaseStorageAccessor {
     defaultBucket: () => StorageBucketId;
@@ -17,7 +20,10 @@ export interface FirebaseStorageAccessorRef {
     readonly storageAccessor: FirebaseStorageAccessor;
 }
 /**
- * Generic interface for accessing data from a file at the given path.
+ * Handle for a single file in Firebase Cloud Storage, providing read, write, and metadata operations.
+ *
+ * Methods marked "optional" are only available on certain platforms (client vs server).
+ * The `R` type parameter exposes the underlying SDK reference type for advanced usage.
  */
 export interface FirebaseStorageAccessorFile<R = unknown> extends StoragePathRef {
     /**
@@ -222,7 +228,9 @@ export interface StorageListFilesResult<R = unknown> {
     nextPageToken(): Maybe<StorageListFilesPageToken>;
 }
 /**
- * Generic interface for accessing "folder" information at the given path.
+ * Handle for a folder (prefix) in Firebase Cloud Storage, providing listing operations.
+ *
+ * Folders in Cloud Storage are virtual — they exist only as shared path prefixes of files.
  */
 export interface FirebaseStorageAccessorFolder<R = unknown> extends StoragePathRef {
     readonly reference: R;
@@ -241,7 +249,10 @@ export type FirebaseStorageAccessorDriverDefaultBucketFunction = (storage: Fireb
 export type FirebaseStorageAccessorDriverFileFunction<R = unknown> = (storage: FirebaseStorage, path: StoragePath) => FirebaseStorageAccessorFile<R>;
 export type FirebaseStorageAccessorDriverFolderFunction<R = unknown> = (storage: FirebaseStorage, path: StoragePath) => FirebaseStorageAccessorFolder<R>;
 /**
- * A driver to use for storage functionality.
+ * Low-level driver that creates file and folder accessors from a {@link FirebaseStorage} instance.
+ *
+ * Implementations exist for the Firebase client SDK and the Google Cloud server SDK.
+ * Used internally by {@link FirebaseStorageContext} — consumers typically don't interact with this directly.
  */
 export interface FirebaseStorageAccessorDriver {
     /**

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

@@ -1,29 +1,46 @@
 import { type FirebaseStorageAccessorFolder, type StorageListFilesOptions, type StorageListFilesResult } from './accessor';
 import { type FetchPageFactory, type IterateFetchPagesByEachItemConfig, type IterateFetchPagesConfigWithFactoryAndInput } from '@dereekb/util/fetch';
 /**
- * Configuration for iterateStorageListFilesFactory()
+ * Configuration for {@link iterateStorageListFilesFactory}. Excludes `pageToken` since it is managed internally during iteration.
  */
 export type IterateStorageListFilesFactoryConfig = Omit<StorageListFilesOptions, 'pageToken'>;
+/**
+ * Input for a single page fetch during storage file iteration.
+ */
 export interface IterateStorageListFilesInput extends StorageListFilesOptions {
     /**
-     * The folder to iterate in.
+     * The folder to iterate files within.
      */
     readonly folder: FirebaseStorageAccessorFolder;
 }
 /**
- * A FetchPageFactory that iterates through the files in a storage folder.
+ * A {@link FetchPageFactory} specialized for paginating through files in a storage folder.
+ *
+ * Produced by {@link iterateStorageListFilesFactory}.
  */
 export type IterateStorageListFilesFactory = FetchPageFactory<IterateStorageListFilesInput, StorageListFilesResult>;
 /**
- * Creates a new IterateStorageListFilesFactory.
+ * Creates an {@link IterateStorageListFilesFactory} for paginated iteration over files in a storage folder.
  *
- * @param config
- * @returns
+ * Wraps the folder's `list()` API with cursor-based pagination via {@link fetchPageFactory}.
+ *
+ * @param config - default listing options (e.g., maxResults)
+ *
+ * @example
+ * ```ts
+ * const factory = iterateStorageListFilesFactory({ maxResults: 100 });
+ * ```
  */
 export declare function iterateStorageListFilesFactory(config: IterateStorageListFilesFactoryConfig): IterateStorageListFilesFactory;
+/**
+ * Configuration for {@link iterateStorageListFilesByEachFile}, extending the per-item iteration config
+ * with folder and listing options.
+ */
 export type IterateStorageListFilesByEachFileConfig<T, R> = Omit<IterateFetchPagesByEachItemConfig<IterateStorageListFilesInput, StorageListFilesResult, T, R>, 'fetchPageFactory'> & Pick<IterateStorageListFilesInput, 'folder' | 'includeNestedResults' | 'pageToken'>;
 /**
- * Convenience function for calling iterateFetchPagesByEachItem() for a storage folder.
+ * 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.
  */
 export declare function iterateStorageListFilesByEachFile<T, R>(input: IterateStorageListFilesByEachFileConfig<T, R>): Promise<{
     totalItemsLoaded: number;
@@ -31,8 +48,14 @@ export declare function iterateStorageListFilesByEachFile<T, R>(input: IterateSt
     totalPages: number;
     totalPagesLimitReached: boolean;
 }>;
+/**
+ * Configuration for {@link iterateStorageListFiles}, extending the page-level iteration config
+ * with folder and listing options.
+ */
 export type IterateStorageListFilesConfig<R> = Omit<IterateFetchPagesConfigWithFactoryAndInput<IterateStorageListFilesInput, StorageListFilesResult, R>, 'fetchPageFactory'> & Pick<IterateStorageListFilesInput, 'folder' | 'includeNestedResults' | 'pageToken'>;
 /**
- * Convenience function for calling iterateFetchPages() for a storage folder.
+ * 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.
  */
 export declare function iterateStorageListFiles<R>(input: IterateStorageListFilesConfig<R>): Promise<import("@dereekb/util/fetch").IterateFetchPagesResult>;

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

@@ -2,13 +2,20 @@ import { type Readable } from 'stream';
 import { type StorageUploadOptions } from '../types';
 import { type FirebaseStorageAccessorFile } from './accessor';
 /**
- * Uploads a file using a Readable, using the uploadStream() method on the FirebaseStorageAccessorFile.
+ * Uploads data to a storage file by piping a readable stream into the file's writable upload stream.
  *
- * If uploadStream is not supported, a StorageFileUploadStreamUnsupportedError will be thrown.
+ * This is a server-side convenience — most client implementations don't support `uploadStream()`.
  *
- * @param file The file to upload to.
- * @param readableStream The stream to upload.
- * @param options The upload options.
- * @returns A promise that resolves when the upload is complete.
+ * @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.)
+ * @throws {StorageFileUploadStreamUnsupportedError} When the file accessor does not support stream uploads.
+ *
+ * @example
+ * ```ts
+ * const file = storageContext.file('data/export.csv');
+ * const readable = fs.createReadStream('/tmp/export.csv');
+ * await uploadFileWithStream(file, readable, { contentType: 'text/csv' });
+ * ```
  */
 export declare function uploadFileWithStream<R = unknown>(file: FirebaseStorageAccessorFile<R>, readableStream: Pick<Readable, 'pipe'>, options?: StorageUploadOptions): Promise<void>;

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

@@ -1,8 +1,17 @@
 import { type FirebaseStorageAccessorDriverRef } from './accessor';
+/**
+ * Unique identifier string for a storage driver implementation.
+ */
 export type FirebaseStorageDriverIdentifier = string;
+/**
+ * Indicates whether the driver targets production Firebase or a test/emulator environment.
+ */
 export type FirebaseStorageDriverType = 'production' | 'testing';
 /**
- * Implements all FirebaseStorage related driver reference interfaces.
+ * Aggregates all storage driver references needed by {@link FirebaseStorageContext}.
+ *
+ * The driver abstraction allows swapping between production (Firebase/Google Cloud) and testing
+ * (in-memory or emulator) implementations without changing consumer code.
  */
 export interface FirebaseStorageDrivers extends FirebaseStorageAccessorDriverRef {
     readonly storageDriverIdentifier?: FirebaseStorageDriverIdentifier;

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

@@ -1,7 +1,23 @@
 import { type StorageDataStringType, type StorageUploadOptions } from '../types';
 import { BaseError } from 'make-error';
+/**
+ * Extracts and asserts that a `stringFormat` is present in the upload options.
+ *
+ * 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
+ * @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.
+ */
 export declare function noStringFormatInStorageUploadOptionsError(): Error;
+/**
+ * Thrown when attempting to use `uploadStream()` on a file accessor that does not support it.
+ *
+ * Stream uploads are typically only available on server-side (Google Cloud Storage) implementations.
+ */
 export declare class StorageFileUploadStreamUnsupportedError extends BaseError {
     constructor();
 }

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

@@ -1,5 +1,14 @@
 import { type Maybe } from '@dereekb/util';
 import { type StorageListFilesPageToken, type FirebaseStorageAccessorFile, type FirebaseStorageAccessorFolder, type StorageListFilesOptions, type StorageListFilesResult, type StorageListItemResult } from './accessor';
+/**
+ * Delegate that adapts platform-specific list results into the generic {@link StorageListFilesResult} interface.
+ *
+ * Implementations extract items, pagination tokens, and convert raw results into typed file/folder accessors.
+ * Used by {@link storageListFilesResultFactory} to create the normalized result objects.
+ *
+ * @template S - the storage instance type (client or server SDK)
+ * @template R - the raw list result type from the underlying SDK
+ */
 export interface StorageListFilesResultFactoryDelegate<S, R> {
     hasItems(result: R): boolean;
     hasNext(result: R): boolean;
@@ -10,6 +19,27 @@ export interface StorageListFilesResultFactoryDelegate<S, R> {
     filesFromResult(result: R, folder: FirebaseStorageAccessorFolder): StorageListItemResult[];
     foldersFromResult(result: R, folder: FirebaseStorageAccessorFolder): StorageListItemResult[];
 }
+/**
+ * Factory function that transforms a raw SDK list result into a normalized {@link StorageListFilesResult}.
+ */
 export type StorageListFilesResultFactory<S, R> = (storage: S, folder: FirebaseStorageAccessorFolder, options: StorageListFilesOptions | undefined, result: R) => StorageListFilesResult;
+/**
+ * Creates a {@link StorageListFilesResultFactory} from a platform-specific delegate.
+ *
+ * The returned factory lazily computes file and folder arrays (via {@link cachedGetter}) and
+ * provides cursor-based pagination through the `next()` method.
+ *
+ * @param delegate - platform-specific implementation for extracting results
+ *
+ * @example
+ * ```ts
+ * const factory = storageListFilesResultFactory(myDelegate);
+ * const result = factory(storage, folder, { maxResults: 50 }, rawSdkResult);
+ * const files = result.files();
+ * ```
+ */
 export declare function storageListFilesResultFactory<S, R>(delegate: StorageListFilesResultFactoryDelegate<S, R>): StorageListFilesResultFactory<S, R>;
+/**
+ * Creates an error thrown when `next()` is called on a list result that has no more pages.
+ */
 export declare function storageListFilesResultHasNoNextError(): Error;