- Added better support for Mutation handling so that single payload (per Mutation convention best practices) can be returned easily via ReceiveGraphQLMutationResult; this eliminates the need to use ReceiveGraphQLRawJsonResponse for dynamic Mutation response handling.

cajuncoding · cajuncoding · commit 1cde15c0161d · 2023-09-30T23:12:42.000-05:00
- Fixed bug to ensure Errors are returned on IGraphQLQueryResults when possible (not available on Batch Queries).
- Fixed bug in processing logic for paginated reqquests when TotalCount is the only selected field on a paginated request; only affected CollectionSegment/Offset Paging requests.
diff --git a/FlurlGraphQL.Querying/Flurl/FlurlGraphQLRequest.cs b/FlurlGraphQL.Querying/Flurl/FlurlGraphQLRequest.cs
@@ -1,4 +1,5 @@
 ﻿using System;
+using System.Collections;
 using System.Collections.Generic;
 using System.Collections.ObjectModel;
 using System.Linq;
@@ -34,6 +35,8 @@ internal FlurlGraphQLRequest(IFlurlRequest baseRequest)
 
         public GraphQLQueryType GraphQLQueryType { get; protected set; }
 
+        public bool IsMutationQuery { get; protected set; }
+
 
         #region GraphQL Variables
 
@@ -121,6 +124,7 @@ public IFlurlGraphQLRequest WithGraphQLQuery(string query, NullValueHandling nul
                 ClearGraphQLQuery();
                 GraphQLQuery = query;
                 GraphQLQueryType = GraphQLQueryType.Query;
+                IsMutationQuery = DetermineIfMutationQuery(query);
             }
 
             return this;
@@ -139,13 +143,21 @@ public IFlurlGraphQLRequest WithGraphQLPersistedQuery(string id, NullValueHandli
                 ClearGraphQLQuery();
                 GraphQLQuery = id;
                 GraphQLQueryType = GraphQLQueryType.PersistedQuery;
+                IsMutationQuery = false;
             }
 
             return this;
         }
 
         #endregion
 
+        #region QueryParsing Helpers
+
+        protected bool DetermineIfMutationQuery(string query)
+            => query?.TrimStart().StartsWith("mutation", StringComparison.OrdinalIgnoreCase) ?? false;
+
+        #endregion
+
         #region ClearGraphQLQuery(), Clone()
 
         public IFlurlGraphQLRequest ClearGraphQLQuery()
@@ -235,8 +247,7 @@ protected string BuildPostRequestJsonPayload()
         {
             //Execute the Query with the GraphQL Server...
             //var graphqlPayload = new FlurlGraphQLRequestPayloadBuilder(graphqlQueryType, graphqlQueryOrId, this.GraphQLVariablesInternal);
-            var graphqlPayload = new Dictionary<string, object>();
-            graphqlPayload.Add("variables", this.GraphQLVariablesInternal);
+            var graphqlPayload = new Dictionary<string, object> { { "variables", this.GraphQLVariablesInternal } };
 
             switch (GraphQLQueryType)
             {
diff --git a/FlurlGraphQL.Querying/Flurl/FlurlGraphQLResponseExtensions.Internal.cs b/FlurlGraphQL.Querying/Flurl/FlurlGraphQLResponseExtensions.Internal.cs
@@ -273,26 +273,31 @@ internal static IGraphQLQueryResults<TEntityResult> ParseJsonToGraphQLResultsWit
                     case JArray arrayResults:
                         entityResults = arrayResults.ToObject<List<TEntityResult>>(jsonSerializer);
                         break;
+                    // ReSharper disable once MergeIntoPattern
                     case JObject jsonObj when jsonObj.First is JArray firstArrayResults:
                         entityResults = firstArrayResults.ToObject<List<TEntityResult>>(jsonSerializer);
                         break;
+                    //If only a single Object was returned then this is likely a Mutation so we return the single
+                    //  item as the first-and-only result of the set...
+                    case JObject jsonObj:
+                        var singleResult = jsonObj.ToObject<TEntityResult>(jsonSerializer);
+                        entityResults = new List<TEntityResult>() { singleResult };
+                        break;
                 }
             }
 
             //If the results have Paging Info we map to the correct type (Connection/Cursor or CollectionSegment/Offset)...
-            //NOTE: If we have a Total Count then we also must return a Paging result because it's possible to
-            //      request TotalCount by itself without any other PageInfo or Nodes...
-            if (paginationType == PaginationType.Cursor || totalCount.HasValue)
-            {
+            if (paginationType == PaginationType.Cursor)
                 return new GraphQLConnectionResults<TEntityResult>(entityResults, totalCount, pageInfo);
-            }
             else if (paginationType == PaginationType.Offset)
