@dereekb/firebase 13.11.2 → 13.11.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.11.2",
+  "version": "13.11.3",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -18,10 +18,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/util": "13.11.2",
-    "@dereekb/date": "13.11.2",
-    "@dereekb/model": "13.11.2",
-    "@dereekb/rxjs": "13.11.2",
+    "@dereekb/util": "13.11.3",
+    "@dereekb/date": "13.11.3",
+    "@dereekb/model": "13.11.3",
+    "@dereekb/rxjs": "13.11.3",
     "@firebase/rules-unit-testing": "5.0.0",
     "arktype": "^2.2.0",
     "date-fns": "^4.1.0",

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

@@ -18,5 +18,6 @@ import { type UpdateData } from '../../common/firestore/types';
  * });
  * await updateDoc(docRef, updateData);
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreClientArrayUpdateToUpdateData<T extends object>(input: FirestoreAccessorArrayUpdate<T>): UpdateData<T>;

package/src/lib/client/firestore/driver.accessor.batch.d.ts

@@ -32,6 +32,7 @@ export declare class WriteBatchFirestoreDocumentDataAccessor<T> extends DefaultF
  * await accessor.set(data);
  * await batch.commit();
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function writeBatchAccessorFactory<T>(writeBatch: FirebaseFirestoreWriteBatch): FirestoreDocumentDataAccessorFactory<T>;
 /**

package/src/lib/client/firestore/driver.accessor.create.d.ts

@@ -15,5 +15,6 @@ import { type WithFieldValue, type WriteResult } from '../../common/firestore/ty
  * const create = createWithAccessor(accessor);
  * await create({ name: 'New Item' }); // throws if document already exists
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function createWithAccessor<T>(accessor: FirestoreDocumentDataAccessor<T>): (data: WithFieldValue<T>) => Promise<void | WriteResult>;

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

@@ -15,5 +15,6 @@ import { type FirestoreAccessorDriver } from '../../common/firestore/driver/acce
  * const driver = firestoreClientAccessorDriver();
  * // Used internally by firebaseFirestoreClientDrivers()
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreClientAccessorDriver(): FirestoreAccessorDriver;

package/src/lib/client/firestore/driver.accessor.default.d.ts

@@ -37,6 +37,7 @@ export declare class DefaultFirestoreDocumentDataAccessor<T> implements Firestor
  * const accessor = factory.accessorFor(documentRef);
  * const snapshot = await accessor.get();
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function defaultFirestoreAccessorFactory<T>(): FirestoreDocumentDataAccessorFactory<T>;
 /**

package/src/lib/client/firestore/driver.accessor.transaction.d.ts

@@ -41,6 +41,7 @@ export declare class TransactionFirestoreDocumentDataAccessor<T> implements Fire
  *   // ... modify and set
  * });
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function transactionAccessorFactory<T>(transaction: FirebaseFirestoreTransaction): FirestoreDocumentDataAccessorFactory<T>;
 /**

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

@@ -14,5 +14,6 @@ import { type FirestoreAccessorIncrementUpdate } from '../../common/firestore/ac
  * const updateData = firestoreClientIncrementUpdateToUpdateData<MyModel>({ viewCount: 1, likeCount: -1 });
  * await updateDoc(docRef, updateData);
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreClientIncrementUpdateToUpdateData<T extends object>(input: FirestoreAccessorIncrementUpdate<T>): UpdateData<T>;

package/src/lib/client/function/development.function.factory.d.ts

@@ -36,5 +36,6 @@ export type DevelopmentFirebaseFunctionMapFactory<M extends DevelopmentFirebaseF
  * const devFns = factory(getFunctions());
  * await devFns.resetData();
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function developmentFirebaseFunctionMapFactory<M extends DevelopmentFirebaseFunctionTypeMap>(configMap: DevelopmentFirebaseFunctionConfigMap<M>): DevelopmentFirebaseFunctionMapFactory<M>;

package/src/lib/client/function/function.factory.d.ts

@@ -39,6 +39,7 @@ export type FirebaseFunctionMapFactory<M extends FirebaseFunctionTypeMap> = (fun
  * const functions = factory(getFunctions());
  * const result = await functions.createUser({ name: 'Alice' });
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firebaseFunctionMapFactory<M extends FirebaseFunctionTypeMap>(configMap: FirebaseFunctionTypeConfigMap<M>): FirebaseFunctionMapFactory<M>;
 /**
@@ -109,5 +110,6 @@ export type LazyFirebaseFunctions<M extends FirebaseFunctionsMap> = {
  * const lazyFns = factory(getFunctions());
  * const notifFns = lazyFns.notificationFunctions(); // initialized on first call
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function lazyFirebaseFunctionsFactory<M extends FirebaseFunctionsMap, C extends FirebaseFunctionsConfigMap<M> = FirebaseFunctionsConfigMap<M>>(configMap: C): LazyFirebaseFunctionsFactory<M>;

package/src/lib/client/function/model.function.factory.d.ts

@@ -150,5 +150,6 @@ export type ModelFirebaseFunctionMapFactory<M extends FirebaseFunctionTypeMap, U
  * await fns.createNotification(data);
  * await fns.updateNotificationStatus(data);
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function callModelFirebaseFunctionMapFactory<M extends FirebaseFunctionTypeMap, U extends ModelFirebaseCrudFunctionTypeMap>(configMap: FirebaseFunctionTypeConfigMap<M>, crudConfigMap: ModelFirebaseCrudFunctionConfigMap<U, FirestoreModelIdentity>): ModelFirebaseFunctionMapFactory<M, U>;

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

@@ -242,5 +242,6 @@ export type UpdateWithAccessorUpdateAndConverterFunction<T> = (data: Partial<T>,
  * @param accessor - The document accessor to use for updates
  * @param converter - The data converter to transform input data to Firestore format
  * @returns A function that updates the document with converted data
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function updateWithAccessorUpdateAndConverterFunction<T>(accessor: FirestoreDocumentDataAccessor<T>, converter: FirestoreDataConverter<T>): UpdateWithAccessorUpdateAndConverterFunction<T>;

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

@@ -136,5 +136,6 @@ export type InterceptAccessorFactoryFunction<T, D = DocumentData> = (input: Fire
  * @template D - The raw document data type in Firestore
  * @param wrap - Function to wrap each created accessor
  * @returns A function that transforms accessor factories to use the wrapper
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function interceptAccessorFactoryFunction<T, D = DocumentData>(wrap: WrapFirestoreDocumentDataAccessorFunction<T, D>): InterceptAccessorFactoryFunction<T, D>;

package/src/lib/common/firestore/accessor/accessor.wrap.modify.d.ts

@@ -60,6 +60,7 @@ export declare class ModifyBeforeSetFirestoreDocumentDataAccessorWrapper<T exten
  *
  * @param fieldName - The field to copy the document ID into
  * @returns A modifier function that sets the field to the document's ID
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function copyDocumentIdToFieldModifierFunction<T extends object>(fieldName: keyof T): ModifyBeforeSetModifierFunction<T>;
 /**
@@ -68,12 +69,14 @@ export declare function copyDocumentIdToFieldModifierFunction<T extends object>(
  *
  * @param config - The ModifyBeforeSetConfig defining when and how to modify documents
  * @returns An InterceptAccessorFactoryFunction that wraps accessors with the modify-before-set behavior
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function modifyBeforeSetInterceptAccessorFactoryFunction<T extends object, D = DocumentData>(config: ModifyBeforeSetConfig<T>): InterceptAccessorFactoryFunction<T, D>;
 /**
  * Creates a modifier that copies the document ID to the `uid` field for {@link UserRelated} models.
  *
  * @returns A ModifyBeforeSetModifierFunction that sets the `uid` field to the document's ID
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function copyDocumentIdForUserRelatedModifierFunction<T extends UserRelated>(): ModifyBeforeSetModifierFunction<T>;
 /**
@@ -92,5 +95,6 @@ export declare const COPY_USER_RELATED_DATA_ACCESSOR_FACTORY_FUNCTION: import("@
  * document ID copy modifier to all accessors created by the factory.
  *
  * @returns A typed InterceptAccessorFactoryFunction with the UserRelated document ID copy modifier applied
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function copyUserRelatedDataAccessorFactoryFunction<T extends UserRelated, D = DocumentData>(): InterceptAccessorFactoryFunction<T, D>;

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

@@ -17,5 +17,6 @@ export type ArrayFieldUpdateWithAccessorFunction<T> = (data: FirestoreAccessorAr
  * @returns A function that applies array updates to the document
  *
  * @see https://firebase.google.com/docs/firestore/manage-data/add-data#update_elements_in_an_array
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function arrayUpdateWithAccessorFunction<T>(accessor: FirestoreDocumentDataAccessor<T>): ArrayFieldUpdateWithAccessorFunction<T>;

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

@@ -300,6 +300,7 @@ export interface LimitedFirestoreDocumentAccessorFactoryConfig<T, D extends Fire
  *
  * @param config - Configuration including converter, accessor factory, and document factory
  * @returns A factory function for creating LimitedFirestoreDocumentAccessor instances
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function limitedFirestoreDocumentAccessorFactory<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: LimitedFirestoreDocumentAccessorFactoryConfig<T, D>): LimitedFirestoreDocumentAccessorFactoryFunction<T, D>;
 /**
@@ -324,6 +325,7 @@ export interface FirestoreDocumentAccessorFactoryConfig<T, D extends FirestoreDo
  *
  * @param config - Configuration including the collection reference and document factory
  * @returns A factory function for creating FirestoreDocumentAccessor instances
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreDocumentAccessorFactory<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: FirestoreDocumentAccessorFactoryConfig<T, D>): FirestoreDocumentAccessorFactoryFunction<T, D>;
 export interface LimitedFirestoreDocumentAccessorForTransactionFactory<T, D extends FirestoreDocument<T> = FirestoreDocument<T>, A extends LimitedFirestoreDocumentAccessor<T, D> = LimitedFirestoreDocumentAccessor<T, D>> {
@@ -357,6 +359,7 @@ export interface FirestoreDocumentAccessorContextExtension<T, D extends Firestor
  * @param config.documentAccessor - The document accessor factory function
  * @param config.firestoreAccessorDriver - The firestore accessor driver used to create transaction and write batch contexts
  * @returns An extension object with document accessor factory methods for default, transaction, and write batch contexts
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreDocumentAccessorContextExtension<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>({ documentAccessor, firestoreAccessorDriver }: FirestoreDocumentAccessorContextExtensionConfig<T, D>): FirestoreDocumentAccessorContextExtension<T, D>;
 export declare function firestoreDocumentAccessorContextExtension<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>({ documentAccessor, firestoreAccessorDriver }: LimitedFirestoreDocumentAccessorContextExtensionConfig<T, D>): LimitedFirestoreDocumentAccessorContextExtension<T, D>;
@@ -399,6 +402,7 @@ export interface FirestoreSingleDocumentAccessorConfig<T, D extends FirestoreDoc
  *
  * @param config - Configuration specifying the single item identifier and the document accessor context extension
  * @returns A FirestoreSingleDocumentAccessor providing convenient access to the single document
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreSingleDocumentAccessor<T, D extends FirestoreDocument<T> = FirestoreDocument<T>>(config: FirestoreSingleDocumentAccessorConfig<T, D>): FirestoreSingleDocumentAccessor<T, D>;
 /**

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

@@ -0,0 +1,134 @@
+/**
+ * @module Firestore Paged Item Accessor
+ *
+ * Internal read/write orchestration for {@link PagedItemFirestoreCollection}.
+ * The accessor distributes a logical `T[]` across N page documents and a
+ * single index document under a parent, then merges them back on read.
+ *
+ * The accessor goes lower-level than the standard
+ * {@link FirestoreSingleDocumentAccessor}: it bypasses per-collection
+ * converters because page documents (`PagedItemPageData<T>`) and the index
+ * document (`PagedItemIndexData`) have different shapes that can't be
+ * expressed by a single document converter.
+ */
+import { type Maybe, type Building } from '@dereekb/util';
+import { type Transaction } from '../types';
+import { type FirestoreDocumentAccessorContextExtension } from './document';
+import { type CollectionReferenceRef, type FirestoreContextReference } from '../reference';
+import { type PagedItemConverter, type PagedItemDistributionScheme, type PagedItemIndexData, type PagedItemPageData } from '../collection/subcollection.paged';
+/**
+ * Accessor for reading and writing paged item data.
+ *
+ * Replaces the per-page document accessor exposed on a standard
+ * {@link FirestoreCollectionWithParent}. All methods orchestrate the
+ * multi-document index/page layout internally.
+ *
+ * @template T - The item type stored across pages
+ *
+ * @example
+ * ```ts
+ * // Read all items (loads index, then all pages in parallel)
+ * const allItems = await pagedCollection.loadAllItems();
+ *
+ * // Read specific pages (static mode — caller knows the scheme)
+ * const cItems = await pagedCollection.loadItemsForPages(['c']);
+ *
+ * // Replace the full T[] (collection handles distribution)
+ * await pagedCollection.writeAllItems(allItems);
+ * ```
+ */
+export interface FirestorePagedItemAccessor<T> {
+    /**
+     * ID of the index document.
+     */
+    readonly indexDocumentId: string;
+    /**
+     * The static distribution scheme, if configured.
+     */
+    readonly distributionScheme: Maybe<PagedItemDistributionScheme<T>>;
+    /**
+     * True when a static distribution scheme is configured.
+     */
+    readonly isStaticDistribution: boolean;
+    /**
+     * Loads only the index document.
+     *
+     * Returns `undefined` when the paged collection has never been written
+     * (the index document does not yet exist).
+     */
+    loadIndex(): Promise<Maybe<PagedItemIndexData>>;
+    /**
+     * Loads all pages and returns the merged `T[]`.
+     *
+     * Reads the index, then all listed pages in parallel, merging items in
+     * page order. Returns an empty array when the collection has never been
+     * written.
+     */
+    loadAllItems(): Promise<T[]>;
+    /**
+     * Loads items from specific page IDs only.
+     *
+     * In static mode this skips the index read — callers know which pages to
+     * fetch from the distribution scheme. In dynamic mode the IDs are numeric
+     * strings (`'0'`, `'1'`, ...) and callers should typically discover them
+     * via {@link loadIndex} first.
+     *
+     * Pages that don't exist are silently skipped.
+     *
+     * @param pageIds - The page IDs to read
+     */
+    loadItemsForPages(pageIds: string[]): Promise<T[]>;
+    /**
+     * Replaces the full `T[]` contents of the paged collection.
+     *
+     * Distributes items into pages, writes/updates page documents, deletes
+     * pages no longer needed, and updates the index — all in a single
+     * WriteBatch.
+     *
+     * @param items - The full set of items to store
+     */
+    writeAllItems(items: T[]): Promise<void>;
+    /**
+     * Same as {@link writeAllItems} but participates in an existing transaction.
+     *
+     * The accessor reads existing pages within the transaction, computes the
+     * new distribution, and writes all changes within the same transaction.
+     *
+     * Cost: N reads (current pages) + M writes (new pages + deletes + index).
+     * For a typical 2–6 page collection this is well within Firestore's
+     * transaction limits.
+     *
+     * @param transaction - Active Firestore transaction
+     * @param items - The full set of items to store
+     */
+    writeAllItemsInTransaction(transaction: Transaction, items: T[]): Promise<void>;
+}
+/**
+ * Configuration for {@link extendFirestoreCollectionWithPagedItemAccessor}.
+ *
+ * @template T - The item type stored across pages
+ */
+export interface PagedItemAccessorExtensionConfig<T> {
+    readonly indexDocumentId: string;
+    readonly distributionScheme: Maybe<PagedItemDistributionScheme<T>>;
+    readonly maxItemsPerPage: number;
+    readonly itemConverter: Maybe<PagedItemConverter<T>>;
+    /**
+     * Standard document accessor extension for the underlying collection.
+     * Currently unused (page CRUD goes through the raw driver) but accepted
+     * for parity with {@link extendFirestoreCollectionWithSingleDocumentAccessor}
+     * and future use.
+     */
+    readonly accessors: FirestoreDocumentAccessorContextExtension<PagedItemPageData<T>>;
+}
+/**
+ * Extends a Firestore collection object in-place with paged item accessor methods.
+ *
+ * The collection must already expose {@link CollectionReferenceRef} and
+ * {@link FirestoreContextReference} from its base — both are provided by
+ * {@link makeFirestoreCollectionWithParent}.
+ *
+ * @param x - The collection object to extend
+ * @param config - Paged accessor configuration
+ */
+export declare function extendFirestoreCollectionWithPagedItemAccessor<X extends FirestorePagedItemAccessor<T> & CollectionReferenceRef<unknown> & FirestoreContextReference, T>(x: Building<X>, config: PagedItemAccessorExtensionConfig<T>): void;