@dereekb/firebase 13.6.6 → 13.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.6.6",
+  "version": "13.6.8",
   "exports": {
     "./test": {
       "module": "./test/index.esm.js",
@@ -17,10 +17,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/util": "13.6.6",
-    "@dereekb/date": "13.6.6",
-    "@dereekb/model": "13.6.6",
-    "@dereekb/rxjs": "13.6.6",
+    "@dereekb/util": "13.6.8",
+    "@dereekb/date": "13.6.8",
+    "@dereekb/model": "13.6.8",
+    "@dereekb/rxjs": "13.6.8",
     "@firebase/rules-unit-testing": "5.0.0",
     "arktype": "^2.2.0",
     "date-fns": "^4.0.0",

package/src/lib/client/firestore/firestore.d.ts

@@ -8,8 +8,13 @@ import { type FirestoreContextFactory } from '../../common/firestore/context';
  *
  * @example
  * ```ts
+ * // Without caching
  * const context = clientFirebaseFirestoreContextFactory(firestore);
- * const collection = context.collection(myCollectionConfig);
+ *
+ * // With caching
+ * const context = clientFirebaseFirestoreContextFactory(firestore, {
+ *   firestoreContextCacheFactory: inMemoryFirestoreContextCacheFactory()
+ * });
  * ```
  */
 export declare const clientFirebaseFirestoreContextFactory: FirestoreContextFactory;

package/src/lib/common/firestore/accessor/document.d.ts

@@ -1,4 +1,5 @@
 import { type Observable } from 'rxjs';
+import { type FirestoreCollectionCache, type FirestoreCollectionDocumentCache } from '../cache/cache';
 import { type FirestoreAccessorDriverRef } from '../driver/accessor';
 import { type FirestoreCollectionNameRef, type FirestoreModelId, type FirestoreModelIdentityCollectionName, type FirestoreModelIdentityModelType, type FirestoreModelIdentityRef, type FirestoreModelIdRef, type FirestoreModelKey, type FirestoreModelKeyRef, type FirestoreModelTypeRef, type FirestoreModelIdentity, type FirestoreModelTypeModelIdentityRef } from './../collection/collection';
 import { type DocumentReference, type CollectionReference, type Transaction, type WriteBatch, type DocumentSnapshot, type SnapshotOptions, type WriteResult, type FirestoreDataConverter } from '../types';
@@ -27,6 +28,7 @@ import { type FirestoreDataConverterFactory, type FirestoreDataConverterFactoryR
  */
 export interface FirestoreDocument<T, I extends FirestoreModelIdentity = FirestoreModelIdentity> extends FirestoreDataConverterRef<T>, DocumentReferenceRef<T>, CollectionReferenceRef<T>, FirestoreModelIdentityRef<I>, FirestoreModelTypeRef<FirestoreModelIdentityModelType<I>>, FirestoreCollectionNameRef<FirestoreModelIdentityCollectionName<I>>, FirestoreModelKeyRef, FirestoreModelIdRef {
     readonly accessor: FirestoreDocumentDataAccessor<T>;
+    readonly cache: FirestoreCollectionDocumentCache<T>;
     readonly id: FirestoreModelId;
     snapshotStream(mode: FirestoreAccessorStreamMode): Observable<DocumentSnapshot<T>>;
     snapshotDataStream(mode: FirestoreAccessorStreamMode, options?: SnapshotOptions): Observable<Maybe<T>>;
@@ -60,10 +62,12 @@ export type FirestoreDocumentData<D extends FirestoreDocument<any>> = D extends
 export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFirestoreDocument<T, any, I>, I extends FirestoreModelIdentity = FirestoreModelIdentity> implements FirestoreDocument<T>, LimitedFirestoreDocumentAccessorRef<T, D>, CollectionReferenceRef<T> {
     private readonly _accessor;
     private readonly _documentAccessor;
+    private readonly _cache;
     readonly stream$: Observable<DocumentSnapshot<T>>;
     readonly data$: Observable<T>;
     constructor(accessor: FirestoreDocumentDataAccessor<T>, documentAccessor: LimitedFirestoreDocumentAccessor<T, D>);
     get accessor(): FirestoreDocumentDataAccessor<T>;
+    get cache(): FirestoreCollectionDocumentCache<T>;
     get documentAccessor(): LimitedFirestoreDocumentAccessor<T, D>;
     abstract get modelIdentity(): I;
     get modelType(): FirestoreModelIdentityModelType<I>;
@@ -76,6 +80,8 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
     /**
      * Retrieves a DocumentSnapshot of the document as an Observable. Streams based on the input mode.
      *
+     * Passively populates the cache with each emitted snapshot.
+     *
      * @param mode - The stream mode controlling how the Observable emits snapshot updates
      * @returns An Observable that emits DocumentSnapshot values based on the given mode
      */
@@ -83,22 +89,29 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
     /**
      * Retrieves the data of the DocumentSnapshot of the document as an Observable. Streams based on the input mode.
      *
+     * Passively populates the cache via {@link snapshotStream}.
+     *
      * @param mode - The stream mode controlling how the Observable emits snapshot data updates
      * @param options - Optional SnapshotOptions for reading the document data
      * @returns An Observable that emits the document data or undefined based on the given mode
      */
     snapshotDataStream(mode: FirestoreAccessorStreamMode, options?: SnapshotOptions): Observable<Maybe<T>>;
     /**
-     * Retrieves a DocumentSnapshot of the document.
+     * Retrieves a DocumentSnapshot of the document from Firestore.
      *
-     * @returns
+     * Passively populates the cache with the fetched snapshot.
+     *
+     * @returns A Promise resolving to the document snapshot
      */
     snapshot(): Promise<DocumentSnapshot<T>>;
     /**
-     * Retrieves the data of the DocumentSnapshot of the document.
+     * Retrieves the data of the document, checking the cache first.
      *
-     * @param options
-     * @returns
+     * If a fresh cache entry exists, returns it without hitting Firestore.
+     * Otherwise falls through to {@link snapshot} which populates the cache.
+     *
+     * @param options - Optional SnapshotOptions for reading the document data
+     * @returns A Promise resolving to the document data, or undefined if the document does not exist
      */
     snapshotData(options?: SnapshotOptions): Promise<Maybe<T>>;
     /**
@@ -111,16 +124,19 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
     /**
      * Creates the document if it does not exist, using the accessor's create functionality.
      *
-     * @param data
-     * @returns
+     * Populates the cache with the written data after a successful create.
+     *
+     * @param data - The document data to create
+     * @returns A Promise that resolves when the create completes
      */
     create(data: T): Promise<WriteResult | void>;
     /**
-     * Updates the document using the accessor's update functionalty if the document exists. This differs from Firestore's default
+     * Updates the document using the accessor's update functionality if the document exists. This differs from Firestore's default
      * update implementation which does not use the configured converter. This update function will, allowing the use of
      * snapshotConverterFunctions().
      *
-     * Throws an exception when it does not exist.
+     * Invalidates the cache entry since partial updates don't provide the full document.
+     * Throws an exception when the document does not exist.
      *
      * @param data - Partial document data to update
      * @param params - Optional update parameters
@@ -130,6 +146,8 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
     /**
      * Updates the document using the accessor's increment functionality.
      *
+     * Invalidates the cache entry since increment updates don't provide the full document.
+     *
      * @param data - The increment update to apply to numeric fields
      * @returns A Promise that resolves when the increment update completes
      */
@@ -137,6 +155,8 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
     /**
      * Updates the document using the accessor's array field update functionality.
      *
+     * Invalidates the cache entry since array updates don't provide the full document.
+     *
      * @param data - The array field update to apply (union or remove elements)
      * @returns A Promise that resolves when the array update completes
      */
@@ -162,6 +182,16 @@ export type FirestoreDocumentAccessorRef<T, D extends FirestoreDocument<T> = Fir
  */
 export interface LimitedFirestoreDocumentAccessor<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> extends FirestoreDataConverterRef<T>, FirestoreModelTypeModelIdentityRef, FirestoreAccessorDriverRef {
     readonly databaseContext: FirestoreDocumentContext<T>;
+    /**
+     * Returns the collection cache for the given document reference.
+     *
+     * Returns a noop cache when operating within a transaction or write batch context,
+     * since cache reads/writes must be bypassed in those contexts.
+     *
+     * @param ref - The document reference to get the cache for
+     * @returns The collection cache (real or noop) for the document
+     */
+    cacheForDocument(ref: DocumentReference<T>): FirestoreCollectionDocumentCache<T>;
     /**
      * Loads a document from the datastore.
      *
@@ -259,6 +289,10 @@ export interface LimitedFirestoreDocumentAccessorFactoryConfig<T, D extends Fire
      * Optional InterceptFirestoreDataConverterFactory to return a modified converter.
      */
     readonly converterFactory?: InterceptFirestoreDataConverterFactory<T>;
+    /**
+     * The collection cache for documents created by this factory.
+     */
+    readonly cache: FirestoreCollectionCache<T>;
     readonly makeDocument: FirestoreDocumentFactoryFunction<T, D>;
 }
 /**

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

@@ -0,0 +1,365 @@
+import { type Observable } from 'rxjs';
+import { type Destroyable, type Maybe, type Milliseconds } from '@dereekb/util';
+import { type FirestoreCollectionType } from '../collection/collection';
+import { type FirestoreModelKey } from '../collection/collection';
+/**
+ * Options for loading a document with cache support.
+ *
+ * These options control whether a document read should consult the cache
+ * and how stale a cached entry is allowed to be. They are passed to
+ * `snapshotData()` (the cache-aware read path) on document instances.
+ *
+ * @example
+ * ```ts
+ * const data = await document.snapshotData({ allowCache: true, maxTtl: 60000 });
+ * ```
+ */
+export interface LoadDocumentOptions {
+    /**
+     * Whether to allow reading from the cache for this read.
+     *
+     * When true, the accessor checks the collection cache before hitting Firestore.
+     * Defaults to false unless the document accessor was created with default cache options enabled.
+     */
+    readonly allowCache?: boolean;
+    /**
+     * Maximum TTL to accept for a cached entry on this specific read.
+     *
+     * Overrides the collection-level TTL. If the cached entry is older than this value,
+     * it is treated as a cache miss. Only relevant when allowCache is true.
+     */
+    readonly maxTtl?: Milliseconds;
+}
+/**
+ * Default cache behavior for a document accessor. When set, all reads through this
+ * accessor use the cache unless overridden per-read via {@link LoadDocumentOptions}.
+ *
+ * @example
+ * ```ts
+ * const defaults: DocumentAccessorCacheDefaults = { allowCache: true, maxTtl: 300000 };
+ * ```
+ */
+export interface DocumentAccessorCacheDefaults {
+    /**
+     * When true, reads through this accessor use the cache by default.
+     */
+    readonly allowCache: boolean;
+    /**
+     * Default max TTL for cached reads through this accessor.
+     */
+    readonly maxTtl?: Milliseconds;
+}
+/**
+ * Type of cache event emitted by {@link FirestoreContextCache}.
+ */
+export type FirestoreCacheEventType = 'hit' | 'miss' | 'update' | 'invalidate' | 'enable_collection' | 'disable_collection';
+/**
+ * Event emitted by {@link FirestoreContextCache.events$} on cache interactions.
+ *
+ * Provides visibility into cache behavior for analytics, debugging,
+ * and monitoring cache effectiveness across all collections.
+ */
+export interface FirestoreCacheEvent {
+    readonly type: FirestoreCacheEventType;
+    readonly collectionType: FirestoreCollectionType;
+    /**
+     * Document key for hit/miss/update/invalidate events.
+     * Undefined for enable_collection/disable_collection events.
+     */
+    readonly key: Maybe<FirestoreModelKey>;
+    readonly timestamp: Date;
+}
+/**
+ * A cached entry for a single document, including Firestore metadata timestamps.
+ *
+ * Only existing documents are cached — `data` is always present (never `Maybe<T>`).
+ *
+ * @template T - The document data type
+ */
+export interface FirestoreCacheEntry<T> {
+    readonly key: FirestoreModelKey;
+    readonly data: T;
+    readonly cachedAt: Date;
+}
+/**
+ * Input for setting a cache entry. Extracted from a DocumentSnapshot.
+ *
+ * @template T - The document data type
+ */
+export interface FirestoreCacheEntryInput<T> {
+    readonly data: T;
+}
+/**
+ * Cache for a single Firestore collection. Entries are keyed by document path.
+ *
+ * Each collection gets its own cache instance managed by {@link FirestoreContextCache}.
+ * The cache supports TTL-based expiration, passive population from reads/writes,
+ * and operation-scoped instances for deduplication.
+ *
+ * @template T - The document data type
+ */
+export interface FirestoreCollectionCache<T = unknown> extends Destroyable {
+    /**
+     * Gets a cached entry if it exists and is within the TTL.
+     *
+     * @param key - The document path
+     * @param maxTtl - Optional TTL override; defaults to the collection's defaultTtl
+     * @returns The cached entry, or undefined if not found or expired
+     */
+    get(key: FirestoreModelKey, maxTtl?: Milliseconds): Maybe<FirestoreCacheEntry<T>>;
+    /**
+     * Sets or updates a cache entry. Called passively on every read/write.
+     *
+     * @param key - The document path
+     * @param entry - The data to cache
+     */
+    set(key: FirestoreModelKey, entry: FirestoreCacheEntryInput<T>): void;
+    /**
+     * Invalidates a specific cache entry.
+     *
+     * @param key - The document path to invalidate
+     */
+    invalidate(key: FirestoreModelKey): void;
+    /**
+     * Clears all entries in this collection cache.
+     */
+    clear(): void;
+    /**
+     * Creates a short-lived in-memory cache instance scoped to a single operation.
+     *
+     * Deduplicates reads within a batch operation — equivalent to what
+     * `LimitedFirestoreDocumentAccessorSnapshotCache` does today, but backed
+     * by this cache's existing entries as a warm start.
+     */
+    instance(): FirestoreCollectionCacheInstance<T>;
+    /**
+     * The default TTL for this collection cache.
+     */
+    readonly defaultTtl: Milliseconds;
+}
+/**
+ * Short-lived, operation-scoped cache instance. Wraps the parent
+ * {@link FirestoreCollectionCache} and adds Promise-level deduplication for
+ * concurrent in-flight reads within the same operation.
+ *
+ * Replaces the existing `LimitedFirestoreDocumentAccessorSnapshotCache` pattern.
+ *
+ * @template T - The document data type
+ */
+export interface FirestoreCollectionCacheInstance<T = unknown> {
+    /**
+     * Gets a cached entry, checking the instance's local cache first,
+     * then the parent {@link FirestoreCollectionCache}.
+     *
+     * @param key - The document path
+     * @param maxTtl - Optional TTL override
+     * @returns The cached entry, or undefined if not found or expired
+     */
+    get(key: FirestoreModelKey, maxTtl?: Milliseconds): Maybe<FirestoreCacheEntry<T>>;
+    /**
+     * Gets or fetches a document, deduplicating concurrent requests for the same key.
+     * If a fetch for this key is already in-flight, returns the same Promise.
+     *
+     * @param key - The document path
+     * @param fetchFn - Function that fetches the document from Firestore
+     * @returns The cached or freshly-fetched entry
+     */
+    getOrFetch(key: FirestoreModelKey, fetchFn: () => Promise<FirestoreCacheEntry<T>>): Promise<FirestoreCacheEntry<T>>;
+}
+/**
+ * Configuration for a cacheable collection.
+ */
+export interface FirestoreCollectionCacheConfig {
+    /**
+     * Default TTL for cached entries in this collection.
+     */
+    readonly defaultTtl: Milliseconds;
+}
+/**
+ * Factory and manager for per-collection caches. Lives on {@link FirestoreContext}.
+ *
+ * Provides global and per-type controls for enabling/disabling caching and
+ * resetting cached data. Uses {@link FirestoreCollectionType} for keying.
+ */
+export interface FirestoreContextCache extends Destroyable {
+    /**
+     * Gets or creates a cache for the given collection.
+     *
+     * @param collectionType - The unique collection type identifier
+     * @param config - TTL configuration for this collection
+     * @returns A cache instance for the collection
+     */
+    cacheForCollection<T>(collectionType: FirestoreCollectionType, config: FirestoreCollectionCacheConfig): FirestoreCollectionCache<T>;
+    /**
+     * Observable stream of cache events (hits, misses, updates) across all collections.
+     *
+     * Useful for analytics, debugging, and monitoring cache effectiveness.
+     */
+    readonly events$: Observable<FirestoreCacheEvent>;
+    /**
+     * Set of model types that have caching explicitly disabled.
+     *
+     * Caching is enabled by default for all types. Only types added here are excluded.
+     */
+    readonly disabledTypes: ReadonlySet<FirestoreCollectionType>;
+    /**
+     * Whether caching is globally enabled. Defaults to true. When false, all
+     * collection caches behave as noops regardless of their individual configuration.
+     */
+    isEnabled(): boolean;
+    /**
+     * Enables or disables caching globally.
+     *
+     * @param enabled - Whether to enable caching
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Clears all cached entries across all collections.
+     */
+    clearAll(): void;
+    /**
+     * Whether caching is enabled for a specific model type/identity.
+     *
+     * Returns false if the type is explicitly disabled or if caching is globally disabled.
+     *
+     * @param collectionType - The collection type to check
+     * @returns Whether caching is active for this type
+     */
+    isEnabledForType(collectionType: FirestoreCollectionType): boolean;
+    /**
+     * Enables or disables caching for a specific model type/identity.
+     *
+     * When disabled, the collection cache for that type behaves as a noop.
+     * When re-enabled, the cache resumes normal operation.
+     *
+     * @param collectionType - The collection type to toggle
+     * @param enabled - Whether to enable caching for this type
+     */
+    setEnabledForType(collectionType: FirestoreCollectionType, enabled: boolean): void;
+    /**
+     * Clears all cached entries for a specific model type/identity.
+     *
+     * @param collectionType - The collection type to clear
+     */
+    clearForType(collectionType: FirestoreCollectionType): void;
+}
+/**
+ * Cache bound to a specific document. Wraps a {@link FirestoreCollectionCache}
+ * with the document's key pre-applied, so callers don't need to pass the key.
+ *
+ * Returned by {@link LimitedFirestoreDocumentAccessor.cacheForDocument}.
+ *
+ * @template T - The document data type
+ */
+export interface FirestoreCollectionDocumentCache<T = unknown> {
+    /**
+     * Gets the cached entry for this document if it exists and is within the TTL.
+     *
+     * @param maxTtl - Optional TTL override; defaults to the collection's defaultTtl
+     * @returns The cached entry, or undefined if not found or expired
+     */
+    get(maxTtl?: Milliseconds): Maybe<FirestoreCacheEntry<T>>;
+    /**
+     * Sets or updates the cache entry for this document.
+     *
+     * @param entry - The data to cache
+     */
+    set(entry: FirestoreCacheEntryInput<T>): void;
+    /**
+     * Invalidates the cache entry for this document.
+     */
+    invalidate(): void;
+}
+/**
+ * Creates a {@link FirestoreCollectionDocumentCache} that delegates to the given
+ * collection cache with the key pre-bound.
+ *
+ * @param collectionCache - The parent collection cache
+ * @param key - The document path to bind
+ * @returns A document-scoped cache
+ *
+ * @example
+ * ```ts
+ * const docCache = firestoreCollectionDocumentCache(collectionCache, 'users/abc');
+ * docCache.set({ data: userData });
+ * const entry = docCache.get();
+ * ```
+ */
+export declare function firestoreCollectionDocumentCache<T>(collectionCache: FirestoreCollectionCache<T>, key: FirestoreModelKey): FirestoreCollectionDocumentCache<T>;
+/**
+ * Returns the singleton noop {@link FirestoreCollectionDocumentCache}.
+ */
+export declare function noopFirestoreCollectionDocumentCache<T>(): FirestoreCollectionDocumentCache<T>;
+/**
+ * Reference to a {@link FirestoreCollectionCache} instance.
+ *
+ * @template T - The document data type
+ */
+export interface FirestoreCollectionCacheRef<T = unknown> {
+    readonly cache: FirestoreCollectionCache<T>;
+}
+/**
+ * Reference to a {@link FirestoreContextCache} instance.
+ *
+ * The cache is always defined — when no cache factory is configured,
+ * a noop implementation is used.
+ */
+export interface FirestoreContextCacheRef {
+    readonly cache: FirestoreContextCache;
+}
+/**
+ * Factory function that creates a {@link FirestoreContextCache}.
+ *
+ * Provided at the app level (Angular providers / NestJS modules) via
+ * {@link FirestoreContextFactoryParams}. Each platform can use its own
+ * implementation — e.g. {@link inMemoryFirestoreContextCacheFactory} for
+ * in-memory TTL-based caching.
+ *
+ * @example
+ * ```ts
+ * const factory: FirestoreContextCacheFactory = (config) => inMemoryFirestoreContextCache(config);
+ * ```
+ */
+export type FirestoreContextCacheFactory = (config?: FirestoreContextCacheFactoryConfig) => FirestoreContextCache;
+/**
+ * Configuration passed to a {@link FirestoreContextCacheFactory} when creating the cache.
+ */
+export interface FirestoreContextCacheFactoryConfig {
+    /**
+     * Default TTL for all collections unless overridden per-collection.
+     */
+    readonly defaultTtl?: Milliseconds;
+}
+/**
+ * Reference to an optional {@link FirestoreContextCacheFactory}.
+ */
+export interface FirestoreContextCacheFactoryRef {
+    readonly firestoreContextCacheFactory?: Maybe<FirestoreContextCacheFactory>;
+}
+/**
+ * Returns the singleton noop {@link FirestoreCollectionCache} that discards all operations.
+ *
+ * Used when no cache driver is configured so that `.cache` is always defined.
+ *
+ * @example
+ * ```ts
+ * const cache = noopFirestoreCollectionCache();
+ * cache.get('path/to/doc'); // always returns undefined
+ * cache.set('path/to/doc', { data }); // no-op
+ * ```
+ */
+export declare function noopFirestoreCollectionCache<T>(): FirestoreCollectionCache<T>;
+/**
+ * Returns the singleton noop {@link FirestoreContextCache}.
+ *
+ * Used when no cache factory is configured so that `FirestoreContext.cache` is always defined,
+ * avoiding null checks throughout the codebase.
+ *
+ * @example
+ * ```ts
+ * const cache = noopFirestoreContextCache();
+ * cache.cacheForCollection('user', { defaultTtl: 0 }); // returns noop collection cache
+ * cache.isEnabled(); // false
+ * ```
+ */
+export declare function noopFirestoreContextCache(): FirestoreContextCache;