-            {
                 return new GraphQLCollectionSegmentResults<TEntityResult>(entityResults, totalCount, GraphQLOffsetPageInfo.FromCursorPageInfo(pageInfo));
-            }
-
+            //If we have a Total Count then we also must return a Paging result because it's possible to request TotalCount by itself without any other PageInfo or Nodes...
+            //NOTE: WE must check this AFTER we process based on Cursor Type to make sure Cursor/Offset are both handled (if specified)...
+            else if (totalCount.HasValue)
+                return new GraphQLConnectionResults<TEntityResult>(entityResults, totalCount, pageInfo);
             //If not a paging result then we simply return the typed results...
-            return new GraphQLQueryResults<TEntityResult>(entityResults);
+            else
+                return new GraphQLQueryResults<TEntityResult>(entityResults);
         }
 
         internal static JArray FlattenGraphQLEdgesJsonToArrayOfNodes(this JArray edgesJson)
diff --git a/FlurlGraphQL.Querying/Flurl/FlurlGraphQLResponseExtensions.cs b/FlurlGraphQL.Querying/Flurl/FlurlGraphQLResponseExtensions.cs
@@ -1,6 +1,7 @@
 ﻿using System;
 using Newtonsoft.Json.Linq;
 using System.Collections.Generic;
+using System.Linq;
 using System.Threading.Tasks;
 using System.Threading;
 
@@ -41,6 +42,42 @@ public static async Task<IGraphQLQueryResults<TResult>> ReceiveGraphQLQueryResul
         public static Task<IGraphQLQueryResults<TResult>> ReceiveGraphQLQueryResults<TResult>(this IFlurlGraphQLResponse response, string queryOperationName = null)
             where TResult : class => Task.FromResult(response).ReceiveGraphQLQueryResults<TResult>(queryOperationName);
 
+        /// <summary>
+        /// Processes/parses the results of the GraphQL mutation execution into the specified result payload. 
+        /// This assumes that the Mutation conventions used follow best practices in that GraphQL mutations should take in and Input payload
+        /// and return a result Payload; the result payload may be the single object type or a root type for a collection of results & errors (as defined by the GraphQL Schema).
+        /// However, if you need more control over the processing of the Results you can dynamically handle it with the ReceiveGraphQLRawJsonResponse() method.
+        /// </summary>
+        /// <typeparam name="TResult"></typeparam>
+        /// <param name="responseTask"></param>
+        /// <param name="queryOperationName"></param>
+        /// <returns>Returns an IGraphQLQueryResults set of typed results.</returns>
+        public static async Task<TResult> ReceiveGraphQLMutationResult<TResult>(this Task<IFlurlGraphQLResponse> responseTask, string queryOperationName = null)
+            where TResult : class
+        {
+            return await responseTask.ProcessResponsePayloadInternalAsync((resultPayload, _) =>
+            {
+                var results = resultPayload.LoadTypedResults<TResult>(queryOperationName);
+                //For Single Item Mutation Result, we process with the same logic but there will be only one item (vs many for a Query)...
+                var mutationResult = results.FirstOrDefault();
+                return mutationResult;
+            }).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// Processes/parses the results of the GraphQL mutation execution into the specified result payload. 
+        /// This assumes that the Mutation conventions used follow best practices in that GraphQL mutations should take in and Input payload
+        /// and return a result Payload; the result payload may be the single object type or a root type for a collection of results & errors (as defined by the GraphQL Schema).
+        /// However, if you need more control over the processing of the Results you can dynamically handle it with the ReceiveGraphQLRawJsonResponse() method.
+        /// </summary>
+        /// <typeparam name="TResult"></typeparam>
+        /// <param name="response"></param>
+        /// <param name="queryOperationName"></param>
+        /// <returns>Returns an IGraphQLQueryResults set of typed results.</returns>
+        public static Task<TResult> ReceiveGraphQLMutationResult<TResult>(this IFlurlGraphQLResponse response, string queryOperationName = null)
+            where TResult : class => Task.FromResult(response).ReceiveGraphQLMutationResult<TResult>(queryOperationName);
+
+
         /// <summary>
         /// Processes/parses the results of the GraphQL query execution into a raw Json Result with all raw Json response Data available for processing.
         /// </summary>
diff --git a/FlurlGraphQL.Querying/Flurl/InternalClasses/FlurlGraphQLResponsePayload.cs b/FlurlGraphQL.Querying/Flurl/InternalClasses/FlurlGraphQLResponsePayload.cs
@@ -39,6 +39,10 @@ public IGraphQLQueryResults<TResult> LoadTypedResults<TResult>(string queryOpera
                 : null;
 
             var typedResults = querySingleResultJson.ParseJsonToGraphQLResultsInternal<TResult>(jsonSerializerSettings);
+            
+            if(typedResults is GraphQLQueryResults<TResult> graphqlResults)
+                graphqlResults.SetErrorsInternal(Errors);
+
             return typedResults;
         }
     }
