genqlient/docs/genqlient.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

# If set, generated code will have a third return parameter of type 
# map[string]interface{}. This will contain the optional values
# of the Extensions field send from Servers.
# ref.: https://spec.graphql.org/October2021/#sec-Response-Format
#
# This can be useful for extending the GraphQL Protocol.
#
# Defaults to false.
use_extensions: boolean

# Customize how models are generated for optional fields. This can currently
# be set to one of the following values:
# - value (default): optional fields are generated as values, the same as
#   non-optional fields. E.g. fields with GraphQL types `String` or `String!`
#   will both map to the Go type `string`. When values are absent in
#   responses the zero value will be used.
# - pointer: optional fields are generated as pointers. E.g. fields with
#   GraphQL type `String` will map to the Go type `*string`. When values are
#   absent in responses `nil` will be used. Optional list fields do not use
#   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.
# - 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
#   type that mimics the behavior of Option<A> or Maybe<A> in other languages like
#   Rust, Java, or Haskell.
optional: value

# Only used when `optional: generic` is set. `example.Type` must be a fully qualified
# generic type with only one generic parameter e.g. atomic.Value[string]. 
# It must also implement the `encoding/json.Marshaler` and `encoding/json.Unmarshaler`
# interface if you want it to serialize / deserialize properly.
optional_generic_type: github.com/organisation/repository/example.Type

# 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.

# A list of packages for which genqlient should automatically generate
# bindings.  This is equivalent to adding a entry
#   TypeName:
#       type: github.com/you/yourpkg/models.TypeName
# to the bindings map, above, for each exported type in the package.  Multiple
# packages may be specified, and later ones take precedence over earlier ones.
# Explicit entries in bindings take precedence over all package bindings.
package_bindings:
- package: github.com/you/yourpkg/models