removing modular pipeline creation and removing fluent pipline execution. This was a decision from API review

Author: MarkDuckworth

packages/firestore/src/api/pipeline.ts

@@ -15,16 +15,12 @@
  * limitations under the License.
  */
 
-import { firestoreClientExecutePipeline } from '../core/firestore_client';
 import { Pipeline as LitePipeline } from '../lite-api/pipeline';
-import { PipelineResult } from '../lite-api/pipeline-result';
-import { DocumentReference } from '../lite-api/reference';
 import { Stage } from '../lite-api/stage';
 import { UserDataReader } from '../lite-api/user_data_reader';
 import { AbstractUserDataWriter } from '../lite-api/user_data_writer';
-import { cast } from '../util/input_validation';
 
-import { ensureFirestoreConfigured, Firestore } from './database';
+import { Firestore } from './database';
 
 export class Pipeline extends LitePipeline {
   /**
@@ -45,61 +41,4 @@ export class Pipeline extends LitePipeline {
   ): Pipeline {
     return new Pipeline(db, userDataReader, userDataWriter, stages);
   }
-
-  /**
-   * Executes this pipeline and returns a Promise to represent the asynchronous operation.
-   *
-   * <p>The returned Promise can be used to track the progress of the pipeline execution
-   * and retrieve the results (or handle any errors) asynchronously.
-   *
-   * <p>The pipeline results are returned as a list of {@link PipelineResult} objects. Each {@link
-   * PipelineResult} typically represents a single key/value map that has passed through all the
-   * stages of the pipeline, however this might differ depending on the stages involved in the
-   * pipeline. For example:
-   *
-   * <ul>
-   *   <li>If there are no stages or only transformation stages, each {@link PipelineResult}
-   *       represents a single document.</li>
-   *   <li>If there is an aggregation, only a single {@link PipelineResult} is returned,
-   *       representing the aggregated results over the entire dataset .</li>
-   *   <li>If there is an aggregation stage with grouping, each {@link PipelineResult} represents a
-   *       distinct group and its associated aggregated values.</li>
-   * </ul>
-   *
-   * <p>Example:
-   *
-   * ```typescript
-   * const futureResults = await firestore.pipeline().collection("books")
-   *     .where(gt(Field.of("rating"), 4.5))
-   *     .select("title", "author", "rating")
-   *     .execute();
-   * ```
-   *
-   * @return A Promise representing the asynchronous pipeline execution.
-   */
-  execute(): Promise<PipelineResult[]> {
-    const firestore = cast(this._db, Firestore);
-    const client = ensureFirestoreConfigured(firestore);
-    return firestoreClientExecutePipeline(client, this).then(result => {
-      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(
-              this._userDataWriter,
-              element.key?.path
-                ? new DocumentReference(firestore, null, element.key)
-                : undefined,
-              element.fields,
-              element.executionTime?.toTimestamp(),
-              element.createTime?.toTimestamp(),
-              element.updateTime?.toTimestamp()
-            )
-        );
-
-      return docs;
-    });
-  }
 }

packages/firestore/src/api/pipeline_impl.ts

@@ -16,6 +16,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';
@@ -24,8 +25,8 @@ import { Stage } from '../lite-api/stage';
 import { newUserDataReader } from '../lite-api/user_data_reader';
 import { cast } from '../util/input_validation';
 
