update comments and changeset

Author: Brian Chen

.changeset/dirty-pandas-pay.md

@@ -3,4 +3,8 @@
 '@firebase/firestore': major
 ---
 
-Added support for FieldValues when using a FirestoreDataConverter and support for update() calls with a converter
+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.

packages/firestore/src/lite/reference.ts

@@ -75,7 +75,8 @@ export type WithFieldValue<T> = T extends Primitive
 /**
  * Update data (for use with {@link (setDoc:1)}) that consists of field paths
  * (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots
- * reference nested fields within the document.
+ * reference nested fields within the document. FieldValues can be passed in
+ * as property values.
  */
 export type UpdateData<T> = T extends Primitive
   ? T

packages/firestore/src/lite/types.ts

@@ -17,6 +17,12 @@
 
 import { UpdateData } from './reference';
 
+/**
+ * These types primarily exist to support the `UpdateData`,
+ * `WithFieldValue`, and `PartialWithFieldValue` types and are not consumed
+ * directly by the end developer.
+ */
+
 /** Primitive types. */
 export type Primitive = string | number | boolean | undefined | null;
 

packages/firestore/test/lite/integration.test.ts

@@ -1285,10 +1285,8 @@ describe('withConverter() support', () => {
       };
 
       it('supports FieldValues', async () => {
-        return withTestDb(async db => {
-          const ref = doc(collection(db, 'testobj')).withConverter(
-            testConverterMerge
-          );
+        return withTestDoc(async doc => {
+          const ref = doc.withConverter(testConverter);
 
           // Allow Field Values in nested partials.
           await setDoc(
@@ -1318,10 +1316,8 @@ describe('withConverter() support', () => {
       });
 
       it('validates types in outer and inner fields', async () => {
-        return withTestDb(async db => {
-          const ref = doc(collection(db, 'testobj')).withConverter(
-            testConverterMerge
-          );
+        return withTestDoc(async doc => {
+          const ref = doc.withConverter(testConverter);
 
           // Check top-level fields.
           await setDoc(
@@ -1362,10 +1358,8 @@ describe('withConverter() support', () => {
       });
 
       it('checks for nonexistent properties', async () => {
-        return withTestDb(async db => {
-          const ref = doc(collection(db, 'testobj')).withConverter(
-            testConverterMerge
-          );
+        return withTestDoc(async doc => {
+          const ref = doc.withConverter(testConverter);
           // Top-level property.
           await setDoc(
             ref,
@@ -1393,10 +1387,8 @@ describe('withConverter() support', () => {
 
     describe('WithFieldValue', () => {
       it('supports FieldValues', async () => {
-        return withTestDb(async db => {
-          const ref = doc(collection(db, 'testobj')).withConverter(
-            testConverter
-          );
+        return withTestDoc(async doc => {
+          const ref = doc.withConverter(testConverter);
 
           // Allow Field Values and nested partials.
           await setDoc(ref, {
@@ -1414,10 +1406,8 @@ describe('withConverter() support', () => {
       });
 
       it('requires all fields to be present', async () => {
-        return withTestDb(async db => {
-          const ref = doc(collection(db, 'testobj')).withConverter(
-            testConverter
-          );
+        return withTestDoc(async doc => {
+          const ref = doc.withConverter(testConverter);
 
           // Allow Field Values and nested partials.
           // @ts-expect-error
@@ -1435,10 +1425,8 @@ describe('withConverter() support', () => {
       });
 
       it('validates inner and outer fields', async () => {
-        return withTestDb(async db => {
-          const ref = doc(collection(db, 'testobj')).withConverter(
-            testConverter
-          );
+        return withTestDoc(async doc => {
+          const ref = doc.withConverter(testConverter);
 
           await setDoc(ref, {
             outerString: 'foo',
@@ -1457,10 +1445,8 @@ describe('withConverter() support', () => {
       });
 
       it('checks for nonexistent properties', async () => {
-        return withTestDb(async db => {
-          const ref = doc(collection(db, 'testobj')).withConverter(
-            testConverter
-          );
+        return withTestDoc(async doc => {
+          const ref = doc.withConverter(testConverter);
 
           // Top-level nonexistent fields should error
           await setDoc(ref, {
@@ -1590,8 +1576,8 @@ describe('withConverter() support', () => {
 
     describe('methods', () => {
       it('addDoc()', () => {
-        return withTestDb(async db => {
-          const ref = collection(db, 'testobj').withConverter(testConverter);
+        return withTestDoc(async doc => {
+          const ref = doc.withConverter(testConverter);
 
           // Requires all fields to be present
           // @ts-expect-error