Change return type of execute from PipelineResult[] to PipelineSnapshot

Author: MarkDuckworth

packages/firestore/src/api/pipeline_impl.ts

@@ -19,7 +19,7 @@ import { Pipeline } from '../api/pipeline';
 import { firestoreClientExecutePipeline } from '../core/firestore_client';
 import { toPipeline } from '../core/pipeline-util';
 import { Pipeline as LitePipeline } from '../lite-api/pipeline';
-import { PipelineResult } from '../lite-api/pipeline-result';
+import { PipelineResult, PipelineSnapshot } from '../lite-api/pipeline-result';
 import { PipelineSource } from '../lite-api/pipeline-source';
 import { Stage } from '../lite-api/stage';
 import { newUserDataReader } from '../lite-api/user_data_reader';
@@ -66,10 +66,16 @@ declare module './database' {
  * @param pipeline The pipeline to execute.
  * @return A Promise representing the asynchronous pipeline execution.
  */
-export function execute(pipeline: LitePipeline): Promise<PipelineResult[]> {
+export function execute(pipeline: LitePipeline): Promise<PipelineSnapshot> {
   const firestore = cast(pipeline._db, Firestore);
   const client = ensureFirestoreConfigured(firestore);
   return firestoreClientExecutePipeline(client, pipeline).then(result => {
+    // Get the execution time from the first result.
+    // firestoreClientExecutePipeline returns at least one PipelineStreamElement
+    // even if the returned document set is empty.
+    const executionTime =
+      result.length > 0 ? result[0].executionTime?.toTimestamp() : undefined;
+
     const docs = result
       // Currently ignore any response from ExecutePipeline that does
       // not contain any document data in the `fields` property.
@@ -82,13 +88,12 @@ export function execute(pipeline: LitePipeline): Promise<PipelineResult[]> {
               ? new DocumentReference(firestore, null, element.key)
               : undefined,
             element.fields,
-            element.executionTime?.toTimestamp(),
             element.createTime?.toTimestamp(),
             element.updateTime?.toTimestamp()
           )
       );
 
-    return docs;
+    return new PipelineSnapshot(pipeline, docs, executionTime);
   });
 }
 

packages/firestore/src/lite-api/pipeline-result.ts

@@ -18,12 +18,58 @@
 import { ObjectValue } from '../model/object_value';
 import { isOptionalEqual } from '../util/misc';
 
+import { Field } from './expressions';
 import { FieldPath } from './field_path';
+import { Pipeline } from './pipeline';
 import { DocumentData, DocumentReference, refEqual } from './reference';
 import { fieldPathFromArgument } from './snapshot';
 import { Timestamp } from './timestamp';
 import { AbstractUserDataWriter } from './user_data_writer';
 
+export class PipelineSnapshot {
+  private readonly _pipeline: Pipeline;
+  private readonly _executionTime: Timestamp | undefined;
+  private readonly _results: PipelineResult[];
+  constructor(
+    pipeline: Pipeline,
+    results: PipelineResult[],
+    executionTime?: Timestamp
+  ) {
+    this._pipeline = pipeline;
+    this._executionTime = executionTime;
+    this._results = results;
+  }
+
+  /**
+   * The Pipeline on which you called `execute()` in order to get this
+   * `PipelineSnapshot`.
+   */
+  get pipeline(): Pipeline {
+    return this._pipeline;
+  }
+
+  /** An array of all the results in the `PipelineSnapshot`. */
+  get results(): PipelineResult[] {
+    return this._results;
+  }
+
+  /**
+   * The time at which the pipeline producing this result is executed.
+   *
+   * @type {Timestamp}
+   * @readonly
+   *
+   */
+  get executionTime(): Timestamp {
+    if (this._executionTime === undefined) {
+      throw new Error(
+        "'executionTime' is expected to exist, but it is undefined"
+      );
+    }
+    return this._executionTime;
+  }
+}
+
 /**
  * @beta
  *
@@ -36,7 +82,6 @@ import { AbstractUserDataWriter } from './user_data_writer';
 export class PipelineResult<AppModelType = DocumentData> {
   private readonly _userDataWriter: AbstractUserDataWriter;
 
-  private readonly _executionTime: Timestamp | undefined;
   private readonly _createTime: Timestamp | undefined;
   private readonly _updateTime: Timestamp | undefined;
 
@@ -69,13 +114,11 @@ export class PipelineResult<AppModelType = DocumentData> {
     userDataWriter: AbstractUserDataWriter,
     ref?: DocumentReference,
     fields?: ObjectValue,
-    executionTime?: Timestamp,
     createTime?: Timestamp,
     updateTime?: Timestamp
   ) {
     this._ref = ref;
     this._userDataWriter = userDataWriter;
-    this._executionTime = executionTime;
     this._createTime = createTime;
     this._updateTime = updateTime;
     this._fields = fields;
@@ -120,22 +163,6 @@ export class PipelineResult<AppModelType = DocumentData> {
     return this._updateTime;
   }
 
-  /**
-   * The time at which the pipeline producing this result is executed.
-   *
-   * @type {Timestamp}
-   * @readonly
-   *
-   */
-  get executionTime(): Timestamp {
-    if (this._executionTime === undefined) {
-      throw new Error(
-        "'executionTime' is expected to exist, but it is undefined"
-      );
-    }
-    return this._executionTime;
-  }
-
   /**
    * Retrieves all fields in the result as an object. Returns 'undefined' if
    * the document doesn't exist.
@@ -166,7 +193,7 @@ export class PipelineResult<AppModelType = DocumentData> {
   /**
    * Retrieves the field specified by `field`.
    *
-   * @param {string|FieldPath} field The field path
+   * @param {string|FieldPath|Field} field The field path
    * (e.g. 'foo' or 'foo.bar') to a specific field.
    * @returns {*} The data at the specified field location or undefined if no
    * such field exists.
@@ -184,7 +211,7 @@ export class PipelineResult<AppModelType = DocumentData> {
   // We deliberately use `any` in the external API to not impose type-checking
   // on end users.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  get(fieldPath: string | FieldPath): any {
+  get(fieldPath: string | FieldPath | Field): any {
     if (this._fields === undefined) {
       return undefined;
     }

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

@@ -20,7 +20,7 @@ import { invokeExecutePipeline } from '../remote/datastore';
 import { getDatastore } from './components';
 import { Firestore } from './database';
 import { Pipeline } from './pipeline';
-import { PipelineResult } from './pipeline-result';
+import { PipelineResult, PipelineSnapshot } from './pipeline-result';
 import { PipelineSource } from './pipeline-source';
 import { DocumentReference, Query } from './reference';
 import { LiteUserDataWriter } from './reference_impl';
@@ -70,28 +70,33 @@ declare module './reference' {
  * @param pipeline The pipeline to execute.
  * @return A Promise representing the asynchronous pipeline execution.
  */
-export function execute(pipeline: Pipeline): Promise<PipelineResult[]> {
+export function execute(pipeline: Pipeline): Promise<PipelineSnapshot> {
   const datastore = getDatastore(pipeline._db);
   return invokeExecutePipeline(datastore, pipeline).then(result => {
-    return (
-      result
-        // Currently ignore any response from ExecutePipeline that does
-        // not contain any document data in the `fields` property.
-        .filter(element => !!element.fields)
-        .map(
-          element =>
-            new PipelineResult(
-              pipeline._userDataWriter,
-              element.key?.path
-                ? new DocumentReference(pipeline._db, null, element.key)
-                : undefined,
-              element.fields,
-              element.executionTime?.toTimestamp(),
-              element.createTime?.toTimestamp(),
-              element.updateTime?.toTimestamp()
-            )
-        )
-    );
+    // Get the execution time from the first result.
+    // firestoreClientExecutePipeline returns at least one PipelineStreamElement
+    // even if the returned document set is empty.
+    const executionTime =
+      result.length > 0 ? result[0].executionTime?.toTimestamp() : undefined;
+
+    const docs = result
+      // Currently ignore any response from ExecutePipeline that does
+      // not contain any document data in the `fields` property.
+      .filter(element => !!element.fields)
+      .map(
+        element =>
+          new PipelineResult(
+            pipeline._userDataWriter,
+            element.key?.path
+              ? new DocumentReference(pipeline._db, null, element.key)
+              : undefined,
+            element.fields,
+            element.createTime?.toTimestamp(),
+            element.updateTime?.toTimestamp()
+          )
+      );
+
+    return new PipelineSnapshot(pipeline, docs, executionTime);
   });
 }
 

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

@@ -23,6 +23,7 @@ import { FieldPath as InternalFieldPath } from '../model/path';
 import { arrayEquals } from '../util/misc';
 
 import { Firestore } from './database';
+import { Field } from './expressions';
 import { FieldPath } from './field_path';
 import {
   DocumentData,
@@ -515,12 +516,14 @@ export function snapshotEqual<AppModelType, DbModelType extends DocumentData>(
  */
 export function fieldPathFromArgument(
   methodName: string,
-  arg: string | FieldPath | Compat<FieldPath>
+  arg: string | FieldPath | Compat<FieldPath> | Field
 ): InternalFieldPath {
   if (typeof arg === 'string') {
     return fieldPathFromDotSeparatedString(methodName, arg);
   } else if (arg instanceof FieldPath) {
     return arg._internalPath;
+  } else if (arg instanceof Field) {
+    return fieldPathFromDotSeparatedString(methodName, arg.fieldName());
   } else {
     return arg._delegate._internalPath;
   }