@dereekb/firebase 13.11.2 → 13.11.4

package/test/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.11.2",
+  "version": "13.11.4",
   "peerDependencies": {
-    "@dereekb/date": "13.11.2",
-    "@dereekb/firebase": "13.11.2",
-    "@dereekb/model": "13.11.2",
-    "@dereekb/rxjs": "13.11.2",
-    "@dereekb/util": "13.11.2",
+    "@dereekb/date": "13.11.4",
+    "@dereekb/firebase": "13.11.4",
+    "@dereekb/model": "13.11.4",
+    "@dereekb/rxjs": "13.11.4",
+    "@dereekb/util": "13.11.4",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.1.0",
     "firebase": "^12.12.1",

package/test/src/lib/common/mock/mock.item.d.ts

@@ -1,5 +1,5 @@
 import { type Maybe } from '@dereekb/util';
-import { type CollectionReference, type FirestoreCollection, type FirestoreContext, AbstractFirestoreDocument, type SingleItemFirestoreCollection, type FirestoreCollectionWithParent, AbstractFirestoreDocumentWithParent, type ExpectedFirestoreModelData, type FirestoreModelData, type CollectionGroup, type FirestoreCollectionGroup, type UserRelated, type UserRelatedById, type SystemStateStoredData, type SystemStateStoredDataConverterMap, type SystemStateStoredDataFieldConverterConfig } from '@dereekb/firebase';
+import { type CollectionReference, type FirestoreCollection, type FirestoreContext, AbstractFirestoreDocument, type SingleItemFirestoreCollection, type FirestoreCollectionWithParent, AbstractFirestoreDocumentWithParent, type ExpectedFirestoreModelData, type FirestoreModelData, type CollectionGroup, type FirestoreCollectionGroup, type UserRelated, type UserRelatedById, type SystemStateStoredData, type SystemStateStoredDataConverterMap, type SystemStateStoredDataFieldConverterConfig, type PagedItemConverter, type PagedItemDistributionScheme, type PagedItemFirestoreCollection, type PagedItemPageData } from '@dereekb/firebase';
 import { type GrantedReadRole } from '@dereekb/model';
 /**
  * Union of all mock model identity types used in the test suite.
@@ -7,7 +7,7 @@ import { type GrantedReadRole } from '@dereekb/model';
  * Each member corresponds to one of the mock Firestore models defined in this file.
  * Useful for generic constraints that need to accept any mock model identity.
  */
-export type MockItemTypes = typeof mockItemIdentity | typeof mockItemPrivateIdentity | typeof mockItemUserIdentity | typeof mockItemSubItemIdentity | typeof mockItemSubItemDeepIdentity;
+export type MockItemTypes = typeof mockItemIdentity | typeof mockItemPrivateIdentity | typeof mockItemUserIdentity | typeof mockItemSubItemIdentity | typeof mockItemSubItemDeepIdentity | typeof mockItemPagedIdentity;
 /**
  * {@link firestoreModelIdentity} for the root-level mock item collection (`mockItem` / `mi`).
  */
@@ -459,6 +459,123 @@ export type MockItemSubItemDeepFirestoreCollectionGroup = FirestoreCollectionGro
  * @returns A typed {@link MockItemSubItemDeepFirestoreCollectionGroup} wired with the {@link mockItemSubItemDeepConverter}.
  */
 export declare function mockItemSubItemDeepFirestoreCollectionGroup(firestoreContext: FirestoreContext): MockItemSubItemDeepFirestoreCollectionGroup;
+/**
+ * {@link firestoreModelIdentity} for the MockItemPaged subcollection (`mockItemPaged` / `mip2`).
+ *
+ * Child of {@link mockItemIdentity}. Stores a logical {@link MockItemPagedEntry} array distributed
+ * across multiple page documents, plus an index document that summarizes the layout. See
+ * {@link PagedItemFirestoreCollection} for the underlying mechanism.
+ */
+export declare const mockItemPagedIdentity: import("@dereekb/firebase").FirestoreModelIdentityWithParent<import("@dereekb/firebase").RootFirestoreModelIdentity<"mockItem", "mi">, "mockItemPaged", "mip2">;
+/**
+ * Single entry stored inside a paged subcollection page.
+ *
+ * Items are grouped by {@link group} when using static distribution and treated as opaque
+ * payloads when using dynamic (count-based) paging.
+ */
+export interface MockItemPagedEntry {
+    readonly id: string;
+    readonly group: string;
+    readonly value: number;
+}
+/**
+ * Possible granted roles for {@link MockItemPagedEntry} pages.
+ */
+export type MockItemPagedRoles = GrantedReadRole | 'admin';
+/**
+ * Page-document model shape for {@link MockItemPagedEntry}. The paged collection stores entries
+ * inside this envelope (`i` = items, `c` = count). The standalone index document
+ * (`{@link DEFAULT_PAGED_ITEM_INDEX_DOCUMENT_ID}`) lives in the same collection but uses a
+ * different shape ({@link PagedItemIndexData}); from the model service's perspective only the
+ * page envelope is the canonical document.
+ */
+export type MockItemPagedDocumentData = PagedItemPageData<MockItemPagedEntry>;
+/**
+ * {@link AbstractFirestoreDocumentWithParent} implementation for a single page document inside a
+ * {@link MockItemPagedFirestoreCollection}. Used by the model service factory to address pages
+ * the same way other subcollection documents are addressed.
+ */
+export declare class MockItemPagedDocument extends AbstractFirestoreDocumentWithParent<MockItem, MockItemPagedDocumentData, MockItemPagedDocument, typeof mockItemPagedIdentity> {
+    get modelIdentity(): import("@dereekb/firebase").FirestoreModelIdentityWithParent<import("@dereekb/firebase").RootFirestoreModelIdentity<"mockItem", "mi">, "mockItemPaged", "mip2">;
+}
+/**
+ * Per-item converter for {@link MockItemPagedEntry} used by the paged accessor.
+ *
+ * The mock entry shape is already Firestore-safe, so the converter is an identity
+ * pass-through. Production usage may wrap a real converter (e.g. for date fields).
+ */
+export declare const mockItemPagedEntryConverter: PagedItemConverter<MockItemPagedEntry>;
+/**
+ * Static distribution scheme for {@link MockItemPagedEntry} that buckets items by their
+ * {@link MockItemPagedEntry.group} field across three page IDs (`a`, `b`, `c`).
+ */
+export declare const mockItemPagedAlphaDistributionScheme: PagedItemDistributionScheme<MockItemPagedEntry>;
+/**
+ * Default `maxItemsPerPage` used by the dynamic mock paged collection factory. Kept small to
+ * exercise multi-page boundary conditions in tests without writing many entries.
+ */
+export declare const MOCK_ITEM_PAGED_DEFAULT_MAX_ITEMS_PER_PAGE = 3;
+/**
+ * Typed {@link PagedItemFirestoreCollection} for {@link MockItemPagedEntry} items under a
+ * {@link MockItem} parent.
+ */
+export type MockItemPagedFirestoreCollection = PagedItemFirestoreCollection<MockItemPagedEntry, MockItem, MockItemPagedDocument, MockItemDocument>;
+/**
+ * Factory function type that creates a {@link MockItemPagedFirestoreCollection} for a given parent.
+ */
+export type MockItemPagedFirestoreCollectionFactory = (parent: MockItemDocument) => MockItemPagedFirestoreCollection;
+/**
+ * Configuration for {@link mockItemPagedFirestoreCollection}.
+ */
+export interface MockItemPagedFirestoreCollectionConfig {
+    /**
+     * When provided, the factory produces a statically-distributed paged collection using the
+     * given scheme. When omitted, the factory produces a dynamic (count-based) paged collection
+     * using {@link maxItemsPerPage}.
+     */
+    readonly distributionScheme?: PagedItemDistributionScheme<MockItemPagedEntry>;
+    /**
+     * Maximum items per page document in dynamic mode. Defaults to
+     * {@link MOCK_ITEM_PAGED_DEFAULT_MAX_ITEMS_PER_PAGE}.
+     */
+    readonly maxItemsPerPage?: number;
+}
+/**
+ * Creates a factory for producing {@link MockItemPagedFirestoreCollection} instances bound to a
+ * parent {@link MockItemDocument}.
+ *
+ * @param firestoreContext - The Firestore context used to resolve the underlying subcollection.
+ * @param config - Optional config selecting between dynamic (default) and static distribution.
+ * @returns A factory that, given a parent {@link MockItemDocument}, returns a paged subcollection
+ * wired with {@link mockItemPagedEntryConverter}.
+ */
+export declare function mockItemPagedFirestoreCollection(firestoreContext: FirestoreContext, config?: MockItemPagedFirestoreCollectionConfig): MockItemPagedFirestoreCollectionFactory;
+/**
+ * Creates a {@link CollectionGroup} reference for querying all {@link MockItemPagedDocumentData}
+ * page documents across parents.
+ *
+ * Note: the index document (`_index`) lives in the same Firestore collection but has a different
+ * shape ({@link PagedItemIndexData}); collection-group queries will surface both. Consumers
+ * should filter by document id when only pages are desired.
+ *
+ * @param context - The Firestore context used to resolve the collection group.
+ * @returns A typed {@link CollectionGroup} reference for the MockItemPaged collection name.
+ */
+export declare function mockItemPagedCollectionReference(context: FirestoreContext): CollectionGroup<MockItemPagedDocumentData>;
+/**
+ * Typed {@link FirestoreCollectionGroup} for querying {@link MockItemPagedDocumentData} page
+ * documents across all parents. Used by the model service factory to address paged page
+ * documents in a parent-agnostic way.
+ */
+export type MockItemPagedFirestoreCollectionGroup = FirestoreCollectionGroup<MockItemPagedDocumentData, MockItemPagedDocument>;
+/**
+ * Creates a {@link MockItemPagedFirestoreCollectionGroup} for cross-parent access to paged
+ * page documents.
+ *
+ * @param firestoreContext - The Firestore context used to resolve the underlying collection group reference.
+ * @returns A typed {@link MockItemPagedFirestoreCollectionGroup}.
+ */
+export declare function mockItemPagedFirestoreCollectionGroup(firestoreContext: FirestoreContext): MockItemPagedFirestoreCollectionGroup;
 /**
  * System state type identifier for mock system state data.
  *

package/test/src/lib/common/mock/mock.item.service.d.ts

@@ -1,4 +1,4 @@
-import { type MockItem, type MockItemSubItemDeep, type MockItemSubItemDeepDocument, type MockItemSubItemDeepFirestoreCollectionFactory, type MockItemSubItemDeepFirestoreCollectionGroup, type MockItemSubItemDeepRoles, type MockItemDocument, type MockItemFirestoreCollection, type MockItemPrivate, type MockItemPrivateDocument, type MockItemPrivateFirestoreCollectionFactory, type MockItemPrivateFirestoreCollectionGroup, type MockItemPrivateRoles, type MockItemRoles, type MockItemSubItem, type MockItemSubItemDocument, type MockItemSubItemFirestoreCollectionFactory, type MockItemSubItemFirestoreCollectionGroup, type MockItemSubItemRoles, type MockItemTypes, type MockItemUser, type MockItemUserDocument, type MockItemUserFirestoreCollectionFactory, type MockItemUserFirestoreCollectionGroup, type MockItemUserRoles } from './mock.item';
+import { type MockItem, type MockItemSubItemDeep, type MockItemSubItemDeepDocument, type MockItemSubItemDeepFirestoreCollectionFactory, type MockItemSubItemDeepFirestoreCollectionGroup, type MockItemSubItemDeepRoles, type MockItemDocument, type MockItemFirestoreCollection, type MockItemPrivate, type MockItemPrivateDocument, type MockItemPrivateFirestoreCollectionFactory, type MockItemPrivateFirestoreCollectionGroup, type MockItemPrivateRoles, type MockItemRoles, type MockItemSubItem, type MockItemSubItemDocument, type MockItemSubItemFirestoreCollectionFactory, type MockItemSubItemFirestoreCollectionGroup, type MockItemSubItemRoles, type MockItemTypes, type MockItemUser, type MockItemUserDocument, type MockItemUserFirestoreCollectionFactory, type MockItemUserFirestoreCollectionGroup, type MockItemUserRoles, type MockItemPagedDocument, type MockItemPagedDocumentData, type MockItemPagedFirestoreCollectionConfig, type MockItemPagedFirestoreCollectionFactory, type MockItemPagedFirestoreCollectionGroup, type MockItemPagedRoles } from './mock.item';
 import { type FirebaseAppModelContext, type FirestoreContext, type SystemStateFirestoreCollection, type SystemState, type SystemStateDocument, type SystemStateTypes } from '@dereekb/firebase';
 import { type GrantedRoleMap } from '@dereekb/model';
 /**
@@ -18,6 +18,16 @@ export declare abstract class MockItemCollections {
     abstract readonly mockItemSubItemCollectionGroup: MockItemSubItemFirestoreCollectionGroup;
     abstract readonly mockItemSubItemDeepCollectionFactory: MockItemSubItemDeepFirestoreCollectionFactory;
     abstract readonly mockItemSubItemDeepCollectionGroup: MockItemSubItemDeepFirestoreCollectionGroup;
+    abstract readonly mockItemPagedCollectionFactory: MockItemPagedFirestoreCollectionFactory;
+    abstract readonly mockItemPagedStaticCollectionFactory: MockItemPagedFirestoreCollectionFactory;
+    /**
+     * Builds a {@link MockItemPagedFirestoreCollectionFactory} with a caller-supplied
+     * configuration. Use this in tests that need to exercise non-default settings such as a
+     * smaller {@link MockItemPagedFirestoreCollectionConfig.maxItemsPerPage} or a custom
+     * distribution scheme without adding another pre-baked factory to {@link MockItemCollections}.
+     */
+    abstract readonly mockItemPagedCollectionFactoryWithConfig: (config: MockItemPagedFirestoreCollectionConfig) => MockItemPagedFirestoreCollectionFactory;
+    abstract readonly mockItemPagedCollectionGroup: MockItemPagedFirestoreCollectionGroup;
     abstract readonly mockItemSystemStateCollection: SystemStateFirestoreCollection;
 }
 /**
@@ -50,6 +60,14 @@ export declare const mockItemSubItemFirebaseModelServiceFactory: import("@dereek
  * Model service factory for {@link MockItemSubItemDeep}. Returns configurable roles from `context.rolesToReturn`, defaulting to `{ read: true }`.
  */
 export declare const mockItemSubItemDeepFirebaseModelServiceFactory: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemSubItemDeep, MockItemSubItemDeepDocument, MockItemSubItemDeepRoles>;
