DML prototype

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

@@ -65,6 +65,9 @@
   Sort,
   Stage,
   Union,
+  Delete,
+  Upsert,
+  Insert,
   Unnest,
   Where
 } from './stage';
@@ -82,11 +85,15 @@
   SortStageOptions,
   StageOptions,
   UnionStageOptions,
+  DeleteStageOptions,
+  UpsertStageOptions,
+  InsertStageOptions,
   UnnestStageOptions,
   WhereStageOptions
 } from './stage_options';
 import { UserDataReader, UserDataSource } from './user_data_reader';
 import { AbstractUserDataWriter } from './user_data_writer';
+import { CollectionReference } from './reference';
 
 /**
  * @beta
@@ -1500,6 +1507,118 @@
   ): Pipeline {
     return new Pipeline(db, userDataReader, userDataWriter, stages);
   }
+  /**
+   * @beta
+   * Deletes the documents resulting from the pipeline.
+   *
+   * @example
+   * ```typescript
+   * firestore.pipeline().collection('books').where(field('rating').lt(2)).delete();
+   * ```
+   *
+   * @param options - Optional parameters for the stage.
+   * @returns A new Pipeline object with this stage appended to the stage list.
+   */
+  delete(): Pipeline;
+  delete(options: DeleteStageOptions): Pipeline;
+  delete(options?: DeleteStageOptions): Pipeline {
+    const stage = new Delete(options || {});
+
+    // User data must be read in the context of the API method to
+    // provide contextual errors
+    const parseContext = this.userDataReader.createContext(
+      UserDataSource.Argument,
+      'delete'
+    );
+    stage._readUserData(parseContext);
+
+    return this._addStage(stage);
+  }
+
+  /**
+   * @beta
+   * Upserts the documents resulting from the pipeline.
+   *
+   * @example
+   * ```typescript
+   * firestore.pipeline().collection('new_books').upsert('books');
+   * ```
+   *
+   * @param collectionOrOptions - The target collection or options for the stage.
+   * @returns A new Pipeline object with this stage appended to the stage list.
+   */
+  upsert(): Pipeline;
+  upsert(collection: string | CollectionReference): Pipeline;
+  upsert(options: UpsertStageOptions): Pipeline;
+  upsert(
+    collectionOrOptions?: string | CollectionReference | UpsertStageOptions
+  ): Pipeline {
+    let options: UpsertStageOptions;
+    if (
+      typeof collectionOrOptions === 'string' ||
+      (typeof collectionOrOptions === 'object' &&
+        'type' in collectionOrOptions &&
+        collectionOrOptions.type === 'collection')
+    ) {
+      options = { collection: collectionOrOptions as string | CollectionReference };
+    } else {
+      options = (collectionOrOptions as UpsertStageOptions) || {};
+    }
+
+    const stage = new Upsert(options);
+
+    // User data must be read in the context of the API method to
+    // provide contextual errors
+    const parseContext = this.userDataReader.createContext(
+      UserDataSource.Argument,
+      'upsert'
+    );
+    stage._readUserData(parseContext);
+
+    return this._addStage(stage);
+  }
+
+  /**
+   * @beta
+   * Inserts the documents resulting from the pipeline.
+   *
+   * @example
+   * ```typescript
+   * firestore.pipeline().collection('new_books').insert('books');
+   * ```
+   *
+   * @param collectionOrOptions - The target collection or options for the stage.
+   * @returns A new Pipeline object with this stage appended to the stage list.
+   */
+  insert(collection: string | CollectionReference): Pipeline;
+  insert(options: InsertStageOptions): Pipeline;
+  insert(
+    collectionOrOptions: string | CollectionReference | InsertStageOptions
+  ): Pipeline {
+    let options: InsertStageOptions;
+    if (
+      typeof collectionOrOptions === 'string' ||
+      (typeof collectionOrOptions === 'object' &&
+        'type' in collectionOrOptions &&
+        collectionOrOptions.type === 'collection')
+    ) {
+      options = { collection: collectionOrOptions as string | CollectionReference };
+    } else {
+      options = collectionOrOptions as InsertStageOptions;
+    }
+
+    const stage = new Insert(options);
+
+    // User data must be read in the context of the API method to
+    // provide contextual errors
+    const parseContext = this.userDataReader.createContext(
+      UserDataSource.Argument,
+      'insert'
+    );
+    stage._readUserData(parseContext);
+
+    return this._addStage(stage);
+  }
 }
 
 export function isPipeline(val: unknown): val is Pipeline {

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

@@ -38,11 +38,13 @@
   Expression,
   Field,
   field,
-  Ordering
+  Ordering,
+  Selectable
 } from './expressions';
 import { Pipeline } from './pipeline';
 import { StageOptions } from './stage_options';
 import { isUserData, UserData } from './user_data_reader';