diff --git a/FlurlGraphQL.Querying/FlurlGraphQL.Querying.csproj b/FlurlGraphQL.Querying/FlurlGraphQL.Querying.csproj
@@ -2,22 +2,26 @@
 
 	<PropertyGroup>
 		<TargetFrameworks>netstandard2.0;netstandard2.1</TargetFrameworks>
-		<Version>1.2.0</Version>
-		<AssemblyVersion>1.2.0</AssemblyVersion>
-		<FileVersion>1.2.0</FileVersion>
+		<Version>1.3.0</Version>
+		<AssemblyVersion>1.3.0</AssemblyVersion>
+		<FileVersion>1.3.0</FileVersion>
 		<Authors>BBernard / CajunCoding</Authors>
 		<Company>CajunCoding</Company>
-		<Description>GraphQL client querying extensions for Flurl.Http -- lightweight, simplified, asynchronous, fluent GraphQL client querying API extensions for the amazing Flurl Http library!</Description>
+		<Description>GraphQL client extensions for Flurl.Http -- lightweight, simplified, asynchronous, fluent GraphQL client API extensions for the amazing Flurl Http library!</Description>
 		<Copyright>Copyright © 2023</Copyright>
 		<PackageLicenseExpression>MIT</PackageLicenseExpression>
 		<PackageProjectUrl>https://github.com/cajuncoding/FlurlGraphQL</PackageProjectUrl>
 		<RepositoryUrl>https://github.com/cajuncoding/FlurlGraphQL</RepositoryUrl>
 		<PackageReleaseNotes>
 			Release Notes:
-			- Added support to control the Persisted Query payload field name for other GraphQL servers (e.g. Relay server) which may be different than HotChocolate .NET GraphQL Server.
-			- Added global configuration support via FlurlGraphQLConfig.ConfigureDefaults(config => ...) so that configurable options can be set once globlly with current support for Persisted Query Field Name and Json Serializer Settings.
+			- Added better support for Mutation handling so that single payload (per Mutation convention best practices) can be returned easily via ReceiveGraphQLMutationResult;
+			this eliminates the need to use ReceiveGraphQLRawJsonResponse for dynamic Mutation response handling.
+			- Fixed bug to ensure Errors are returned on IGraphQLQueryResults when possible (not available on Batch Queries).
+			- Fixed bug in processing logic for paginated reqquests when TotalCount is the only selected field on a paginated request; only affected CollectionSegment/Offset Paging requests.
 
 			Prior Release Notes:
+			- Added support to control the Persisted Query payload field name for other GraphQL servers (e.g. Relay server) which may be different than HotChocolate .NET GraphQL Server.
+			- Added global configuration support via FlurlGraphQLConfig.ConfigureDefaults(config => ...) so that configurable options can be set once globlly with current support for Persisted Query Field Name and Json Serializer Settings.
 			- Added support for Persisted Queries via .WithGraphQLPersistedQuery() api.
 			- Added support to execute GraphQL as GET requests for edge cases, though POST requests are highly encouraged.
 			- Improved consistency of use of (optional) custom Json Serialization settings when SetGraphQLNewtonsoftJsonSerializerSettings() is used to override the default GraphQL settings;
