Add @cppType directive for custom scalar C++ types (fixes #346)

Co-authored-by: wravery <6502881+wravery@users.noreply.github.com>

Author: Copilot

README.md

@@ -232,6 +232,7 @@ There are some more targeted documents in the [doc](./doc) directory:
 * [Field Resolvers](./doc/resolvers.md)
 * [Field Parameters](./doc/fieldparams.md)
 * [Directives](./doc/directives.md)
+* [Custom Scalars](./doc/scalars.md)
 * [Subscriptions](./doc/subscriptions.md)
 
 ### Samples

doc/directives.md

@@ -18,4 +18,11 @@ The `schema` can also define custom `directives` which are valid on different
 elements of the `query`. The library does not handle them automatically, but it
 will pass them to the `getField` implementations through the optional
 `graphql::service::FieldParams` struct (see [fieldparams.md](fieldparams.md)
-for more information).
+for more information).
+
+There is also one code-generation directive which `schemagen` consumes at build
+time and does not serve through introspection:
+
+* `@cppType(name: String! header: String)`: Map a custom `scalar` type onto a
+custom C++ type instead of the default `response::Value`. See
+[Custom Scalars](./scalars.md) for details.

doc/scalars.md

@@ -0,0 +1,122 @@
+# Custom Scalars
+
+GraphQL lets a schema declare [custom scalar](https://spec.graphql.org/October2021/#sec-Scalars.Custom-Scalars)
+types, e.g.:
+
+```graphql
+scalar DateTime
+scalar BigInt
+```
+
+The wire representation of a scalar is always a `graphql::response::Value` (the JSON-like
+discriminated union described in [Query Responses](./responses.md)). By default `schemagen`
+generates the resolvers and argument accessors for every custom scalar in terms of
+`response::Value`, so you receive and return the value as generic JSON-like data:
+
+```cpp
+service::AwaitableScalar<response::Value> getWhen(service::FieldParams&& params) const override;
+```
+
+That is convenient, but it forces your implementation to store and manipulate the value as a
+`response::Value` even when a dedicated C++ type would be much more natural or efficient (for
+example a `std::chrono::system_clock::time_point` for `DateTime`, or a 64-bit integer for a
+`BigInt` that does not fit in the 32-bit `response::IntType`).
+
+## The `@cppType` directive
+
+You can map a custom scalar onto any C++ type using the `@cppType` directive on the `scalar`
+declaration:
+
+```graphql
+scalar BigInt @cppType(
+	name: "bigint::BigInt"
+	header: "BigIntScalar.h"
+)
+```
+
+* `name` (required) is the fully-qualified C++ type that `schemagen` uses everywhere the scalar
+  appears in the generated code, instead of `response::Value`. It may be qualified with any
+  namespace (`bigint::BigInt`, `my::project::BigInt`, ...).
+* `header` (optional) is added as an `#include` at the top of the generated schema header so the
+  custom type and its conversion specializations are visible to the generated code.
+
+With the directive above, the generated resolver interface changes to use your type directly:
+
+```cpp
+service::AwaitableScalar<bigint::BigInt> getEcho(
+	service::FieldParams&& params, bigint::BigInt&& valueArg) const override;
+```
+
+The scalar is still declared to clients exactly as `scalar BigInt` in introspection; `@cppType`
+is a code-generation hint only and never appears in the served schema.
+
+## Providing the conversions
+
+Because `schemagen` no longer knows how to translate the scalar to and from the `response::Value`
+wire representation, you provide that translation by specializing three members of the
+`graphql::service` templates. These are the type-erased boundary between your C++ type and the
+JSON-like data on the wire:
+
+```cpp
+namespace graphql::service {
+
+// Deserialize an argument or input value into your custom type.
+template <>
+bigint::BigInt Argument<bigint::BigInt>::convert(const response::Value& value);
+
+// Serialize a resolver result of your custom type back into a response::Value.
+template <>
+AwaitableResolver Result<bigint::BigInt>::convert(
+	AwaitableScalar<bigint::BigInt> result, ResolverParams&& params);
+
+// Validate a cached response::Value (returned directly by a resolver) for this scalar.
+template <>
+void Result<bigint::BigInt>::validateScalar(const response::Value& value);
+
+} // namespace graphql::service
+```
+
+`Result<T>::convert` is usually implemented with the `ModifiedResult<T>::resolve` helper, passing a
+callback that turns a `T&&` into a `response::Value`:
+
+```cpp
+template <>
+AwaitableResolver Result<bigint::BigInt>::convert(
+	AwaitableScalar<bigint::BigInt> result, ResolverParams&& params)
+{
+	return ModifiedResult<bigint::BigInt>::resolve(std::move(result),
+		std::move(params),
+		[](bigint::BigInt&& value, const ResolverParams&) {
+			return response::Value { std::to_string(value.value) };
+		});
+}
+```
+
+Declare these specializations in the header named by `@cppType`'s `header` argument so they are
+visible to the generated code, and define them in a matching `.cpp` which is compiled and linked
+into the schema library.
+
+## Nullable scalar arguments
+
+Nullable arguments of built-in scalar types are passed as `std::optional<T>`. So that your custom
+scalar behaves the same way (instead of being treated like a generated `INPUT_OBJECT` type, which
+would be wrapped in `std::unique_ptr<T>`), specialize the `CustomScalarArgument` trait and inherit
+from `std::true_type`:
+
+```cpp
+namespace graphql::service {
+
+template <>
+struct CustomScalarArgument<bigint::BigInt> : std::true_type
+{
+};
+
+} // namespace graphql::service
+```
+
+## Complete example
+
+See [`samples/scalar`](../samples/scalar) for a complete, buildable example of a `BigInt` custom
+scalar whose C++ storage is a `std::int64_t` (serialized on the wire as a JSON `String` so it keeps
+full precision), along with the [`test/ScalarTests.cpp`](../test/ScalarTests.cpp) unit tests which
+exercise serializing, deserializing, nullable arguments, and error handling through live queries.

include/SchemaLoader.h

@@ -43,11 +43,24 @@ using TypeNameMap = std::unordered_map<std::string_view, size_t>;
 // Scalar types are opaque to the generator, it's up to the service implementation
 // to handle parsing, validating, and serializing them. We just need to track which
 // scalar type names have been declared so we recognize the references.
+//
+// By default a scalar is represented in the generated C++ code with response::Value, but
+// the schema author can override that with the @cppType directive to store, serialize, and
+// deserialize the scalar as any custom C++ type (e.g. a BigInt):
+//
+//   scalar BigInt @cppType(name: "bigint::BigInt" header: "BigIntScalar.h")
+//
+// The `name` argument is the fully-qualified C++ type used everywhere the scalar appears in
+// the generated resolvers and argument accessors. The optional `header` argument is added as
+// an #include in the generated schema header so that the custom type (and its
+// service::Argument/service::Result specializations) are visible to the generated code.
 struct [[nodiscard("unnecessary construction")]] ScalarType
 {
 	std::string_view type;
 	std::string_view description;
 	std::string_view specifiedByURL {};
+	std::string_view cppType {};
+	std::string_view cppHeader {};
 };
 
 using ScalarTypeList = std::vector<ScalarType>;

include/graphqlservice/GraphQLService.h

@@ -629,6 +629,17 @@ struct Argument
 	[[nodiscard("unnecessary conversion")]] static Type convert(const response::Value& value);
 };
 
