@dereekb/firebase 13.11.2 → 13.11.3

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

@@ -154,8 +154,11 @@ export type FirestoreModelTypes<I extends FirestoreModelIdentity> = I extends Fi
 /**
  * Creates a FirestoreModelIdentity value.
  *
- * @param modelName
- * @returns
+ * @param parentOrModelName The parent FirestoreModelIdentity or the model name if not nested
+ * @param collectionNameOrModelName The collection name or the model name if not nested
+ * @param inputCollectionName Optional explicit collection name (used when parent is provided)
+ * @returns The created FirestoreModelIdentity
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelIdentity<M extends FirestoreModelType>(modelName: M): RootFirestoreModelIdentity<M, FirestoreModelDefaultCollectionName<M>>;
 export declare function firestoreModelIdentity<P extends FirestoreModelIdentity<string, string>, M extends FirestoreModelType>(parent: P, modelName: M): FirestoreModelIdentityWithParent<P, M, FirestoreModelDefaultCollectionName<M>>;
@@ -170,6 +173,7 @@ export type FirestoreModelIdentityTypeMap = Map<FirestoreModelType | FirestoreCo
  *
  * @param identities
  * @returns
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelIdentityTypeMap(identities: Iterable<FirestoreModelIdentity>): FirestoreModelIdentityTypeMap;
 /**
@@ -186,6 +190,7 @@ export interface FirestoreModelTypeRef<M extends FirestoreModelType = FirestoreM
  *
  * @param modelTypeInput
  * @returns
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelType(modelTypeInput: FirestoreModelType | FirestoreModelTypeRef): FirestoreModelType;
 /**
@@ -239,6 +244,7 @@ export type FirestoreModelIdInput = FirestoreModelId | FirestoreModelKey | Docum
  *
  * @param input
  * @returns
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelId(input: FirestoreModelIdInput): FirestoreModelId;
 /**
@@ -246,6 +252,7 @@ export declare function firestoreModelId(input: FirestoreModelIdInput): Firestor
  *
  * @param input
  * @returns
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelIdsFromKey(input: FirestoreModelKey | DocumentReferenceRef<unknown> | FirestoreModelKeyRef): FirestoreModelId[];
 /**
@@ -328,6 +335,7 @@ export type FirestoreModelKeyCollectionTypePair = FirestoreModelKeyRef & Firesto
  *
  * @param key
  * @returns
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyCollectionTypePair(key: FirestoreModelKey): FirestoreModelKeyCollectionTypePair;
 /**
@@ -367,6 +375,7 @@ export type FirestoreCollectionModelKey<N extends FirestoreCollectionNameRef = F
  * @param identity
  * @param id
  * @returns
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyPart<N extends FirestoreCollectionNameRef, K extends FirestoreModelId = FirestoreModelId>(identity: N, id: K): FirestoreCollectionModelKeyPart<N, K>;
 /**
@@ -386,6 +395,7 @@ export type FirestoreModelKeyFactory<I extends RootFirestoreModelIdentity, K ext
  *
  * @param identity - The root FirestoreModelIdentity to bind the factory to
  * @returns A factory function that creates FirestoreModelKey values for the given identity and a provided id
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyFactory<I extends RootFirestoreModelIdentity, K extends FirestoreModelId = FirestoreModelId>(identity: I): (id: K) => FirestoreCollectionModelKeyPart<I, K>;
 /**
@@ -394,6 +404,7 @@ export declare function firestoreModelKeyFactory<I extends RootFirestoreModelIde
  * @param identity
  * @param ids
  * @returns
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeys<I extends RootFirestoreModelIdentity, K extends FirestoreModelId = FirestoreModelId>(identity: I, ids: K[]): FirestoreCollectionModelKey<I, K>[];
 /**
@@ -419,6 +430,7 @@ export declare function childFirestoreModelKeys(parent: ReadFirestoreModelKeyInp
  *
  * @param parts
  * @returns
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyPath(...parts: FirestoreModelKeyPart[]): FirestoreModelKey;
 /**
@@ -435,6 +447,7 @@ export type FirestoreModelCollectionAndIdPairObject = Record<FirestoreCollection
  *
  * @param input - The FirestoreModelKey, DocumentReferenceRef, or FirestoreModelKeyRef to convert
  * @returns An object mapping collection names to document ids, or undefined if the key is unavailable
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyPairObject(input: FirestoreModelKey | DocumentReferenceRef<unknown> | FirestoreModelKeyRef): Maybe<FirestoreModelCollectionAndIdPairObject>;
 /**
@@ -453,6 +466,7 @@ export type FirestoreModelCollectionTypeArrayName = string;
  *
  * @param input - The key or reference to extract the collection type from
  * @returns The FirestoreCollectionType string, or undefined if the key is unavailable
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyCollectionType<T = unknown>(input: ReadFirestoreModelKeyInput<T>): Maybe<FirestoreCollectionType>;
 /**
@@ -461,6 +475,7 @@ export declare function firestoreModelKeyCollectionType<T = unknown>(input: Read
  * @param input - The key or reference to extract collection names from
  * @param separator - The separator to join collection names with; defaults to the Firestore collection name separator
  * @returns The joined collection type array name string, or undefined if the key is unavailable
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyCollectionTypeArrayName<T = unknown>(input: ReadFirestoreModelKeyInput<T>, separator?: string): Maybe<FirestoreModelCollectionTypeArrayName>;
 /**
@@ -469,6 +484,7 @@ export declare function firestoreModelKeyCollectionTypeArrayName<T = unknown>(in
  * @param input - The FirestoreModelIdentity to derive collection names from
  * @param separator - The separator to join collection names with; defaults to the Firestore collection name separator
  * @returns The joined collection type array name string
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreIdentityTypeArrayName(input: FirestoreModelIdentity, separator?: string): FirestoreModelCollectionTypeArrayName;
 export type FirestoreModelCollectionTypeArray = FirestoreCollectionName[];
@@ -477,6 +493,7 @@ export type FirestoreModelCollectionTypeArray = FirestoreCollectionName[];
  *
  * @param input - The FirestoreModelIdentity to traverse
  * @returns An array of FirestoreCollectionName values ordered from root to leaf
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreIdentityTypeArray(input: FirestoreModelIdentity): FirestoreModelCollectionTypeArray;
 /**
@@ -484,6 +501,7 @@ export declare function firestoreIdentityTypeArray(input: FirestoreModelIdentity
  *
  * @param input - The key or reference to extract collection names from
  * @returns An array of FirestoreCollectionName values, or undefined if the key is unavailable
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyCollectionTypeArray<T = unknown>(input: ReadFirestoreModelKeyInput<T>): Maybe<FirestoreModelCollectionTypeArray>;
 export interface FirestoreModelCollectionAndIdPair extends FirestoreModelIdRef, FirestoreCollectionNameRef {
@@ -493,6 +511,7 @@ export interface FirestoreModelCollectionAndIdPair extends FirestoreModelIdRef,
  *
  * @param input - The key or reference to extract the collection name from
  * @returns The FirestoreCollectionName from the deepest key pair, or undefined if unavailable
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyCollectionName<T = unknown>(input: ReadFirestoreModelKeyInput<T>): Maybe<FirestoreCollectionName>;
 /**
@@ -501,6 +520,7 @@ export declare function firestoreModelKeyCollectionName<T = unknown>(input: Read
  * @param input - The key or reference to extract the parent key from
  * @param maxLevelsUp - The number of levels to traverse up the key hierarchy; defaults to 1
  * @returns The parent FirestoreModelKey, or undefined if no parent exists
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyParentKey<T = unknown>(input: ReadFirestoreModelKeyInput<T>, maxLevelsUp?: number): Maybe<FirestoreModelKey>;
 /**
@@ -509,6 +529,7 @@ export declare function firestoreModelKeyParentKey<T = unknown>(input: ReadFires
  * @param input - The key or reference to extract pairs from
  * @param maxLevelsUp - The number of levels to remove from the end; defaults to 1
  * @returns An array of FirestoreModelCollectionAndIdPair values up to the parent level, or undefined if unavailable
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyParentKeyPartPairs<T = unknown>(input: ReadFirestoreModelKeyInput<T>, maxLevelsUp?: number): Maybe<FirestoreModelCollectionAndIdPair[]>;
 /**
@@ -516,6 +537,7 @@ export declare function firestoreModelKeyParentKeyPartPairs<T = unknown>(input:
  *
  * @param input
  * @returns
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyTypePair<T = unknown>(input: ReadFirestoreModelKeyInput<T>): Maybe<FirestoreModelCollectionAndIdPair>;
 /**
@@ -523,6 +545,7 @@ export declare function firestoreModelKeyTypePair<T = unknown>(input: ReadFirest
  *
  * @param input - The key or reference to parse
  * @returns An array of FirestoreModelCollectionAndIdPair values, or undefined if the key is unavailable
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyPartPairs<T = unknown>(input: ReadFirestoreModelKeyInput<T>): Maybe<FirestoreModelCollectionAndIdPair[]>;
 /**
@@ -530,6 +553,7 @@ export declare function firestoreModelKeyPartPairs<T = unknown>(input: ReadFires
  *
  * @param input
  * @returns
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyPartPairsKeyPath(input: FirestoreModelCollectionAndIdPair[]): FirestoreModelKey;
 /**
@@ -537,6 +561,7 @@ export declare function firestoreModelKeyPartPairsKeyPath(input: FirestoreModelC
  *
  * @param input
  * @returns
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelKeyPartPairsPaths(input: FirestoreModelCollectionAndIdPair[]): FirestoreModelKeyPart[];
 export type ReadFirestoreModelKeyInput<T = unknown> = FirestoreModelKey | FirestoreModelKeyRef | DocumentReferenceRef<T>;
@@ -564,6 +589,7 @@ export type FirestoreDummyModelKey = typeof FIRESTORE_DUMMY_MODEL_KEY;
  * require a key before one is available.
  *
  * @returns The dummy model key constant
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreDummyKey(): FirestoreDummyModelKey;
 /**
@@ -641,5 +667,6 @@ export interface FirestoreCollectionRef<T, D extends FirestoreDocument<T> = Fire
  * @template D - The FirestoreDocument type that wraps the data
  * @param inputConfig - Configuration for the collection
  * @returns A fully configured FirestoreCollection instance
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function makeFirestoreCollection<T, D extends FirestoreDocument<T>>(inputConfig: FirestoreCollectionConfig<T, D>): FirestoreCollection<T, D>;

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

@@ -52,5 +52,6 @@ export interface FirestoreCollectionGroup<T, D extends FirestoreDocument<T> = Fi
  * @template D - The FirestoreDocument type that wraps the data
  * @param config - Configuration for the collection group
  * @returns A fully configured FirestoreCollectionGroup instance
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function makeFirestoreCollectionGroup<T, D extends FirestoreDocument<T>>(config: FirestoreCollectionGroupConfig<T, D>): FirestoreCollectionGroup<T, D>;

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

@@ -208,5 +208,6 @@ export interface FirestoreCollectionQueryFactory<T, D extends FirestoreDocument<
  * const activeUsers = await userQueryFactory
  *   .queryDocument(where('status', '==', 'active'))
  *   .getDocs();
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreCollectionQueryFactory<T, D extends FirestoreDocument<T>>(queryFactory: FirestoreQueryFactory<T>, accessorContext: LimitedFirestoreDocumentAccessorContextExtension<T, D>): FirestoreCollectionQueryFactory<T, D>;

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

@@ -47,5 +47,6 @@ export interface RootSingleItemFirestoreCollection<T, D extends FirestoreDocumen
  * @template D - The FirestoreDocument type, defaults to FirestoreDocument<T>
  * @param config - Configuration for the single document collection
  * @returns A RootSingleItemFirestoreCollection instance configured for the specified document
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function makeRootSingleItemFirestoreCollection<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: RootSingleItemFirestoreCollectionConfig<T, D>): RootSingleItemFirestoreCollection<T, D>;

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

@@ -15,5 +15,6 @@ import { type FirestoreModelId } from './collection';
  * const id = firestoreModelIdFromEmail('user@example.com');
  * // id === 'userAAAexamplecom'
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreModelIdFromEmail(emailAddress: EmailAddress): FirestoreModelId;

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

@@ -6,3 +6,4 @@ export * from './collection.group';
 export * from './collection.util';
 export * from './subcollection';
 export * from './subcollection.single';
+export * from './subcollection.paged';

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

@@ -97,5 +97,6 @@ export type FirestoreCollectionWithParentFactory<T, PT, D extends FirestoreDocum
  * @template PD - The document type for the parent document, defaults to FirestoreDocument<PT>
  * @param config - Configuration for the subcollection, including the parent document reference
  * @returns A subcollection instance linked to the specified parent document
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function makeFirestoreCollectionWithParent<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>>(config: FirestoreCollectionWithParentConfig<T, PT, D, PD>): FirestoreCollectionWithParent<T, PT, D, PD>;

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

@@ -0,0 +1,226 @@
+import { type FirestorePagedItemAccessor } from '../accessor/document.paged';
+import { type FirestoreDocument } from '../accessor/document';
+import { type FirestoreCollectionWithParent, type FirestoreCollectionWithParentConfig } from './subcollection';
+import { type SnapshotConverterFunctions } from '../snapshot/snapshot.type';
+/**
+ * Default ID for the index document inside a paged subcollection.
+ *
+ * The underscore prefix visually distinguishes the index from page documents
+ * and sorts before numeric/alphabetic page IDs.
+ */
+export declare const DEFAULT_PAGED_ITEM_INDEX_DOCUMENT_ID = "_index";
+/**
+ * Default maximum number of items per page document when using dynamic
+ * (count-based) distribution.
+ */
+export declare const DEFAULT_PAGED_ITEM_MAX_ITEMS_PER_PAGE = 500;
+/**
+ * Defines how items are distributed across page documents.
+ *
+ * The scheme must be deterministic — for any item, {@link distribute} always
+ * returns the same page ID. This determinism is what enables selective reads
+ * in static mode: callers can read a specific page directly without first
+ * consulting the index document.
+ *
+ * @template T - The item type stored in the paged collection
+ *
+ * @example
+ * ```ts
+ * // Alphabetic distribution: items bucketed by first letter
+ * const alphaScheme: PagedItemDistributionScheme<NameEntry> = {
+ *   pageIds: 'abcdefghijklmnopqrstuvwxyz'.split(''),
+ *   distribute: (entry) => entry.name[0]?.toLowerCase() ?? 'a'
+ * };
+ * ```
+ */
+export interface PagedItemDistributionScheme<T> {
+    /**
+     * All possible page IDs in this scheme, in deterministic order.
+     *
+     * Defines the full set of page documents that may exist. Empty pages are
+     * not written, so this is the universe of allowed IDs, not necessarily
+     * the set of pages currently present.
+     */
+    readonly pageIds: readonly string[];
+    /**
+     * Maps an item to its target page ID.
+     *
+     * Must return a value that exists in {@link pageIds}. If it returns an
+     * unknown ID, the write throws.
+     */
+    readonly distribute: (item: T) => string;
+}
+/**
+ * Ref to a {@link PagedItemDistributionScheme}.
+ */
+export interface PagedItemDistributionSchemeRef<T> {
+    readonly distributionScheme: PagedItemDistributionScheme<T>;
+}
+/**
+ * Converts individual items to/from their Firestore POJO representation.
+ *
+ * Distinct from a {@link FirestoreDataConverter}: this operates on individual
+ * items inside a page's items array, not on whole DocumentSnapshots. The
+ * collection wraps these per-item conversions inside the paged page envelope
+ * (`{ i, c }`) automatically.
+ *
+ * @template T - The item type the consumer sees in memory
+ */
+export interface PagedItemConverter<T> {
+    /**
+     * Convert from a Firestore POJO to in-memory T.
+     */
+    readonly fromData: (data: object) => T;
+    /**
+     * Convert from in-memory T to a Firestore-safe POJO.
+     */
+    readonly toData: (item: T) => object;
+}
+/**
+ * Data stored in the index document of a paged subcollection.
+ *
+ * Field names are short to keep the index document small; this is internal
+ * framework data, not developer-facing state.
+ */
+export interface PagedItemIndexData {
+    /**
+     * Total item count across all pages.
+     */
+    readonly tc: number;
+    /**
+     * Page IDs that currently contain at least one item, in insertion order.
+     *
+     * For dynamic mode: `['0', '1', '2', ...]`.
+     * For static mode: a subset of the scheme's `pageIds` (only pages with items).
+     */
+    readonly p: string[];
+    /**
+     * Per-page item counts, keyed by page ID. Lets consumers know how many
+     * items are on each page without reading the page document itself.
+     */
+    readonly pc: Record<string, number>;
+    /**
+     * Timestamp (ms) of the last write operation. Useful for staleness checks.
+     */
+    readonly u: number;
+}
+/**
+ * Data stored in each page document of a paged subcollection.
+ *
+ * The {@link i} array contains the actual `T[]` slice. The `c` field is a
+ * denormalized count, available without deserializing `i`.
+ *
+ * @template T - The item type stored in the paged collection
+ */
+export interface PagedItemPageData<T> {
+    /**
+     * Items on this page. Each item is converted via {@link PagedItemConverter}.
+     */
+    readonly i: T[];
+    /**
+     * Item count on this page (denormalized).
+     */
+    readonly c: number;
+}
+/**
+ * Configuration for creating a {@link PagedItemFirestoreCollection}.
+ *
+ * Extends {@link FirestoreCollectionWithParentConfig} for parent/identity/context.
+ * The page-document data type is the {@link PagedItemPageData} envelope so the
+ * standard accessor returns the actual stored shape (mirroring the
+ * {@link SystemState}/{@link SystemStateDocument} pattern). The paged accessor
+ * methods bypass the converter and operate on the raw collection so the index
+ * document — which has a different shape — is read/written correctly.
+ *
+ * The {@link converter} field is optional: when omitted, the collection uses
+ * {@link defaultPagedItemPageDataConverter}, a pass-through converter for the
+ * envelope. Provide a custom converter only when you need per-field handling on
+ * the page document.
+ *
+ * @template T - The item type stored across page documents
+ * @template PT - The parent document data type
+ * @template D - The page document type (data shape: {@link PagedItemPageData}<T>)
+ * @template PD - The parent document type
+ */
+export interface PagedItemFirestoreCollectionConfig<T, PT, D extends FirestoreDocument<PagedItemPageData<T>> = FirestoreDocument<PagedItemPageData<T>>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>> extends Omit<FirestoreCollectionWithParentConfig<PagedItemPageData<T>, PT, D, PD>, 'converter'> {
+    /**
+     * Optional snapshot converter for the page document envelope. Defaults to
+     * {@link defaultPagedItemPageDataConverter} when omitted.
+     */
+    readonly converter?: FirestoreCollectionWithParentConfig<PagedItemPageData<T>, PT, D, PD>['converter'];
+    /**
+     * ID of the index document. Defaults to {@link DEFAULT_PAGED_ITEM_INDEX_DOCUMENT_ID}.
+     */
+    readonly indexDocumentId?: string;
+    /**
+     * Static distribution scheme. When provided, the collection uses
+     * scheme-based static distribution. When omitted, the collection uses
+     * dynamic count-based paging.
+     */
+    readonly distributionScheme?: PagedItemDistributionScheme<T>;
+    /**
+     * Max items per page document. Only used in dynamic mode. Defaults to
+     * {@link DEFAULT_PAGED_ITEM_MAX_ITEMS_PER_PAGE}.
+     */
+    readonly maxItemsPerPage?: number;
+    /**
+     * Per-item converter applied to individual `T`s when reading/writing the
+     * `i` array of a page document. If omitted, items are stored as-is and
+     * must already be Firestore-safe POJOs.
+     */
+    readonly itemConverter?: PagedItemConverter<T>;
+}
+/**
+ * A subcollection that stores a logical `T[]` distributed across multiple
+ * page documents under a parent.
+ *
+ * Combines {@link FirestoreCollectionWithParent} (for parent/context/identity)
+ * with {@link FirestorePagedItemAccessor} (for paged read/write operations).
+ *
+ * The standard document accessor methods inherited from
+ * {@link FirestoreCollectionWithParent} return the raw {@link PagedItemPageData}
+ * envelope. In normal usage callers should use the paged accessor methods
+ * (e.g. {@link FirestorePagedItemAccessor.loadAllItems}) which apply the
+ * configured {@link PagedItemConverter} per item.
+ *
+ * @template T - The item type stored across pages
+ * @template PT - The parent document data type
+ * @template D - The page document type (data shape: {@link PagedItemPageData}<T>)
+ * @template PD - The parent document type
+ */
+export interface PagedItemFirestoreCollection<T, PT, D extends FirestoreDocument<PagedItemPageData<T>> = FirestoreDocument<PagedItemPageData<T>>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>> extends FirestoreCollectionWithParent<PagedItemPageData<T>, PT, D, PD>, FirestorePagedItemAccessor<T> {
+}
+/**
+ * Builds the default snapshot converter used by {@link PagedItemFirestoreCollection}
+ * when no consumer-supplied converter is provided.
+ *
+ * The page envelope is the framework's internal storage shape: `i` is the array of
+ * raw entries (already Firestore-safe at this level — per-entry conversion is
+ * handled by the paged accessor's {@link PagedItemConverter}) and `c` is the
+ * denormalized count.
+ *
+ * @template T - The item type stored across pages
+ * @returns A snapshot converter for {@link PagedItemPageData}<T>
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function defaultPagedItemPageDataConverter<T>(): SnapshotConverterFunctions<PagedItemPageData<T>>;
+/**
+ * Creates a {@link PagedItemFirestoreCollection}.
+ *
+ * Mirrors the `build()` + extend pattern used by
+ * {@link makeSingleItemFirestoreCollection}: the base
+ * {@link FirestoreCollectionWithParent} provides parent/identity/context, and
+ * {@link extendFirestoreCollectionWithPagedItemAccessor} attaches the paged
+ * read/write methods. When the config does not supply a `converter`, the
+ * default {@link defaultPagedItemPageDataConverter} is used so consumers don't
+ * have to model the envelope shape themselves.
+ *
+ * @template T - The item type stored across pages
+ * @template PT - The parent document data type
+ * @template D - The page document type
+ * @template PD - The parent document type
+ * @param config - Paged collection configuration
+ * @returns A configured paged subcollection
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function makePagedItemFirestoreCollection<T, PT, D extends FirestoreDocument<PagedItemPageData<T>> = FirestoreDocument<PagedItemPageData<T>>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>>(config: PagedItemFirestoreCollectionConfig<T, PT, D, PD>): PagedItemFirestoreCollection<T, PT, D, PD>;

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

@@ -50,5 +50,6 @@ export interface SingleItemFirestoreCollection<T, PT, D extends FirestoreDocumen
  * @template PD - The document type for the parent document, defaults to FirestoreDocument<PT>
  * @param config - Configuration for the single document subcollection
  * @returns A subcollection instance with specialized accessors for the single document
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function makeSingleItemFirestoreCollection<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>>(config: SingleItemFirestoreCollectionConfig<T, PT, D, PD>): SingleItemFirestoreCollection<T, PT, D, PD>;

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

@@ -1,5 +1,5 @@
 import { type FirestoreDocument, type SingleItemFirestoreCollectionDocumentIdentifierRef } from './accessor/document';
-import { type FirestoreCollection, type FirestoreCollectionConfig, type FirestoreCollectionWithParent, type SingleItemFirestoreCollection, type FirestoreCollectionGroup, type RootSingleItemFirestoreCollection } from './collection';
+import { type FirestoreCollection, type FirestoreCollectionConfig, type FirestoreCollectionWithParent, type SingleItemFirestoreCollection, type FirestoreCollectionGroup, type RootSingleItemFirestoreCollection, type PagedItemFirestoreCollection, type PagedItemDistributionScheme, type PagedItemConverter, type PagedItemPageData } from './collection';
 import { type FirestoreContextCacheFactoryRef, type FirestoreContextCacheRef } from './cache/cache';
 import { type FirestoreDrivers } from './driver/driver';
 import { type WriteBatchFactoryReference, type RunTransactionFactoryReference } from './driver';
@@ -104,6 +104,18 @@ export interface FirestoreContext<F extends Firestore = Firestore> extends RunTr
      * @returns A SingleItemFirestoreCollection instance for the specified document
      */
     singleItemFirestoreCollection<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>>(config: FirestoreContextSingleItemFirestoreCollectionConfig<T, PT, D, PD>): SingleItemFirestoreCollection<T, PT, D, PD>;
