Pipeline and stage options. Tangential renames and minor fixes

Author: MarkDuckworth

packages/firestore/lite/pipelines/pipelines.ts

@@ -50,6 +50,8 @@ export type {
 
 export { PipelineSource } from '../../src/lite-api/pipeline-source';
 
+export { OneOf } from '../../src/util/types';
+
 export {
   PipelineResult,
   PipelineSnapshot
@@ -59,9 +61,30 @@ export { Pipeline } from '../../src/lite-api/pipeline';
 
 export { execute } from '../../src/lite-api/pipeline_impl';
 
+export {
+  StageOptions,
+  CollectionStageOptions,
+  CollectionGroupStageOptions,
+  DatabaseStageOptions,
+  DocumentsStageOptions,
+  AddFieldsStageOptions,
+  RemoveFieldsStageOptions,
+  SelectStageOptions,
+  WhereStageOptions,
+  OffsetStageOptions,
+  LimitStageOptions,
+  DistinctStageOptions,
+  AggregateStageOptions,
+  FindNearestStageOptions,
+  ReplaceWithStageOptions,
+  SampleStageOptions,
+  UnionStageOptions,
+  UnnestStageOptions,
+  SortStageOptions
+} from '../../src/lite-api/stage_options';
+
 export {
   Stage,
-  FindNearestOptions,
   AddFields,
   Aggregate,
   Distinct,
@@ -83,7 +106,6 @@ export {
   field,
   and,
   array,
-  arrayOffset,
   constant,
   add,
   subtract,

packages/firestore/src/api/pipeline_impl.ts

@@ -24,7 +24,7 @@ import {
 import { Pipeline as LitePipeline } from '../lite-api/pipeline';
 import { PipelineResult, PipelineSnapshot } from '../lite-api/pipeline-result';
 import { PipelineSource } from '../lite-api/pipeline-source';
-import { PipelineOptions } from '../lite-api/pipeline_settings';
+import { PipelineOptions } from '../lite-api/pipeline_options';
 import { Stage } from '../lite-api/stage';
 import {
   newUserDataReader,
@@ -91,7 +91,6 @@ export function execute(
     };
 
   const { pipeline, customOptions, ...rest } = options;
-  const genericOptions: { [name:string]: unknown } = customOptions ?? {};
 
   const firestore = cast(pipeline._db, Firestore);
   const client = ensureFirestoreConfigured(firestore);
@@ -102,8 +101,8 @@ export function execute(
   );
   const context = udr.createContext(UserDataSource.Argument, 'execute');
 
-  const structuredPipelineOptions = new StructuredPipelineOptions(rest, genericOptions);
-  structuredPipelineOptions._readUserData(udr, context);
+  const structuredPipelineOptions = new StructuredPipelineOptions(rest, customOptions);
+  structuredPipelineOptions._readUserData(context);
 
   const structuredPipeline: StructuredPipeline = new StructuredPipeline(
     pipeline,
@@ -142,10 +141,12 @@ export function execute(
 
 // Augment the Firestore class with the pipeline() factory method
 Firestore.prototype.pipeline = function (): PipelineSource<Pipeline> {
-  return new PipelineSource<Pipeline>(this._databaseId, (stages: Stage[]) => {
+  const userDataReader =
+    newUserDataReader(this);
+  return new PipelineSource<Pipeline>(this._databaseId, userDataReader, (stages: Stage[]) => {
     return new Pipeline(
       this,
-      newUserDataReader(this),
+      userDataReader,
       new ExpUserDataWriter(this),
       stages
     );

packages/firestore/src/api_pipelines.ts

@@ -17,6 +17,8 @@
 
 export { PipelineSource } from './lite-api/pipeline-source';
 
+export { OneOf } from './util/types';
+
 export {
   PipelineResult,
   PipelineSnapshot,
@@ -27,9 +29,32 @@ export { Pipeline } from './api/pipeline';
 
 export { execute } from './api/pipeline_impl';
 
+export { PipelineOptions } from './lite-api/pipeline_options';
+
+export {
+  StageOptions,
+  CollectionStageOptions,
+  CollectionGroupStageOptions,
+  DatabaseStageOptions,
+  DocumentsStageOptions,
+  AddFieldsStageOptions,
+  RemoveFieldsStageOptions,
+  SelectStageOptions,
+  WhereStageOptions,
+  OffsetStageOptions,
+  LimitStageOptions,
+  DistinctStageOptions,
+  AggregateStageOptions,
+  FindNearestStageOptions,
+  ReplaceWithStageOptions,
+  SampleStageOptions,
+  UnionStageOptions,
+  UnnestStageOptions,
+  SortStageOptions
+} from './lite-api/stage_options';
+
 export {
   Stage,
-  FindNearestOptions,
   AddFields,
   Aggregate,
   Distinct,
@@ -121,7 +146,7 @@ export {
   bitRightShift,
   rand,
   array,
-  arrayOffset,
+  arrayGet,
   isError,
   ifError,
   isAbsent,

packages/firestore/src/core/options_util.ts

@@ -0,0 +1,94 @@
+// 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 {ParseContext} from "../api/parse_context";
+import {
+  parseData,
+} from "../lite-api/user_data_reader";
+import { ObjectValue } from '../model/object_value';
+import { FieldPath } from '../model/path';
+import {ApiClientObjectMap, Value} from "../protos/firestore_proto_api";
+import {isPlainObject} from "../util/input_validation";
+import { mapToArray } from '../util/obj';
+export type OptionsDefinitions = Record<string, OptionDefinition>;
+export interface OptionDefinition {
+  serverName: string;
+  nestedOptions?: OptionsDefinitions;
+}
+
+export class OptionsUtil {
+  constructor(private optionDefinitions: OptionsDefinitions) {}
+
+  private _getKnownOptions(
+    options: Record<string, unknown>,
+    context: ParseContext
+  ): ObjectValue {
+    const knownOptions: ObjectValue = ObjectValue.empty();
+
+    // SERIALIZE KNOWN OPTIONS
+    for (const knownOptionKey in this.optionDefinitions) {
+      if (this.optionDefinitions.hasOwnProperty(knownOptionKey)) {
+        const optionDefinition: OptionDefinition =
+          this.optionDefinitions[knownOptionKey];
+
+        if (knownOptionKey in options) {
+          const optionValue: unknown = options[knownOptionKey];
+          let protoValue: Value | undefined = undefined;
+
+          if (optionDefinition.nestedOptions && isPlainObject(optionValue)) {
+            const nestedUtil = new OptionsUtil(optionDefinition.nestedOptions);
+            protoValue = {
+              mapValue: {
+                fields: nestedUtil.getOptionsProto(context, optionValue),
+              },
+            };
+          } else if (optionValue) {
+            protoValue = parseData(optionValue, context) ?? undefined;
+          }
+
+          if (protoValue) {
+            knownOptions.set(
+              FieldPath.fromServerFormat(optionDefinition.serverName),
+              protoValue
+            );
+          }
+        }
+      }
+    }
+
+    return knownOptions;
+  }
+
+  getOptionsProto(
+    context: ParseContext,
+    knownOptions: Record<string, unknown>,
+    optionsOverride?: Record<string, unknown>
+  ): ApiClientObjectMap<Value> | undefined {
+    const result: ObjectValue = this._getKnownOptions(knownOptions, context);
+
+    // APPLY OPTIONS OVERRIDES
+    if (optionsOverride) {
+      const optionsMap = new Map(
+        mapToArray(optionsOverride, (value, key) => [
+          FieldPath.fromServerFormat(key),
+          value !== undefined ? parseData(value, context) : null,
+        ])
+      );
+      result.setAll(optionsMap);
+    }
+
+    // Return MapValue from `result` or empty map value
+    return result.value.mapValue.fields ?? {};
+  }
+}

packages/firestore/src/core/pipeline-util.ts

@@ -161,7 +161,8 @@ function reverseOrderings(orderings: Ordering[]): Ordering[] {
     o =>
       new Ordering(
         o.expr,
-        o.direction === 'ascending' ? 'descending' : 'ascending'
+        o.direction === 'ascending' ? 'descending' : 'ascending',
+        undefined
       )
   );
 }

packages/firestore/src/core/structured_pipeline.ts

@@ -16,7 +16,7 @@
  */
 
 import {ParseContext} from "../api/parse_context";
-import {UserDataReader, UserDataSource} from "../lite-api/user_data_reader";
+import {UserData} from "../lite-api/user_data_reader";
 import {
   ApiClientObjectMap, firestoreV1ApiClientInterfaces,
   Pipeline as PipelineProto,
@@ -25,7 +25,6 @@ import {
 import {
   JsonProtoSerializer,
   ProtoSerializable,
-  UserData
 } from '../remote/serializer';
 
 import {OptionsUtil} from "./options_util";
@@ -43,10 +42,7 @@ export class StructuredPipelineOptions implements UserData{
     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");
-    }
+  _readUserData(context: ParseContext): void {
     this.proto = this.optionsUtil.getOptionsProto(context, this._userOptions, this._optionsOverride);
   }
 }