Add addDoc function overloading to accept DocumentRef

.changeset/silly-seahorses-jump.md

@@ -0,0 +1,5 @@
+---
+'@firebase/firestore': minor
+---
+
+Add addDoc function overloading to accept DocumentRef

common/api-review/firestore.api.md

@@ -9,6 +9,9 @@ import { FirebaseApp } from '@firebase/app';
 import { FirebaseError } from '@firebase/util';
 import { LogLevelString as LogLevel } from '@firebase/logger';
 
+// @public
+export function addDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, data: WithFieldValue<AppModelType>): Promise<DocumentReference<AppModelType, DbModelType>>;
+
 // @public
 export function addDoc<AppModelType, DbModelType extends DocumentData>(reference: CollectionReference<AppModelType, DbModelType>, data: WithFieldValue<AppModelType>): Promise<DocumentReference<AppModelType, DbModelType>>;
 

packages/firestore/src/api/reference_impl.ts

@@ -438,6 +438,20 @@ export function deleteDoc<AppModelType, DbModelType extends DocumentData>(
   return executeWrite(firestore, mutations);
 }
 
+/**
+ * Add a new document to specified `DocReference` with the given data.
+ *
+ * @param reference - A reference to the document to add.
+ * @param data - An Object containing the data for the new document.
+ * @returns A `Promise` resolved with a `DocumentReference` pointing to the
+ * newly created document after it has been written to the backend (Note that it
+ * won't resolve while you're offline).
+ * @throws FirestoreError if the document already exists.
+ */
+export function addDoc<AppModelType, DbModelType extends DocumentData>(
+  reference: DocumentReference<AppModelType, DbModelType>,
+  data: WithFieldValue<AppModelType>
+): Promise<DocumentReference<AppModelType, DbModelType>>;
 /**
  * Add a new document to specified `CollectionReference` with the given data,
  * assigning it a document ID automatically.
@@ -451,10 +465,17 @@ export function deleteDoc<AppModelType, DbModelType extends DocumentData>(
 export function addDoc<AppModelType, DbModelType extends DocumentData>(
   reference: CollectionReference<AppModelType, DbModelType>,
   data: WithFieldValue<AppModelType>
+): Promise<DocumentReference<AppModelType, DbModelType>>;
+export function addDoc<AppModelType, DbModelType extends DocumentData>(
+  reference:
+    | CollectionReference<AppModelType, DbModelType>
+    | DocumentReference<AppModelType, DbModelType>,
+  data: WithFieldValue<AppModelType>
 ): Promise<DocumentReference<AppModelType, DbModelType>> {
   const firestore = cast(reference.firestore, Firestore);
 
-  const docRef = doc(reference);
+  const docRef =
+    reference instanceof DocumentReference ? reference : doc(reference);
   const convertedValue = applyFirestoreDataConverter(reference.converter, data);
 
   const dataReader = newUserDataReader(reference.firestore);

packages/firestore/test/integration/api/database.test.ts

@@ -16,7 +16,7 @@
  */
 
 import { deleteApp } from '@firebase/app';
-import { Deferred } from '@firebase/util';
+import { Deferred, FirebaseError } from '@firebase/util';
 import { expect, use } from 'chai';
 import chaiAsPromised from 'chai-as-promised';
 
@@ -106,6 +106,33 @@ apiDescribe('Database', persistence => {
     });
   });
 
+  it('can add a document with DocRef', () => {
+    return withTestCollection(persistence, {}, async coll => {
+      const docRef = doc(coll, 'foo');
+      await addDoc(docRef, { a: 'a' });
+      const docSnapshot = await getDoc(docRef);
+      expect(docSnapshot.data()).to.be.deep.equal({ a: 'a' });
+    });
+  });
+
+  it('can add a document with CollectionRef', () => {
+    return withTestCollection(persistence, {}, async coll => {
+      const docRef = await addDoc(coll, { a: 'a' });
+      const docSnapshot = await getDoc(docRef);
+      expect(docSnapshot.data()).to.be.deep.equal({ a: 'a' });
+    });
+  });
+
+  it("can't add a document with duplicated id", () => {
+    return withTestDoc(persistence, async docRef => {
+      await addDoc(docRef, { a: 'a' });
+      await expect(addDoc(docRef, { a: 'a' })).to.be.rejectedWith(
+        FirebaseError,
+        'Document already exists:'
+      );
+    });
+  });
+
   it('can delete a document', () => {
     // TODO(#1865): This test fails with node:persistence against Prod
     return withTestDoc(persistence, docRef => {