+    /**
+     * Creates a PagedItemFirestoreCollection that distributes a logical T[] across
+     * multiple page documents under a parent.
+     *
+     * @template T - The item type stored across pages
+     * @template PT - The parent document data type
+     * @template D - The page document type
+     * @template PD - The parent FirestoreDocument implementation type
+     * @param config - Configuration for the paged collection
+     * @returns A PagedItemFirestoreCollection instance
+     */
+    pagedItemFirestoreCollection<T, PT, D extends FirestoreDocument<PagedItemPageData<T>> = FirestoreDocument<PagedItemPageData<T>>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>>(config: FirestoreContextPagedItemFirestoreCollectionConfig<T, PT, D, PD>): PagedItemFirestoreCollection<T, PT, D, PD>;
 }
 /**
  * Configuration for creating a FirestoreCollection through a FirestoreContext.
@@ -166,6 +178,29 @@ export interface FirestoreContextFirestoreCollectionWithParentConfig<T, PT, D ex
  */
 export interface FirestoreContextSingleItemFirestoreCollectionConfig<T, PT, D extends FirestoreDocument<T> = FirestoreDocument<T>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>> extends FirestoreContextFirestoreCollectionWithParentConfig<T, PT, D, PD>, Partial<SingleItemFirestoreCollectionDocumentIdentifierRef> {
 }
