@dereekb/firebase 13.11.12 → 13.11.14

package/package.json

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

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

@@ -2,7 +2,27 @@ import { type DateRange, type DateRangeInput } from '@dereekb/date';
 import { type StringKeyPropertyKeys } from '@dereekb/util';
 import { type RootFirestoreModelIdentity } from '../collection/collection';
 import { type DocumentReference, type FieldPathOrStringPath, type FieldPathOrStringPathOf } from '../types';
-import { type FirestoreQueryConstraint, type OrderByDirection } from './constraint';
+import { type EndAtValueQueryConstraintData, type FirestoreQueryConstraint, type OrderByDocumentIdQueryConstraintData, type OrderByQueryConstraintData, type StartAtValueQueryConstraintData, type OrderByDirection, type WhereQueryConstraintData } from './constraint';
+/**
+ * Fixed-shape tuple returned by helpers that combine `orderBy` with `startAtValue` + `endAtValue`
+ * range bounds on the same field (e.g. {@link whereStringValueHasPrefix}, {@link allChildDocumentsUnderRelativePath}).
+ */
+export type FirestoreQueryOrderByRangeBoundsTuple = [FirestoreQueryConstraint<OrderByQueryConstraintData>, FirestoreQueryConstraint<StartAtValueQueryConstraintData>, FirestoreQueryConstraint<EndAtValueQueryConstraintData>];
+/**
+ * Fixed-shape tuple returned by helpers that combine `orderByDocumentId` with `startAtValue` + `endAtValue`
+ * range bounds on the document id (e.g. {@link allChildDocumentsUnderParentPath}).
+ */
+export type FirestoreQueryOrderByDocumentIdRangeBoundsTuple = [FirestoreQueryConstraint<OrderByDocumentIdQueryConstraintData>, FirestoreQueryConstraint<StartAtValueQueryConstraintData>, FirestoreQueryConstraint<EndAtValueQueryConstraintData>];
+/**
+ * Fixed-shape tuple returned by helpers that pair an `orderBy` with a single `where` comparison
+ * on the same field (e.g. the `whereDateIs*WithSort` family).
+ */
+export type FirestoreQueryOrderByAndWhereTuple = [FirestoreQueryConstraint<OrderByQueryConstraintData>, FirestoreQueryConstraint<WhereQueryConstraintData>];
+/**
+ * Fixed-shape tuple returned by helpers that pair an `orderBy` with two `where` comparisons
+ * on the same field, defining a closed range (e.g. {@link whereDateIsBetween}).
+ */
+export type FirestoreQueryOrderByAndRangeWhereTuple = [FirestoreQueryConstraint<OrderByQueryConstraintData>, FirestoreQueryConstraint<WhereQueryConstraintData>, FirestoreQueryConstraint<WhereQueryConstraintData>];
 /**
  * Creates constraints to query all child documents under a specific parent document reference.
  *
@@ -20,7 +40,7 @@ import { type FirestoreQueryConstraint, type OrderByDirection } from './constrai
  * const query = collectionGroup(firestore, 'comments')
  *   .where(...allChildDocumentsUnderParent(postRef));
  */
-export declare function allChildDocumentsUnderParent<P>(parentRef: DocumentReference<P>): FirestoreQueryConstraint[];
+export declare function allChildDocumentsUnderParent<P>(parentRef: DocumentReference<P>): FirestoreQueryOrderByDocumentIdRangeBoundsTuple;
 /**
  * Creates constraints to query all child documents under a specific parent path.
  *
@@ -36,7 +56,7 @@ export declare function allChildDocumentsUnderParent<P>(parentRef: DocumentRefer
  * const query = collectionGroup(firestore, 'comments')
  *   .where(...allChildDocumentsUnderParentPath('posts/abc123'));
  */