+import { selectablesToMap } from '../util/pipeline_util';
 
 /**
  * @beta
@@ -762,3 +764,127 @@
   }
   return expressionMap;
 }
+
+/**
+ * @beta
+ */
+export class Delete extends Stage {
+  get _name(): string {
+    return 'delete';
+  }
+
+  get _optionsUtil(): OptionsUtil {
+    return new OptionsUtil({
+      transactional: { serverName: 'transactional' },
+      returns: { serverName: 'returns' }
+    });
+  }
+
+  constructor(options: StageOptions) {
+    super(options);
+  }
+
+  /**
+   * @internal
+   * @private
+   */
+  _toProto(serializer: JsonProtoSerializer): ProtoStage {
+    return {
+      ...super._toProto(serializer),
+      args: []
+    };
+  }
+
+  _readUserData(context: ParseContext): void {
+    super._readUserData(context);
+  }
+}
+
+/**
+ * @beta
+ */
+export class Upsert extends Stage {
+  get _name(): string {
+    return 'upsert';
+  }
+
+  get _optionsUtil(): OptionsUtil {
+    return new OptionsUtil({
+      transactional: { serverName: 'transactional' },
+      returns: { serverName: 'returns' },
+      conflictResolution: { serverName: 'conflict_resolution' }
+    });
+  }
+
+  constructor(options: StageOptions) {
+    super(options);
+
+    if ('collection' in this.knownOptions && typeof this.knownOptions.collection === 'string') {
+      const collection = this.knownOptions.collection;
+      this.knownOptions.collection = collection.startsWith('/') ? collection : '/' + collection;
+    }
+  }
+
+  /**
+   * @internal
+   * @private
+   */
+  _toProto(serializer: JsonProtoSerializer): ProtoStage {
+    let args: any[] = [];
+    if (this.knownOptions.collection) {
+      args.push({ referenceValue: this.knownOptions.collection });
+    }
+    return {
+      ...super._toProto(serializer),
+      args
+    };
+  }
+
+  _readUserData(context: ParseContext): void {
+    super._readUserData(context);
+  }
+}
+
+/**
+ * @beta
+ */
+export class Insert extends Stage {
+  get _name(): string {
+    return 'insert';
+  }
+
+  get _optionsUtil(): OptionsUtil {
+    return new OptionsUtil({
+      transactional: { serverName: 'transactional' },
+      returns: { serverName: 'returns' }
+    });
+  }
+
+  constructor(options: StageOptions) {
+    super(options);
+
+    if ('collection' in this.knownOptions && typeof this.knownOptions.collection === 'string') {
+      const collection = this.knownOptions.collection;
+      this.knownOptions.collection = collection.startsWith('/') ? collection : '/' + collection;
+    }
+  }
+
+  /**
+   * @internal
+   * @private
+   */
+  _toProto(serializer: JsonProtoSerializer): ProtoStage {
+    let args: any[] = [];
+    if (this.knownOptions.collection) {
+      args.push({ referenceValue: this.knownOptions.collection });
+    }
+    return {
+      ...super._toProto(serializer),
+      args
+    };
+  }
+
+  _readUserData(context: ParseContext): void {
+    super._readUserData(context);
+  }
+}

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

@@ -343,3 +343,76 @@ export type SortStageOptions = StageOptions & {
    */
   orderings: Ordering[];
 };
+
+/**
+ * @beta
+ * Options defining how a WriteStage is evaluated.
+ */
+export type WriteStageOptions = StageOptions & {
+  /**
+   * @beta
+   * Whether the write should be performed in a transaction.
+   */
+  transactional?: boolean;
+};
+
+/**
+ * @beta
+ * Options defining how a DeleteStage is evaluated. See {@link @firebase/firestore/pipelines#Pipeline.(delete:1)}.
+ */
+export type DeleteStageOptions = WriteStageOptions & {
+  /**
+   * @beta
+   * Specifies what to return from the delete operation.
+   */
+  returns?: 'empty' | 'document_id';
+};
+
+/**
+ * @beta
+ * Options defining how an UpsertStage is evaluated. See {@link @firebase/firestore/pipelines#Pipeline.(upsert:1)}.
+ */
+export type UpsertStageOptions = WriteStageOptions & {
+  /**
+   * @beta
+   * Name or reference to the collection where documents will be upserted.
+   */
+  collection?: string | CollectionReference;
+  /**
+   * @beta
+   * Specifies what to return from the upsert operation.
+   */
+  returns?: 'empty' | 'document_id';
+  /**
+   * @beta
+   * Specifies the conflict resolution strategy.
+   */
+  conflictResolution?: 'overwrite' | 'merge' | 'fail' | 'keep';
+  /**
+   * @beta
+   * Expressions to apply during the upsert.
+   */
+  transformations?: Selectable[];
+};
+
+/**
+ * @beta
+ * Options defining how an InsertStage is evaluated. See {@link @firebase/firestore/pipelines#Pipeline.(insert:1)}.
+ */
+export type InsertStageOptions = WriteStageOptions & {
+  /**
+   * @beta
+   * Name or reference to the collection where documents will be inserted.
+   */
+  collection: string | CollectionReference;
+  /**
+   * @beta
+   * Specifies what to return from the insert operation.
+   */
+  returns?: 'empty' | 'document_id';
+  /**
+   * @beta
+   * Expressions to apply during the insert.
+   */
+  transformations?: Selectable[];
+};