-import { Firestore } from './database';
-import { Query } from './reference';
+import { ensureFirestoreConfigured, Firestore } from './database';
+import { DocumentReference, Query } from './reference';
 import { ExpUserDataWriter } from './user_data_writer';
 
 declare module './database' {
@@ -35,52 +36,78 @@ declare module './database' {
 }
 
 /**
- * Experimental Modular API for console testing.
- * @param firestore
- */
-export function pipeline(firestore: Firestore): PipelineSource<Pipeline>;
-
-/**
- * Experimental Modular API for console testing.
- * @param query
+ * Executes this pipeline and returns a Promise to represent the asynchronous operation.
+ *
+ * <p>The returned Promise can be used to track the progress of the pipeline execution
+ * and retrieve the results (or handle any errors) asynchronously.
+ *
+ * <p>The pipeline results are returned as a list of {@link PipelineResult} objects. Each {@link
+ * PipelineResult} typically represents a single key/value map that has passed through all the
+ * stages of the pipeline, however this might differ depending on the stages involved in the
+ * pipeline. For example:
+ *
+ * <ul>
+ *   <li>If there are no stages or only transformation stages, each {@link PipelineResult}
+ *       represents a single document.</li>
+ *   <li>If there is an aggregation, only a single {@link PipelineResult} is returned,
+ *       representing the aggregated results over the entire dataset .</li>
+ *   <li>If there is an aggregation stage with grouping, each {@link PipelineResult} represents a
+ *       distinct group and its associated aggregated values.</li>
+ * </ul>
+ *
+ * <p>Example:
+ *
+ * ```typescript
+ * const futureResults = await execute(firestore.pipeline().collection("books")
+ *     .where(gt(Field.of("rating"), 4.5))
+ *     .select("title", "author", "rating"));
+ * ```
+ *
+ * @param pipeline The pipeline to execute.
+ * @return A Promise representing the asynchronous pipeline execution.
  */
-export function pipeline(query: Query): Pipeline;
-
-export function pipeline(
-  firestoreOrQuery: Firestore | Query
-): PipelineSource<Pipeline> | Pipeline {
-  if (firestoreOrQuery instanceof Firestore) {
-    const firestore = firestoreOrQuery;
-    return new PipelineSource<Pipeline>(
-      firestore._databaseId,
-      (stages: Stage[]) => {
-        return new Pipeline(
-          firestore,
-          newUserDataReader(firestore),
-          new ExpUserDataWriter(firestore),
-          stages
-        );
-      }
-    );
-  } else {
-    const query = firestoreOrQuery;
-    const db = cast<Firestore>(query.firestore, Firestore);
-
-    const litePipeline: LitePipeline = toPipeline(query._query, db);
-    return cast<Pipeline>(litePipeline, Pipeline);
-  }
-}
-
 export function execute(pipeline: LitePipeline): Promise<PipelineResult[]> {
-  return pipeline.execute();
+  const firestore = cast(pipeline._db, Firestore);
+  const client = ensureFirestoreConfigured(firestore);
+  return firestoreClientExecutePipeline(client, pipeline).then(result => {
+    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(firestore, null, element.key)
+              : undefined,
+            element.fields,
+            element.executionTime?.toTimestamp(),
+            element.createTime?.toTimestamp(),
+            element.updateTime?.toTimestamp()
+          )
+      );
+
+    return docs;
+  });
 }
 
 // Augment the Firestore class with the pipeline() factory method
 Firestore.prototype.pipeline = function (): PipelineSource<Pipeline> {
-  return pipeline(this);
+  return new PipelineSource<Pipeline>(this._databaseId, (stages: Stage[]) => {
+    return new Pipeline(
+      this,
+      newUserDataReader(this),
+      new ExpUserDataWriter(this),
+      stages
+    );
+  });
 };
 
 // Augment the Query class with the pipeline() factory method
 Query.prototype.pipeline = function (): Pipeline {
-  return pipeline(this);
+  const db = cast<Firestore>(this.firestore, Firestore);
+
+  const litePipeline: LitePipeline = toPipeline(this._query, db);
+  return cast<Pipeline>(litePipeline, Pipeline);
 };

packages/firestore/src/api_pipelines.ts

@@ -21,7 +21,7 @@ export { PipelineResult } from './lite-api/pipeline-result';
 
 export { Pipeline } from './api/pipeline';
 
