Allow type T in WithFieldValue<T>

Author: Brian Chen

.changeset/short-mice-itch.md

@@ -0,0 +1,5 @@
+---
+'@firebase/firestore': minor
+---
+
+Expanded `Firestore.WithFieldValue<T>` to include `T`. This allows developers to delegate `WithFieldValue<T>` inside a wrappers of type `T` to avoid exposing Firebase types beyond Firebase-specific logic.

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

@@ -204,9 +204,7 @@ export function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDir
 export type OrderByDirection = 'desc' | 'asc';
 
 // @public
-export type PartialWithFieldValue<T> = T extends Primitive ? T : T extends {} ? {
-    [K in keyof T]?: PartialWithFieldValue<T[K]> | FieldValue;
-} : Partial<T>;
+export type PartialWithFieldValue<T> = Partial<WithFieldValue<T>>;
 
 // @public
 export type Primitive = string | number | boolean | undefined | null;
@@ -352,9 +350,9 @@ export function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value
 export type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in';
 
 // @public
-export type WithFieldValue<T> = T extends Primitive ? T : T extends {} ? {
+export type WithFieldValue<T> = T | (T extends Primitive ? T : T extends {} ? {
     [K in keyof T]: WithFieldValue<T[K]> | FieldValue;
-} : Partial<T>;
+} : Partial<T>);
 
 // @public
 export class WriteBatch {

common/api-review/firestore.api.md

@@ -328,9 +328,7 @@ export function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDir
 export type OrderByDirection = 'desc' | 'asc';
 
 // @public
-export type PartialWithFieldValue<T> = T extends Primitive ? T : T extends {} ? {
-    [K in keyof T]?: PartialWithFieldValue<T[K]> | FieldValue;
-} : Partial<T>;
+export type PartialWithFieldValue<T> = Partial<WithFieldValue<T>>;
 
 // @public
 export interface PersistenceSettings {
@@ -504,9 +502,9 @@ export function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value
 export type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in';
 
 // @public
-export type WithFieldValue<T> = T extends Primitive ? T : T extends {} ? {
+export type WithFieldValue<T> = T | (T extends Primitive ? T : T extends {} ? {
     [K in keyof T]: WithFieldValue<T[K]> | FieldValue;
-} : Partial<T>;
+} : Partial<T>);
 
 // @public
 export class WriteBatch {

packages/firestore/src/lite-api/reference.ts

@@ -54,22 +54,19 @@ export interface DocumentData {
  * Similar to Typescript's `Partial<T>`, but allows nested fields to be
  * omitted and FieldValues to be passed in as property values.
  */
-export type PartialWithFieldValue<T> = T extends Primitive
-  ? T
-  : T extends {}
-  ? { [K in keyof T]?: PartialWithFieldValue<T[K]> | FieldValue }
-  : Partial<T>;
+export type PartialWithFieldValue<T> = Partial<WithFieldValue<T>>;
 
 /**
  * Allows FieldValues to be passed in as a property value while maintaining
  * type safety.
  */
-export type WithFieldValue<T> = T extends Primitive
-  ? T
-  : T extends {}
-  ? { [K in keyof T]: WithFieldValue<T[K]> | FieldValue }
-  : Partial<T>;
-
+export type WithFieldValue<T> =
+  | T
+  | (T extends Primitive
+      ? T
+      : T extends {}
+      ? { [K in keyof T]: WithFieldValue<T[K]> | FieldValue }
+      : Partial<T>);
 /**
  * Update data (for use with {@link (updateDoc:1)}) that consists of field paths
  * (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots

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

@@ -1286,7 +1286,7 @@ describe('withConverter() support', () => {
       }
     };
 
-    describe('NestedPartial', () => {
+    describe('nested partial support', () => {
       const testConverterMerge = {
         toFirestore(
           testObj: PartialWithFieldValue<TestObject>,
@@ -1496,6 +1496,51 @@ describe('withConverter() support', () => {
           });
         });
       });
+
+      describe('used as a type', () => {
+        class ObjectWrapper<T> {
+          withFieldValueT(value: WithFieldValue<T>): void {
+            // eslint-disable-next-line no-console
+            console.log(value);
+          }
+
+          withPartialFieldValueT(value: PartialWithFieldValue<T>): void {
+            // eslint-disable-next-line no-console
+            console.log(value);
+          }
+
+          // Wrapper to avoid having Firebase types in non-Firebase code.
+          withT(value: T): void {
+            this.withFieldValueT(value);
+          }
+
+          // Wrapper to avoid having Firebase types in non-Firebase code.
+          withPartialT(value: Partial<T>): void {
+            this.withPartialFieldValueT(value);
+          }
+        }
+
+        it('supports passing in the object as `T`', () => {
+          interface Foo {
+            id: string;
+            foo: number;
+          }
+          const foo = new ObjectWrapper<Foo>();
+          foo.withFieldValueT({ id: '', foo: increment(1) });
+          foo.withPartialFieldValueT({ foo: increment(1) });
+          foo.withT({ id: '', foo: 1 });
+          foo.withPartialT({ foo: 1 });
+        });
+
+        it('does not allow primitive types to use FieldValue', () => {
+          type Bar = number;
+          const bar = new ObjectWrapper<Bar>();
+          // @ts-expect-error
+          bar.withFieldValueT(increment(1));
+          // @ts-expect-error
+          bar.withPartialFieldValueT(increment(1));
+        });
+      });
     });
 
     describe('UpdateData', () => {