Documentation ¶
Overview ¶
Package goql is a low-level client interface that can communicate with a running GraphQL server.
Index ¶
- Constants
- Variables
- func MarshalMutation(q interface{}, fields Fields) (string, error)
- func MarshalQuery(q interface{}, fields Fields) (string, error)
- func Walk(s interface{}, visit Visit) error
- type Client
- func (c *Client) CustomOperation(ctx context.Context, query string, variables map[string]interface{}, ...) error
- func (c *Client) CustomOperationWithHeaders(ctx context.Context, query string, variables map[string]interface{}, ...) error
- func (c *Client) Mutate(ctx context.Context, operation *Operation) error
- func (c *Client) MutateWithHeaders(ctx context.Context, operation *Operation, headers http.Header) error
- func (c *Client) Query(ctx context.Context, operation *Operation) error
- func (c *Client) QueryWithHeaders(ctx context.Context, operation *Operation, headers http.Header) error
- type ClientOptions
- type Declaration
- type Directive
- type DirectiveEnum
- type Error
- type ErrorMapper
- type Errors
- type Field
- type Fields
- type Node
- type Operation
- type Request
- type Response
- type Token
- type Visit
Constants ¶
const ( DirectiveAlias = DirectiveEnum("alias") DirectiveSkip = DirectiveEnum("skip") DirectiveInclude = DirectiveEnum("include") )
Directive constants using the DirectiveEnum type.
Variables ¶
var DefaultClientOptions = ClientOptions{ HTTPClient: nil, ErrorMapper: nil, }
DefaultClientOptions is a variable that can be passed for the ClientOptions when calling NewClient that will trigger use of all of the default options.
Functions ¶
func MarshalMutation ¶
MarshalMutation takes a variable that must be a struct type and constructs a GraphQL operation using it's fields and graphql struct tags that can be used as a GraphQL mutation operation.
func MarshalQuery ¶
MarshalQuery takes a variable that must be a struct type and constructs a GraphQL operation using it's fields and graphql struct tags that can be used as a GraphQL query operation.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client contains all of the necessary fields and receiver functions to carry out requests to a GraphQL server in an idiomatic way.
func NewClient ¶
func NewClient(clientURL string, options ClientOptions) *Client
NewClient returns a configured pointer to a Client. If httpClient is nil, http.DefaultClient will be used in place of it. If errorMapper is omitted the Errors type will be returned in the case of any errors that came from the GraphQL server.
func (*Client) CustomOperation ¶
func (c *Client) CustomOperation(ctx context.Context, query string, variables map[string]interface{}, resp interface{}) error
CustomOperation is a wrapper around CustomOperationWithHeaders that passes no headers.
func (*Client) CustomOperationWithHeaders ¶
func (c *Client) CustomOperationWithHeaders(ctx context.Context, query string, variables map[string]interface{}, resp interface{}, headers http.Header) error
CustomOperationWithHeaders takes a query in the form of a string and attempts to marshal the response into the resp parameter, which should be passed by reference (as a pointer). If nil is passed as the actual parameter for the formal parameter resp, the response is discarded.
func (*Client) MutateWithHeaders ¶
func (c *Client) MutateWithHeaders(ctx context.Context, operation *Operation, headers http.Header) error
MutateWithHeaders performs a mutate type of request to mutate and retrieve data from a GraphQL server. q should be passed by reference and all variables defined in the struct tag of q should exist within the variables map as well.
func (*Client) QueryWithHeaders ¶
func (c *Client) QueryWithHeaders(ctx context.Context, operation *Operation, headers http.Header) error
QueryWithHeaders performs a query type of request to retrieve data from a GraphQL server. q should be passed by reference and all variables defined in the struct tag of q should exist within the variables map as well.
type ClientOptions ¶
type ClientOptions struct { HTTPClient *http.Client ErrorMapper ErrorMapper }
ClientOptions is the type passed to NewClient that allows for configuration of the client.
HTTPClient is an optional http.Client that the GraphQL client will use underneath the hood. If this field is omitted or nil then the client will use http.DefaultClient.
ErrorMapper allows the Errors type potentially returned from the GraphQL server to be mapped to a different type that implements the error interface, optionally. The status code of the response from the GraphQL server is also passed to this function to attempt to give more context to the callee. If omitted or nil the Errors type will be returned in the case of any errors that came from the GraphQL server. See the documentation for the Errors type for more information as to what can be done with this mapping function.
type Declaration ¶
Declaration is a data structure that represents a field or model in a GraphQL operation.
func (Declaration) Tokenize ¶
func (d Declaration) Tokenize(w io.Writer)
Tokenize is a receiver function of the Declaration type which takes the information contained within and writes it to any type that implements the io.Writer interface.
type Directive ¶
type Directive struct { Type DirectiveEnum Token Token Template string }
Directive is a data structure that represents a directive for a field or model in a GraphQL operation.
type DirectiveEnum ¶
type DirectiveEnum string
DirectiveEnum is an alias to a string that has distinct constant values defined for it allowing it to act as if it were a classic enum.
type Error ¶
type Error struct { Message string `json:"message"` Path []string `json:"path"` Extensions json.RawMessage `json:"extensions"` }
Error is the type that contains the structure of an error returned from a GraphQL server. The Extensions key is intentionally left as a json.RawMessage so that it can optionally be handled and marshaled into whatever type necessary by the ErrorMapper passed to the client.
type ErrorMapper ¶
ErrorMapper is a type that is used for error mapping functions. The status code and Errors are sent as parameters and it is the functions responsibility to map the Errors into a type that implements the error interface.
type Errors ¶
type Errors []Error
Errors is a type alias for a slice of Error, which is what is returned in the response of a request to a GraphQL server. More information is available on the Error type's documentation.
type Field ¶
type Field struct { Decl Declaration Directives []Directive Fields []Field // Keep, if set to true, tells the marshaling process to ignore whatever is // contained in the sparse fieldset information about the current field and // to always render it. Keep is automatically set to true if the marshaler // detects that the current field is an operation declaration. Keep bool }
Field is a data structure that represents a field or model in a GraphQL query.
type Fields ¶
type Fields map[string]interface{}
Fields is a type that is intended to be used to allow sparse field sets when rendering by specifying the fields within the underlying map. Take the following desired GraphQL operation for example:
query { roleCollection { collection { id name parentRole { id } } } }
The following variable would denote those fields being requested, given that the "keep" tag was specified on roleCollection and collection (since they're always necessary in the above query):
f := graphql.Fields{ "id": true, "name": true, "parentRole": graphql.Fields{ "id": true, }, }
Any omitted fields or fields explicitly set to false will not be included in the resulting query. If fields is passed as nil, all fields will be rendered on the operation.
func FieldsFromDelimitedList ¶
FieldsFromDelimitedList is meant to be used to transform a URL query parameter in a Fields type variable to get the sparse fieldset functionality from an HTTP API.
The fieldDelimiter is the delimiter that separates each individual field entry, and usually would be a comma (,). The subFieldDelimiter is the delimiter that separates nested field entries, and usually would be a period. Take the following as an example of how the inputs of this function correlate to the output:
list: id,name,parent.id,parent.parentOfParent.id fieldDelimiter: , subFieldDelimiter: . --- Output:
graphql.Fields{ "id": true, "name": true, "parent": graphql.Fields{ "id": true, "parentOfParent": graphql.Fields{ "id": true, }, }, }
func FieldsFromURLQueryParam ¶
FieldsFromURLQueryParam uses FieldsFromDelimitedList in an opinionated fashion, assuming your fields are separated by a comma and the subfields are separated by a period. See the documentation for FieldsFromDelimitedList for a more granular description on how this process works.
type Operation ¶
Operation is an encapsulation of all of the elements that are used to compose an operation using struct tags. The OperationType field should always be passed by reference in order for the data to be able to be marshaled back into it.
type Request ¶
type Request struct { Query string `json:"query"` Variables map[string]interface{} `json:"variables"` }
Request is the type that contains the structure of a request that a GraphQL server expects.
type Response ¶
type Response struct { // Data uses json.RawMessage to delay decoding of itself since we don't // know the type of it at compile time. Data json.RawMessage `json:"data"` Errors Errors `json:"errors,omitempty"` }
Response is the type that contains the structure of a response from a GraphQL server.
Directories ¶
Path | Synopsis |
---|---|
Package graphql_test exports a Server that facilitates the testing of client integrations of GraphQL by mocking a GraphQL server.
|
Package graphql_test exports a Server that facilitates the testing of client integrations of GraphQL by mocking a GraphQL server. |