docs: add @throws API comment for CRUD methods (#1647)

Author: schmidt-sebastian

dev/src/bulk-writer.ts

@@ -554,6 +554,7 @@ export class BulkWriter {
    * @param {DocumentReference} documentRef A reference to the document to be
    * created.
    * @param {T} data The object to serialize as the document.
+   * @throws {Error} If the provided input is not a valid Firestore document.
    * @returns {Promise<WriteResult>} A promise that resolves with the result of
    * the write. If the write fails, the promise is rejected with a
    * [BulkWriterError]{@link BulkWriterError}.
@@ -643,6 +644,7 @@ export class BulkWriter {
    * set.
    * @param {T} data The object to serialize as the document.
    * @param {SetOptions=} options An object to configure the set behavior.
+   * @throws {Error} If the provided input is not a valid Firestore document.
    * @param {boolean=} options.merge - If true, set() merges the values
    * specified in its data argument. Fields omitted from this set() call remain
    * untouched.
@@ -711,6 +713,7 @@ export class BulkWriter {
    * @param {...(Precondition|*|string|FieldPath)} preconditionOrValues - An
    * alternating list of field paths and values to update or a Precondition to
    * restrict this update
+   * @throws {Error} If the provided input is not valid Firestore data.
    * @returns {Promise<WriteResult>} A promise that resolves with the result of
    * the write. If the write fails, the promise is rejected with a
    * [BulkWriterError]{@link BulkWriterError}.

dev/src/reference.ts

@@ -359,6 +359,7 @@ export class DocumentReference<T = firestore.DocumentData>
    *
    * @param {DocumentData} data An object that contains the fields and data to
    * serialize as the document.
+   * @throws {Error} If the provided input is not a valid Firestore document.
    * @returns {Promise.<WriteResult>} A Promise that resolves with the
    * write time of this create.
    *
@@ -432,6 +433,7 @@ export class DocumentReference<T = firestore.DocumentData>
    * @param {Array.<string|FieldPath>=} options.mergeFields If provided,
    * set() only replaces the specified field paths. Any field path that is not
    * specified is ignored and remains untouched.
+   * @throws {Error} If the provided input is not a valid Firestore document.
    * @returns {Promise.<WriteResult>} A Promise that resolves with the
    * write time of this set.
    *
@@ -476,6 +478,7 @@ export class DocumentReference<T = firestore.DocumentData>
    * ...(*|string|FieldPath|Precondition)} preconditionOrValues An alternating
    * list of field paths and values to update or a Precondition to restrict
    * this update.
+   * @throws {Error} If the provided input is not valid Firestore data.
    * @returns {Promise.<WriteResult>} A Promise that resolves once the
    * data has been successfully written to the backend.
    *
@@ -2685,6 +2688,7 @@ export class CollectionReference<T = firestore.DocumentData>
    *
    * @param {DocumentData} data An Object containing the data for the new
    * document.
+   * @throws {Error} If the provided input is not a valid Firestore document.
    * @returns {Promise.<DocumentReference>} A Promise resolved with a
    * [DocumentReference]{@link DocumentReference} pointing to the
    * newly created document.

dev/src/transaction.ts

@@ -252,6 +252,7 @@ export class Transaction implements firestore.Transaction {
    * @param {Array.<string|FieldPath>=} options.mergeFields - If provided,
    * set() only replaces the specified field paths. Any field path that is not
    * specified is ignored and remains untouched.
+   * @throws {Error} If the provided input is not a valid Firestore document.
    * @returns {Transaction} This Transaction instance. Used for
    * chaining method calls.
    *
@@ -300,6 +301,7 @@ export class Transaction implements firestore.Transaction {
    * ...(Precondition|*|string|FieldPath)} preconditionOrValues -
    * An alternating list of field paths and values to update or a Precondition
    * to to enforce on this update.
+   * @throws {Error} If the provided input is not valid Firestore data.
    * @returns {Transaction} This Transaction instance. Used for
    * chaining method calls.
    *

dev/src/write-batch.ts

@@ -174,6 +174,7 @@ export class WriteBatch implements firestore.WriteBatch {
    * @param {DocumentReference} documentRef A reference to the document to be
    * created.
    * @param {T} data The object to serialize as the document.
+   * @throws {Error} If the provided input is not a valid Firestore document.
    * @returns {WriteBatch} This WriteBatch instance. Used for chaining
    * method calls.
    *
@@ -302,6 +303,7 @@ export class WriteBatch implements firestore.WriteBatch {
    * @param {Array.<string|FieldPath>=} options.mergeFields - If provided,
    * set() only replaces the specified field paths. Any field path that is not
    * specified is ignored and remains untouched.
+   * @throws {Error} If the provided input is not a valid Firestore document.
    * @returns {WriteBatch} This WriteBatch instance. Used for chaining
    * method calls.
    *
@@ -401,6 +403,7 @@ export class WriteBatch implements firestore.WriteBatch {
    * ...(Precondition|*|string|FieldPath)} preconditionOrValues -
    * An alternating list of field paths and values to update or a Precondition
    * to restrict this update.
+   * @throws {Error} If the provided input is not valid Firestore data.
    * @returns {WriteBatch} This WriteBatch instance. Used for chaining
    * method calls.
    *

types/firestore.d.ts

@@ -598,6 +598,7 @@ declare namespace FirebaseFirestore {
      *
      * @param documentRef A reference to the document to be create.
      * @param data The object data to serialize as the document.
+     * @throws Error If the provided input is not a valid Firestore document.
      * @return This `Transaction` instance. Used for chaining method calls.
      */
     create<T>(
@@ -613,6 +614,7 @@ declare namespace FirebaseFirestore {
      * @param documentRef A reference to the document to be set.
      * @param data An object of the fields and values for the document.
      * @param options An object to configure the set behavior.
+     * @throws Error If the provided input is not a valid Firestore document.
      * @return This `Transaction` instance. Used for chaining method calls.
      */
     set<T>(
@@ -637,6 +639,7 @@ declare namespace FirebaseFirestore {
      * @param data An object containing the fields and values with which to
      * update the document.
      * @param precondition A Precondition to enforce on this update.
+     * @throws Error If the provided input is not valid Firestore data.
      * @return This `Transaction` instance. Used for chaining method calls.
      */
     update<T>(
@@ -662,6 +665,7 @@ declare namespace FirebaseFirestore {
      * @param fieldsOrPrecondition An alternating list of field paths and values
      * to update, optionally followed by a `Precondition` to enforce on this
      * update.
+     * @throws Error If the provided input is not valid Firestore data.
      * @return This `Transaction` instance. Used for chaining method calls.
      */
     update(
@@ -700,6 +704,7 @@ declare namespace FirebaseFirestore {
      * @param documentRef A reference to the document to be
      * created.
      * @param data The object to serialize as the document.
+     * @throws Error If the provided input is not a valid Firestore document.
      * @returns A promise that resolves with the result of the write. If the
      * write fails, the promise is rejected with a
      * [BulkWriterError]{@link BulkWriterError}.
@@ -747,6 +752,7 @@ declare namespace FirebaseFirestore {
      * @param options.mergeFields - If provided,
      * set() only replaces the specified field paths. Any field path that is not
      * specified is ignored and remains untouched.
+     * @throws Error If the provided input is not a valid Firestore document.
      * @returns A promise that resolves with the result of the write. If the
      * write fails, the promise is rejected with a
      * [BulkWriterError]{@link BulkWriterError}.
@@ -780,6 +786,7 @@ declare namespace FirebaseFirestore {
      * @param data An object containing the fields and values with which to
      * update the document.
      * @param precondition A Precondition to enforce on this update.
+     * @throws Error If the provided input is not valid Firestore data.
      * @returns A promise that resolves with the result of the write. If the
      * write fails, the promise is rejected with a
      * [BulkWriterError]{@link BulkWriterError}.
@@ -809,7 +816,9 @@ declare namespace FirebaseFirestore {
      * @param field The first field to update.
      * @param value The first value
      * @param fieldsOrPrecondition An alternating list of field paths and values
-     * to update, optionally followed a `Precondition` to enforce on this update.
+     * to update, optionally followed a `Precondition` to enforce on this
+     * update.
+     * @throws Error If the provided input is not valid Firestore data;
      * @returns A promise that resolves with the result of the write. If the
      * write fails, the promise is rejected with a
      * [BulkWriterError]{@link BulkWriterError}.
@@ -953,6 +962,7 @@ declare namespace FirebaseFirestore {
      *
      * @param documentRef A reference to the document to be created.
      * @param data The object data to serialize as the document.
+     * @throws Error If the provided input is not a valid Firestore document.
      * @return This `WriteBatch` instance. Used for chaining method calls.
      */
     create<T>(
@@ -968,6 +978,7 @@ declare namespace FirebaseFirestore {
      * @param documentRef A reference to the document to be set.
      * @param data An object of the fields and values for the document.
      * @param options An object to configure the set behavior.
+     * @throws Error If the provided input is not a valid Firestore document.
      * @return This `WriteBatch` instance. Used for chaining method calls.
      */
     set<T>(
@@ -992,6 +1003,7 @@ declare namespace FirebaseFirestore {
      * @param data An object containing the fields and values with which to
      * update the document.
      * @param precondition A Precondition to enforce on this update.
+     * @throws Error If the provided input is not valid Firestore data.
      * @return This `WriteBatch` instance. Used for chaining method calls.
      */
     update<T>(
@@ -1015,7 +1027,9 @@ declare namespace FirebaseFirestore {
      * @param field The first field to update.
      * @param value The first value
      * @param fieldsOrPrecondition An alternating list of field paths and values
-     * to update, optionally followed a `Precondition` to enforce on this update.
+     * to update, optionally followed a `Precondition` to enforce on this
+     * update.
+     * @throws Error If the provided input is not valid Firestore data.
      * @return This `WriteBatch` instance. Used for chaining method calls.
      */
     update(
@@ -1174,6 +1188,7 @@ declare namespace FirebaseFirestore {
      * provided object values. The write fails if the document already exists
      *
      * @param data The object data to serialize as the document.
+     * @throws Error If the provided input is not a valid Firestore document.
      * @return A Promise resolved with the write time of this create.
      */
     create(data: WithFieldValue<T>): Promise<WriteResult>;
@@ -1185,6 +1200,7 @@ declare namespace FirebaseFirestore {
      *
      * @param data A map of the fields and values for the document.
      * @param options An object to configure the set behavior.
+     * @throws Error If the provided input is not a valid Firestore document.
      * @return A Promise resolved with the write time of this set.
      */
     set(
@@ -1203,6 +1219,7 @@ declare namespace FirebaseFirestore {
      * @param data An object containing the fields and values with which to
      * update the document.
      * @param precondition A Precondition to enforce on this update.
+     * @throws Error If the provided input is not valid Firestore data.
      * @return A Promise resolved with the write time of this update.
      */
     update(
@@ -1225,6 +1242,7 @@ declare namespace FirebaseFirestore {
      * @param moreFieldsOrPrecondition An alternating list of field paths and
      * values to update, optionally followed by a `Precondition` to enforce on
      * this update.
+     * @throws Error If the provided input is not valid Firestore data.
      * @return A Promise resolved with the write time of this update.
      */
     update(
@@ -1816,6 +1834,7 @@ declare namespace FirebaseFirestore {
      * it a document ID automatically.
      *
      * @param data An Object containing the data for the new document.
+     * @throws Error If the provided input is not a valid Firestore document.
      * @return A Promise resolved with a `DocumentReference` pointing to the
      * newly created document after it has been written to the backend.
      */