feat(api): add copyWith to GraphQLRequest (#4365)

packages/amplify_core/lib/src/types/api/graphql/graphql_request.dart

@@ -74,4 +74,39 @@ class GraphQLRequest<T> with AWSSerializable<Map<String, Object?>> {
           'authorizationMode': authorizationMode!.name,
         if (decodePath != null) 'decodePath': decodePath,
       };
+
+  /// Creates a copy of this request with the given fields replaced with the new values.
+  /// If no new value is given, the old value is used.
+  ///
+  /// ```dart
+  /// final original = ModelQueries.list(
+  ///   Blog.classType,
+  /// );
+  /// final modified = original.copyWith(
+  ///   document: yourCustomQuery,
+  /// );
+  /// ```
+  ///
+  /// Useful in advanced scenarios where you want to modify the request before sending it.
+  ///
+  /// See https://docs.amplify.aws/lib/graphqlapi/advanced-workflows/q/platform/flutter/.
+  GraphQLRequest<T> copyWith({
+    String? document,
+    String? apiName,
+    Map<String, String>? headers,
+    APIAuthorizationType? authorizationMode,
+    Map<String, dynamic>? variables,
+    String? decodePath,
+    ModelType? modelType,
+  }) {
+    return GraphQLRequest<T>(
+      document: document ?? this.document,
+      apiName: apiName ?? this.apiName,
+      headers: headers ?? this.headers,
+      authorizationMode: authorizationMode ?? this.authorizationMode,
+      variables: variables ?? this.variables,
+      decodePath: decodePath ?? this.decodePath,
+      modelType: modelType ?? this.modelType,
+    );
+  }
 }

packages/api/amplify_api/example/integration_test/graphql/iam_test.dart

@@ -188,6 +188,37 @@ void main({bool useExistingTestUser = false}) {
         expect(postFromResponse?.title, title);
       });
 
+      testWidgets('should copyWith request', (WidgetTester tester) async {
+        final title = 'Lorem Ipsum Test Post: ${uuid()}';
+        const rating = 0;
+        final createdPost = await addPostAndBlog(title, rating);
+        final blogId = createdPost.blog?.id;
+
+        // Original request with mock id
+        final req = ModelQueries.list(
+          Post.classType,
+          where: Post.BLOG.eq(uuid()),
+          limit: _limit,
+        );
+
+        // Copy request with actual blog id
+        final copiedRequest = req.copyWith(
+          variables: {
+            ...req.variables,
+            'filter': {
+              'blogID': {'eq': blogId},
+            },
+          },
+        );
+        final res = await Amplify.API.query(request: copiedRequest).response;
+        final postFromResponse = res.data?.items[0];
+
+        expect(res, hasNoGraphQLErrors);
+        expect(postFromResponse?.blog?.id, isNotNull);
+        expect(postFromResponse?.blog?.id, blogId);
+        expect(postFromResponse?.title, title);
+      });
+
       testWidgets('should decode a custom list request',
           (WidgetTester tester) async {
         final name = 'Lorem Ipsum Test Blog: ${uuid()}';