+/**
+ * Model service factory for {@link MockItemPagedDocumentData} (paged page documents).
+ *
+ * Returns configurable roles from `context.rolesToReturn`, defaulting to `{ read: true }`. The
+ * page document is the framework envelope (`{ i, c }`); per-entry permissions are not modelled
+ * because entries live inside the page array, not as standalone documents.
+ */
+export declare const mockItemPagedFirebaseModelServiceFactory: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemPagedDocumentData, MockItemPagedDocument, MockItemPagedRoles>;
 /**
  * Model service factory for {@link SystemState}. Only grants access to system admins via {@link grantFullAccessIfAdmin}.
  */
@@ -87,6 +105,7 @@ export declare const MOCK_FIREBASE_MODEL_SERVICE_FACTORIES: {
     mockItemUser: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemUser, MockItemUserDocument, MockItemUserRoles>;
     mockItemSub: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemSubItem, MockItemSubItemDocument, MockItemSubItemRoles>;
     mockItemSubItemDeep: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemSubItemDeep, MockItemSubItemDeepDocument, MockItemSubItemDeepRoles>;
+    mockItemPaged: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemPagedDocumentData, MockItemPagedDocument, MockItemPagedRoles>;
 };
 /**
  * Composite model service built from {@link MOCK_FIREBASE_MODEL_SERVICE_FACTORIES}.
@@ -100,6 +119,7 @@ export declare const mockFirebaseModelServices: import("@dereekb/firebase").Fire
     mockItemUser: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemUser, MockItemUserDocument, MockItemUserRoles>;
     mockItemSub: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemSubItem, MockItemSubItemDocument, MockItemSubItemRoles>;
     mockItemSubItemDeep: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemSubItemDeep, MockItemSubItemDeepDocument, MockItemSubItemDeepRoles>;
+    mockItemPaged: import("@dereekb/firebase").FirebaseModelServiceFactory<MockFirebaseContext, MockItemPagedDocumentData, MockItemPagedDocument, MockItemPagedRoles>;
 }, MockFirebaseContext>;
 /**
  * Full mock Firebase context type used throughout the test suite.