Firestore: QoL improvements for converters

.changeset/dirty-pandas-pay.md

@@ -0,0 +1,10 @@
+---
+'firebase': major
+'@firebase/firestore': major
+---
+
+This change contains multiple quality-of-life improvements when using the `FirestoreDataConverter` in `@firebase/firestore/lite` and `@firebase/firestore/exp`:
+- Support for passing in `FieldValue` property values when using a converter (via `WithFieldValue<T>` and `PartialWithFieldValue<T>`).
+- Support for omitting properties in nested fields when performing a set operation with `{merge: true}` with a converter (via `PartialWithFieldValue<T>`).
+- [breaking] Support for typed update operations when using a converter (via the newly typed `UpdateData`). Improperly typed fields in
+update operations on typed document references will no longer compile.

common/api-review/firestore-lite.api.md

@@ -9,7 +9,12 @@ import { FirebaseApp } from '@firebase/app-exp';
 import { LogLevelString as LogLevel } from '@firebase/logger';
 
 // @public
-export function addDoc<T>(reference: CollectionReference<T>, data: T): Promise<DocumentReference<T>>;
+export function addDoc<T>(reference: CollectionReference<T>, data: WithFieldValue<T>): Promise<DocumentReference<T>>;
+
+// @public
+export type AddPrefixToKeys<Prefix extends string, T extends Record<string, unknown>> = {
+    [K in keyof T & string as `${Prefix}.${K}`]+?: T[K];
+};
 
 // @public
 export function arrayRemove(...elements: unknown[]): FieldValue;