+// Custom scalar C++ types (e.g. those declared with the @cppType schema directive) are usually
+// represented with a class or struct rather than one of the built-in types. Specialize this trait
+// and inherit from std::true_type so that the custom type is treated as a scalar argument instead
+// of a generated INPUT_OBJECT type. That controls whether a nullable argument is wrapped in a
+// std::optional (scalar) or a std::unique_ptr (input object), matching the type which schemagen
+// declares for the resolver accessor.
+template <typename Type>
+struct CustomScalarArgument : std::false_type
+{
+};
+
 #ifdef GRAPHQL_DLLEXPORTS
 // Export all of the built-in converters
 template <>
@@ -652,7 +663,8 @@ namespace {
 // These types are used as scalar arguments even though they are represented with a class.
 template <typename Type>
 concept ScalarArgumentClass = std::is_same_v<Type, std::string>
-	|| std::is_same_v<Type, response::IdType> || std::is_same_v<Type, response::Value>;
+	|| std::is_same_v<Type, response::IdType> || std::is_same_v<Type, response::Value>
+	|| CustomScalarArgument<Type>::value;
 
 // Any non-scalar class used in an argument is a generated INPUT_OBJECT type.
 template <typename Type>

samples/CMakeLists.txt

@@ -5,6 +5,7 @@ cmake_minimum_required(VERSION 3.15)
 
 add_subdirectory(client)
 add_subdirectory(learn)
+add_subdirectory(scalar)
 add_subdirectory(today)
 add_subdirectory(validation)
 

samples/scalar/BigIntScalar.cpp

@@ -0,0 +1,75 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+#include "BigIntScalar.h"
+
+#include <charconv>
+#include <string>
+#include <string_view>
+
+using namespace std::literals;
+
+namespace {
+
+using namespace graphql;
+
+// Parse a std::int64_t out of the JSON-like response::Value wire representation. BigInt values are
+// serialized as Strings so they survive without the precision loss of a 32-bit response::IntType,
+// but we also accept a plain Int for convenience when the value is small enough.
+[[nodiscard]] std::int64_t parseBigInt(const response::Value& value)
+{
+	switch (value.type())
+	{
+		case response::Type::Int:
+			return static_cast<std::int64_t>(value.get<response::IntType>());
+
+		case response::Type::String:
+		{
+			const auto& str = value.get<response::StringType>();
+			std::int64_t result = 0;
+			const auto* first = str.data();
+			const auto* last = first + str.size();
+			const auto [ptr, ec] = std::from_chars(first, last, result);
+
+			if (ec != std::errc {} || ptr != last)
+			{
+				throw service::schema_exception { { "not a valid BigInt value"s } };
+			}
+
+			return result;
+		}
+
+		default:
+			throw service::schema_exception { { "not a valid BigInt value"s } };
+	}
+}
+
+} // namespace
+
+namespace graphql::service {
+
+template <>
+bigint::BigInt Argument<bigint::BigInt>::convert(const response::Value& value)
+{
+	return bigint::BigInt { parseBigInt(value) };
+}
+
+template <>
+AwaitableResolver Result<bigint::BigInt>::convert(
+	AwaitableScalar<bigint::BigInt> result, ResolverParams&& params)
+{
+	return ModifiedResult<bigint::BigInt>::resolve(std::move(result),
+		std::move(params),
+		[](bigint::BigInt&& value, const ResolverParams&) {
+			return response::Value { std::to_string(value.value) };
+		});
+}
+
+template <>
+void Result<bigint::BigInt>::validateScalar(const response::Value& value)
+{
+	// Reuse the argument parser to confirm the cached wire representation is well formed.
+	static_cast<void>(parseBigInt(value));
+}
+
+} // namespace graphql::service

samples/scalar/BigIntScalar.h

@@ -0,0 +1,69 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+#pragma once
+
+#ifndef BIGINTSCALAR_H
+#define BIGINTSCALAR_H
+
+#include "graphqlservice/GraphQLService.h"
+
+#include <cstdint>
+
+// This is the custom C++ type backing the GraphQL `BigInt` scalar. It is associated with the
+// scalar in schema.scalar.graphql using the `@cppType` directive:
+//
+//   scalar BigInt @cppType(name: "bigint::BigInt" header: "BigIntScalar.h")
+//
+// A BigInt can hold values which do not fit in the 32-bit response::IntType, so instead of forcing
+// the field accessors to work with response::Value, schemagen generates the resolvers and argument
+// accessors in terms of bigint::BigInt. The service::Argument and service::Result specializations
+// below are the type-erased bridge that (de)serializes the value to and from the JSON-like
+// response::Value wire representation (here, a String so the full 64-bit precision survives).
+namespace bigint {
+
+struct [[nodiscard("unnecessary construction")]] BigInt
+{
+	BigInt() noexcept = default;
+
+	explicit BigInt(std::int64_t value) noexcept
+		: value { value }
+	{
+	}
+
+	[[nodiscard]] bool operator==(const BigInt& rhs) const noexcept
+	{
+		return value == rhs.value;
+	}
+
+	std::int64_t value = 0;
+};
+
+} // namespace bigint
+
+namespace graphql::service {
+
+// Parse a BigInt argument from the request (a JSON String, or an Int for small values).
+template <>
+[[nodiscard("unnecessary conversion")]] bigint::BigInt Argument<bigint::BigInt>::convert(
+	const response::Value& value);
+
+// Treat bigint::BigInt as a scalar argument (wrapped in std::optional when nullable) rather than a
+// generated INPUT_OBJECT type (which would be wrapped in std::unique_ptr).
+template <>
+struct CustomScalarArgument<bigint::BigInt> : std::true_type
+{
+};
+
+// Serialize a BigInt result back into a response::Value (a JSON String).
+template <>
+[[nodiscard("unnecessary conversion")]] AwaitableResolver Result<bigint::BigInt>::convert(
+	AwaitableScalar<bigint::BigInt> result, ResolverParams&& params);
+
+// Validate that a cached response::Value for this scalar is the expected wire representation.
+template <>
+void Result<bigint::BigInt>::validateScalar(const response::Value& value);
+
+} // namespace graphql::service
+
+#endif // BIGINTSCALAR_H

samples/scalar/CMakeLists.txt

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+cmake_minimum_required(VERSION 3.15)
+
+# scalargraphql demonstrates a custom scalar (BigInt) whose C++ storage is a dedicated type
+# (bigint::BigInt) instead of response::Value. See schema.scalar.graphql and BigIntScalar.h. The
+# custom scalar (de)serialization in BigIntScalar.cpp is compiled into the scalar_schema library
+# (see schema/CMakeLists.txt), so this is just a friendly alias target for the sample.
+add_subdirectory(schema)
+
+add_library(scalargraphql INTERFACE)
+target_link_libraries(scalargraphql INTERFACE scalar_schema)
+target_include_directories(scalargraphql INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})

samples/scalar/schema.scalar.graphql

@@ -0,0 +1,24 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+# This sample demonstrates a custom scalar whose C++ storage is NOT response::Value.
+#
+# The @cppType directive tells schemagen to use the bigint::BigInt C++ type (declared in
+# BigIntScalar.h) for this scalar everywhere it appears in the generated resolvers and argument
+# accessors, instead of the default response::Value. See samples/scalar/BigIntScalar.h for the
+# service::Argument/service::Result specializations which serialize and deserialize the value.
+#
+# BigInt values are too large to fit in the 32-bit response::IntType, so on the wire they are
+# represented as a JSON String, while the C++ side stores a std::int64_t.
+scalar BigInt @cppType(name: "bigint::BigInt" header: "BigIntScalar.h")
+
+type Query {
+	"Echo a BigInt argument straight back out, round-tripping through bigint::BigInt."
+	echo(value: BigInt!): BigInt!
+
+	"Add two BigInt values together on the C++ side and return the result."
+	add(left: BigInt! right: BigInt!): BigInt!
+
+	"Return an optional BigInt, or null when no value is provided."
+	maybe(value: BigInt): BigInt
+}