Add support for binding with a custom marshal/unmarshal function

This is useful if you want to bind to a type you don't control (or use
for other things) but need different serialization than its default.
This is a feature gqlgen has and we've found it very useful.  For
example, in webapp we want to bind `DateTime` to `time.Time`, but its
default serialization is not compatible with Python, so currently we
have to bind to a wrapper type and cast all over the place, which is
exactly the sort of boilerplate genqlient is supposed to avoid.

For unmarshaling, the implementation basically just follows the existing
support for abstract types; instead of calling our own generated
helper, we now call your specified function.  This required some
refactoring to abstract the handling of custom unmarshalers generally
from abstract types specifically, and to wire in not only the
unmarshaler-name but also the `generator` (in order to compute the right
import alias).

For marshaling, I had to implement all that stuff over again; it's
mostly parallel to unmarshaling (and I made a few minor changes to
unmarshaling to make the two more parallel).  Luckily, after #103 I at
least only had to do it once, rather than implementing the same
functionality for arguments and for input-type fields.  It was still
quite a bit of code; I didn't try to be quite as completionist about the
tests as with unmarshal but still had to add a few.

Issue: #38

Test plan:
make check

Reviewers: marksandstrom, steve, adam, jvoll, miguel, mahtab

docs/CHANGELOG.md

@@ -23,10 +23,12 @@ When releasing a new version:
 ### Breaking changes:
 
 - The [`graphql.Client`](https://pkg.go.dev/github.com/Khan/genqlient/graphql#Client) interface now accepts `variables interface{}` (containing a JSON-marshalable value) rather than `variables map[string]interface{}`.  Clients implementing the interface themselves will need to change the signature; clients who simply call `graphql.NewClient` are unaffected.
-- genqlient's handling of the `omitempty` option has changed to match that of `encoding/json`, from which it had inadvertently differed.  In particular, this means struct-typed arguments with `# @genqlient(omitempty: true)` will no longer be omitted if they are the zero value.  (Struct-pointers are still omitted if nil, so adding `pointer: true` will typically work fine.)
+- genqlient's handling of the `omitempty` option has changed to match that of `encoding/json`, from which it had inadvertently differed.  In particular, this means struct-typed arguments with `# @genqlient(omitempty: true)` will no longer be omitted if they are the zero value.  (Struct-pointers are still omitted if nil, so adding `pointer: true` will typically work fine.  It's also now possible to use a custom marshaler to explicitly map zero to null.)
 
 ### New features:
 
+- The new `bindings.marshaler` and `bindings.unmarshaler` options in `genqlient.yaml` allow binding to a type without using its standard JSON serialization; see the [documentation](docs/genqlient.yaml) for details.
+
 ### Bug fixes:
 
 - The `omitempty` option now works correctly for struct- and map-typed variables, matching `encoding/json`, which is to say it never omits structs, and omits empty maps.

docs/genqlient.yaml

@@ -104,6 +104,42 @@ bindings:
     # - a nonstandard way of spelling those, (interface {/* hi */},
     #   map[  string      ]T)
     type: time.Time
+    # Optionally, the fully-qualified name of the function to use when
+    # marshaling this type.
+    #
+    # This is useful when you want to bind to a standard type, but use
+    # nonstandard marshaling, for example when making requests to a server
+    # that's not compatible with Go's default time format. It is only used for
+    # types passed as arguments, i.e. input types, scalars, and enums.
+    #
+    # The function should have a signature similar to json.Marshal, i.e., it
+    # will be passed one argument which will be a pointer to a value of the
+    # given type, and must return two values: the JSON as a `[]byte`, and an
+    # error. For example, you might specify
+    #  unmarshaler: github.com/you/yourpkg.MarshalMyType
+    # and that function is defined as e.g.:
+    #  func MarshalMyType(v *MyType) ([]byte, error)
+    #
+    # Note that the `omitempty` option is ignored for types with custom
+    # marshalers; the custom marshaler can of course choose to map any value it
+    # wishes to `"null"` which in GraphQL has the same effect.
+    # 
+    # The default is to use ordinary JSON-marshaling.
+    marshaler: github.com/you/yourpkg.MarshalDateTime
+    # Optionally, the fully-qualified name of the function to use when
+    # unmarshaling this type.
+    #
+    # This is similar to marshaler, above, but for unmarshaling.  The specified
+    # function should have a signature similar to json.Unmarshal, i.e., it will
+    # be passed two arguments, a []byte of JSON to unmarshal and a pointer to a
+    # value of the given type, and must return an error.  For example, you
+    # might specify
+    #  unmarshaler: github.com/you/yourpkg.UnmarshalMyType
+    # and that function is defined as e.g.:
+    #  func UnmarshalMyType(b []byte, v *MyType) error
+    # 
+    # The default is to use ordinary JSON-unmarshaling.
+    unmarshaler: github.com/you/yourpkg.UnmarshalDateTime
 
   # To bind an object type:
   MyType:
