Nathan Stitt
2fdbb629be
Adds a "struct_references" configuration that will: * Use a pointer type for struct fields that are a complex type * The behaviour can be overridden by setting "pointer: false" in the proceeding comment blocks * Sets the "omitempty: true" flag on fields matching the criteria. This can also be overriden by setting "omitempty: false" Although we'd debated not setting the pointer for array elements, it did turn out to be simpler to set them everywhere and also made the documentation cleaner to have a single rule to explain. Fixes #149.
186 lines
8.1 KiB
YAML
186 lines
8.1 KiB
YAML
# genqlient.yaml is genqlient's configuration file. This genqlient.yaml is an
|
|
# example; use `go run github.com/Khan/genqlient --init` to generate a simple
|
|
# starting point. By default, genqlient looks for the configuration file
|
|
# named [.]genqlient.y[a]ml in the current directory or any ancestor; or the
|
|
# filename may be given as an argument.
|
|
|
|
# The filename with the GraphQL schema (in SDL format), relative to
|
|
# genqlient.yaml.
|
|
# This can also be a list of filenames, such as:
|
|
# schema:
|
|
# - user.graphql
|
|
# - ./schema/*.graphql
|
|
# - ./another_directory/*/*.graphql
|
|
schema: schema.graphql
|
|
|
|
# Filename(s) or globs with the operations for which to generate code, relative
|
|
# to genqlient.yaml.
|
|
#
|
|
# These may be .graphql files, containing the queries in SDL format, or
|
|
# Go files, in which case any string-literal starting with (optional
|
|
# whitespace and) the string "# @genqlient" will be extracted as a query.
|
|
#
|
|
# Like schema, this may be a single file or a list.
|
|
operations:
|
|
- genqlient.graphql
|
|
- "pkg/*.go"
|
|
|
|
# The filename to which to write the generated code, relative to
|
|
# genqlient.yaml.
|
|
generated: generated/genqlient.go
|
|
|
|
# The package name for the output code; defaults to the directory name of
|
|
# the generated-code file.
|
|
package: mygenerated
|
|
|
|
# If set, a file at this path (relative to genqlient.yaml) will be generated
|
|
# containing the exact operations that genqlient will send to the server.
|
|
#
|
|
# This is useful for systems which require queries to be explicitly
|
|
# safelisted (e.g. [1]), especially for cases like queries involving fragments
|
|
# where it may not exactly match the input queries, or for other static
|
|
# analysis. The JSON is an object of the form
|
|
# {"operations": [{
|
|
# "operationName": "operationname",
|
|
# "query": "query operationName { ... }",
|
|
# "sourceLocation": "myqueriesfile.graphql",
|
|
# }]}
|
|
# Keys may be added in the future.
|
|
#
|
|
# By default, no such file is written.
|
|
#
|
|
# [1] https://www.apollographql.com/docs/studio/operation-registry/
|
|
export_operations: operations.json
|
|
|
|
# Set to the fully-qualified name of a Go type which generated helpers
|
|
# should accept and use as the context.Context for HTTP requests.
|
|
#
|
|
# Defaults to context.Context; set to "-" to omit context entirely (i.e.
|
|
# use context.Background()). Must be a type which implements
|
|
# context.Context.
|
|
context_type: context.Context
|
|
|
|
# If set, a function to get a graphql.Client, perhaps from the context.
|
|
# By default, the client must be passed explicitly to each genqlient
|
|
# generated query-helper.
|
|
#
|
|
# This is useful if you have a shared client, either a global, or
|
|
# available from context, and don't want to pass it explicitly. In this
|
|
# case the signature of the genqlient-generated helpers will omit the
|
|
# `graphql.Context` and they will call this function instead.
|
|
#
|
|
# Must be the fully-qualified name of a function which accepts a context
|
|
# (of the type configured as ContextType (above), which defaults to
|
|
# `context.Context`, or a function of no arguments if ContextType is set
|
|
# to the empty string) and returns (graphql.Client, error). If the
|
|
# client-getter returns an error, the helper will return the error
|
|
# without making a query.
|
|
client_getter: "github.com/you/yourpkg.GetClient"
|
|
|
|
|
|
# If set, fields with a struct type will default to having
|
|
# the "pointer: true, omitempty: true" flag.
|
|
#
|
|
# This can be useful for struct schema where it would be burdensome
|
|
# to manually set the flags on a large number of fields.
|
|
#
|
|
# Defaults to false.
|
|
use_struct_references: boolean
|
|
|
|
|
|
# A map from GraphQL type name to Go fully-qualified type name to override
|
|
# the Go type genqlient will use for this GraphQL type.
|
|
#
|
|
# This is primarily used for custom scalars, or to map builtin scalars
|
|
# to a nonstandard type that is defined elsewhere. By default,
|
|
# builtin scalars are mapped to the obvious Go types (String and ID to
|
|
# string, Int to int, Float to float64, and Boolean to bool), but this
|
|
# setting will extend or override those mappings. (See also
|
|
# @genqlient(typename: ...), which can be used to map builtin scalars
|
|
# to a nonstandard type that genqlient defines for you.)
|
|
#
|
|
# genqlient does not validate these types in any way; they must define
|
|
# whatever logic is needed (MarshalJSON/UnmarshalJSON or JSON tags) to
|
|
# convert to/from JSON. For this reason, it's not recommended to use this
|
|
# setting to map object, interface, or union types, because nothing
|
|
# guarantees that the fields requested in the query match those present in
|
|
# the Go type.
|
|
#
|
|
# To get equivalent behavior in just one query, use @genqlient(bind: ...);
|
|
# see genqlient_directive.graphql for more details.
|
|
bindings:
|
|
# To bind a scalar:
|
|
DateTime:
|
|
# The fully-qualified name of the Go type to which to bind. For example:
|
|
# time.Time
|
|
# map[string]interface{}
|
|
# github.com/you/yourpkg/subpkg.MyType
|
|
# Specifically, this can be any of the following expressions:
|
|
# - any named type (qualified by the full package path)
|
|
# - any predeclared basic type (string, int, etc.)
|
|
# - interface{}
|
|
# - for any allowed type T, *T, []T, [N]T, and map[string]T
|
|
# but can't be, for example:
|
|
# - an inline (unnamed) struct or interface type
|
|
# - a map whose key-type is not string
|
|
# - 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:
|
|
type: github.com/you/yourpkg.GoType
|
|
# If set, a GraphQL selection which must exactly match the fields
|
|
# requested whenever this type is used. Only applies if the GraphQL type
|
|
# is a composite output type (object, interface, or union).
|
|
#
|
|
# This is useful if Type is a struct whose UnmarshalJSON or other methods
|
|
# expect that you requested certain fields. For example, given the below
|
|
# config, genqlient will reject if you make a query
|
|
# { fieldOfMytype { id title } }
|
|
# The fields must match exactly, including the ordering: "{ name id }"
|
|
# will be rejected. But the arguments and directives, if any, need not
|
|
# match.
|
|
#
|
|
# TODO(benkraft): Also add ExpectIncludesFields and ExpectSubsetOfFields,
|
|
# 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.
|