Annotated optional fields with omitempty by using new optional config value (#308)

It could be useful to annotate optional fields annotate with `omitempty`
when using pointers.
By allowing this option, input fields that get removed (and not used is
the executed queries) will not break.
This gives the library an advantage to be more resilient against break
API changes.

To introduce this option, a new `optional` config value is introduced
`pointer_omitempty`.

If `optional: pointer_omitempty` is set. We generate
```
type Task_insert_input struct {
  Id: *int `json:"id,omitempty"`
}
```
based on 
```
input task_insert_input {
  id: Int
}
```

The `@genqlient(omitempty)` config will override the previous defined
config.

Author: rmennes

docs/CHANGELOG.md

@@ -78,6 +78,7 @@ In addition to several new features and bugfixes, along with this release comes
 ### New features:
 
 - The new `optional: generic` allows using a generic type to represent optionality. See the [documentation](genqlient.yaml) for details.
+- The new `optional: pointer_omitempty` allows using a pointer that is also annotated with `omitempty`. See the [documentation](genqlient.yaml) for details.
 - For schemas with enum values that differ only in casing, it's now possible to disable smart-casing in genqlient.yaml; see the [documentation](genqlient.yaml) for `casing` for details.
 - genqlient now supports .graphqls and .gql file extensions for schemas and queries.
 - More accurately guess the package name for generated code (and warn if the config option -- now almost never needed -- looks wrong).

docs/genqlient.yaml

@@ -116,6 +116,9 @@ use_extensions: boolean
 #   pointers-to-slices, so the GraphQL type `[String]` will map to the Go
 #   type `[]*string`, not `*[]*string`; GraphQL null and empty list simply
 #   map to Go nil- and empty-slice.
+# - pointer_omitempty: optional fields are generated as pointers, as described above.
+#   Additionally, the fields are annotated with omitempty. Fields that are not defined,
+#   will not be exposed.
 # - generic: optional fields are generated as type parameters to a generic type
 #   specified by `optional_generic_type`. E.g. fields with GraphQL type `String`
 #   will map to the Go type `generic.Type[string]`. This is useful if you have a

generate/config.go

@@ -212,8 +212,8 @@ func (c *Config) ValidateAndFillDefaults(baseDir string) error {
 		c.ContextType = "context.Context"
 	}
 
-	if c.Optional != "" && c.Optional != "value" && c.Optional != "pointer" && c.Optional != "generic" {
-		return errorf(nil, "optional must be one of: 'value' (default), 'pointer', or 'generic'")
+	if c.Optional != "" && c.Optional != "value" && c.Optional != "pointer" && c.Optional != "pointer_omitempty" && c.Optional != "generic" {
+		return errorf(nil, "optional must be one of: 'value' (default), 'pointer', 'pointer_omitempty' or 'generic'")
 	}
 
 	if c.Optional == "generic" && c.OptionalGenericType == "" {

generate/convert.go

@@ -258,6 +258,15 @@ func (g *generator) convertType(
 			oe := true
 			options.Omitempty = &oe
 		}
+	} else if g.Config.Optional == "pointer_omitempty" && (options.GetPointer() || !typ.NonNull) {
+		if !options.PointerIsFalse() {
+			goTyp = &goPointerType{Elem: goTyp}
+		}
+
+		if options.Omitempty == nil {
+			oe := true
+			options.Omitempty = &oe
+		}
 	} else if !options.PointerIsFalse() && (options.GetPointer() || (!typ.NonNull && g.Config.Optional == "pointer")) {
 		// Whatever we get, wrap it in a pointer.  (Because of the way the
 		// options work, recursing here isn't as connvenient.)

generate/generate_test.go

@@ -9,8 +9,9 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/Khan/genqlient/internal/testutil"
 	"gopkg.in/yaml.v2"
+
+	"github.com/Khan/genqlient/internal/testutil"
 )
 
 const (
@@ -239,6 +240,26 @@ func TestGenerateWithConfig(t *testing.T) {
 				Enums: map[string]CasingAlgorithm{"Role": CasingRaw},
 			},
 		}},
+		{"OptionalPointerOmitEmpty", "", []string{
+			"InputObject.graphql",
+			"PointersOmitEmpty.graphql",
+			"Omitempty.graphql",
+			"ListInput.graphql",
+		}, &Config{
+			Optional: "pointer_omitempty",
+			Bindings: map[string]*TypeBinding{
+				"Date": {
+					Type:        "time.Time",
+					Marshaler:   "github.com/Khan/genqlient/internal/testutil.MarshalDate",
+					Unmarshaler: "github.com/Khan/genqlient/internal/testutil.UnmarshalDate",
+				},
+				"DateTime": {
+					Type:        "time.Time",
+					Marshaler:   "github.com/Khan/genqlient/internal/testutil.MarshalDate",
+					Unmarshaler: "github.com/Khan/genqlient/internal/testutil.UnmarshalDate",
+				},
+			},
+		}},
 		{
 			"UseStructReference", "", []string{"UseStructReference.graphql"}, &Config{
 				StructReferences: true,

generate/testdata/queries/PointersOmitEmpty.graphql

@@ -0,0 +1,22 @@
+# @genqlient(for: "UserQueryInput.id", pointer: false)
+# @genqlient(for: "User.id", pointer: false)
+query PointersOmitEmptyQuery(
+  $query: UserQueryInput,
+  $dt: DateTime,
+  # @genqlient(pointer: false)
+  $tz: String,
+) {
+  user(query: $query) {
+    # @genqlient(pointer: true)
+    id
+    roles
+    name
+    emails
+    # @genqlient(pointer: false)
+    emailsNoPtr: emails
+  }
+  otherUser: user(query: $query) {
+    id
+  }
+  maybeConvert(dt: $dt, tz: $tz)
+}

generate/testdata/snapshots/TestGenerate-PointersOmitEmpty.graphql-PointersOmitEmpty.graphql.go

@@ -0,0 +1,9 @@
+{
+  "operations": [
+    {
+      "operationName": "PointersOmitEmptyQuery",
+      "query": "\nquery PointersOmitEmptyQuery ($query: UserQueryInput, $dt: DateTime, $tz: String) {\n\tuser(query: $query) {\n\t\tid\n\t\troles\n\t\tname\n\t\temails\n\t\temailsNoPtr: emails\n\t}\n\totherUser: user(query: $query) {\n\t\tid\n\t}\n\tmaybeConvert(dt: $dt, tz: $tz)\n}\n",
+      "sourceLocation": "testdata/queries/PointersOmitEmpty.graphql"
+    }
+  ]
+}