-export declare function allChildDocumentsUnderParentPath(parentPath: string): FirestoreQueryConstraint[];
+export declare function allChildDocumentsUnderParentPath(parentPath: string): FirestoreQueryOrderByDocumentIdRangeBoundsTuple;
 /**
  * Creates constraints to query documents that have a field value starting with a specific prefix.
  *
@@ -58,8 +78,8 @@ export declare function allChildDocumentsUnderParentPath(parentPath: string): Fi
  * const query = collectionGroup(firestore, 'tasks')
  *   .where(...allChildDocumentsUnderRelativePath('parentPath', 'organizations/org123/'));
  */
-export declare function allChildDocumentsUnderRelativePath<T>(orderByFieldPath: StringKeyPropertyKeys<T>, parentValue: string, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
-export declare function allChildDocumentsUnderRelativePath(orderByFieldPath: FieldPathOrStringPath, parentValue: string, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
+export declare function allChildDocumentsUnderRelativePath<T>(orderByFieldPath: StringKeyPropertyKeys<T>, parentValue: string, sortDirection?: OrderByDirection): FirestoreQueryOrderByRangeBoundsTuple;
+export declare function allChildDocumentsUnderRelativePath(orderByFieldPath: FieldPathOrStringPath, parentValue: string, sortDirection?: OrderByDirection): FirestoreQueryOrderByRangeBoundsTuple;
 /**
  * Creates constraints to find documents where a field contains a reference to a specific model type.
  *
@@ -78,7 +98,7 @@ export declare function allChildDocumentsUnderRelativePath(orderByFieldPath: Fie
  * const query = collection(firestore, 'documents')
  *   .where(...whereStringHasRootIdentityModelKey('reference', { collectionType: 'users' }));
  */
-export declare function whereStringHasRootIdentityModelKey<T = object>(orderByFieldPath: FieldPathOrStringPathOf<T> | FieldPathOrStringPath, value: RootFirestoreModelIdentity, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
+export declare function whereStringHasRootIdentityModelKey<T = object>(orderByFieldPath: FieldPathOrStringPathOf<T> | FieldPathOrStringPath, value: RootFirestoreModelIdentity, sortDirection?: OrderByDirection): FirestoreQueryOrderByRangeBoundsTuple;
 /**
  * Creates constraints to find documents where a string field starts with a specific prefix.
  *
@@ -97,8 +117,8 @@ export declare function whereStringHasRootIdentityModelKey<T = object>(orderByFi
  * const query = collection(firestore, 'users')
  *   .where(...whereStringValueHasPrefix('email', 'admin@'));
  */
-export declare function whereStringValueHasPrefix<T>(orderByFieldPath: StringKeyPropertyKeys<T>, parentValue: string, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
-export declare function whereStringValueHasPrefix(orderByFieldPath: FieldPathOrStringPath, parentValue: string, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
+export declare function whereStringValueHasPrefix<T>(orderByFieldPath: StringKeyPropertyKeys<T>, parentValue: string, sortDirection?: OrderByDirection): FirestoreQueryOrderByRangeBoundsTuple;
+export declare function whereStringValueHasPrefix(orderByFieldPath: FieldPathOrStringPath, parentValue: string, sortDirection?: OrderByDirection): FirestoreQueryOrderByRangeBoundsTuple;
 /**
  * Creates constraints to filter documents by a date field within a specific date range.
  *
@@ -138,8 +158,8 @@ export declare function filterWithDateRange(field: FieldPathOrStringPath, dateRa
  * const query = collection(firestore, 'documents')
  *   .where(...whereDateIsInRange('createdAt', { month: 0, year: 2023 }));
  */
-export declare function whereDateIsInRange<T>(field: StringKeyPropertyKeys<T>, rangeInput: DateRangeInput, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
-export declare function whereDateIsInRange(field: FieldPathOrStringPath, rangeInput: DateRangeInput, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
+export declare function whereDateIsInRange<T>(field: StringKeyPropertyKeys<T>, rangeInput: DateRangeInput, sortDirection?: OrderByDirection): FirestoreQueryOrderByAndRangeWhereTuple;
+export declare function whereDateIsInRange(field: FieldPathOrStringPath, rangeInput: DateRangeInput, sortDirection?: OrderByDirection): FirestoreQueryOrderByAndRangeWhereTuple;
 /**
  * Creates constraints to filter documents where a date field falls within a half-open range `[start, end)`.
  *
@@ -151,8 +171,8 @@ export declare function whereDateIsInRange(field: FieldPathOrStringPath, rangeIn
  * @param sortDirection - Direction to sort results (default: 'asc')
  * @returns Array of query constraints for the date range filter and sort
  */
-export declare function whereDateIsBetween<T>(field: StringKeyPropertyKeys<T>, range: DateRange, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
-export declare function whereDateIsBetween(field: FieldPathOrStringPath, range: DateRange, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
+export declare function whereDateIsBetween<T>(field: StringKeyPropertyKeys<T>, range: DateRange, sortDirection?: OrderByDirection): FirestoreQueryOrderByAndRangeWhereTuple;
+export declare function whereDateIsBetween(field: FieldPathOrStringPath, range: DateRange, sortDirection?: OrderByDirection): FirestoreQueryOrderByAndRangeWhereTuple;
 /**
  * Creates a constraint to filter documents where a date field is greater than or equal to a specified date.
  *
@@ -174,8 +194,8 @@ export declare function whereDateIsBetween(field: FieldPathOrStringPath, range:
  * const query = collection(firestore, 'documents')
  *   .where(whereDateIsOnOrAfter('createdAt', startOfYear));
  */
-export declare function whereDateIsOnOrAfter<T>(field: StringKeyPropertyKeys<T>, date?: Date): FirestoreQueryConstraint;
-export declare function whereDateIsOnOrAfter(field: FieldPathOrStringPath, date?: Date): FirestoreQueryConstraint;
+export declare function whereDateIsOnOrAfter<T>(field: StringKeyPropertyKeys<T>, date?: Date): FirestoreQueryConstraint<WhereQueryConstraintData>;
+export declare function whereDateIsOnOrAfter(field: FieldPathOrStringPath, date?: Date): FirestoreQueryConstraint<WhereQueryConstraintData>;
 /**
  * Creates constraints to filter documents by dates on or after a specified date, with sorting.
  *
@@ -194,8 +214,8 @@ export declare function whereDateIsOnOrAfter(field: FieldPathOrStringPath, date?
  * const query = collection(firestore, 'documents')
  *   .where(...whereDateIsOnOrAfterWithSort('createdAt', new Date(), 'desc'));
  */
-export declare function whereDateIsOnOrAfterWithSort<T>(field: StringKeyPropertyKeys<T>, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
-export declare function whereDateIsOnOrAfterWithSort(field: FieldPathOrStringPath, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
+export declare function whereDateIsOnOrAfterWithSort<T>(field: StringKeyPropertyKeys<T>, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryOrderByAndWhereTuple;
+export declare function whereDateIsOnOrAfterWithSort(field: FieldPathOrStringPath, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryOrderByAndWhereTuple;
 /**
  * Creates a constraint to filter documents where a date field is less than or equal to a specified date.
  *
@@ -205,8 +225,8 @@ export declare function whereDateIsOnOrAfterWithSort(field: FieldPathOrStringPat
  * @param date - The maximum date to include (default: current date/time)
  * @returns A query constraint for dates on or before the specified date
  */
-export declare function whereDateIsOnOrBefore<T>(field: StringKeyPropertyKeys<T>, date?: Date): FirestoreQueryConstraint;
-export declare function whereDateIsOnOrBefore(field: FieldPathOrStringPath, date?: Date): FirestoreQueryConstraint;
+export declare function whereDateIsOnOrBefore<T>(field: StringKeyPropertyKeys<T>, date?: Date): FirestoreQueryConstraint<WhereQueryConstraintData>;
+export declare function whereDateIsOnOrBefore(field: FieldPathOrStringPath, date?: Date): FirestoreQueryConstraint<WhereQueryConstraintData>;
 /**
  * Creates constraints to filter documents where a date field is on or before a specified date, with sorting.
  *
@@ -219,8 +239,8 @@ export declare function whereDateIsOnOrBefore(field: FieldPathOrStringPath, date
  * @param sortDirection - Direction to sort results (default: 'desc')
  * @returns Array of query constraints for filtering and sorting
  */
-export declare function whereDateIsOnOrBeforeWithSort<T>(field: StringKeyPropertyKeys<T>, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
-export declare function whereDateIsOnOrBeforeWithSort(field: FieldPathOrStringPath, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
+export declare function whereDateIsOnOrBeforeWithSort<T>(field: StringKeyPropertyKeys<T>, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryOrderByAndWhereTuple;
+export declare function whereDateIsOnOrBeforeWithSort(field: FieldPathOrStringPath, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryOrderByAndWhereTuple;
 /**
  * Creates a constraint to filter documents where a date field is strictly after a specified date.
  *
@@ -230,8 +250,8 @@ export declare function whereDateIsOnOrBeforeWithSort(field: FieldPathOrStringPa
  * @param date - The exclusive lower bound date (default: current date/time)
  * @returns A query constraint for dates strictly after the specified date
  */
-export declare function whereDateIsAfter<T>(field: StringKeyPropertyKeys<T>, date?: Date): FirestoreQueryConstraint;
-export declare function whereDateIsAfter(field: FieldPathOrStringPath, date?: Date): FirestoreQueryConstraint;
+export declare function whereDateIsAfter<T>(field: StringKeyPropertyKeys<T>, date?: Date): FirestoreQueryConstraint<WhereQueryConstraintData>;
+export declare function whereDateIsAfter(field: FieldPathOrStringPath, date?: Date): FirestoreQueryConstraint<WhereQueryConstraintData>;
 /**
  * Creates constraints to filter documents where a date field is strictly after a specified date, with sorting.
  *
@@ -243,8 +263,8 @@ export declare function whereDateIsAfter(field: FieldPathOrStringPath, date?: Da
  * @param sortDirection - Direction to sort results (default: 'asc')
  * @returns Array of query constraints for filtering and sorting
  */
-export declare function whereDateIsAfterWithSort<T>(field: StringKeyPropertyKeys<T>, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
-export declare function whereDateIsAfterWithSort(field: FieldPathOrStringPath, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
+export declare function whereDateIsAfterWithSort<T>(field: StringKeyPropertyKeys<T>, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryOrderByAndWhereTuple;
+export declare function whereDateIsAfterWithSort(field: FieldPathOrStringPath, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryOrderByAndWhereTuple;
 /**
  * Creates a constraint to filter documents where a date field is strictly before a specified date.
  *
@@ -254,8 +274,8 @@ export declare function whereDateIsAfterWithSort(field: FieldPathOrStringPath, d
  * @param date - The exclusive upper bound date (default: current date/time)
  * @returns A query constraint for dates strictly before the specified date
  */
-export declare function whereDateIsBefore<T>(field: StringKeyPropertyKeys<T>, date?: Date): FirestoreQueryConstraint;
-export declare function whereDateIsBefore(field: FieldPathOrStringPath, date?: Date): FirestoreQueryConstraint;
+export declare function whereDateIsBefore<T>(field: StringKeyPropertyKeys<T>, date?: Date): FirestoreQueryConstraint<WhereQueryConstraintData>;
+export declare function whereDateIsBefore(field: FieldPathOrStringPath, date?: Date): FirestoreQueryConstraint<WhereQueryConstraintData>;
 /**
  * Creates constraints to filter documents where a date field is strictly before a specified date, with sorting.
  *
@@ -268,5 +288,5 @@ export declare function whereDateIsBefore(field: FieldPathOrStringPath, date?: D
  * @param sortDirection - Direction to sort results (default: 'desc')
  * @returns Array of query constraints for filtering and sorting
  */
-export declare function whereDateIsBeforeWithSort<T>(field: StringKeyPropertyKeys<T>, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
-export declare function whereDateIsBeforeWithSort(field: FieldPathOrStringPath, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
+export declare function whereDateIsBeforeWithSort<T>(field: StringKeyPropertyKeys<T>, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryOrderByAndWhereTuple;
+export declare function whereDateIsBeforeWithSort(field: FieldPathOrStringPath, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryOrderByAndWhereTuple;

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

@@ -0,0 +1,19 @@
+/**
+ * Marker interface for a Firestore model whose document id IS the id of a
+ * record in an external system (e.g. a Zoho candidate id, a CheckHQ payroll
+ * id, a Typeform response id). Generic over a phantom `TId` discriminator so
+ * different external systems' ids do not interchange at compile-time.
+ *
+ * The phantom `__externalIdType` field is never persisted — it only exists in
+ * the TypeScript surface so semantic-typed external-id aliases (`type
+ * HellosubsZohoRecruitCandidateId = string`) flow through.
+ *
+ * The `extract-firebase-models` extractor recognises the exact-name marker
+ * and emits the `external-id-keyed-entity-root` archetype on the model.
+ */
+export interface ExternalRelatedById<TId extends string = string> {
+    /**
+     * Phantom type discriminator; never persisted.
+     */
+    readonly __externalIdType?: TId;
+}

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

@@ -1,3 +1,4 @@
+export * from './external';
 export * from './user';
 export * from './notification';
 export * from './oidcmodel';

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

@@ -194,6 +194,9 @@ export declare const NOTIFICATION_SUMMARY_EMBEDDED_NOTIFICATION_ITEM_MESSAGE_MAX
  * Implements {@link InitializedNotificationModel} — requires server-side initialization to populate the owner (`o`) field.
  *
  * @dbxModel
+ * @dbxModelArchetype root-singleton-aggregate
+ * @dbxModelArchetype composite-key-root
+ * @dbxModelCompositeKey from=* encoding=two-way
  */
 export interface NotificationSummary extends InitializedNotificationModel {
     /**
@@ -288,6 +291,8 @@ export declare const notificationBoxIdentity: import("../..").RootFirestoreModel
  * @see `NotificationServerActions.createNotificationBox` in `@dereekb/firebase-server/model` for creation logic
  *
  * @dbxModel
+ * @dbxModelArchetype composite-key-root
+ * @dbxModelCompositeKey from=* encoding=two-way
  */
 export interface NotificationBox extends InitializedNotificationModel {
     /**

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

@@ -46,6 +46,7 @@ export declare const OIDC_ENTRY_CLIENT_TYPE: OidcEntryType;
  * (used primarily for Client entries so users can query their own registered OAuth clients).
  *
  * @dbxModel
+ * @dbxModelArchetype reference-registry hasChildren=false,hasInheritance=false
  */
 export interface OidcEntry {
     /**

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

@@ -262,6 +262,8 @@ export type StorageFileDownloadUrl = StorageFilePublicDownloadUrl | StorageFileS
  *
  * @template M - type of the arbitrary metadata stored in the `d` field
  * @dbxModel
+ * @dbxModelArchetype root-entity
+ * @dbxModelArchetype state-machine-item
  */
 export interface StorageFile<M extends StorageFileMetadata = StorageFileMetadata> extends StoragePath {
     /**

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

@@ -60,6 +60,7 @@ export type SystemStateStoredData = Record<string, any>;
  *
  * @template T - shape of the stored data record
  * @dbxModel
+ * @dbxModelArchetype system-state-singleton
  */
 export interface SystemState<T extends SystemStateStoredData = SystemStateStoredData> {
     /**

package/test/package.json

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