@firebase/firestore 3.4.1 → 3.4.2-202205224240

package/dist/lite/internal.d.ts

@@ -10,6 +10,7 @@
 import { DocumentData as DocumentData_2 } from '@firebase/firestore-types';
 import { EmulatorMockTokenOptions } from '@firebase/util';
 import { FirebaseApp } from '@firebase/app';
+import { FirebaseError } from '@firebase/util';
 import { _FirebaseService } from '@firebase/app';
 import { LogLevelString as LogLevel } from '@firebase/logger';
 import { SetOptions as SetOptions_2 } from '@firebase/firestore-types';
@@ -43,6 +44,7 @@ declare abstract class AbstractUserDataWriter {
  *
  * @param reference - A reference to the collection to add this document to.
  * @param data - An Object containing the data for the new document.
+ * @throws Error - If the provided input is not a valid Firestore document.
  * @returns A `Promise` resolved with a `DocumentReference` pointing to the
  * newly created document after it has been written to the backend.
  */
@@ -274,6 +276,7 @@ declare class ByteString {
     private constructor();
     static fromBase64String(base64: string): ByteString;
     static fromUint8Array(array: Uint8Array): ByteString;
+    [Symbol.iterator](): Iterator<number>;
     toBase64(): string;
     toUint8Array(): Uint8Array;
     approximateByteSize(): number;
@@ -637,6 +640,8 @@ declare interface Document_2 {
      */
     isUnknownDocument(): boolean;
     isEqual(other: Document_2 | null | undefined): boolean;
+    /** Creates a mutable copy of this document. */
+    mutableCopy(): MutableDocument;
     toString(): string;
 }
 
@@ -1062,7 +1067,7 @@ export declare interface FirestoreDataConverter<T> {
 }
 
 /** An error returned by a Firestore operation. */
-export declare class FirestoreError extends Error {
+export declare class FirestoreError extends FirebaseError {
     /**
      * The backend error code associated with this error.
      */
@@ -1071,8 +1076,6 @@ export declare class FirestoreError extends Error {
      * A custom error description.
      */
     readonly message: string;
-    /** The custom name for all FirestoreErrors. */
-    readonly name: string;
     /** The stack of the error. */
     readonly stack?: string;
     /** @hideconstructor */
@@ -1087,22 +1090,6 @@ export declare class FirestoreError extends Error {
     message: string);
 }
 
-/**
- * @license
- * Copyright 2017 Google LLC
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *   http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
 /**
  * The set of Firestore status codes. The codes are the same at the ones
  * exposed by gRPC here:
@@ -1622,6 +1609,71 @@ export { LogLevel }
 
 declare type MapValue = firestoreV1ApiClientInterfaces.MapValue;
 
+/**
+ * Represents a document in Firestore with a key, version, data and whether it
+ * has local mutations applied to it.
+ *
+ * Documents can transition between states via `convertToFoundDocument()`,
+ * `convertToNoDocument()` and `convertToUnknownDocument()`. If a document does
+ * not transition to one of these states even after all mutations have been
+ * applied, `isValidDocument()` returns false and the document should be removed
+ * from all views.
+ */
+declare class MutableDocument implements Document_2 {
+    readonly key: DocumentKey;
+    private documentType;
+    version: SnapshotVersion;
+    data: ObjectValue;
+    private documentState;
+    private constructor();
+    /**
+     * Creates a document with no known version or data, but which can serve as
+     * base document for mutations.
+     */
+    static newInvalidDocument(documentKey: DocumentKey): MutableDocument;
+    /**
+     * Creates a new document that is known to exist with the given data at the
+     * given version.
+     */
+    static newFoundDocument(documentKey: DocumentKey, version: SnapshotVersion, value: ObjectValue): MutableDocument;
+    /** Creates a new document that is known to not exist at the given version. */
+    static newNoDocument(documentKey: DocumentKey, version: SnapshotVersion): MutableDocument;
+    /**
+     * Creates a new document that is known to exist at the given version but
+     * whose data is not known (e.g. a document that was updated without a known
+     * base document).
+     */
+    static newUnknownDocument(documentKey: DocumentKey, version: SnapshotVersion): MutableDocument;
+    /**
+     * Changes the document type to indicate that it exists and that its version
+     * and data are known.
+     */
+    convertToFoundDocument(version: SnapshotVersion, value: ObjectValue): MutableDocument;
+    /**
+     * Changes the document type to indicate that it doesn't exist at the given
+     * version.
+     */
+    convertToNoDocument(version: SnapshotVersion): MutableDocument;
+    /**
+     * Changes the document type to indicate that it exists at a given version but
+     * that its data is not known (e.g. a document that was updated without a known
+     * base document).
+     */
+    convertToUnknownDocument(version: SnapshotVersion): MutableDocument;
+    setHasCommittedMutations(): MutableDocument;
+    setHasLocalMutations(): MutableDocument;
+    get hasLocalMutations(): boolean;
+    get hasCommittedMutations(): boolean;
+    get hasPendingWrites(): boolean;
+    isValidDocument(): boolean;
+    isFoundDocument(): boolean;
+    isNoDocument(): boolean;
+    isUnknownDocument(): boolean;
+    isEqual(other: Document_2 | null | undefined): boolean;
+    mutableCopy(): MutableDocument;
+    toString(): string;
+}
+
 /**
  * A mutation describes a self-contained change to a document. Mutations can
  * create, replace, delete, and update subsets of documents.
@@ -2065,6 +2117,7 @@ declare type ServerTimestampBehavior = 'estimate' | 'previous' | 'none';
  *
  * @param reference - A reference to the document to write.
  * @param data - A map of the fields and values for the document.
+ * @throws Error - If the provided input is not a valid Firestore document.
  * @returns A `Promise` resolved once the data has been successfully written
  * to the backend.
  */
@@ -2083,6 +2136,7 @@ export declare function setDoc<T>(reference: DocumentReference<T>, data: WithFie
  * @param reference - A reference to the document to write.
  * @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.
  * @returns A `Promise` resolved once the data has been successfully written
  * to the backend.
  */
@@ -2111,10 +2165,12 @@ export declare function setLogLevel(logLevel: LogLevel): void;
  *
  * @param merge - Changes the behavior of a `setDoc()` call to only replace the
  * values specified in its data argument. Fields omitted from the `setDoc()`
- * call remain untouched.
+ * call remain untouched. If your input sets any field to an empty map, all
+ * nested fields are overwritten.
  * @param mergeFields - Changes the behavior of `setDoc()` calls to only replace
  * the specified field paths. Any field path that is not specified is ignored
- * and remains untouched.
+ * and remains untouched. If your input sets any field to an empty map, all
+ * nested fields are overwritten.
  */
 export declare type SetOptions = {
     readonly merge?: boolean;
@@ -2448,6 +2504,7 @@ export declare class Transaction {
      *
      * @param documentRef - A reference to the document to be set.
      * @param data - An object of the fields and values for the document.
+     * @throws Error - If the provided input is not a valid Firestore document.
      * @returns This `Transaction` instance. Used for chaining method calls.
      */
     set<T>(documentRef: DocumentReference<T>, data: WithFieldValue<T>): this;
@@ -2460,6 +2517,7 @@ export declare class Transaction {
      * @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.
      * @returns This `Transaction` instance. Used for chaining method calls.
      */
     set<T>(documentRef: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions): this;
@@ -2472,6 +2530,7 @@ export declare class Transaction {
      * @param data - An object containing the fields and values with which to
      * update the document. Fields can contain dots to reference nested fields
      * within the document.
+     * @throws Error - If the provided input is not valid Firestore data.
      * @returns This `Transaction` instance. Used for chaining method calls.
      */
     update<T>(documentRef: DocumentReference<T>, data: UpdateData<T>): this;
@@ -2487,6 +2546,7 @@ export declare class Transaction {
      * @param field - The first field to update.
      * @param value - The first value.
      * @param moreFieldsAndValues - Additional key/value pairs.
+     * @throws Error - If the provided input is not valid Firestore data.
      * @returns This `Transaction` instance. Used for chaining method calls.
      */
     update(documentRef: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): this;
@@ -2593,6 +2653,7 @@ export declare type UpdateData<T> = T extends Primitive ? T : T extends {} ? {
  * @param data - An object containing the fields and values with which to
  * update the document. Fields can contain dots to reference nested fields
  * within the document.
+ * @throws Error - If the provided input is not valid Firestore data.
  * @returns A `Promise` resolved once the data has been successfully written
  * to the backend.
  */
@@ -2615,6 +2676,7 @@ export declare function updateDoc<T>(reference: DocumentReference<T>, data: Upda
  * @param field - The first field to update.
  * @param value - The first value.
  * @param moreFieldsAndValues - Additional key value pairs.
+ * @throws Error - If the provided input is not valid Firestore data.
  * @returns A `Promise` resolved once the data has been successfully written
  * to the backend.
  */
@@ -2723,6 +2785,7 @@ export declare class WriteBatch {
      * @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.
      * @returns This `WriteBatch` instance. Used for chaining method calls.
      */
     set<T>(documentRef: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions): WriteBatch;
@@ -2735,6 +2798,7 @@ export declare class WriteBatch {
      * @param data - An object containing the fields and values with which to
      * update the document. Fields can contain dots to reference nested fields
      * within the document.
+     * @throws Error - If the provided input is not valid Firestore data.
      * @returns This `WriteBatch` instance. Used for chaining method calls.
      */
     update<T>(documentRef: DocumentReference<T>, data: UpdateData<T>): WriteBatch;
@@ -2750,6 +2814,7 @@ export declare class WriteBatch {
      * @param field - The first field to update.
      * @param value - The first value.
      * @param moreFieldsAndValues - Additional key value pairs.
+     * @throws Error - If the provided input is not valid Firestore data.
      * @returns This `WriteBatch` instance. Used for chaining method calls.
      */
     update(documentRef: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): WriteBatch;