+/**
+ * Configuration for creating a PagedItemFirestoreCollection through a FirestoreContext.
+ *
+ * Mirrors FirestoreContextSingleItemFirestoreCollectionConfig but for the paged
+ * variant. Page documents are typed against the {@link PagedItemPageData} envelope
+ * so the standard accessor returns the actual stored shape; per-entry conversion
+ * is performed by the paged accessor methods using {@link itemConverter}.
+ *
+ * The {@link converter} field is optional — when omitted the collection uses the
+ * default page-envelope converter built by `defaultPagedItemPageDataConverter`.
+ *
+ * @template T - The item type stored across pages
+ * @template PT - The parent document data type
+ * @template D - The page document type
+ * @template PD - The parent FirestoreDocument implementation type
+ */
+export interface FirestoreContextPagedItemFirestoreCollectionConfig<T, PT, D extends FirestoreDocument<PagedItemPageData<T>> = FirestoreDocument<PagedItemPageData<T>>, PD extends FirestoreDocument<PT> = FirestoreDocument<PT>> extends Omit<FirestoreContextFirestoreCollectionWithParentConfig<PagedItemPageData<T>, PT, D, PD>, 'converter'> {
+    readonly converter?: FirestoreContextFirestoreCollectionWithParentConfig<PagedItemPageData<T>, PT, D, PD>['converter'];
+    readonly indexDocumentId?: string;
+    readonly distributionScheme?: PagedItemDistributionScheme<T>;
+    readonly maxItemsPerPage?: number;
+    readonly itemConverter?: PagedItemConverter<T>;
+}
 /**
  * Optional parameters for {@link FirestoreContextFactory} that configure context-level
  * features like caching. These are separate from the platform drivers because they
@@ -204,5 +239,6 @@ export type FirestoreContextFactory<F extends Firestore = Firestore> = (firestor
  * @template F - The Firestore implementation type
  * @param drivers - The Firestore drivers to use in created contexts
  * @returns A factory function that creates FirestoreContext instances
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreContextFactory<F extends Firestore = Firestore>(drivers: FirestoreDrivers): FirestoreContextFactory<F>;

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

@@ -34,5 +34,6 @@ export interface MakeFirestoreQueryConstraintFunctionsDriver<B> extends Omit<Fir
  * @returns A fully configured constraint functions driver
  *
  * @throws {Error} When a query uses a constraint type not present in the handler map
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function makeFirestoreQueryConstraintFunctionsDriver<B>(config: MakeFirestoreQueryConstraintFunctionsDriver<B>): FirestoreQueryConstraintFunctionsDriver;

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

@@ -22,5 +22,6 @@ export declare function assertFirestoreUpdateHasData(data: UpdateData<object>):
  * Creates and throws an error for empty update data passed to a {@link FirestoreDocumentDataAccessor}'s `update()` method.
  *
  * @throws {Error} Always throws
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreUpdateWithNoDataError(): void;

package/src/lib/common/firestore/query/constraint.d.ts

@@ -40,6 +40,7 @@ export interface FirestoreQueryConstraint<T = unknown> {
  * @param type - The constraint type identifier (e.g., 'where', 'limit')
  * @param data - The constraint-specific configuration data
  * @returns A typed constraint object
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreQueryConstraint<T = unknown>(type: string, data: T): FirestoreQueryConstraint<T>;
 /**
@@ -59,6 +60,7 @@ export declare function firestoreQueryConstraint<T = unknown>(type: string, data
  * // Use the factory to create constraints
  * const nameConstraint = whereFactory({ field: 'name', op: '==', value: 'John' });
  * const ageConstraint = whereFactory({ field: 'age', op: '>', value: 21 });
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreQueryConstraintFactory(type: string): <T = unknown>(data: T) => FirestoreQueryConstraint<T>;
 /**

package/src/lib/common/firestore/query/iterator.d.ts

@@ -177,6 +177,7 @@ export declare const DEFAULT_FIRESTORE_ITEM_PAGE_ITERATOR_ITEMS_PER_PAGE = 50;
  *    with `reload()` and `stream()` capabilities
  *
  * @returns A delegate instance for use with {@link ItemPageIterator}
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function makeFirestoreItemPageIteratorDelegate<T>(): FirestoreItemPageIteratorDelegate<T>;
 export interface FirestoreItemPageIteration<T> extends MappedPageItemIterationInstance<QueryDocumentSnapshotArray<T>, FirestoreItemPageQueryResult<T>, PageLoadingState<QueryDocumentSnapshotArray<T>>, PageLoadingState<FirestoreItemPageQueryResult<T>>, InternalFirestoreItemPageIterationInstance<T>> {
@@ -259,6 +260,7 @@ export type FirestoreItemPageIterationFactoryFunction<T> = (filter?: FirestoreIt
  * const adminPaginator = usersPaginator({
  *   constraints: [where('role', '==', 'admin')]
  * });
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreItemPageIterationFactory<T>(baseConfig: FirestoreItemPageIterationBaseConfig<T>): FirestoreItemPageIterationFactoryFunction<T>;
 /**
@@ -305,6 +307,7 @@ export declare const FIRESTORE_ITEM_PAGE_ITERATOR: ItemPageIterator<FirestoreIte
  * // Load the next page when needed
  * const secondPage = await usersPagination.loadNextPage().toPromise();
  * console.log('Next 10 users:', secondPage);
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreItemPageIteration<T>(config: FirestoreItemPageIterationConfig<T>): FirestoreItemPageIterationInstance<T>;
 /**
@@ -326,6 +329,7 @@ export type FirestoreFixedItemPageIterationFactoryFunction<T> = (items: Document
  * @param baseConfig - Base pagination configuration (query reference, driver, page size)
  * @param documentAccessor - Accessor used to load document snapshots from the references
  * @returns A factory function that creates fixed-set pagination instances
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreFixedItemPageIterationFactory<T>(baseConfig: FirestoreItemPageIterationConfig<T>, documentAccessor: LimitedFirestoreDocumentAccessor<T>): FirestoreFixedItemPageIterationFactoryFunction<T>;
 /**
@@ -359,5 +363,6 @@ export interface FirestoreFixedItemPageIterationConfig<T> extends FirestoreItemP
  *
  * @param config - Configuration including the document references, accessor, and pagination settings
  * @returns A pagination instance that pages through the fixed reference set
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreFixedItemPageIteration<T>(config: FirestoreFixedItemPageIterationConfig<T>): FirestoreItemPageIterationInstance<T>;

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

@@ -158,5 +158,6 @@ export interface FirestoreQueryConfig<T> extends FirestoreQueryDriverRef, QueryL
  * const adminUsers = activeUsers.filter(
  *   where('role', '==', 'admin')
  * ).getDocs();
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreQueryFactory<T>(config: FirestoreQueryConfig<T>): FirestoreQueryFactory<T>;

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

@@ -28,5 +28,6 @@ import { type FirestoreModelData, type SnapshotConverterConfig, type SnapshotCon
  *
  * // Use with a collection reference
  * const usersCollection = firestore.collection('users').withConverter(userConverter);
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function snapshotConverterFunctions<T extends object, O extends object = FirestoreModelData<T>>(config: SnapshotConverterConfig<T, O>): SnapshotConverterFunctions<T, O>;