Document SRTP wrapper dispatch and finalize type safety changes

Agent-Logs-Url: https://github.com/fsprojects/FSharp.Data.GraphQL/sessions/7e806543-4139-4145-940a-64322cdd35cd

Co-authored-by: xperiandri <2365592+xperiandri@users.noreply.github.com>

Author: Copilot

src/FSharp.Data.GraphQL.Shared/SchemaDefinitions.fs

@@ -392,7 +392,7 @@ module SchemaDefinitions =
             | false, _ -> getParseError destinationType s
         | InlineConstant value -> value.GetCoerceError destinationType
 
-    type TypeWrapperDispatch =
+    type TypeWrapperStaticDispatch =
         static member Nullable<'Val>(innerDef : InputOutputDef<'Val>) : NullableDef<'Val> =
             let ofType : TypeDef<'Val> = upcast innerDef
             upcast { NullableDefinition.OfType = ofType }
@@ -431,24 +431,33 @@ module SchemaDefinitions =
 
     /// Wraps a GraphQL input or output type definition, allowing defining field/argument
     /// to take option of provided value while preserving input/output kind of wrapped type.
-    let inline Nullable< ^Def, ^Wrapped when (^Def or TypeWrapperDispatch) : (static member Nullable : ^Def -> ^Wrapped) >
+    /// Input wrappers produce input definitions, output wrappers produce output definitions,
+    /// and wrappers over types implementing both kinds keep both capabilities.
+    /// Dispatch is selected at compile time via SRTP.
+    let inline Nullable< ^Def, ^Wrapped when (^Def or TypeWrapperStaticDispatch) : (static member Nullable : ^Def -> ^Wrapped) >
         (innerDef : ^Def)
         : ^Wrapped =
-        ((^Def or TypeWrapperDispatch) : (static member Nullable : ^Def -> ^Wrapped) innerDef)
+        ((^Def or TypeWrapperStaticDispatch) : (static member Nullable : ^Def -> ^Wrapped) innerDef)
 
     /// Wraps a GraphQL input or output type definition, allowing defining field/argument
     /// to take voption of provided value while preserving input/output kind of wrapped type.
-    let inline StructNullable< ^Def, ^Wrapped when (^Def or TypeWrapperDispatch) : (static member StructNullable : ^Def -> ^Wrapped) >
+    /// Input wrappers produce input definitions, output wrappers produce output definitions,
+    /// and wrappers over types implementing both kinds keep both capabilities.
+    /// Dispatch is selected at compile time via SRTP.
+    let inline StructNullable< ^Def, ^Wrapped when (^Def or TypeWrapperStaticDispatch) : (static member StructNullable : ^Def -> ^Wrapped) >
         (innerDef : ^Def)
         : ^Wrapped =
-        ((^Def or TypeWrapperDispatch) : (static member StructNullable : ^Def -> ^Wrapped) innerDef)
+        ((^Def or TypeWrapperStaticDispatch) : (static member StructNullable : ^Def -> ^Wrapped) innerDef)
 
     /// Wraps a GraphQL input or output type definition, allowing defining field/argument
     /// to take collection of provided value while preserving input/output kind of wrapped type.
-    let inline ListOf< ^Def, ^Wrapped when (^Def or TypeWrapperDispatch) : (static member ListOf : ^Def -> ^Wrapped) >
+    /// Input wrappers produce input definitions, output wrappers produce output definitions,
+    /// and wrappers over types implementing both kinds keep both capabilities.
+    /// Dispatch is selected at compile time via SRTP.
+    let inline ListOf< ^Def, ^Wrapped when (^Def or TypeWrapperStaticDispatch) : (static member ListOf : ^Def -> ^Wrapped) >
         (innerDef : ^Def)
         : ^Wrapped =
