@dereekb/firebase 13.2.2 → 13.3.1

package/src/lib/model/system/system.d.ts

@@ -4,10 +4,33 @@ import { type FirestoreCollection } from '../../common/firestore/collection/coll
 import { type FirestoreContext } from '../../common/firestore/context';
 import { type CollectionReference } from '../../common/firestore/types';
 import { type ModelFieldMapFunctionsConfig } from '@dereekb/util';
+/**
+ * @module system
+ *
+ * Defines the SystemState Firestore model for storing system-wide singleton state and settings.
+ *
+ * Each {@link SystemState} document is identified by a {@link SystemStateTypeIdentifier} and acts
+ * as a singleton for that type — storing arbitrary key-value data about the state of a system
+ * subcomponent (e.g., last migration timestamp, feature flags, processing checkpoints).
+ *
+ * Supports per-type data conversion via the `converterFactory` pattern in
+ * {@link systemStateFirestoreCollection}.
+ */
+/**
+ * Abstract base providing access to the SystemState Firestore collection.
+ *
+ * Implement this in your app module to wire up dependency injection.
+ */
 export declare abstract class SystemStateFirestoreCollections {
     abstract readonly systemStateCollection: SystemStateFirestoreCollection;
 }
+/**
+ * Union of all SystemState-related model identity types.
+ */
 export type SystemStateTypes = typeof systemStateIdentity;
+/**
+ * Model identity for the SystemState collection (collection name: `systemState`, prefix: `sys`).
+ */
 export declare const systemStateIdentity: import("../..").RootFirestoreModelIdentity<"systemState", "sys">;
 /**
  * Used to identify a SystemStateId.
@@ -22,28 +45,81 @@ export type SystemStateId = SystemStateTypeIdentifier;
  */
 export type SystemStateStoredData = Record<string, any>;
 /**
- * A collection used for recording the current state of system subcomponents. System states for a given identifier are treated as a system-wide singleton/state/setting.
+ * A singleton Firestore document storing the current state of a system subcomponent.
+ *
+ * Each document is identified by a {@link SystemStateTypeIdentifier} and stores arbitrary
+ * key-value data. Used for tracking migration progress, feature flags, processing checkpoints,
+ * or any system-wide state that needs persistence.
  *
- * For example, a SystemState with a specific SystemStateId may be relied on for information about the previous update, etc.
+ * @template T - shape of the stored data record
  */
 export interface SystemState<T extends SystemStateStoredData = SystemStateStoredData> {
     data: T;
 }
+/**
+ * Permission roles for SystemState operations. Restricted to system administrators.
+ */
 export type SystemStateRoles = GrantedSysAdminRole;
 /**
- * Refers to a singleton SystemState based on this model's identifier.
+ * Firestore document wrapper for a {@link SystemState} singleton.
+ *
+ * The document ID serves as the {@link SystemStateTypeIdentifier}, making each
+ * SystemState a singleton keyed by its type.
+ *
+ * @template T - shape of the stored data record
  */
 export declare class SystemStateDocument<T extends SystemStateStoredData = SystemStateStoredData> extends AbstractFirestoreDocument<SystemState<T>, SystemStateDocument<T>, typeof systemStateIdentity> {
     get modelIdentity(): import("../..").RootFirestoreModelIdentity<"systemState", "sys">;
 }
+/**
+ * Default snapshot converter for {@link SystemState} documents.
+ *
+ * Uses pass-through conversion for the `data` field. Per-type converters can be
+ * supplied via the `converterFactory` in {@link systemStateFirestoreCollection}.
+ */
 export declare const systemStateConverter: import("../..").SnapshotConverterFunctions<SystemState<SystemStateStoredData>, Partial<import("@dereekb/util").ReplaceType<SystemState<SystemStateStoredData>, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Returns the raw Firestore CollectionReference for the SystemState collection.
+ *
+ * @example
+ * ```ts
+ * const colRef = systemStateCollectionReference(firestoreContext);
+ * ```
+ */
 export declare function systemStateCollectionReference(context: FirestoreContext): CollectionReference<SystemState>;
 export type SystemStateFirestoreCollection<T extends SystemStateStoredData = SystemStateStoredData> = FirestoreCollection<SystemState<T>, SystemStateDocument<T>>;
 /**
- * A ModelFieldMapFunctionsConfig used for data conversion.
+ * Field conversion config for a specific SystemState data type.
+ *
+ * Maps the typed `data` field to/from Firestore using {@link ModelFieldMapFunctionsConfig}.
+ *
+ * @template T - shape of the stored data
  */
 export type SystemStateStoredDataFieldConverterConfig<T extends SystemStateStoredData = SystemStateStoredData> = ModelFieldMapFunctionsConfig<T, any>;
+/**
+ * Map of {@link SystemStateTypeIdentifier} to their data field converters.
+ *
+ * Each entry defines how a specific SystemState type's `data` field is serialized/deserialized.
+ */
 export type SystemStateStoredDataConverterMap = {
     [key: string]: SystemStateStoredDataFieldConverterConfig<any>;
 };
+/**
+ * Creates a {@link SystemStateFirestoreCollection} with per-type data converters.
+ *
+ * The `converters` map is used via a `converterFactory` that selects the appropriate
+ * converter based on the document ID (which is the {@link SystemStateTypeIdentifier}).
+ * Documents with no matching converter use the default pass-through converter.
+ *
+ * @param firestoreContext - the Firestore context
+ * @param converters - map of type identifiers to their data field converters
+ *
+ * @example
+ * ```ts
+ * const collection = systemStateFirestoreCollection(firestoreContext, {
+ *   'migration_v2': { fields: { lastRun: firestoreDate() } }
+ * });
+ * const doc = collection.documentAccessor().loadDocumentForId('migration_v2');
+ * ```
+ */
 export declare function systemStateFirestoreCollection(firestoreContext: FirestoreContext, converters: SystemStateStoredDataConverterMap): SystemStateFirestoreCollection;

package/src/lib/model/user.d.ts

@@ -1,9 +1,15 @@
 import { type FirebaseAuthUserIdRef } from '../common/auth/auth';
 /**
- * The model is related to a user with the model's uid.
+ * Marker interface for models that are related to a user via a `uid` field.
+ *
+ * Extends {@link FirebaseAuthUserIdRef} to carry the Firebase Auth user ID.
+ * Use this when the model stores the user ID explicitly as a field.
  */
 export type UserRelated = FirebaseAuthUserIdRef;
 /**
- * The model is related to a user by the model's own identifier.
+ * Marker interface for models related to a user by the model's own document ID.
+ *
+ * The document ID itself is the user's Firebase Auth UID, so no separate `uid` field is needed.
+ * Use this for user-profile-style documents where the document key equals the user ID.
  */
 export type UserRelatedById = object;