feat: support appendMissingElements (arrayUnion) in YustFieldTransform

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 3.34.0 - 2026-05-19
+
+- Add `appendMissingElements` to `YustFieldTransform` (Firestore `arrayUnion`) on Dart, Flutter, and mocked backends; mocked service now also honors `removeFromArray`, `setToServerTimestamp`, and `delete`
+
 ## 3.33.2 - 2026-05-18
 
 - Fix handling of empty maps in `YustDatabaseService` (dart-only)

lib/src/services/yust_database_service_mocked.dart

@@ -512,13 +512,47 @@ class YustDatabaseServiceMocked extends YustDatabaseService
 
     for (final t in fieldTransforms) {
       final unescapedPath = t.fieldPath.replaceAll('`', '');
-      final oldValue =
-          (_readValueInJsonDoc(jsonDocClone, unescapedPath) ?? 0) as num;
-      _changeValueInJsonDoc(
-        jsonDocClone,
-        oldValue + (t.increment ?? 0),
-        unescapedPath,
-      );
+      if (t.appendMissingElements != null) {
+        final current = _readValueInJsonDoc(jsonDocClone, unescapedPath);
+        final list = (current is List)
+            ? List<dynamic>.from(current)
+            : <dynamic>[];
+        for (final element in t.appendMissingElements!) {
+          if (!list.any(
+            (e) => const DeepCollectionEquality().equals(e, element),
+          )) {
+            list.add(element);
+          }
+        }
+        _changeValueInJsonDoc(jsonDocClone, list, unescapedPath);
+      } else if (t.removeFromArray != null) {
+        final current = _readValueInJsonDoc(jsonDocClone, unescapedPath);
+        final list = (current is List)
+            ? List<dynamic>.from(current)
+            : <dynamic>[];
+        list.removeWhere(
+          (e) => t.removeFromArray!.any(
+            (r) => const DeepCollectionEquality().equals(e, r),
+          ),
+        );
+        _changeValueInJsonDoc(jsonDocClone, list, unescapedPath);
+      } else if (t.delete == true) {
+        _changeValueInJsonDoc(jsonDocClone, null, unescapedPath);
+      } else if (t.setToServerTimestamp == true) {
+        _changeValueInJsonDoc(
+          jsonDocClone,
+          DateTime.now().toUtc().toIso8601String(),
+          unescapedPath,
+        );
+      } else {
+        final oldValue =
+            (_readValueInJsonDoc(jsonDocClone, unescapedPath) ?? 0) as num;
+        _changeValueInJsonDoc(
+          jsonDocClone,
+          oldValue + (t.increment ?? 0),
+          unescapedPath,
+        );
+      }
       jsonDocs[index] = jsonDocClone;
       await onChange?.call(
         _getParentPath(docSetup, id: id),

lib/src/util/yust_field_transform_dart.dart

@@ -5,13 +5,15 @@ import '../../yust.dart';
 class YustFieldTransform {
   String fieldPath;
   double? increment;
+  List<dynamic>? appendMissingElements;
   List<dynamic>? removeFromArray;
   bool? setToServerTimestamp;
   bool? delete;
 
   YustFieldTransform({
     required String fieldPath,
     this.increment,
+    this.appendMissingElements,
     this.removeFromArray,
     this.setToServerTimestamp,
     this.delete,
@@ -27,6 +29,11 @@ class YustFieldTransform {
     return FieldTransform(
       fieldPath: YustHelpers().toQuotedFieldPath(fieldPath),
       increment: increment != null ? Value(doubleValue: increment) : null,
+      appendMissingElements: appendMissingElements != null
+          ? ArrayValue.fromJson(<dynamic, dynamic>{
+              'values': appendMissingElements,
+            })
+          : null,
       removeAllFromArray: removeFromArray != null
           ? ArrayValue.fromJson(<dynamic, dynamic>{'values': removeFromArray})
           : null,

lib/src/util/yust_field_transform_flutter.dart

@@ -3,13 +3,15 @@ import 'package:cloud_firestore/cloud_firestore.dart';
 class YustFieldTransform {
   String fieldPath;
   double? increment;
+  List<dynamic>? appendMissingElements;
   List<dynamic>? removeFromArray;
   bool? setToServerTimestamp;
   bool? delete;
 
   YustFieldTransform({
     required String fieldPath,
     this.increment,
+    this.appendMissingElements,
     this.removeFromArray,
     this.setToServerTimestamp,
     this.delete,
@@ -23,6 +25,9 @@ class YustFieldTransform {
   /// ... and for dart (googleapis/firestore) its a [FieldTransform]
   dynamic toNativeTransform() {
     if (increment != null) return FieldValue.increment(increment!);
+    if (appendMissingElements != null) {
+      return FieldValue.arrayUnion(appendMissingElements!);
+    }
     if (removeFromArray != null) {
       return FieldValue.arrayRemove(removeFromArray!);
     }

pubspec.yaml

@@ -1,6 +1,6 @@
 name: yust
 description: Build awesome apps with Flutter and Firebase - this package allows communication with Firebase to be a breeze.
-version: 3.33.2
+version: 3.34.0
 homepage: https://github.com/univelop/yust
 
 environment: