Add DocumentSnapshot (#3130)

Author: schmidt-sebastian

packages/firestore/lite/index.node.ts

@@ -47,6 +47,8 @@ export {
   serverTimestamp
 } from './src/api/field_value';
 
+export { DocumentSnapshot, QueryDocumentSnapshot } from './src/api/snapshot';
+
 export { setLogLevel } from '../src/util/log';
 
 export function registerFirestore(): void {

packages/firestore/lite/src/api/field_path.ts

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2020 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.
+ */
+
+import * as firestore from '../../index';
+
+import { cast } from './util';
+import {
+  DOCUMENT_KEY_NAME,
+  FieldPath as InternalFieldPath
+} from '../../../src/model/path';
+import { validateNamedArrayAtLeastNumberOfElements } from '../../../src/util/input_validation';
+import { Code, FirestoreError } from '../../../src/util/error';
+
+/**
+ * A FieldPath refers to a field in a document. The path may consist of a single
+ * field name (referring to a top-level field in the document), or a list of
+ * field names (referring to a nested field in the document).
+ */
+export class FieldPath implements firestore.FieldPath {
+  // Note: This class is stripped down a copy of the FieldPath class in the
+  // legacy SDK. The changes are:
+  // - The `documentId()` static method has been removed
+  // - Input validation is limited to errors that cannot be caught by the
+  //   TypeScript transpiler.
+
+  /** Internal representation of a Firestore field path. */
+  _internalPath: InternalFieldPath;
+
+  /**
+   * Creates a FieldPath from the provided field names. If more than one field
+   * name is provided, the path will point to a nested field in a document.
+   *
+   * @param fieldNames A list of field names.
+   */
+  constructor(...fieldNames: string[]) {
+    validateNamedArrayAtLeastNumberOfElements(
+      'FieldPath',
+      fieldNames,
+      'fieldNames',
+      1
+    );
+
+    const emptyElement = fieldNames.indexOf('');
+    if (emptyElement !== -1) {
+      throw new FirestoreError(
+        Code.INVALID_ARGUMENT,
+        `Invalid field name at argument $(i + 1). ` +
+          'Field names must not be empty.'
+      );
+    }
+
+    this._internalPath = new InternalFieldPath(fieldNames);
+  }
+
+  isEqual(other: firestore.FieldPath): boolean {
+    const path = cast(other, FieldPath);
+    return this._internalPath.isEqual(path._internalPath);
+  }
+}
+
+export function documentId(): firestore.FieldPath {
+  return new FieldPath(DOCUMENT_KEY_NAME);
+}

packages/firestore/lite/src/api/snapshot.ts

@@ -0,0 +1,123 @@
+/**
+ * @license
+ * Copyright 2020 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.
+ */
+
+import * as firestore from '../../index';
+
+import { Firestore } from './database';
+import { DocumentReference } from './reference';
+import { FieldPath } from './field_path';
+import { cast } from './util';
+import { DocumentKey } from '../../../src/model/document_key';
+import { Document } from '../../../src/model/document';
+import { UserDataWriter } from '../../../src/api/user_data_writer';
+import { FieldPath as InternalFieldPath } from '../../../src/model/path';
+import { fieldPathFromDotSeparatedString } from '../../../src/api/user_data_reader';
+
+export class DocumentSnapshot<T = firestore.DocumentData>
+  implements firestore.DocumentSnapshot<T> {
+  // Note: This class is stripped down version of the DocumentSnapshot in
+  // the legacy SDK. The changes are:
+  // - No support for SnapshotMetadata.
+  // - No support for SnapshotOptions.
+
+  constructor(
+    private _firestore: Firestore,
+    private _key: DocumentKey,
+    private _document: Document | null,
+    private _converter?: firestore.FirestoreDataConverter<T>
+  ) {}
+
+  get id(): string {
+    return this._key.path.lastSegment();
+  }
+
+  get ref(): firestore.DocumentReference<T> {
+    return new DocumentReference<T>(
+      this._firestore,
+      this._key,
+      this._converter
+    );
+  }
+
+  exists(): this is firestore.QueryDocumentSnapshot<T> {
+    return this._document !== null;
+  }
+
+  data(): T | undefined {
+    if (!this._document) {
+      return undefined;
+    } else if (this._converter) {
+      // We only want to use the converter and create a new DocumentSnapshot
+      // if a converter has been provided.
+      const snapshot = new QueryDocumentSnapshot(
+        this._firestore,
+        this._key,
+        this._document
+      );
+      return this._converter.fromFirestore(snapshot);
+    } else {
+      const userDataWriter = new UserDataWriter(
+        this._firestore._databaseId,
+        /* timestampsInSnapshots= */ false,
+        /* serverTimestampBehavior=*/ 'none',
+        key => new DocumentReference(this._firestore, key)
+      );
+      return userDataWriter.convertValue(this._document.toProto()) as T;
+    }
+  }
+
+  get(fieldPath: string | firestore.FieldPath): unknown {
+    if (this._document) {
+      const value = this._document
+        .data()
+        .field(fieldPathFromArgument('DocumentSnapshot.get', fieldPath));
+      if (value !== null) {
+        const userDataWriter = new UserDataWriter(
+          this._firestore._databaseId,
+          /* timestampsInSnapshots= */ false,
+          /* serverTimestampBehavior=*/ 'none',
+          key => new DocumentReference(this._firestore, key, this._converter)
+        );
+        return userDataWriter.convertValue(value);
+      }
+    }
+    return undefined;
+  }
+}
+
+export class QueryDocumentSnapshot<T = firestore.DocumentData>
+  extends DocumentSnapshot<T>
+  implements firestore.QueryDocumentSnapshot<T> {
+  data(): T {
+    return super.data() as T;
+  }
+}
+
+/**
+ * Helper that calls fromDotSeparatedString() but wraps any error thrown.
+ */
+export function fieldPathFromArgument(
+  methodName: string,
+  arg: string | firestore.FieldPath
+): InternalFieldPath {
+  if (typeof arg === 'string') {
+    return fieldPathFromDotSeparatedString(methodName, arg);
+  } else {
+    const path = cast(arg, FieldPath);
+    return path._internalPath;
+  }
+}

packages/firestore/src/api/user_data_reader.ts

@@ -769,7 +769,7 @@ export function fieldPathFromArgument(
  * @param path The dot-separated string form of a field path which will be split
  * on dots.
  */
-function fieldPathFromDotSeparatedString(
+export function fieldPathFromDotSeparatedString(
   methodName: string,
   path: string
 ): FieldPath {