-        ((^Def or TypeWrapperDispatch) : (static member ListOf : ^Def -> ^Wrapped) innerDef)
+        ((^Def or TypeWrapperStaticDispatch) : (static member ListOf : ^Def -> ^Wrapped) innerDef)
 
     let internal variableOrElse other (_ : InputExecutionContextProvider) value (variables : IReadOnlyDictionary<string, obj>)  =
         match value with

src/FSharp.Data.GraphQL.Shared/SchemaDefinitionsExtensions.fs

@@ -27,6 +27,8 @@ type internal CustomFieldsObjectDefinition<'Val> (source : ObjectDef<'Val>, fiel
         member _.Implements = source.Implements
         member _.IsTypeOf = source.IsTypeOf
     interface TypeDef with
+        // We construct wrappers directly here because this API works with untyped TypeDef values.
+        // The public ListOf/Nullable helpers use SRTP dispatch and require statically known direction.
         member this.MakeList () = upcast { ListOfDefinition.OfType = this }
         member this.MakeNullable () = upcast { NullableDefinition.OfType = this }
         member _.Type = (source :> TypeDef).Type

src/FSharp.Data.GraphQL.Shared/TypeSystem.fs

@@ -609,17 +609,20 @@ and OutputDef<'Val> =
         inherit TypeDef<'Val>
     end
 
-/// Representation of all type definitions, that can be used as both inputs and outputs.
+/// Representation of type definitions that can be used as both inputs and outputs
+/// (for example scalars and enums). This marker is also used by SRTP wrapper dispatch.
 and InputOutputDef =
     interface
         inherit InputDef
         inherit OutputDef
     end
 
-/// Representation of all type definitions, that can be used as both inputs and outputs.
+/// Representation of all type definitions, that can be used as both inputs and outputs
+/// and are constrained to represent the provided .NET type.
 and InputOutputDef<'Val> =
     interface
         inherit InputOutputDef
+        inherit TypeDef<'Val>
         inherit InputDef<'Val>
         inherit OutputDef<'Val>
     end

tests/FSharp.Data.GraphQL.Tests/TypeWrappersKindSafetyTests.fs

@@ -20,18 +20,21 @@ let private OutputOnlyType =
 
 [<Fact>]
 let ``ListOf keeps input-output direction`` () =
-    let _ : InputDef<InputOnly list> = ListOf InputOnlyType
-    let _ : OutputDef<OutputOnly list> = ListOf OutputOnlyType
-    Assert.True true
+    let inputList : InputDef<InputOnly list> = ListOf InputOnlyType
+    let outputList : OutputDef<OutputOnly list> = ListOf OutputOnlyType
+    Assert.Equal ("[InputOnlyType!]!", inputList.ToString ())
+    Assert.Equal ("[OutputOnlyType!]!", outputList.ToString ())
 
 [<Fact>]
 let ``Nullable keeps input-output direction`` () =
-    let _ : InputDef<InputOnly option> = Nullable InputOnlyType
-    let _ : OutputDef<OutputOnly option> = Nullable OutputOnlyType
-    Assert.True true
+    let nullableInput : InputDef<InputOnly option> = Nullable InputOnlyType
+    let nullableOutput : OutputDef<OutputOnly option> = Nullable OutputOnlyType
+    Assert.Equal ("InputOnlyType", nullableInput.ToString ())
+    Assert.Equal ("OutputOnlyType", nullableOutput.ToString ())
 
 [<Fact>]
 let ``StructNullable keeps input-output direction`` () =
-    let _ : InputDef<InputOnly voption> = StructNullable InputOnlyType
-    let _ : OutputDef<OutputOnly voption> = StructNullable OutputOnlyType
-    Assert.True true
+    let nullableInput : InputDef<InputOnly voption> = StructNullable InputOnlyType
+    let nullableOutput : OutputDef<OutputOnly voption> = StructNullable OutputOnlyType
+    Assert.Equal ("InputOnlyType", nullableInput.ToString ())
+    Assert.Equal ("OutputOnlyType", nullableOutput.ToString ())