genqlient

Genqlient follows semantic versioning, but because it is currently in 0.x versioning, breaking changes may occur. The project aims to limit breaking changes to minor version bumps (e.g., 0.6.0 instead of 0.5.1).

What constitutes a breaking change?

• Breaking changes to the runtime graphql package.
• Changes that alter the API or behavior of the generated code for the same valid query (re-running a newer version of genqlient on existing queries should be safe).
• Changes to the graphql runtime package that require corresponding changes to the code-generator.

What is NOT considered a breaking change?

• Syntactic changes to generated output (if you use CI to check that generated code is up to date, you should expect to update it when upgrading genqlient).
• Breaking changes to double-underscore-prefixed names (__name) in generated code or names in the graphql runtime documented as "intended for the use of genqlient's generated code only".
• Changes to the code-generator that require corresponding changes to the graphql runtime package.
• Dropping support for Go versions that are no longer supported by the Go project.

Runtime Compatibility

Your version of the graphql runtime package must be the same major version and the same or newer than your version of the code-generator. It is recommended to use the same version for both.

Genqlient allows you to configure how the generated query functions are structured, specifically regarding how they handle context.Context and the GraphQL Client.

You can configure the following:

• Context usage: Specify whether to use no context, a specific custom context type, or the default context.Context.
• Client retrieval: Specify how to obtain the graphql.Client. This can be via a global client or by providing a hook/function to retrieve the client from the context (e.g., using context.Value or a custom method).

This flexibility allows the generated code to integrate with various dependency injection patterns or custom context implementations used in your project.

// Example of possible generated signatures:

// Uses a standard context
func GetUser(ctx context.Context, id string) (*GetUserResponse, error)

// Uses a custom context
func GetUser(ctx mypkg.Context, id string) (*GetUserResponse, error)

// Uses a client object
func GetUser(client graphql.Client, id string) (*GetUserResponse, error)

// Uses both
func GetUser(ctx context.Context, client graphql.Client, id string) (*GetUserResponse, error)

When a GraphQL query returns an interface, genqlient uses Go interfaces to represent the result. This is considered the most natural translation of GraphQL to Go.

How it works:

1. A Go interface is generated for the GraphQL interface (e.g., type I interface { isI() }).
2. Every concrete GraphQL type that implements that interface gets its own Go struct (e.g., type T struct { ... }).
3. These concrete structs implement the interface by providing the required methods (e.g., func (t T) isI() {}).

Usage: To access fields on an interface, you typically use a type switch to determine the concrete type, or you can use getter methods if they are provided by the interface.

// Example of interface representation
// GraphQL: interface I { b: String } | type T implements I { b: String, c: String } | type U implements I { b: String }

type I interface {
    isI()
    GetB() string
}

type T struct {
    B string
    C string
}
func (t T) isI() {}
func (t T) GetB() string { return t.B }

type U struct {
    B string
}
func (u U) isI() {}
func (u U) GetB() string { return u.B }

type Response struct {
    A I
}

In traditional Go GraphQL clients, developers often manually define query strings and response structs. This approach has several risks:

1. Schema Mismatch: The Go struct might not match the actual GraphQL schema (e.g., wrong field names or casing), which is only discovered at runtime.
2. Variable Type Safety: GraphQL variables are often passed as map[string]interface{}, allowing for type errors that only surface at runtime.
3. Boilerplate: Developers must write both the query and the corresponding struct, often requiring complex struct tags.

genqlient solves this by allowing you to simply specify the query; it then automatically validates the query against the schema and generates the necessary type-safe Go helpers and structs.

// Example of the manual, less safe approach used by other clients:
query := `query GetUser($id: ID!) { user(id: $id) { name } }`
variables := map[string]interface{}{"id": "123"}
var resp struct {
	Me struct {
		Name graphql.String
	}
}
client.Query(ctx, query, &resp, variables)
fmt.Println(resp.Me.Name)