feat!: Switches SubscriptionResult with Result

Author: NeedleInAJayStack

MIGRATION.md

@@ -20,6 +20,10 @@ This was changed to `ConcurrentFieldExecutionStrategy`, and takes no parameters.
 
 The `EventStream` abstraction used to provide pre-concurrency subscription support has been removed. This means that `graphqlSubscribe(...).stream` will now be an `AsyncThrowingStream<GraphQLResult, Error>` type, instead of an `EventStream` type, and that downcasting to `ConcurrentEventStream` is no longer necessary.
 
+### SubscriptionResult removal
+
+The `SubscriptionResult` type was removed, and `graphqlSubscribe` now returns a true Swift `Result` type.
+
 ### Instrumentation removal
 
 The `Instrumentation` type has been removed, with anticipated support for tracing using [`swift-distributed-tracing`](https://github.com/apple/swift-distributed-tracing). `instrumentation` arguments must be removed from `graphql` and `graphqlSubscribe` calls.

Sources/GraphQL/GraphQL.swift

@@ -42,16 +42,11 @@ public struct GraphQLResult: Equatable, Codable, Sendable, CustomStringConvertib
     }
 }
 
-/// SubscriptionResult wraps the observable and error data returned by the subscribe request.
-public struct SubscriptionResult {
-    public let stream: AsyncThrowingStream<GraphQLResult, Error>?
+/// A collection of GraphQL errors. Enables returning multiple errors from Result types.
+public struct GraphQLErrors: Error, Sendable {
     public let errors: [GraphQLError]
 
-    public init(
-        stream: AsyncThrowingStream<GraphQLResult, Error>? = nil,
-        errors: [GraphQLError] = []
-    ) {
-        self.stream = stream
+    public init(_ errors: [GraphQLError]) {
         self.errors = errors
     }
 }
@@ -228,7 +223,7 @@ public func graphqlSubscribe(
     context: Any = (),
     variableValues: [String: Map] = [:],
     operationName: String? = nil
-) async throws -> SubscriptionResult {
+) async throws -> Result<AsyncThrowingStream<GraphQLResult, Error>, GraphQLErrors> {
     let source = Source(body: request, name: "GraphQL Subscription request")
     let documentAST = try parse(source: source)
     let validationErrors = validate(
@@ -238,7 +233,7 @@ public func graphqlSubscribe(
     )
 
     guard validationErrors.isEmpty else {
-        return SubscriptionResult(errors: validationErrors)
+        return .failure(.init(validationErrors))
     }
 
     return try await subscribe(

Sources/GraphQL/Subscription/Subscribe.swift

@@ -3,22 +3,16 @@ import OrderedCollections
 /**
  * Implements the "Subscribe" algorithm described in the GraphQL specification.
  *
- * Returns a future which resolves to a SubscriptionResult containing either
- * a SubscriptionObservable (if successful), or GraphQLErrors (error).
+ * Returns a `Result` that either succeeds with an `AsyncThrowingStream`, or fails with `GraphQLErrors`.
  *
  * If the client-provided arguments to this function do not result in a
- * compliant subscription, the future will resolve to a
- * SubscriptionResult containing `errors` and no `observable`.
+ * compliant subscription, the `Result` will fails with descriptive errors.
  *
  * If the source stream could not be created due to faulty subscription
- * resolver logic or underlying systems, the future will resolve to a
- * SubscriptionResult containing `errors` and no `observable`.
+ * resolver logic or underlying systems, the `Result` will fail with errors.
  *
- * If the operation succeeded, the future will resolve to a SubscriptionResult,
- * containing an `observable` which yields a stream of GraphQLResults
+ * If the operation succeeded, the `Result` will succeed with an `AsyncThrowingStream` of `GraphQLResult`s
  * representing the response stream.
- *
- * Accepts either an object with named arguments, or individual arguments.
  */
 func subscribe(
     queryStrategy: QueryFieldExecutionStrategy,
@@ -30,7 +24,7 @@ func subscribe(
     context: Any,
     variableValues: [String: Map] = [:],
     operationName: String? = nil
-) async throws -> SubscriptionResult {
+) async throws -> Result<AsyncThrowingStream<GraphQLResult, Error>, GraphQLErrors> {
     let sourceResult = try await createSourceEventStream(
         queryStrategy: queryStrategy,
         mutationStrategy: mutationStrategy,
@@ -43,7 +37,7 @@ func subscribe(
         operationName: operationName
     )
 
-    if let sourceStream = sourceResult.stream {
+    return sourceResult.map { sourceStream in
         // We must create a new AsyncSequence because AsyncSequence.map requires a concrete type
         // (which we cannot know),
         // and we need the result to be a concrete type.
@@ -80,30 +74,24 @@ func subscribe(
                 task.cancel()
             }
         }
-        return SubscriptionResult(stream: subscriptionStream, errors: sourceResult.errors)
-    } else {
-        return SubscriptionResult(errors: sourceResult.errors)
+        return subscriptionStream
     }
 }
 
 /**
  * Implements the "CreateSourceEventStream" algorithm described in the
  * GraphQL specification, resolving the subscription source event stream.
  *
- * Returns a Future which resolves to a SourceEventStreamResult, containing
- * either an Observable (if successful) or GraphQLErrors (error).
+ * Returns a Result that either succeeds with an `AsyncSequence` or fails with `GraphQLErrors`.
  *
  * If the client-provided arguments to this function do not result in a
- * compliant subscription, the future will resolve to a
- * SourceEventStreamResult containing `errors` and no `observable`.
+ * compliant subscription, the `Result` will fail with descriptive errors.
  *
  * If the source stream could not be created due to faulty subscription
- * resolver logic or underlying systems, the future will resolve to a
- * SourceEventStreamResult containing `errors` and no `observable`.
+ * resolver logic or underlying systems, the `Result` will fail with errors.
  *
- * If the operation succeeded, the future will resolve to a SubscriptionResult,
- * containing an `observable` which yields a stream of event objects
- * returned by the subscription resolver.
+ * If the operation succeeded, the `Result` will succeed with an AsyncSequence for the
+ * event stream returned by the resolver.
  *
  * A Source Event Stream represents a sequence of events, each of which triggers
  * a GraphQL execution for that event.
@@ -123,32 +111,37 @@ func createSourceEventStream(
     context: Any,
     variableValues: [String: Map] = [:],
     operationName: String? = nil
-) async throws -> SourceEventStreamResult {
+) async throws -> Result<any AsyncSequence, GraphQLErrors> {
+    // If a valid context cannot be created due to incorrect arguments,
+    // this will throw an error.
+    let exeContext = try buildExecutionContext(
+        queryStrategy: queryStrategy,
+        mutationStrategy: mutationStrategy,
+        subscriptionStrategy: subscriptionStrategy,
+        schema: schema,
+        documentAST: documentAST,
+        rootValue: rootValue,
+        context: context,
+        rawVariableValues: variableValues,
+        operationName: operationName
+    )
     do {
-        // If a valid context cannot be created due to incorrect arguments,
-        // this will throw an error.
-        let exeContext = try buildExecutionContext(
-            queryStrategy: queryStrategy,
-            mutationStrategy: mutationStrategy,
-            subscriptionStrategy: subscriptionStrategy,
-            schema: schema,
-            documentAST: documentAST,
-            rootValue: rootValue,
-            context: context,
-            rawVariableValues: variableValues,
-            operationName: operationName
-        )
         return try await executeSubscription(context: exeContext)
     } catch let error as GraphQLError {
-        return SourceEventStreamResult(errors: [error])
+        // If it is a GraphQLError, report it as a failure.
+        return .failure(.init([error]))
+    } catch let errors as GraphQLErrors {
+        // If it is a GraphQLErrors, report it as a failure.
+        return .failure(errors)
     } catch {
-        return SourceEventStreamResult(errors: [GraphQLError(error)])
+        // Otherwise treat the error as a system-class error and re-throw it.
+        throw error
     }
 }
 
 func executeSubscription(
     context: ExecutionContext
-) async throws -> SourceEventStreamResult {
+) async throws -> Result<any AsyncSequence, GraphQLErrors> {
     // Get the first node
     let type = try getOperationRootType(schema: context.schema, operation: context.operation)
     var inputFields: OrderedDictionary<String, [Field]> = [:]
@@ -238,35 +231,21 @@ func executeSubscription(
         resolved = success
     }
     if !context.errors.isEmpty {
-        return SourceEventStreamResult(errors: context.errors)
+        return .failure(.init(context.errors))
     } else if let error = resolved as? GraphQLError {
-        return SourceEventStreamResult(errors: [error])
+        return .failure(.init([error]))
     } else if let stream = resolved as? any AsyncSequence {
-        return SourceEventStreamResult(stream: stream)
+        return .success(stream)
     } else if resolved == nil {
-        return SourceEventStreamResult(errors: [
+        return .failure(.init([
             GraphQLError(message: "Resolved subscription was nil"),
-        ])
+        ]))
     } else {
         let resolvedObj = resolved as AnyObject
-        return SourceEventStreamResult(errors: [
+        return .failure(.init([
             GraphQLError(
                 message: "Subscription field resolver must return an AsyncSequence. Received: '\(resolvedObj)'"
             ),
-        ])
-    }
-}
-
-// Subscription resolvers MUST return observables that are declared as 'Any' due to Swift not having
-// covariant generic support for type
-// checking. Normal resolvers for subscription fields should handle type casting, same as resolvers
-// for query fields.
-struct SourceEventStreamResult {
-    public let stream: (any AsyncSequence)?
-    public let errors: [GraphQLError]
-
-    public init(stream: (any AsyncSequence)? = nil, errors: [GraphQLError] = []) {
-        self.stream = stream
-        self.errors = errors
+        ]))
     }
 }

Tests/GraphQLTests/SubscriptionTests/SubscriptionSchema.swift

@@ -197,10 +197,5 @@ func createSubscription(
         variableValues: variableValues,
         operationName: nil
     )
-
-    if let stream = result.stream {
-        return stream
-    } else {
-        throw result.errors.first! // We may have more than one...
-    }
+    return try result.get()
 }

Tests/GraphQLTests/SubscriptionTests/SubscriptionTests.swift

@@ -30,10 +30,7 @@ class SubscriptionTests: XCTestCase {
             schema: schema,
             request: query
         )
-        guard let stream = subscriptionResult.stream else {
-            XCTFail(subscriptionResult.errors.description)
-            return
-        }
+        let stream = try subscriptionResult.get()
         var iterator = stream.makeAsyncIterator()
 
         db.trigger(email: Email(
@@ -241,15 +238,19 @@ class SubscriptionTests: XCTestCase {
             """)
             XCTFail("Error should have been thrown")
         } catch {
-            guard let graphQLError = error as? GraphQLError else {
-                XCTFail("Error was not of type GraphQLError")
+            guard let graphQLErrors = error as? GraphQLErrors else {
+                XCTFail("Error was not of type GraphQLErrors")
                 return
             }
             XCTAssertEqual(
-                graphQLError.message,
-                "Cannot query field \"unknownField\" on type \"Subscription\"."
+                graphQLErrors.errors,
+                [
+                    GraphQLError(
+                        message: "Cannot query field \"unknownField\" on type \"Subscription\".",
+                        locations: [SourceLocation(line: 2, column: 5)]
+                    ),
+                ]
             )
-            XCTAssertEqual(graphQLError.locations, [SourceLocation(line: 2, column: 5)])
         }
     }
 
@@ -284,13 +285,15 @@ class SubscriptionTests: XCTestCase {
             """)
             XCTFail("Error should have been thrown")
         } catch {
-            guard let graphQLError = error as? GraphQLError else {
+            guard let graphQLErrors = error as? GraphQLErrors else {
                 XCTFail("Error was not of type GraphQLError")
                 return
             }
             XCTAssertEqual(
-                graphQLError.message,
-                "Subscription field resolver must return an AsyncSequence. Received: 'test'"
+                graphQLErrors.errors,
+                [GraphQLError(
+                    message: "Subscription field resolver must return an AsyncSequence. Received: 'test'"
+                )]
             )
         }
     }
@@ -310,11 +313,11 @@ class SubscriptionTests: XCTestCase {
                 """)
                 XCTFail("Error should have been thrown")
             } catch {
-                guard let graphQLError = error as? GraphQLError else {
+                guard let graphQLErrors = error as? GraphQLErrors else {
                     XCTFail("Error was not of type GraphQLError")
                     return
                 }
-                XCTAssertEqual(graphQLError.message, "test error")
+                XCTAssertEqual(graphQLErrors.errors, [GraphQLError(message: "test error")])
             }
         }