@@ -124,3 +160,4 @@ bindings:
     # or something, if you want to say, for example, that you have to request
     # certain fields but others are optional.
     expect_exact_fields: "{ id name }"
+    # unmarshaler and marshaler are also valid here, see above for details.

docs/genqlient_directive.graphql

@@ -44,7 +44,8 @@ directive genqlient(
   # which will pass {"arg": null} to GraphQL if arg is "", and the actual
   # value otherwise.
   #
-  # Only applicable to arguments of nullable types.
+  # Only applicable to arguments of nullable types.  Ignored for types with
+  # custom marshalers (see their documentation in genqlient.yaml for details).
   omitempty: Boolean
 
   # If set, this argument or field will use a pointer type in Go.  Response

generate/config.go

@@ -44,6 +44,8 @@ type Config struct {
 type TypeBinding struct {
 	Type              string `yaml:"type"`
 	ExpectExactFields string `yaml:"expect_exact_fields"`
+	Marshaler         string `yaml:"marshaler"`
+	Unmarshaler       string `yaml:"unmarshaler"`
 }
 
 // ValidateAndFillDefaults ensures that the configuration is valid, and fills

generate/convert.go

@@ -125,6 +125,7 @@ func (g *generator) convertOperation(
 		},
 		Fields:    fields,
 		Selection: operation.SelectionSet,
+		Generator: g,
 	}
 
 	return g.addType(goType, goType.GoName, operation.Position)
@@ -186,6 +187,7 @@ func (g *generator) convertArguments(
 			// fake name, used by addType
 			GraphQLName: name,
 		},
+		Generator: g,
 	}
 	goTypAgain, err := g.addType(goTyp, goTyp.GoName, operation.Position)
 	if err != nil {
@@ -215,7 +217,9 @@ func (g *generator) convertType(
 	localBinding := options.Bind
 	if localBinding != "" && localBinding != "-" {
 		goRef, err := g.ref(localBinding)
-		return &goOpaqueType{goRef, typ.Name()}, err
+		// TODO(benkraft): Add syntax to specify a custom (un)marshaler, if
+		// it proves useful.
+		return &goOpaqueType{GoRef: goRef, GraphQLName: typ.Name()}, err
 	}
 
 	if typ.Elem != nil {
@@ -267,11 +271,16 @@ func (g *generator) convertDefinition(
 			}
 		}
 		goRef, err := g.ref(globalBinding.Type)
-		return &goOpaqueType{goRef, def.Name}, err
+		return &goOpaqueType{
+			GoRef:       goRef,
+			GraphQLName: def.Name,
+			Marshaler:   globalBinding.Marshaler,
+			Unmarshaler: globalBinding.Unmarshaler,
+		}, err
 	}
 	goBuiltinName, ok := builtinTypes[def.Name]
 	if ok {
-		return &goOpaqueType{goBuiltinName, def.Name}, nil
+		return &goOpaqueType{GoRef: goBuiltinName, GraphQLName: def.Name}, nil
 	}
 
 	// Determine the name to use for this type.
@@ -335,6 +344,7 @@ func (g *generator) convertDefinition(
 			Fields:          fields,
 			Selection:       selectionSet,
 			descriptionInfo: desc,
+			Generator:       g,
 		}
 		return g.addType(goType, goType.GoName, pos)
 
@@ -344,6 +354,7 @@ func (g *generator) convertDefinition(
 			Fields:          make([]*goStructField, len(def.Fields)),
 			descriptionInfo: desc,
 			IsInput:         true,
+			Generator:       g,
 		}
 		// To handle recursive types, we need to add the type to the type-map
 		// *before* converting its fields.
@@ -693,6 +704,7 @@ func (g *generator) convertNamedFragment(fragment *ast.FragmentDefinition) (goTy
 			Fields:          fields,
 			Selection:       fragment.SelectionSet,
 			descriptionInfo: desc,
+			Generator:       g,
 		}
 		g.typeMap[fragment.Name] = goType
 		return goType, nil
@@ -722,6 +734,7 @@ func (g *generator) convertNamedFragment(fragment *ast.FragmentDefinition) (goTy
 				Fields:          implFields,
 				Selection:       fragment.SelectionSet,
 				descriptionInfo: implDesc,
+				Generator:       g,
 			}
 			goType.Implementations[i] = implTyp
 			g.typeMap[implTyp.GoName] = implTyp

generate/generate_test.go

@@ -83,8 +83,13 @@ func TestGenerate(t *testing.T) {
 				ExportOperations: queriesFilename,
 				ContextType:      "-",
 				Bindings: map[string]*TypeBinding{
-					"ID":          {Type: "github.com/Khan/genqlient/internal/testutil.ID"},
-					"DateTime":    {Type: "time.Time"},
+					"ID":       {Type: "github.com/Khan/genqlient/internal/testutil.ID"},
+					"DateTime": {Type: "time.Time"},
+					"Date": {
+						Type:        "time.Time",
+						Marshaler:   "github.com/Khan/genqlient/internal/testutil.MarshalDate",
+						Unmarshaler: "github.com/Khan/genqlient/internal/testutil.UnmarshalDate",
+					},
 					"Junk":        {Type: "interface{}"},
 					"ComplexJunk": {Type: "[]map[string]*[]*map[string]interface{}"},
 					"Pokemon": {

generate/marshal.go.tmpl

@@ -0,0 +1,52 @@
+{{/* See unmarshal.go.tmpl for more on how this works; this is mostly just
+     parallel (and simplified -- we don't need to handle embedding). */}}
+
+func (v *{{.GoName}}) MarshalJSON() ([]byte, error) {
+    {{/* We do the two passes in the opposite order of unmarshal: first, we
+         marshal the special fields, then we assign those to the wrapper struct
+         and finish marshaling the whole object.  But first we set up the
+         object for the second part, so we can assign to it as we go. */}}
+    var fullObject struct{
+        *{{.GoName}}
+        {{range .Fields -}}
+        {{if .NeedsMarshaler -}}
+        {{.GoName}} {{repeat .GoType.SliceDepth "[]"}}{{ref "encoding/json.RawMessage"}} `json:"{{.JSONName}}"`
+        {{end -}}
+        {{end -}}
+        {{ref "github.com/Khan/genqlient/graphql.NoUnmarshalJSON"}}
+    }
+    fullObject.{{.GoName}} = v
+
+    {{range $field := .Fields -}}
+    {{if $field.NeedsMarshaler -}}
+    {
+        {{/* Here dst is the json.RawMessage, and src is the Go type */}}
+        dst := &fullObject.{{$field.GoName}}
+        src := v.{{$field.GoName}}
+        {{range $i := intRange $field.GoType.SliceDepth -}}
+        *dst = make(
+            {{repeat (sub $field.GoType.SliceDepth $i) "[]"}}{{ref "encoding/json.RawMessage"}},
+            len(src))
+        for i, src := range src {
+            dst := &(*dst)[i]
+        {{end -}}
+        var err error
+        *dst, err = {{$field.Marshaler $.Generator}}(
+            {{/* src is a pointer to the struct-field (or field-element, etc.).
+                 We want to pass a pointer to the type you specified, so if
+                 there's a pointer on the field that's exactly what we want,
+                 and if not we need to take the address. */ -}}
+            {{if not $field.GoType.IsPointer}}&{{end}}src)
+        if err != nil {
+            return nil, fmt.Errorf(
+                "Unable to marshal {{$.GoName}}.{{$field.GoName}}: %w", err)
+        }
+        {{range $i := intRange $field.GoType.SliceDepth -}}
+        }
+        {{end -}}
+    }
+    {{end -}}
+    {{end}}
+
+    return {{ref "encoding/json.Marshal"}}(&fullObject)
+}

generate/testdata/queries/CustomMarshal.graphql

@@ -0,0 +1,6 @@
+query CustomMarshal($date: Date!) {
+  usersBornOn(date: $date) {
+    id
+    birthdate
+  }
+}

generate/testdata/queries/CustomMarshalSlice.graphql

@@ -0,0 +1,8 @@
+query CustomMarshalSlice(
+  $datesss: [[[Date!]!]!]!,
+  # @genqlient(pointer: true)
+  $datesssp: [[[Date!]!]!]!,
+) {
+  acceptsListOfListOfListsOfDates(datesss: $datesss)
+  withPointer: acceptsListOfListOfListsOfDates(datesss: $datesssp)
+}

generate/testdata/queries/schema.graphql

@@ -3,6 +3,7 @@
 We don't really have anything useful to do with this description though.
 """
 scalar DateTime
+scalar Date
 scalar Junk
 scalar ComplexJunk
 
@@ -44,6 +45,7 @@ input UserQueryInput {
   role: Role
   names: [String]
   hasPokemon: PokemonInput
+  birthdate: Date
 }
 
 type AuthMethod {
@@ -66,6 +68,7 @@ type User {
   authMethods: [AuthMethod!]!
   pokemon: [Pokemon!]
   greeting: Clip
+  birthdate: Date
 }
 
 """An audio clip, such as of a user saying hello."""
@@ -153,6 +156,9 @@ type Query {
 
   """usersWithRole looks a user up by role."""
   usersWithRole(role: Role!): [User!]!
+
+  usersBornOn(date: Date!): [User!]!
+
   root: Topic!
   randomItem: Content!
   randomLeaf: LeafContent!
@@ -163,6 +169,7 @@ type Query {
   listOfListsOfLists: [[[String!]!]!]!
   listOfListsOfListsOfContent: [[[Content!]!]!]!
   recur(input: RecursiveInput!): Recursive
+  acceptsListOfListOfListsOfDates(datesss: [[[Date!]!]!]!): Boolean
 }
 
 type Mutation {