@@ -132,8 +137,8 @@ export class Firestore {
 // @public
 export interface FirestoreDataConverter<T> {
     fromFirestore(snapshot: QueryDocumentSnapshot<DocumentData>): T;
-    toFirestore(modelObject: T): DocumentData;
-    toFirestore(modelObject: Partial<T>, options: SetOptions): DocumentData;
+    toFirestore(modelObject: WithFieldValue<T>): DocumentData;
+    toFirestore(modelObject: PartialWithFieldValue<T>, options: SetOptions): DocumentData;
 }
 
 // @public
@@ -182,12 +187,25 @@ export function limitToLast(limit: number): QueryConstraint;
 
 export { LogLevel }
 
+// @public
+export type NestedUpdateFields<T extends Record<string, unknown>> = UnionToIntersection<{
+    [K in keyof T & string]: T[K] extends Record<string, unknown> ? AddPrefixToKeys<K, UpdateData<T[K]>> : never;
+}[keyof T & string]>;
+
 // @public
 export function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryConstraint;
 
 // @public
 export type OrderByDirection = 'desc' | 'asc';
 
+// @public
+export type PartialWithFieldValue<T> = T extends Primitive ? T : T extends Map<infer K, infer V> ? Map<PartialWithFieldValue<K>, PartialWithFieldValue<V>> : T extends {} ? {
+    [K in keyof T]?: PartialWithFieldValue<T[K]> | FieldValue;
+} : Partial<T>;
+
+// @public
+export type Primitive = string | number | boolean | undefined | null;
+
 // @public
 export class Query<T = DocumentData> {
     protected constructor();
@@ -237,10 +255,10 @@ export function runTransaction<T>(firestore: Firestore, updateFunction: (transac
 export function serverTimestamp(): FieldValue;
 
 // @public
-export function setDoc<T>(reference: DocumentReference<T>, data: T): Promise<void>;
+export function setDoc<T>(reference: DocumentReference<T>, data: WithFieldValue<T>): Promise<void>;
 
 // @public
-export function setDoc<T>(reference: DocumentReference<T>, data: Partial<T>, options: SetOptions): Promise<void>;
+export function setDoc<T>(reference: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions): Promise<void>;
 
 // @public
 export function setLogLevel(logLevel: LogLevel): void;
@@ -302,19 +320,22 @@ export class Timestamp {
 export class Transaction {
     delete(documentRef: DocumentReference<unknown>): this;
     get<T>(documentRef: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
-    set<T>(documentRef: DocumentReference<T>, data: T): this;
-    set<T>(documentRef: DocumentReference<T>, data: Partial<T>, options: SetOptions): this;
-    update(documentRef: DocumentReference<unknown>, data: UpdateData): this;
+    set<T>(documentRef: DocumentReference<T>, data: WithFieldValue<T>): this;
+    set<T>(documentRef: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions): this;
+    update<T>(documentRef: DocumentReference<T>, data: UpdateData<T>): this;
     update(documentRef: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): this;
 }
 
 // @public
-export interface UpdateData {
-    [fieldPath: string]: any;
-}
+export type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
 
 // @public
-export function updateDoc(reference: DocumentReference<unknown>, data: UpdateData): Promise<void>;
+export type UpdateData<T> = T extends Primitive ? T : T extends Map<infer K, infer V> ? Map<UpdateData<K>, UpdateData<V>> : T extends {} ? {
+    [K in keyof T]?: UpdateData<T[K]> | FieldValue;
+} & NestedUpdateFields<T> : Partial<T>;
+
+// @public
+export function updateDoc<T>(reference: DocumentReference<T>, data: UpdateData<T>): Promise<void>;
 
 // @public
 export function updateDoc(reference: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise<void>;
@@ -325,13 +346,18 @@ export function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value
 // @public
 export type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in';
 
+// @public
+export type WithFieldValue<T> = T extends Primitive ? T : T extends {} ? {
+    [K in keyof T]: WithFieldValue<T[K]> | FieldValue;
+} : Partial<T>;
+
 // @public
 export class WriteBatch {
     commit(): Promise<void>;
     delete(documentRef: DocumentReference<unknown>): WriteBatch;
-    set<T>(documentRef: DocumentReference<T>, data: T): WriteBatch;
-    set<T>(documentRef: DocumentReference<T>, data: Partial<T>, options: SetOptions): WriteBatch;
-    update(documentRef: DocumentReference<unknown>, data: UpdateData): WriteBatch;
+    set<T>(documentRef: DocumentReference<T>, data: WithFieldValue<T>): WriteBatch;
+    set<T>(documentRef: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions): WriteBatch;
+    update<T>(documentRef: DocumentReference<T>, data: UpdateData<T>): WriteBatch;
     update(documentRef: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): WriteBatch;
 }
 

common/api-review/firestore.api.md

@@ -9,7 +9,12 @@ import { FirebaseApp } from '@firebase/app-exp';
 import { LogLevelString as LogLevel } from '@firebase/logger';
 
 // @public
-export function addDoc<T>(reference: CollectionReference<T>, data: T): Promise<DocumentReference<T>>;
+export function addDoc<T>(reference: CollectionReference<T>, data: WithFieldValue<T>): Promise<DocumentReference<T>>;
+
+// @public
+export type AddPrefixToKeys<Prefix extends string, T extends Record<string, unknown>> = {
+    [K in keyof T & string as `${Prefix}.${K}`]+?: T[K];
+};
 
 // @public
 export function arrayRemove(...elements: unknown[]): FieldValue;
@@ -162,8 +167,8 @@ export class Firestore {
 // @public
 export interface FirestoreDataConverter<T> {
     fromFirestore(snapshot: QueryDocumentSnapshot<DocumentData>, options?: SnapshotOptions): T;
-    toFirestore(modelObject: T): DocumentData;
-    toFirestore(modelObject: Partial<T>, options: SetOptions): DocumentData;
+    toFirestore(modelObject: WithFieldValue<T>): DocumentData;
+    toFirestore(modelObject: PartialWithFieldValue<T>, options: SetOptions): DocumentData;
 }
 
 // @public
@@ -256,6 +261,11 @@ export { LogLevel }
 // @public
 export function namedQuery(firestore: Firestore, name: string): Promise<Query | null>;
 
+// @public
+export type NestedUpdateFields<T extends Record<string, unknown>> = UnionToIntersection<{
+    [K in keyof T & string]: T[K] extends Record<string, unknown> ? AddPrefixToKeys<K, UpdateData<T[K]>> : never;
+}[keyof T & string]>;
+
 // @public
 export function onSnapshot<T>(reference: DocumentReference<T>, observer: {
     next?: (snapshot: DocumentSnapshot<T>) => void;
@@ -312,11 +322,19 @@ export function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDir
 // @public
 export type OrderByDirection = 'desc' | 'asc';
 
+// @public
+export type PartialWithFieldValue<T> = T extends Primitive ? T : T extends Map<infer K, infer V> ? Map<PartialWithFieldValue<K>, PartialWithFieldValue<V>> : T extends {} ? {
+    [K in keyof T]?: PartialWithFieldValue<T[K]> | FieldValue;
+} : Partial<T>;
+
 // @public
 export interface PersistenceSettings {
     forceOwnership?: boolean;
 }
 
+// @public
+export type Primitive = string | number | boolean | undefined | null;
+
 // @public
 export class Query<T = DocumentData> {
     protected constructor();
@@ -368,10 +386,10 @@ export function runTransaction<T>(firestore: Firestore, updateFunction: (transac
 export function serverTimestamp(): FieldValue;
 
 // @public
-export function setDoc<T>(reference: DocumentReference<T>, data: T): Promise<void>;
+export function setDoc<T>(reference: DocumentReference<T>, data: WithFieldValue<T>): Promise<void>;
 
 // @public
-export function setDoc<T>(reference: DocumentReference<T>, data: Partial<T>, options: SetOptions): Promise<void>;
+export function setDoc<T>(reference: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions): Promise<void>;
 
 // @public
 export function setLogLevel(logLevel: LogLevel): void;
@@ -446,24 +464,27 @@ export class Timestamp {
 export class Transaction {
     delete(documentRef: DocumentReference<unknown>): this;
     get<T>(documentRef: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
-    set<T>(documentRef: DocumentReference<T>, data: T): this;
-    set<T>(documentRef: DocumentReference<T>, data: Partial<T>, options: SetOptions): this;
-    update(documentRef: DocumentReference<unknown>, data: UpdateData): this;
+    set<T>(documentRef: DocumentReference<T>, data: WithFieldValue<T>): this;
+    set<T>(documentRef: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions): this;
+    update<T>(documentRef: DocumentReference<T>, data: UpdateData<T>): this;
     update(documentRef: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): this;
 }
 
+// @public
+export type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+
 // @public
 export interface Unsubscribe {
     (): void;
 }
 
 // @public
-export interface UpdateData {
-    [fieldPath: string]: any;
-}
+export type UpdateData<T> = T extends Primitive ? T : T extends Map<infer K, infer V> ? Map<UpdateData<K>, UpdateData<V>> : T extends {} ? {
+    [K in keyof T]?: UpdateData<T[K]> | FieldValue;
+} & NestedUpdateFields<T> : Partial<T>;
 
 // @public
-export function updateDoc(reference: DocumentReference<unknown>, data: UpdateData): Promise<void>;
+export function updateDoc<T>(reference: DocumentReference<T>, data: UpdateData<T>): Promise<void>;
 
 // @public
 export function updateDoc(reference: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise<void>;
@@ -477,13 +498,18 @@ export function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value
 // @public
 export type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in';
 
+// @public
+export type WithFieldValue<T> = T extends Primitive ? T : T extends {} ? {
+    [K in keyof T]: WithFieldValue<T[K]> | FieldValue;
+} : Partial<T>;
+
 // @public
 export class WriteBatch {
     commit(): Promise<void>;
     delete(documentRef: DocumentReference<unknown>): WriteBatch;
-    set<T>(documentRef: DocumentReference<T>, data: T): WriteBatch;
-    set<T>(documentRef: DocumentReference<T>, data: Partial<T>, options: SetOptions): WriteBatch;
-    update(documentRef: DocumentReference<unknown>, data: UpdateData): WriteBatch;
+    set<T>(documentRef: DocumentReference<T>, data: WithFieldValue<T>): WriteBatch;
+    set<T>(documentRef: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions): WriteBatch;
+    update<T>(documentRef: DocumentReference<T>, data: UpdateData<T>): WriteBatch;
     update(documentRef: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): WriteBatch;
 }
 

packages/firebase/index.d.ts

@@ -7852,9 +7852,13 @@ declare namespace firebase.storage {
      * @param port - The emulator port (ex: 5001)
      * @param options.mockUserToken the mock auth token to use for unit testing Security Rules
      */
-    useEmulator(host: string, port: number, options?: {
-      mockUserToken?: EmulatorMockTokenOptions | string;
-    }): void;
+    useEmulator(
+      host: string,
+      port: number,
+      options?: {
+        mockUserToken?: EmulatorMockTokenOptions | string;
+      }
+    ): void;
   }
 
   /**

packages/firestore/compat/config.ts

@@ -22,7 +22,7 @@ import { _FirebaseNamespace } from '@firebase/app-types/private';
 import { Component, ComponentType } from '@firebase/component';
 
 import {
-  FirebaseFirestore,
+  Firestore as FirebaseFirestore,
   CACHE_SIZE_UNLIMITED,
   GeoPoint,
   Timestamp

packages/firestore/exp/api.ts

@@ -64,6 +64,8 @@ export {
   SetOptions,
   DocumentData,
   UpdateData,
+  WithFieldValue,
+  PartialWithFieldValue,
   refEqual,
   queryEqual
 } from '../src/exp/reference';
@@ -129,3 +131,10 @@ export { CACHE_SIZE_UNLIMITED } from '../src/exp/database';
 export { FirestoreErrorCode, FirestoreError } from '../src/util/error';
 
 export { AbstractUserDataWriter } from '../src/lite/user_data_writer';
+
+export {
+  Primitive,
+  NestedUpdateFields,
+  AddPrefixToKeys,
+  UnionToIntersection
+} from '../src/lite/types';

packages/firestore/lite/index.ts

@@ -38,9 +38,11 @@ export {
 } from '../src/lite/database';
 
 export {
-  SetOptions,
   DocumentData,
   UpdateData,
+  WithFieldValue,
+  PartialWithFieldValue,
+  SetOptions,
   DocumentReference,
   Query,
   CollectionReference,
@@ -76,6 +78,13 @@ export {
   getDocs
 } from '../src/lite/reference_impl';
 
+export {
+  Primitive,
+  NestedUpdateFields,
+  AddPrefixToKeys,
+  UnionToIntersection
+} from '../src/lite/types';
+
 // TOOD(firestorelite): Add tests when Queries are usable
 export { FieldPath, documentId } from '../src/lite/field_path';