-export { pipeline, execute } from './api/pipeline_impl';
+export { execute } from './api/pipeline_impl';
 
 export {
   Stage,

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

@@ -22,11 +22,9 @@ import {
   Pipeline as ProtoPipeline,
   Stage as ProtoStage
 } from '../protos/firestore_proto_api';
-import { invokeExecutePipeline } from '../remote/datastore';
 import { JsonProtoSerializer, ProtoSerializable } from '../remote/serializer';
 import { isPlainObject } from '../util/input_validation';
 
-import { getDatastore } from './components';
 import { Firestore } from './database';
 import {
   _mapValue,
@@ -40,8 +38,6 @@ import {
   Ordering,
   Selectable
 } from './expressions';
-import { PipelineResult } from './pipeline-result';
-import { DocumentReference } from './reference';
 import {
   AddFields,
   Aggregate,
@@ -99,23 +95,20 @@ function isReadableUserData(value: any): value is ReadableUserData {
  * const db: Firestore; // Assumes a valid firestore instance.
  *
  * // Example 1: Select specific fields and rename 'rating' to 'bookRating'
- * const results1 = await db.pipeline()
+ * const results1 = await execute(db.pipeline()
  *     .collection("books")
- *     .select("title", "author", Field.of("rating").as("bookRating"))
- *     .execute();
+ *     .select("title", "author", Field.of("rating").as("bookRating")));
  *
  * // Example 2: Filter documents where 'genre' is "Science Fiction" and 'published' is after 1950
- * const results2 = await db.pipeline()
+ * const results2 = await execute(db.pipeline()
  *     .collection("books")
- *     .where(and(Field.of("genre").eq("Science Fiction"), Field.of("published").gt(1950)))
- *     .execute();
+ *     .where(and(Field.of("genre").eq("Science Fiction"), Field.of("published").gt(1950))));
  *
  * // Example 3: Calculate the average rating of books published after 1980
- * const results3 = await db.pipeline()
+ * const results3 = await execute(db.pipeline()
  *     .collection("books")
  *     .where(Field.of("published").gt(1980))
- *     .aggregate(avg(Field.of("rating")).as("averageRating"))
- *     .execute();
+ *     .aggregate(avg(Field.of("rating")).as("averageRating")));
  * ```
  */
 
@@ -760,62 +753,6 @@ export class Pipeline implements ProtoSerializable<ProtoPipeline> {
     return this._addStage(new GenericStage(name, expressionParams));
   }
 
-  /**
-   * Executes this pipeline and returns a Promise to represent the asynchronous operation.
-   *
-   * <p>The returned Promise can be used to track the progress of the pipeline execution
-   * and retrieve the results (or handle any errors) asynchronously.
-   *
-   * <p>The pipeline results are returned as a list of {@link PipelineResult} objects. Each {@link
-   * PipelineResult} typically represents a single key/value map that has passed through all the
-   * stages of the pipeline, however this might differ depending on the stages involved in the
-   * pipeline. For example:
-   *
-   * <ul>
-   *   <li>If there are no stages or only transformation stages, each {@link PipelineResult}
-   *       represents a single document.</li>
-   *   <li>If there is an aggregation, only a single {@link PipelineResult} is returned,
-   *       representing the aggregated results over the entire dataset .</li>
-   *   <li>If there is an aggregation stage with grouping, each {@link PipelineResult} represents a
-   *       distinct group and its associated aggregated values.</li>
-   * </ul>
-   *
-   * <p>Example:
-   *
-   * ```typescript
-   * const futureResults = await firestore.pipeline().collection("books")
-   *     .where(gt(Field.of("rating"), 4.5))
-   *     .select("title", "author", "rating")
-   *     .execute();
-   * ```
-   *
-   * @return A Promise representing the asynchronous pipeline execution.
-   */
-  execute(): Promise<PipelineResult[]> {
-    const datastore = getDatastore(this._db);
-    return invokeExecutePipeline(datastore, this).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(
-                this._userDataWriter,
-                element.key?.path
-                  ? new DocumentReference(this._db, null, element.key)
-                  : undefined,
-                element.fields,
-                element.executionTime?.toTimestamp(),
-                element.createTime?.toTimestamp(),
-                element.updateTime?.toTimestamp()
-              )
-          )
-      );
-    });
-  }
-
   /**
    * @internal
    * @private