feat: Revise Scalar and remove default impl

The default is very unperformant, as it requires a full encode/decode step.

Author: NeedleInAJayStack

Examples/HelloWorldServer/Sources/HelloWorldServer/Resolvers.swift

@@ -17,7 +17,43 @@ public class Context: @unchecked Sendable {
     }
 }
 // Scalars must be represented by a Swift type of the same name, conforming to the Scalar protocol
-struct DateTime: Scalar {}
+public struct EmailAddress: Scalar {
+    let email: String
+
+    init(email: String) {
+        self.email = email
+    }
+
+    // Codability conformance. Required for usage in InputObject
+    public init(from decoder: any Decoder) throws {
+        self.email = try decoder.singleValueContainer().decode(String.self)
+    }
+    public func encode(to encoder: any Encoder) throws {
+        try self.email.encode(to: encoder)
+    }
+
+    // Scalar conformance. Not necessary, but default methods are very inefficient.
+    public static func serialize(this: Self) throws -> Map {
+        return .string(this.email)
+    }
+    public static func parseValue(map: Map) throws -> Map {
+        switch map {
+        case .string:
+            return map
+        default:
+            throw GraphQLError(message: "EmailAddress cannot represent non-string value: \(map)")
+        }
+    }
+    public static func parseLiteral(value: any Value) throws -> Map {
+        guard let ast = value as? StringValue else {
+            throw GraphQLError(
+                message: "EmailAddress cannot represent non-string value: \(print(ast: value))",
+                nodes: [value]
+            )
+        }
+        return .string(ast.value)
+    }
+}
 
 // Now create types that conform to the expected protocols
 struct Resolvers: ResolversProtocol {
@@ -39,8 +75,8 @@ struct User: UserProtocol {
     func name(context: Context, info: GraphQL.GraphQLResolveInfo) async throws -> String {
         return name
     }
-    func email(context: Context, info: GraphQL.GraphQLResolveInfo) async throws -> String {
-        return email
+    func email(context: Context, info: GraphQL.GraphQLResolveInfo) async throws -> EmailAddress {
+        return EmailAddress(email: email)
     }
     func age(context: Context, info: GraphQL.GraphQLResolveInfo) async throws -> Int? {
         return age
@@ -54,8 +90,8 @@ struct Contact: ContactProtocol {
     let email: String
 
     // Required implementations
-    func email(context: Context, info: GraphQL.GraphQLResolveInfo) async throws -> String {
-        return email
+    func email(context: Context, info: GraphQL.GraphQLResolveInfo) async throws -> EmailAddress {
+        return EmailAddress(email: email)
     }
 }
 struct Post: PostProtocol {
@@ -105,7 +141,7 @@ struct Mutation: MutationProtocol {
         let user = User(
             id: userInfo.id,
             name: userInfo.name,
-            email: userInfo.email,
+            email: userInfo.email.email,
             age: userInfo.age,
             role: userInfo.role
         )

Examples/HelloWorldServer/Sources/HelloWorldServer/schema.graphql

@@ -1,16 +1,18 @@
+scalar EmailAddress
+
 interface HasEmail {
   """
   An email address
   """
-  email: String!
+  email: EmailAddress!
 }
 
 union UserOrPost = User | Post
 
 input UserInfo {
   id: ID!
   name: String!
-  email: String!
+  email: EmailAddress!
   age: Int
   role: Role
 }
@@ -32,7 +34,7 @@ type User implements HasEmail {
   """
   The user's email address
   """
-  email: String!
+  email: EmailAddress!
 
   """
   The user's age
@@ -46,7 +48,7 @@ type User implements HasEmail {
 }
 
 type Contact implements HasEmail {
-  email: String!
+  email: EmailAddress!
 }
 
 """

README.md

@@ -2,7 +2,7 @@
 
 A Swift package plugin that generates server-side GraphQL API code from GraphQL schema files, inspired by [GraphQL Tools' makeExecutableSchema](https://the-guild.dev/graphql/tools/docs/generate-schema).
 
-This tool uses [GraphQL Swift](https://github.com/GraphQLSwift/GraphQL) to generate type-safe Swift code and protocol stubs from your GraphQL schema files, eliminating boilerplate while maintaining full control over your business logic.
+This tool uses [GraphQL Swift](https://github.com/GraphQLSwift/GraphQL) to generate type-safe Swift code and protocol stubs from your GraphQL schema files, eliminating boilerplate while allowing you full control over your business logic.
 
 ## Features
 
@@ -44,14 +44,12 @@ Create a `.graphql` file in your target's `Sources` directory:
 **Sources/YourTarget/schema.graphql**:
 ```graphql
 type User {
-  id: ID!
   name: String!
-  email: String!
+  email: EmailAddress!
 }
 
 type Query {
-  user(id: ID!): User
-  users: [User!]!
+  user: User
 }
 ```
 
@@ -71,11 +69,7 @@ public actor Context {
 }
 ```
 
-Create any scalar types (with names matching GraphQL), and conform them to `Scalar`:
-
-```swift
-struct DateTime: Scalar {}
-```
+Create any scalar types (with names matching GraphQL), and conform them to `Scalar`. See the `Scalars` usage section below for details.
 
 Create a resolvers struct with the required typealiases:
 ```swift
@@ -85,8 +79,7 @@ struct Resolvers: ResolversProtocol {
 }
 ```
 
-As you build the `Query` and `Mutation` types and their resolution logic, you will be forced to define a concrete type for every reachable GraphQL result, according to its generated protocol.
-Here's a small example of a schema that allows querying for the current user, who is only identified by an email address:
+As you build the `Query` and `Mutation` types and their resolution logic, you will be forced to define a concrete type for every reachable GraphQL result, according to its generated protocol:
 
 ```swift
 struct Query: QueryProtocol {
@@ -99,12 +92,16 @@ struct Query: QueryProtocol {
 
 struct User: UserProtocol {
     // You can define the type internals however you like
+    let name: String
     let email: String
 
-    // This is required by `UserProtocol`, and used by GraphQL field resolution.
-    func email(context: Context, info: GraphQL.GraphQLResolveInfo) async throws -> String {
+    // These are required by `UserProtocol`, and used by GraphQL field resolution.
+    func name(context: Context, info: GraphQLResolveInfo) async throws -> String {
+        return name
+    }
+    func email(context: Context, info: GraphQLResolveInfo) async throws -> EmailAddress {
         // You can implement resolution logic however you like.
-        return email
+        return EmailAddress(email: self.email)
     }
 }
 ```
@@ -121,6 +118,54 @@ let result = try await graphql(schema: schema, request: "{ users { name email }
 print(result)
 ```
 
+## Detailed Usage
+
+### Scalars
+
+Scalar types must be provided for each GraphQL scalar. Since GraphQL uses a different serialization system than Swift, you must conform the type to Swift's `Codable` and GraphQL's `Scalar`, and have them agree on a representation.
+
+Below is an example that represents a scalar struct as a raw String:
+
+```swift
+public struct EmailAddress: Scalar {
+    let email: String
+
+    init(email: String) {
+        self.email = email
+    }
+
+    // Codability conformance. Represent simply as `email` string.
+    public init(from decoder: any Decoder) throws {
+        self.email = try decoder.singleValueContainer().decode(String.self)
+    }
+    public func encode(to encoder: any Encoder) throws {
+        try self.email.encode(to: encoder)
+    }
+
+    // Scalar conformance. Parse & serialize simply as `email` string.
+    public static func serialize(this: Self) throws -> Map {
+        return .string(this.email)
+    }
+    public static func parseValue(map: Map) throws -> Map {
+        switch map {
+        case .string:
+            return map
+        default:
+            throw GraphQLError(message: "EmailAddress cannot represent non-string value: \(map)")
+        }
+    }
+    public static func parseLiteral(value: any Value) throws -> Map {
+        guard let ast = value as? StringValue else {
+            throw GraphQLError(
+                message: "EmailAddress cannot represent non-string value: \(print(ast: value))",
+                nodes: [value]
+            )
+        }
+        return .string(ast.value)
+    }
+}
+```
+
 ## Development Roadmap
 
 1. Default values: Default values are currently ignored

Sources/GraphQLGeneratorRuntime/Scalar.swift

@@ -1,77 +1,25 @@
 import GraphQL
 import OrderedCollections
 
-public protocol Scalar: Sendable {
-    static func serialize(any: Any) throws -> Map
+public protocol Scalar: Sendable, Codable {
+    static func serialize(this: Self) throws -> Map
     static func parseValue(map: Map) throws -> Map
     static func parseLiteral(value: any Value) throws -> Map
 }
 
+// Graphiti provides default serializations that the underlying type's Codability requirements, but they are very
+// inefficient. They typically pass through a full serialize/deserialize step on each call.
+// Because of this, we have chosen not to vend defaults to force the user to implement more performant versions.
+
 public extension Scalar {
+    /// This wraps the GraphQLScalar definition in a type-safe one
     static func serialize(any: Any) throws -> Map {
-        return try Map(any: any)
-    }
-    static func parseValue(map: Map) throws -> Map {
-        return map
-    }
-    static func parseLiteral(value: any Value) throws -> Map {
-        return value.map
-    }
-}
-
-
-extension GraphQL.Value {
-    var map: Map {
-        if
-            let value = self as? BooleanValue
-        {
-            return .bool(value.value)
-        }
-
-        if
-            let value = self as? IntValue,
-            let int = Int(value.value)
-        {
-            return .int(int)
-        }
-
-        if
-            let value = self as? FloatValue,
-            let double = Double(value.value)
-        {
-            return .double(double)
+        // We should always get a value of `Self` for custom scalars.
+        guard let scalar = any as? Self else {
+            throw GraphQLError(
+                message: "Serialize expected type \(Self.self) but got \(type(of: any))"
+            )
         }
-
-        if
-            let value = self as? StringValue
-        {
-            return .string(value.value)
-        }
-
-        if
-            let value = self as? EnumValue
-        {
-            return .string(value.value)
-        }
-
-        if
-            let value = self as? ListValue
-        {
-            let array = value.values.map { $0.map }
-            return .array(array)
-        }
-
-        if
-            let value = self as? ObjectValue
-        {
-            let dictionary: OrderedDictionary<String, Map> = value.fields
-                .reduce(into: [:]) { result, field in
-                    result[field.name.value] = field.value.map
-                }
-
-            return .dictionary(dictionary)
-        }
-
-        return .null
+        return try Self.serialize(this: scalar)
     }
 }