Add support for binding with a custom marshal/unmarshal function

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](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. (#43)

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)
@@ -188,6 +189,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 {
@@ -217,7 +219,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 {
@@ -269,11 +273,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.
@@ -337,6 +346,7 @@ func (g *generator) convertDefinition(
 			Fields:          fields,
 			Selection:       selectionSet,
 			descriptionInfo: desc,
+			Generator:       g,
 		}
 		return g.addType(goType, goType.GoName, pos)
 
@@ -346,6 +356,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.
@@ -700,6 +711,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
@@ -729,6 +741,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.NoMarshalJSON"}}
+    }
+    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 {