diff --git a/FlurlGraphQL.Querying/GraphQL/GraphQLQueryResults.cs b/FlurlGraphQL.Querying/GraphQL/GraphQLQueryResults.cs
@@ -10,7 +10,7 @@ namespace FlurlGraphQL.Querying
     public class GraphQLQueryResults<TResult> : IReadOnlyList<TResult>, IGraphQLQueryResults<TResult> 
         where TResult : class
     {
-        public GraphQLQueryResults(IList<TResult> results = null, IList<GraphQLError> errors = null)
+        public GraphQLQueryResults(IList<TResult> results = null, IReadOnlyList<GraphQLError> errors = null)
         {
             //The Results should be null safe as an empty list if no results exist.
             Results = results ?? new List<TResult>();
@@ -19,12 +19,19 @@ public GraphQLQueryResults(IList<TResult> results = null, IList<GraphQLError> er
             Errors = errors;
         }
 
+        //NOTE: Due to various code flows and inheritance it's not easy (or clean) to pass the Errors through
+        //      to the constructor so to simplify we have support to Internally Set this value when building the Results...
+        internal void SetErrorsInternal(IReadOnlyList<GraphQLError> errors)
+        {
+            Errors = errors;
+        }
+
         protected IList<TResult> Results { get; }
         public bool HasAnyResults() => Results.Count > 0;
         // Internal Helper for Constructing results (e.g. GraphQLCollectionSegmentResults paging which is adapted from the Connection Results)...
         internal IList<TResult> GetResultsInternal() => Results;
 
-        public IList<GraphQLError> Errors { get; }
+        public IReadOnlyList<GraphQLError> Errors { get; protected set; }
         public bool HasAnyErrors() => this.Errors?.Count > 0;
 
         #region IReadOnlyList / IEnumerable Implementation
diff --git a/FlurlGraphQL.Querying/GraphQL/Interfaces/IGraphQLQueryResults.cs b/FlurlGraphQL.Querying/GraphQL/Interfaces/IGraphQLQueryResults.cs
@@ -6,7 +6,7 @@ public interface IGraphQLQueryResults<out TResult> : IReadOnlyList<TResult>
         where TResult: class
     {
         bool HasAnyResults();
-        IList<GraphQLError> Errors { get; }
+        IReadOnlyList<GraphQLError> Errors { get; }
         bool HasAnyErrors();
     }
 
diff --git a/README.md b/README.md
@@ -260,7 +260,6 @@ foreach (var pageTask in graphqlPagesTasks)
 }
 ```
 
-
 ### Offset/Slice Paging results via CollectionSegment...
 Offset based paging is not recommeded by GraphQL.org and therefore is less formalized with [no recommended implemenation](https://graphql.org/learn/pagination/#pagination-and-edges). 
 So this api is compliant with the [HotChocolate .NET GraphQL Server] approach wich is fully GraphQL Spec compliant and [provides a formal implementaiton of Offset paging](https://chillicream.com/docs/hotchocolate/v12/fetching-data/pagination#offset-pagination) 
@@ -389,6 +388,49 @@ foreach (var result in results)
 }
 ```
 
+### Mutations...
+GraphQL provides the ability to create, update, delete data in what are called mutation operations. In addition, *mutations* are different from queries in that they
+have different conventions and best practices for their implementations. In general, GraphQL mutations should take in a single *Input* and return a single 
+result *Payload*; the result payload may be a single business object type but is more commonly a root type for a collection of Results & Errors (as defined by the GraphQL Schema).
+
+Due to the complexity of all the varying types of Mutation Input & result Paylaod designs the API for mutations will fallback to parse the response as a single
+object result model (as opposed to a an Array that a Query would return). Therefore, your model should implement any/all of the response Payload field features you are interested in.
+
+And if you need even more low level processing or just want to handle the Mutation result more dynamically then you can always use raw Json handling 
+via the ReceiveGraphQLRawJsonResponse API (see below).
+
+```csharp
+var newCharacterModel = new CharacterModel()
+{
+    //...Populate the new Character Model...
+};
+
+var json = await "https://graphql-star-wars.azurewebsites.net/api/graphql"
+    .WithGraphQLQuery(@"
+        mutation ($newCharacter: Character) {
+            characterCreateOrUpdate(input: $newCharacter) {
+		        result {
+                    personalIdentifier
+	                name
+		        }
+		        errors {
+			        ... on Error {
+				        errorCode
+				        message
+			        }
+		        }
+	        }
+        }
+    ")
+    .SetGraphQLVariables(new { newCharacter: newCharacterModel })
+    .PostGraphQLQueryAsync()
+    //NOTE: Here CharacterCreateOrUpdate Result will a single Payload result (vs a List as  Query would return)
+    //      for which teh model would have both a Result property & an Errors property to be deserialized based
+    //      on the unique GraphQL Schema Mutation design...
+    .ReceiveGraphQLMutationResult<CharacterCreateOrUpdateResult>();
+```
+
+
 ### Batch Querying...
 GraphQL provides the ability to execute multiple queries in a single request as a batch. When this is done each response is provided in the same order as requested
 in the json response object named the same as the GraphQL Query operation. The api provides the ability to retrieve all results (vs only the first by default) by

Original file line number	Diff line number	Diff line change
`@@ -39,6 +39,10 @@ public IGraphQLQueryResults<TResult> LoadTypedResults<TResult>(string queryOpera`
`39`	`39`	`: null;`
`40`	`40`
`41`	`41`	`var typedResults = querySingleResultJson.ParseJsonToGraphQLResultsInternal<TResult>(jsonSerializerSettings);`
	`42`	`+`
	`43`	`+ if(typedResults is GraphQLQueryResults<TResult> graphqlResults)`
	`44`	`+ graphqlResults.SetErrorsInternal(Errors);`
	`45`	`+`
`42`	`46`	`return typedResults;`
`43`	`47`	`}`
`44`	`48`	`}`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ public interface IGraphQLQueryResults<out TResult> : IReadOnlyList<TResult>`
`6`	`6`	`where TResult: class`
`7`	`7`	`{`
`8`	`8`	`bool HasAnyResults();`
`9`		`- IList<GraphQLError> Errors { get; }`
	`9`	`+ IReadOnlyList<GraphQLError> Errors { get; }`
`10`	`10`	`bool HasAnyErrors();`
`11`	`11`	`}`
`12`	`12`