feat: add SetOptions for merging data in BulkWriter and WriteBatch

Author: demolaf

packages/googleapis_firestore/lib/googleapis_firestore.dart

@@ -48,4 +48,5 @@ export 'src/firestore.dart'
         DocumentChange,
         DocumentChangeType,
         Precondition,
-        TransactionHandler;
+        TransactionHandler,
+        SetOptions;

packages/googleapis_firestore/lib/src/bulk_writer.dart

@@ -575,9 +575,17 @@ class BulkWriter {
   ///     print('Write failed with: $err');
   ///   });
   /// ```
-  Future<WriteResult> set<T>(DocumentReference<T> ref, T data) {
+  Future<WriteResult> set<T>(
+    DocumentReference<T> ref,
+    T data, {
+    SetOptions? options,
+  }) {
     _verifyNotClosed();
-    return _enqueue(ref, 'set', (batch) => batch.set(ref, data));
+    return _enqueue(
+      ref,
+      'set',
+      (batch) => batch.set(ref, data, options: options),
+    );
   }
 
   /// Update fields of the document referred to by the provided

packages/googleapis_firestore/lib/src/document.dart

@@ -474,8 +474,110 @@ class _DocumentMask {
     return _DocumentMask(fieldPaths);
   }
 
+  /// Creates a document mask from a list of field paths.
+  factory _DocumentMask.fromFieldMask(List<FieldPath> fieldMask) {
+    return _DocumentMask(List.from(fieldMask));
+  }
+
+  /// Creates a document mask with the field names of a document.
+  /// Recursively extracts all field paths from the data object.
+  factory _DocumentMask.fromObject(Map<String, Object?> data) {
+    final fieldPaths = <FieldPath>[];
+
+    void extractFieldPaths(
+      Map<String, Object?> currentData, [
+      FieldPath? currentPath,
+    ]) {
+      var isEmpty = true;
+
+      for (final entry in currentData.entries) {
+        isEmpty = false;
+
+        final key = entry.key;
+        final childSegment = FieldPath([key]);
+        final childPath = currentPath != null
+            ? currentPath.append(childSegment)
+            : childSegment;
+        final value = entry.value;
+
+        if (value is _FieldTransform) {
+          if (value.includeInDocumentMask) {
+            fieldPaths.add(childPath);
+          }
+        } else if (value is Map<String, Object?>) {
+          extractFieldPaths(value, childPath);
+        } else if (value != null) {
+          fieldPaths.add(childPath);
+        }
+      }
+
+      // Add a field path for an explicitly updated empty map.
+      if (currentPath != null && isEmpty) {
+        fieldPaths.add(currentPath);
+      }
+    }
+
+    extractFieldPaths(data);
+    return _DocumentMask(fieldPaths);
+  }
+
   final List<FieldPath> _sortedPaths;
 
+  bool get isEmpty => _sortedPaths.isEmpty;
+
+  /// Removes the specified field paths from this document mask.
+  void removeFields(List<FieldPath> fieldPaths) {
+    _sortedPaths.removeWhere((path) => fieldPaths.any((fp) => path == fp));
+  }
+
+  /// Returns whether this document mask contains the specified field path.
+  bool contains(FieldPath fieldPath) {
+    return _sortedPaths.any((path) => path == fieldPath);
+  }
+
+  /// Applies this DocumentMask to data and returns a new object containing only
+  /// the fields specified in the mask.
+  Map<String, Object?> applyTo(Map<String, Object?> data) {
+    final remainingPaths = List<FieldPath>.from(_sortedPaths);
+
+    Map<String, Object?> processObject(
+      Map<String, Object?> currentData, [
+      FieldPath? currentPath,
+    ]) {
+      final result = <String, Object?>{};
+
+      for (final entry in currentData.entries) {
+        final key = entry.key;
+        final childSegment = FieldPath([key]);
+        final childPath = currentPath != null
+            ? currentPath.append(childSegment)
+            : childSegment;
+
+        // Check if this field or any of its children are in the mask
+        final shouldInclude = remainingPaths.any((path) {
+          return path == childPath || path.isPrefixOf(childPath);
+        });
+
+        if (shouldInclude) {
+          final value = entry.value;
+
+          if (value is Map<String, Object?>) {
+            result[key] = processObject(value, childPath);
+          } else {
+            result[key] = value;
+          }
+
+          // Remove this path from remaining
+          remainingPaths.removeWhere((path) => path == childPath);
+        }
+      }
+
+      return result;
+    }
+
+    return processObject(data);
+  }
+
   firestore_v1.DocumentMask toProto() {
     if (_sortedPaths.isEmpty) return firestore_v1.DocumentMask();
 

packages/googleapis_firestore/lib/src/firestore.dart

@@ -3,6 +3,7 @@ import 'dart:convert' show jsonDecode, jsonEncode;
 import 'dart:io';
 import 'dart:math' as math;
 import 'dart:typed_data';
+
 import 'package:collection/collection.dart';
 import 'package:googleapis/firestore/v1.dart' as firestore_v1;
 import 'package:googleapis_auth/googleapis_auth.dart'
@@ -13,11 +14,11 @@ import 'package:http/http.dart'
     show BaseRequest, StreamedResponse, ByteStream, BaseClient, Client;
 import 'package:intl/intl.dart';
 import 'package:meta/meta.dart';
-
 import 'backoff.dart';
 import 'environment.dart';
 
 part 'aggregate.dart';
+part 'bulk_writer.dart';
 part 'collection_group.dart';
 part 'convert.dart';
 part 'document.dart';
@@ -29,6 +30,7 @@ part 'firestore_exception.dart';
 part 'firestore_http_client.dart';
 part 'geo_point.dart';
 part 'path.dart';
+part 'rate_limiter.dart';
 part 'reference/aggregate_query.dart';
 part 'reference/aggregate_query_snapshot.dart';
 part 'reference/collection_reference.dart';
@@ -44,15 +46,14 @@ part 'reference/query_snapshot.dart';
 part 'reference/query_util.dart';
 part 'reference/types.dart';
 part 'serializer.dart';
+part 'set_options.dart';
 part 'status_code.dart';
 part 'timestamp.dart';
 part 'transaction.dart';
 part 'types.dart';
 part 'util.dart';
 part 'validate.dart';
 part 'write_batch.dart';
-part 'rate_limiter.dart';
-part 'bulk_writer.dart';
 
 /// Plain credentials object for service account authentication.
 ///

packages/googleapis_firestore/lib/src/path.dart

@@ -312,6 +312,12 @@ class FieldPath extends _Path<FieldPath> {
         .join('.');
   }
 
+  /// Checks whether this field path is a prefix of the specified path.
+  bool isPrefixOf(FieldPath other) => _isPrefixOf(other);
+
+  /// Appends a child segment to this field path.
+  FieldPath append(FieldPath childSegment) => _appendPath(childSegment);
+
   @override
   FieldPath _construct(List<String> segments) => FieldPath(segments);
 

packages/googleapis_firestore/lib/src/reference/document_reference.dart

@@ -135,9 +135,11 @@ final class DocumentReference<T> implements _Serializable {
   }
 
   /// Writes to the document referred to by this DocumentReference. If the
-  /// document does not yet exist, it will be created.
-  Future<WriteResult> set(T data) async {
-    final writeBatch = WriteBatch._(firestore)..set(this, data);
+  /// document does not yet exist, it will be created. If [SetOptions] is provided,
+  /// the data can be merged into the existing document.
+  Future<WriteResult> set(T data, {SetOptions? options}) async {
+    final writeBatch = WriteBatch._(firestore)
+      ..set(this, data, options: options);
 
     final results = await writeBatch.commit();
     return results.single;

packages/googleapis_firestore/lib/src/set_options.dart

@@ -0,0 +1,94 @@
+part of 'firestore.dart';
+
+/// Options to configure [WriteBatch.set], [Transaction.set], and [BulkWriter.set] behavior.
+///
+/// Provides control over whether the set operation should merge data into an
+/// existing document instead of replacing it entirely.
+@immutable
+sealed class SetOptions {
+  const SetOptions._();
+
+  /// Merge all provided fields.
+  ///
+  /// If a field is present in the data but not in the document, it will be added.
+  /// If a field is present in both, the document's field will be updated.
+  /// Fields in the document that are not in the data will remain untouched.
+  const factory SetOptions.merge() = _MergeAllSetOptions;
+
+  /// Merge only the specified fields.
+  ///
+  /// Only the field paths listed in [mergeFields] will be updated or created.
+  /// All other fields will remain untouched.
+  ///
+  /// Example:
+  /// ```dart
+  /// // Only update the 'name' field, leave other fields unchanged
+  /// ref.set(
+  ///   {'name': 'John', 'age': 30},
+  ///   SetOptions.mergeFields([FieldPath(['name'])]),
+  /// );
+  /// ```
+  const factory SetOptions.mergeFields(List<FieldPath> fields) =
+      _MergeFieldsSetOptions;
+
+  /// Whether this represents a merge operation (either merge all or specific fields).
+  bool get isMerge;
+
+  /// The list of field paths to merge. Null if merging all fields or not merging.
+  List<FieldPath>? get mergeFields;
+
+  @override
+  bool operator ==(Object other);
+
+  @override
+  int get hashCode;
+}
+
+/// Merge all fields from the provided data.
+@immutable
+class _MergeAllSetOptions extends SetOptions {
+  const _MergeAllSetOptions() : super._();
+
+  @override
+  bool get isMerge => true;
+
+  @override
+  List<FieldPath>? get mergeFields => null;
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) || other is _MergeAllSetOptions;
+
+  @override
+  int get hashCode => runtimeType.hashCode;
+
+  @override
+  String toString() => 'SetOptions.merge()';
+}
+
+/// Merge only the specified field paths.
+@immutable
+class _MergeFieldsSetOptions extends SetOptions {
+  const _MergeFieldsSetOptions(this.fields) : super._();
+
+  final List<FieldPath> fields;
+
+  @override
+  bool get isMerge => true;
+
+  @override
+  List<FieldPath>? get mergeFields => fields;
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      (other is _MergeFieldsSetOptions &&
+          const ListEquality<FieldPath>().equals(fields, other.fields));
+
+  @override
+  int get hashCode =>
+      Object.hash(runtimeType, const ListEquality<FieldPath>().hash(fields));
+
+  @override
+  String toString() => 'SetOptions.mergeFields($fields)';
+}

packages/googleapis_firestore/lib/src/transaction.dart

@@ -140,24 +140,24 @@ class Transaction {
     _writeBatch.create(documentRef, documentData);
   }
 
-  //TODO support SetOptions to include merge parameter
-
   /// Write to the document referred to by the provided
   /// [DocumentReference]. If the document does not exist yet, it will be
   /// created. If the document already exists, its contents will be
-  /// overwritten with the newly provided data.
+  /// overwritten with the newly provided data unless [SetOptions] is provided
+  /// to merge the data.
   ///
   /// - [documentRef]: A reference to the document to be set.
   /// - [data] The object to serialize as the document.
+  /// - [options] Optional [SetOptions] to control merge behavior.
   ///
-  void set<T>(DocumentReference<T> documentRef, T data) {
+  void set<T>(DocumentReference<T> documentRef, T data, {SetOptions? options}) {
     if (_writeBatch == null) {
       throw FirestoreException(
         FirestoreClientErrorCode.failedPrecondition,
         readOnlyWriteErrorMsg,
       );
     }
-    _writeBatch.set<T>(documentRef, data);
+    _writeBatch.set<T>(documentRef, data, options: options);
   }
 
   /// Updates fields in the document referred to by the provided