feat(firestore, iOS): iOS implementation for Pipeline APIs (#18099)

* feat(firestore): iOS implementation for Pipeline APIs

* fix: conditionally import FIRPipelineBridge.h for iOS

* chore: add macOS support for FLTPipelineParser by linking to iOS implementation

* fix: conditionally include FIRPipelineBridge.h for macOS support in FLTPipelineParser

* chore: add support for missing Expression function

* refactor: clean up formatting in FLTPipelineParser.m for improved readability

* chore: enhance FLTPipelineParser with support for array and map expressions, ensuring proper argument handling

* chore: implement conditional expression and current timestamp handling in FLTPipelineParser

* chore: add 'find_nearest' stage support in FLTPipelineParser with validation for vector_field, vector_value, and distance_measure

* chore: introduce FLTFirebaseFirestoreErrorCodePipelineParse for improved error handling in pipeline parsing

* trigger CI

* fix: update header inclusion logic for FirebaseFirestore in FLTPipelineParser.m

* trigger CI

* chore: enhance FLTPipelineParser with new expression handling

Author: SelaseKay

packages/cloud_firestore/cloud_firestore/ios/cloud_firestore/Sources/cloud_firestore/FLTFirebaseFirestorePlugin.m

@@ -15,6 +15,7 @@
 #import "include/cloud_firestore/Private/FLTFirebaseFirestoreReader.h"
 #import "include/cloud_firestore/Private/FLTFirebaseFirestoreUtils.h"
 #import "include/cloud_firestore/Private/FLTLoadBundleStreamHandler.h"
+#import "include/cloud_firestore/Private/FLTPipelineParser.h"
 #import "include/cloud_firestore/Private/FLTQuerySnapshotStreamHandler.h"
 #import "include/cloud_firestore/Private/FLTSnapshotsInSyncStreamHandler.h"
 #import "include/cloud_firestore/Private/FLTTransactionStreamHandler.h"
@@ -73,6 +74,20 @@ - (NSString *)registerEventChannelWithPrefix:(NSString *)prefix
 
 static NSCache<NSNumber *, NSString *> *_serverTimestampMap;
 
+static id _Nullable FLTPipelineNullSafe(id value) {
+  return (value == nil || [value isKindOfClass:[NSNull class]]) ? nil : value;
+}
+
+static NSNumber *_Nullable FLTPipelineTimestampToMs(id value) {
+  if (!value) return nil;
+  if ([value isKindOfClass:[NSNumber class]]) return value;
+  if ([value isKindOfClass:[FIRTimestamp class]]) {
+    FIRTimestamp *ts = value;
+    return @((int64_t)ts.seconds * 1000 + (int64_t)ts.nanoseconds / 1000000);
+  }
+  return nil;
+}
+
 @implementation FLTFirebaseFirestorePlugin {
   NSMutableDictionary<NSString *, FlutterEventChannel *> *_eventChannels;
   NSMutableDictionary<NSString *, NSObject<FlutterStreamHandler> *> *_streamHandlers;
@@ -883,4 +898,66 @@ - (void)aggregateQueryApp:(nonnull FirestorePigeonFirebaseApp *)app
                  }];
 }
 
+- (void)executePipelineApp:(nonnull FirestorePigeonFirebaseApp *)app
+                    stages:(nonnull NSArray<NSDictionary<NSString *, id> *> *)stages
+                   options:(nullable NSDictionary<NSString *, id> *)options
+                completion:(nonnull void (^)(PigeonPipelineSnapshot *_Nullable,
+                                             FlutterError *_Nullable))completion {
+  FIRFirestore *firestore = [self getFIRFirestoreFromAppNameFromPigeon:app];
+
+  [FLTPipelineParser
+      executePipelineWithFirestore:firestore
+                            stages:stages
+                           options:options
+                        completion:^(id _Nullable snapshot, NSError *_Nullable error) {
+                          if (error) {
+                            completion(nil, [self convertToFlutterError:error]);
+                            return;
+                          }
+                          if (snapshot == nil) {
+                            completion(
+                                nil,
+                                [FlutterError errorWithCode:@"error"
+                                                    message:@"Pipeline execution returned no result"
+                                                    details:nil]);
+                            return;
+                          }
+
+                          NSMutableArray<PigeonPipelineResult *> *pigeonResults =
+                              [NSMutableArray array];
+                          NSArray *results = [snapshot results];
+                          if ([results isKindOfClass:[NSArray class]]) {
+                            for (id result in results) {
+                              id ref = [result reference];
+                              NSString *path = (ref && [ref respondsToSelector:@selector(path)])
+                                                   ? [ref path]
+                                                   : FLTPipelineNullSafe([result documentID]);
+                              NSNumber *createTime =
+                                  FLTPipelineTimestampToMs([result valueForKey:@"create_time"]);
+                              NSNumber *updateTime =
+                                  FLTPipelineTimestampToMs([result valueForKey:@"update_time"]);
+                              NSDictionary *data = FLTPipelineNullSafe([result data]);
+                              PigeonPipelineResult *pigeonResult =
+                                  [PigeonPipelineResult makeWithDocumentPath:path
+                                                                  createTime:createTime
+                                                                  updateTime:updateTime
+                                                                        data:data];
+                              [pigeonResults addObject:pigeonResult];
+                            }
+                          }
+
+                          NSNumber *executionTime =
+                              FLTPipelineTimestampToMs([snapshot execution_time]);
+                          if (executionTime == nil) {
+                            executionTime =
+                                @((int64_t)([[NSDate date] timeIntervalSince1970] * 1000));
+                          }
+
+                          PigeonPipelineSnapshot *pigeonSnapshot =
+                              [PigeonPipelineSnapshot makeWithResults:pigeonResults
+                                                        executionTime:executionTime];
+                          completion(pigeonSnapshot, nil);
+                        }];
+}
+
 @end

packages/cloud_firestore/cloud_firestore/ios/cloud_firestore/Sources/cloud_firestore/FLTFirebaseFirestoreUtils.m

@@ -21,6 +21,8 @@ - (FlutterStandardReader *_Nonnull)readerWithData:(NSData *)data {
 
 NSMutableDictionary<NSString *, FLTFirebaseFirestoreExtension *> *firestoreInstanceCache;
 
+const NSInteger FLTFirebaseFirestoreErrorCodePipelineParse = -1;
+
 @implementation FLTFirebaseFirestoreUtils
 
 + (NSString *)generateKeyForAppName:(NSString *)appName andDatabaseURL:(NSString *)databaseURL {
@@ -240,6 +242,11 @@ + (NSArray *)ErrorCodeAndMessageFromNSError:(NSError *)error {
       code = @"unknown";
       message = @"Unknown error or an error from a different error domain.";
       break;
+    case FLTFirebaseFirestoreErrorCodePipelineParse:
+      code = @"parse-error";
+      message = (error.localizedDescription.length > 0) ? error.localizedDescription
+                                                        : @"An unknown error occurred.";
+      break;
     default:
       code = @"unknown";
       message = @"An unknown error occurred.";