Refactor and test pipeline options implementation

Author: MarkDuckworth

packages/firestore/src/api/pipeline_impl.ts

@@ -28,11 +28,9 @@ import { PipelineOptions } from '../lite-api/pipeline_settings';
 import { Stage } from '../lite-api/stage';
 import {
   newUserDataReader,
-  parseData,
   UserDataReader,
   UserDataSource
 } from '../lite-api/user_data_reader';
-import { ApiClientObjectMap, Value } from '../protos/firestore_proto_api';
 import { cast } from '../util/input_validation';
 
 import { ensureFirestoreConfigured, Firestore } from './database';
@@ -84,17 +82,16 @@ export function execute(options: PipelineOptions): Promise<PipelineSnapshot>;
 export function execute(
   pipelineOrOptions: LitePipeline | PipelineOptions
 ): Promise<PipelineSnapshot> {
-  const pipeline: LitePipeline =
-    pipelineOrOptions instanceof LitePipeline
-      ? pipelineOrOptions
-      : pipelineOrOptions.pipeline;
-  const options: StructuredPipelineOptions = !(
+  const options: PipelineOptions = !(
     pipelineOrOptions instanceof LitePipeline
   )
     ? pipelineOrOptions
-    : {};
-  const genericOptions: { [name: string]: unknown } =
-    (pipelineOrOptions as PipelineOptions).genericOptions ?? {};
+    : {
+      pipeline: pipelineOrOptions
+    };
+
+  const { pipeline, customOptions, ...rest } = options;
+  const genericOptions: { [name:string]: unknown } = customOptions ?? {};
 
   const firestore = cast(pipeline._db, Firestore);
   const client = ensureFirestoreConfigured(firestore);
@@ -104,13 +101,13 @@ export function execute(
     /* ignoreUndefinedProperties */ true
   );
   const context = udr.createContext(UserDataSource.Argument, 'execute');
-  const optionsOverride: ApiClientObjectMap<Value> =
-    parseData(genericOptions, context)?.mapValue?.fields ?? {};
+
+  const structuredPipelineOptions = new StructuredPipelineOptions(rest, genericOptions);
+  structuredPipelineOptions._readUserData(udr, context);
 
   const structuredPipeline: StructuredPipeline = new StructuredPipeline(
     pipeline,
-    options,
-    optionsOverride
+    structuredPipelineOptions
   );
 
   return firestoreClientExecutePipeline(client, structuredPipeline).then(

packages/firestore/src/core/structured_pipeline.ts

@@ -15,19 +15,40 @@
  * limitations under the License.
  */
 
-import { ObjectValue } from '../model/object_value';
-import { FieldPath } from '../model/path';
+import {ParseContext} from "../api/parse_context";
+import {UserDataReader, UserDataSource} from "../lite-api/user_data_reader";
 import {
-  StructuredPipeline as StructuredPipelineProto,
+  ApiClientObjectMap, firestoreV1ApiClientInterfaces,
   Pipeline as PipelineProto,
-  ApiClientObjectMap,
-  Value
+  StructuredPipeline as StructuredPipelineProto
 } from '../protos/firestore_proto_api';
-import { JsonProtoSerializer, ProtoSerializable } from '../remote/serializer';
-import { mapToArray } from '../util/obj';
+import {
+  JsonProtoSerializer,
+  ProtoSerializable,
+  UserData
+} from '../remote/serializer';
+
+import {OptionsUtil} from "./options_util";
+
+export class StructuredPipelineOptions implements UserData{
+  proto: ApiClientObjectMap<firestoreV1ApiClientInterfaces.Value> | undefined;
+
+  readonly optionsUtil = new OptionsUtil({
+    indexMode: {
+      serverName: 'index_mode',
+    }
+  });
 
-export interface StructuredPipelineOptions {
-  indexMode?: 'recommended';
+  constructor(
+    private _userOptions: Record<string, unknown> = {},
+    private _optionsOverride: Record<string, unknown> = {}) {}
+
+  _readUserData(dataReader: UserDataReader, context?: ParseContext): void {
+    if (!context) {
+      context = dataReader.createContext(UserDataSource.Argument, "StructuredPipelineOptions._readUserData");
+    }
+    this.proto = this.optionsUtil.getOptionsProto(context, this._userOptions, this._optionsOverride);
+  }
 }
 
 export class StructuredPipeline
@@ -36,45 +57,12 @@ export class StructuredPipeline
   constructor(
     private pipeline: ProtoSerializable<PipelineProto>,
     private options: StructuredPipelineOptions,
-    private optionsOverride: ApiClientObjectMap<Value>
   ) {}
 
-  /**
-   * @private
-   * @internal for testing
-   */
-  _getKnownOptions(): ObjectValue {
-    const options: ObjectValue = ObjectValue.empty();
-
-    // SERIALIZE KNOWN OPTIONS
-    if (typeof this.options.indexMode === 'string') {
-      options.set(FieldPath.fromServerFormat('index_mode'), {
-        stringValue: this.options.indexMode
-      });
-    }
-
-    return options;
-  }
-
-  private getOptionsProto(): ApiClientObjectMap<Value> {
-    const options: ObjectValue = this._getKnownOptions();
-
-    // APPLY OPTIONS OVERRIDES
-    const optionsMap = new Map(
-      mapToArray(this.optionsOverride, (value, key) => [
-        FieldPath.fromServerFormat(key),
-        value
-      ])
-    );
-    options.setAll(optionsMap);
-
-    return options.value.mapValue.fields ?? {};
-  }
-
   _toProto(serializer: JsonProtoSerializer): StructuredPipelineProto {
     return {
       pipeline: this.pipeline._toProto(serializer),
-      options: this.getOptionsProto()
+      options: this.options.proto
     };
   }
 }

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

@@ -15,6 +15,10 @@
  * limitations under the License.
  */
 
+import {
+  StructuredPipeline,
+  StructuredPipelineOptions
+} from "../core/structured_pipeline";
 import { invokeExecutePipeline } from '../remote/datastore';
 
 import { getDatastore } from './components';
@@ -25,7 +29,11 @@ import { PipelineSource } from './pipeline-source';
 import { DocumentReference } from './reference';
 import { LiteUserDataWriter } from './reference_impl';
 import { Stage } from './stage';
-import { newUserDataReader } from './user_data_reader';
+import {
+  newUserDataReader,
+  UserDataReader,
+  UserDataSource
+} from './user_data_reader';
 
 declare module './database' {
   interface Firestore {
@@ -69,7 +77,22 @@ declare module './database' {
  */
 export function execute(pipeline: Pipeline): Promise<PipelineSnapshot> {
   const datastore = getDatastore(pipeline._db);
-  return invokeExecutePipeline(datastore, pipeline).then(result => {
+
+  const udr = new UserDataReader(
+    pipeline._db._databaseId,
+    /* ignoreUndefinedProperties */ true
+  );
+  const context = udr.createContext(UserDataSource.Argument, 'execute');
+
+  const structuredPipelineOptions = new StructuredPipelineOptions({}, {});
+  structuredPipelineOptions._readUserData(udr, context);
+
+  const structuredPipeline: StructuredPipeline = new StructuredPipeline(
+    pipeline,
+    structuredPipelineOptions
+  );
+
+  return invokeExecutePipeline(datastore, structuredPipeline).then(result => {
     // Get the execution time from the first result.
     // firestoreClientExecutePipeline returns at least one PipelineStreamElement
     // even if the returned document set is empty.

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

@@ -1,7 +1,20 @@
+// Copyright 2025 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 type { Pipeline } from './pipeline';
 
 /**
- * Options defining how a Pipeline is evaluated.
+ * Options defining Pipeline execution.
  */
 export interface PipelineOptions {
   /**
@@ -18,21 +31,21 @@ export interface PipelineOptions {
    * An escape hatch to set options not known at SDK build time. These values
    * will be passed directly to the Firestore backend and not used by the SDK.
    *
-   * The generic option name will be used as provided. And must match the name
+   * The option name will be used as provided. And must match the name
    * format used by the backend (hint: use a snake_case_name).
    *
-   * Generic option values can be any type supported
+   * Custom option values can be any type supported
    * by Firestore (for example: string, boolean, number, map, …). Value types
    * not known to the SDK will be rejected.
    *
-   * Values specified in genericOptions will take precedence over any options
+   * Values specified in customOptions will take precedence over any options
    * with the same name set by the SDK.
    *
    * Override the `example_option`:
    * ```
    *   execute({
    *     pipeline: myPipeline,
-   *     genericOptions: {
+   *     customOptions: {
    *       // Override `example_option`. This will not
    *       // merge with the existing `example_option` object.
    *       "example_option": {
@@ -42,20 +55,20 @@ export interface PipelineOptions {
    *   }
    * ```
    *
-   * `genericOptions` supports dot notation, if you want to override
+   * `customOptions` supports dot notation, if you want to override
    * a nested option.
    * ```
    *   execute({
    *     pipeline: myPipeline,
-   *     genericOptions: {
+   *     customOptions: {
    *       // Override `example_option.foo` and do not override
    *       // any other properties of `example_option`.
    *       "example_option.foo": "bar"
    *     }
    *   }
    * ```
    */
-  genericOptions?: {
+  customOptions?: {
     [name: string]: unknown;
   };
 }

packages/firestore/src/util/input_validation.ts

@@ -15,6 +15,7 @@
  * limitations under the License.
  */
 
+import {DocumentData} from "../lite-api/reference";
 import { DocumentKey } from '../model/document_key';
 import { ResourcePath } from '../model/path';
 
@@ -92,7 +93,7 @@ export function validateCollectionPath(path: ResourcePath): void {
  * Returns true if it's a non-null object without a custom prototype
  * (i.e. excludes Array, Date, etc.).
  */
-export function isPlainObject(input: unknown): boolean {
+export function isPlainObject(input: unknown): input is DocumentData {
   return (
     typeof input === 'object' &&
     input !== null &&

packages/firestore/test/unit/api/pipeline_impl.test.ts

@@ -165,7 +165,7 @@ describe('execute(Pipeline|PipelineOptions)', () => {
 
     await execute({
       pipeline: firestore.pipeline().collection('foo'),
-      genericOptions: {
+      customOptions: {
         'foo': 'bar'
       }
     });