graphqlclientgen

README

graphqlclientgen

Here Be Dragons 🐉

This is an experiment of generating GraphQL clients in Golang. It's heavily inspired by gqlgen.

• Goals
  • Structure config and generated clients in a future proof way to enable redesign of codegen
  • Single client generated for entire schema
  • ProtoClient interface to support multiple protocols and custom clients
  • Use static types in client interface to check api compability during build time
  • Enable field selection in client to partially fetch objects
• Limitations
  • No support for arguments on fields (yet)

Get started

1. Add graphqlclientgen to tools.go

   //go:build tools
   
   package tools
   
   import (
     _ "github.com/loa/graphqlclientgen/cmd"
   )
   

2. Run go tidy to add graphqlclientgen as dependency

   go mod tidy
   

3. Create a new directory and run graphqlclientgen init

   mkdir exampleclient
   cd exampleclient
   
   go run github.com/loa/graphqlclientgen/cmd init --schema-path='../graph/*.graphqls'
   

4. Run generate (init creates exampleclient.go with go gen comment)

   go generate .
   

Examples

func Example() {
  // create client, supports custom protocols through ProtoClient interface
  c := client.New(graphqlclientgen.NewHttpClient("http://localhost:8080/query"))

  todo, err := c.CreateTodo(context.TODO(),
    // static typed inputs
    client.NewTodo{
      Text:   "bar",
      UserId: "5",
    },
    // explicit requested fields, easy to use with auto-complete
    client.TodoFields{
      client.TodoFieldID,
      client.TodoFieldText,
      // supports requesting specific fields of related objects
      client.TodoFieldUser{
        client.UserFieldID,
        client.UserFieldName,
      },
    })

  if err != nil {
    var gerr graphqlclientgen.Error
    if errors.As(err, &gerr) {
      // match errors by extension
      if gerr.ExtensionEqualString("code", "NOT_FOUND") {
        // handle user not found
      } else if gerr.ExtensionEqualString("code", "INVALID_INPUT") {
        // handle invalid text input
      }
    }
  }
}

Documentation

Index

• Variables
• type Body
• type Error
  • func (err Error) Error() string
  • func (err Error) ExtensionBool(key string) (bool, bool)
  • func (err Error) ExtensionEqualBool(key string, value bool) bool
  • func (err Error) ExtensionEqualInt(key string, value int) bool
  • func (err Error) ExtensionEqualString(key, value string) bool
  • func (err Error) ExtensionFloat64(key string) (float64, bool)
  • func (err Error) ExtensionInt(key string) (int, bool)
  • func (err Error) ExtensionString(key string) (string, bool)
  • func (err Error) ExtensionUnmarshal(key string, in any) error
  • func (err Error) Unwrap() []error
• type ErrorEntry
  • func (entry ErrorEntry) Error() string
  • func (entry ErrorEntry) ExtensionBool(key string) (bool, bool)
  • func (entry ErrorEntry) ExtensionFloat64(key string) (float64, bool)
  • func (entry ErrorEntry) ExtensionInt(key string) (int, bool)
  • func (entry ErrorEntry) ExtensionString(key string) (string, bool)
  • func (entry ErrorEntry) ExtensionUnmarshal(key string, in any) error
• type HttpClient
  • func NewHttpClient(url string, opts ...HttpClientOpts) HttpClient
  • func (httpClient HttpClient) Do(ctx context.Context, in Body, out any) error
• type HttpClientOpts
  • func WithHttpClient(c *http.Client) HttpClientOpts
• type Location
• type ProtoClient
• type Response

Examples

• Error

Variables

var (
	ErrExtensionNotFound = errors.New("extension not found")
)

Types

type Body

type Body struct {
	Query     string         `json:"query"`
	Variables map[string]any `json:"variables"`
}

type Error

type Error []ErrorEntry

https://spec.graphql.org/draft/#sec-Errors

Example

err := Error{
	{
		Message: "entry with incorrect type",
		Extensions: map[string]json.RawMessage{
			"featureA": json.RawMessage(`"true"`),
		},
	},
	{
		Message: "entry with correct type",
		Extensions: map[string]json.RawMessage{
			"featureA": json.RawMessage("true"),
		},
	},
}

fmt.Println(err.Error())

Output:

entry with incorrect type
entry with correct type

func (Error) Error

func (err Error) Error() string

func (Error) ExtensionBool

func (err Error) ExtensionBool(key string) (bool, bool)

func (Error) ExtensionEqualBool

func (err Error) ExtensionEqualBool(key string, value bool) bool

func (Error) ExtensionEqualInt

func (err Error) ExtensionEqualInt(key string, value int) bool

func (Error) ExtensionEqualString

func (err Error) ExtensionEqualString(key, value string) bool

func (Error) ExtensionFloat64

func (err Error) ExtensionFloat64(key string) (float64, bool)

func (Error) ExtensionInt

func (err Error) ExtensionInt(key string) (int, bool)

func (Error) ExtensionString

func (err Error) ExtensionString(key string) (string, bool)

func (Error) ExtensionUnmarshal

func (err Error) ExtensionUnmarshal(key string, in any) error

func (Error) Unwrap

func (err Error) Unwrap() []error

type ErrorEntry

type ErrorEntry struct {
	Message    string                     `json:"message"`
	Path       []string                   `json:"path"`
	Locations  []Location                 `json:"locations"`
	Extensions map[string]json.RawMessage `json:"extensions"`
}

func (ErrorEntry) Error

func (entry ErrorEntry) Error() string

func (ErrorEntry) ExtensionBool

func (entry ErrorEntry) ExtensionBool(key string) (bool, bool)

func (ErrorEntry) ExtensionFloat64

func (entry ErrorEntry) ExtensionFloat64(key string) (float64, bool)

func (ErrorEntry) ExtensionInt

func (entry ErrorEntry) ExtensionInt(key string) (int, bool)

func (ErrorEntry) ExtensionString

func (entry ErrorEntry) ExtensionString(key string) (string, bool)

func (ErrorEntry) ExtensionUnmarshal

func (entry ErrorEntry) ExtensionUnmarshal(key string, in any) error

type HttpClient

type HttpClient struct {
	// contains filtered or unexported fields
}

func NewHttpClient

func NewHttpClient(url string, opts ...HttpClientOpts) HttpClient

NewHttpClient creates a new HttpClient for graphqlclientgen clients

func (HttpClient) Do

func (httpClient HttpClient) Do(ctx context.Context, in Body, out any) error

Do performs http post request towards a GraphQL api

type HttpClientOpts

type HttpClientOpts func(*HttpClient)

func WithHttpClient

func WithHttpClient(c *http.Client) HttpClientOpts

WithHttpClient sets a custom http.Client for HttpClient

type Location

type Location struct {
	Line   int `json:"line"`
	Column int `json:"column"`
}

type ProtoClient

type ProtoClient interface {
	Do(ctx context.Context, in Body, out any) error
}

type Response

type Response struct {
	Data   json.RawMessage `json:"data"`
	Errors *Error          `json:"errors"`
}