CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/golang-github-com--graphql-go--graphql

Complete GraphQL implementation in Go with schema definition, query execution, and validation.

Overview
Eval results
Files

schema.mddocs/reference/

Schema & Type System

The type system is the foundation of a GraphQL API. Use these types to build a schema that describes your data and how it can be queried.

Schema

A schema is the entry point for all GraphQL operations. It defines the root query type, optional mutation type, and optional subscription type.

type SchemaConfig struct {
    Query        *Object
    Mutation     *Object      // optional
    Subscription *Object      // optional
    Types        []Type       // additional types to include
    Directives   []*Directive // custom directives; if nil, uses SpecifiedDirectives
    Extensions   []Extension  // schema-level extensions
}

func NewSchema(config SchemaConfig) (Schema, error)
type Schema struct{} // opaque

func (gq *Schema) QueryType() *Object
func (gq *Schema) MutationType() *Object
func (gq *Schema) SubscriptionType() *Object
func (gq *Schema) TypeMap() TypeMap
func (gq *Schema) Type(name string) Type
func (gq *Schema) Directives() []*Directive
func (gq *Schema) Directive(name string) *Directive
func (gq *Schema) PossibleTypes(abstractType Abstract) []*Object
func (gq *Schema) IsPossibleType(abstractType Abstract, possibleType *Object) bool
func (gq *Schema) AddExtensions(e ...Extension)
func (gq *Schema) AddImplementation() error
func (gq *Schema) AppendType(objectType Type) error

Example:

schema, err := graphql.NewSchema(graphql.SchemaConfig{
    Query:    queryType,
    Mutation: mutationType,
})

Object Type

The most common type. Defines a set of fields that can be queried.

type ObjectConfig struct {
    Name        string
    Interfaces  interface{} // []*Interface or func() []*Interface (InterfacesThunk)
    Fields      interface{} // Fields or FieldsThunk
    IsTypeOf    IsTypeOfFn
    Description string
}

func NewObject(config ObjectConfig) *Object
type Object struct {
    PrivateName        string     `json:"name"`
    PrivateDescription string     `json:"description"`
    IsTypeOf           IsTypeOfFn
    // unexported fields
}

func (gt *Object) Name() string
func (gt *Object) Description() string
func (gt *Object) Fields() FieldDefinitionMap
func (gt *Object) Interfaces() []*Interface
func (gt *Object) AddFieldConfig(fieldName string, fieldConfig *Field)
func (gt *Object) String() string
func (gt *Object) Error() error
type Fields map[string]*Field

type FieldsThunk func() Fields  // use for circular references

type Field struct {
    Name              string              `json:"name"`
    Type              Output              `json:"type"`
    Args              FieldConfigArgument `json:"args"`
    Resolve           FieldResolveFn      `json:"-"`
    Subscribe         FieldResolveFn      `json:"-"` // for subscription fields
    DeprecationReason string              `json:"deprecationReason"`
    Description       string              `json:"description"`
}

type FieldResolveFn func(p ResolveParams) (interface{}, error)

Example with thunk (for circular references):

var personType = graphql.NewObject(graphql.ObjectConfig{
    Name: "Person",
    Fields: graphql.FieldsThunk(func() graphql.Fields {
        return graphql.Fields{
            "name": &graphql.Field{Type: graphql.String},
            "friends": &graphql.Field{Type: graphql.NewList(personType)},
        }
    }),
})

FieldConfigArgument

type FieldConfigArgument map[string]*ArgumentConfig

type ArgumentConfig struct {
    Type         Input       `json:"type"`
    DefaultValue interface{} `json:"defaultValue"`
    Description  string      `json:"description"`
}

FieldDefinition (resolved field)

type FieldDefinitionMap map[string]*FieldDefinition

type FieldDefinition struct {
    Name              string         `json:"name"`
    Description       string         `json:"description"`
    Type              Output         `json:"type"`
    Args              []*Argument    `json:"args"`
    Resolve           FieldResolveFn `json:"-"`
    Subscribe         FieldResolveFn `json:"-"`
    DeprecationReason string         `json:"deprecationReason"`
}

FieldResolver Interface

type FieldResolver interface {
    Resolve(p ResolveParams) (interface{}, error)
}

DefaultResolveFn checks if the source implements FieldResolver. If so, it calls Resolve. Otherwise, it reflects on the source struct field with the same name as the field.

func DefaultResolveFn(p ResolveParams) (interface{}, error)

Reflection Helpers

func BindFields(obj interface{}) Fields
// Binds exported struct fields to GraphQL Fields. Cannot handle recursive types.

func BindArg(obj interface{}, tags ...string) FieldConfigArgument
// Lazily binds struct fields to FieldConfigArgument using struct tags (default: "json").

const TAG = "json" // struct tag name used by BindFields

Interface Type

Defines a set of fields that multiple object types can implement.

type InterfaceConfig struct {
    Name        string
    Fields      interface{} // Fields or FieldsThunk
    ResolveType ResolveTypeFn
    Description string
}

func NewInterface(config InterfaceConfig) *Interface
type Interface struct {
    PrivateName        string `json:"name"`
    PrivateDescription string `json:"description"`
    ResolveType        ResolveTypeFn
    // unexported fields
}

func (it *Interface) Name() string
func (it *Interface) Description() string
func (it *Interface) Fields() (fields FieldDefinitionMap)
func (it *Interface) AddFieldConfig(fieldName string, fieldConfig *Field)
func (it *Interface) String() string
func (it *Interface) Error() error
type ResolveTypeFn func(p ResolveTypeParams) *Object

type ResolveTypeParams struct {
    Value   interface{}
    Info    ResolveInfo
    Context context.Context
}

Union Type

Describes a type that can be one of several object types.

type UnionConfig struct {
    Name        string
    Types       interface{} // []*Object or UnionTypesThunk
    ResolveType ResolveTypeFn
    Description string
}

type UnionTypesThunk func() []*Object

func NewUnion(config UnionConfig) *Union
type Union struct {
    PrivateName        string `json:"name"`
    PrivateDescription string `json:"description"`
    ResolveType        ResolveTypeFn
    // unexported fields
}

func (ut *Union) Name() string
func (ut *Union) Description() string
func (ut *Union) Types() []*Object
func (ut *Union) String() string
func (ut *Union) Error() error

Enum Type

Defines a set of named values.

type EnumConfig struct {
    Name        string             `json:"name"`
    Values      EnumValueConfigMap `json:"values"`
    Description string             `json:"description"`
}

type EnumValueConfigMap map[string]*EnumValueConfig

type EnumValueConfig struct {
    Value             interface{} `json:"value"`
    DeprecationReason string      `json:"deprecationReason"`
    Description       string      `json:"description"`
}

func NewEnum(config EnumConfig) *Enum
type Enum struct {
    PrivateName        string `json:"name"`
    PrivateDescription string `json:"description"`
    // unexported fields
}

func (gt *Enum) Name() string
func (gt *Enum) Description() string
func (gt *Enum) Values() []*EnumValueDefinition
func (gt *Enum) Serialize(value interface{}) interface{}
func (gt *Enum) ParseValue(value interface{}) interface{}
func (gt *Enum) ParseLiteral(valueAST ast.Value) interface{}
func (gt *Enum) String() string
func (gt *Enum) Error() error

type EnumValueDefinition struct {
    Name              string      `json:"name"`
    Value             interface{} `json:"value"`
    DeprecationReason string      `json:"deprecationReason"`
    Description       string      `json:"description"`
}

Example:

episodeEnum := graphql.NewEnum(graphql.EnumConfig{
    Name: "Episode",
    Values: graphql.EnumValueConfigMap{
        "NEWHOPE": &graphql.EnumValueConfig{Value: 4},
        "EMPIRE":  &graphql.EnumValueConfig{Value: 5},
        "JEDI":    &graphql.EnumValueConfig{Value: 6},
    },
})

Scalar Type

Custom leaf values with serialize/parse logic.

type ScalarConfig struct {
    Name         string         `json:"name"`
    Description  string         `json:"description"`
    Serialize    SerializeFn
    ParseValue   ParseValueFn
    ParseLiteral ParseLiteralFn
}

type SerializeFn    func(value interface{}) interface{}
type ParseValueFn   func(value interface{}) interface{}
type ParseLiteralFn func(valueAST ast.Value) interface{}

func NewScalar(config ScalarConfig) *Scalar
type Scalar struct {
    PrivateName        string `json:"name"`
    PrivateDescription string `json:"description"`
    // unexported fields
}

func (st *Scalar) Name() string
func (st *Scalar) Description() string
func (st *Scalar) Serialize(value interface{}) interface{}
func (st *Scalar) ParseValue(value interface{}) interface{}
func (st *Scalar) ParseLiteral(valueAST ast.Value) interface{}
func (st *Scalar) String() string
func (st *Scalar) Error() error

InputObject Type

A structured collection of fields used as argument values.

type InputObjectConfig struct {
    Name        string      `json:"name"`
    Fields      interface{} `json:"fields"` // InputObjectConfigFieldMap or InputObjectConfigFieldMapThunk
    Description string      `json:"description"`
}

type InputObjectConfigFieldMap map[string]*InputObjectFieldConfig

type InputObjectConfigFieldMapThunk func() InputObjectConfigFieldMap

type InputObjectFieldConfig struct {
    Type         Input       `json:"type"`
    DefaultValue interface{} `json:"defaultValue"`
    Description  string      `json:"description"`
}

func NewInputObject(config InputObjectConfig) *InputObject
type InputObject struct {
    PrivateName        string `json:"name"`
    PrivateDescription string `json:"description"`
    // unexported fields
}

func (gt *InputObject) Name() string
func (gt *InputObject) Description() string
func (gt *InputObject) Fields() InputObjectFieldMap
func (gt *InputObject) AddFieldConfig(fieldName string, fieldConfig *InputObjectFieldConfig)
func (gt *InputObject) String() string
func (gt *InputObject) Error() error

type InputObjectFieldMap map[string]*InputObjectField

type InputObjectField struct {
    PrivateName        string      `json:"name"`
    Type               Input       `json:"type"`
    DefaultValue       interface{} `json:"defaultValue"`
    PrivateDescription string      `json:"description"`
}

func (st *InputObjectField) Name() string
func (st *InputObjectField) Description() string
func (st *InputObjectField) String() string
func (st *InputObjectField) Error() error

List and NonNull Modifiers

type List struct {
    OfType Type `json:"ofType"`
    // unexported fields
}

func NewList(ofType Type) *List
func (gl *List) Name() string
func (gl *List) Description() string
func (gl *List) String() string
func (gl *List) Error() error
type NonNull struct {
    OfType Type `json:"ofType"`
    // unexported fields
}

func NewNonNull(ofType Type) *NonNull
func (gl *NonNull) Name() string
func (gl *NonNull) Description() string
func (gl *NonNull) String() string
func (gl *NonNull) Error() error

Directives

type DirectiveConfig struct {
    Name        string              `json:"name"`
    Description string              `json:"description"`
    Locations   []string            `json:"locations"`
    Args        FieldConfigArgument `json:"args"`
}

func NewDirective(config DirectiveConfig) *Directive

type Directive struct {
    Name        string      `json:"name"`
    Description string      `json:"description"`
    Locations   []string    `json:"locations"`
    Args        []*Argument `json:"args"`
    // unexported fields
}

Directive Location Constants

const (
    // Executable locations
    DirectiveLocationQuery              = "QUERY"
    DirectiveLocationMutation          = "MUTATION"
    DirectiveLocationSubscription      = "SUBSCRIPTION"
    DirectiveLocationField             = "FIELD"
    DirectiveLocationFragmentDefinition = "FRAGMENT_DEFINITION"
    DirectiveLocationFragmentSpread    = "FRAGMENT_SPREAD"
    DirectiveLocationInlineFragment    = "INLINE_FRAGMENT"

    // Type system locations
    DirectiveLocationSchema               = "SCHEMA"
    DirectiveLocationScalar               = "SCALAR"
    DirectiveLocationObject               = "OBJECT"
    DirectiveLocationFieldDefinition      = "FIELD_DEFINITION"
    DirectiveLocationArgumentDefinition   = "ARGUMENT_DEFINITION"
    DirectiveLocationInterface            = "INTERFACE"
    DirectiveLocationUnion                = "UNION"
    DirectiveLocationEnum                 = "ENUM"
    DirectiveLocationEnumValue            = "ENUM_VALUE"
    DirectiveLocationInputObject          = "INPUT_OBJECT"
    DirectiveLocationInputFieldDefinition = "INPUT_FIELD_DEFINITION"
)

Built-in Directives

var IncludeDirective    *Directive // @include(if: Boolean!)
var SkipDirective       *Directive // @skip(if: Boolean!)
var DeprecatedDirective *Directive // @deprecated(reason: String)

var SpecifiedDirectives = []*Directive{IncludeDirective, SkipDirective, DeprecatedDirective}

const DefaultDeprecationReason = "No longer supported"

Arguments

type Argument struct {
    PrivateName        string      `json:"name"`
    Type               Input       `json:"type"`
    DefaultValue       interface{} `json:"defaultValue"`
    PrivateDescription string      `json:"description"`
}

func (st *Argument) Name() string
func (st *Argument) Description() string
func (st *Argument) String() string
func (st *Argument) Error() error
// FieldArgument represents a resolved argument on a field definition.
type FieldArgument struct {
    Name         string      `json:"name"`
    Type         Type        `json:"type"`
    DefaultValue interface{} `json:"defaultValue"`
    Description  string      `json:"description"`
}

Built-in Scalar Types

var Int      *Scalar // GraphQL Int (32-bit signed)
var Float    *Scalar // GraphQL Float (double-precision)
var String   *Scalar // GraphQL String (UTF-8)
var Boolean  *Scalar // GraphQL Boolean
var ID       *Scalar // GraphQL ID (serialized as string)
var DateTime *Scalar // RFC 3339 date-time

Type Interfaces

type Type interface {
    Name() string
    Description() string
    String() string
    Error() error
}

type Input interface {
    Name() string
    Description() string
    String() string
    Error() error
}

type Output interface {
    Name() string
    Description() string
    String() string
    Error() error
}

type Leaf interface {
    Name() string
    Description() string
    String() string
    Error() error
    Serialize(value interface{}) interface{}
}

type Composite interface {
    Name() string
    Description() string
    String() string
    Error() error
}

type Abstract interface {
    Name() string
}

type Named interface {
    String() string
}

type Nullable interface{}

type TypeMap map[string]Type

Type Utility Functions

func IsInputType(ttype Type) bool
func IsOutputType(ttype Type) bool
func IsLeafType(ttype Type) bool
func IsCompositeType(ttype interface{}) bool
func IsAbstractType(ttype interface{}) bool
func GetNamed(ttype Type) Named
func GetNullable(ttype Type) Nullable

TypeKind Constants

const (
    TypeKindScalar      = "SCALAR"
    TypeKindObject      = "OBJECT"
    TypeKindInterface   = "INTERFACE"
    TypeKindUnion       = "UNION"
    TypeKindEnum        = "ENUM"
    TypeKindInputObject = "INPUT_OBJECT"
    TypeKindList        = "LIST"
    TypeKindNonNull     = "NON_NULL"
)

Introspection Types

These are automatically added to every schema:

var SchemaType      *Object // __Schema
var TypeType        *Object // __Type
var FieldType       *Object // __Field
var InputValueType  *Object // __InputValue
var EnumValueType   *Object // __EnumValue
var DirectiveType   *Object // __Directive

var TypeKindEnumType          *Enum // __TypeKind
var DirectiveLocationEnumType *Enum // __DirectiveLocation

var SchemaMetaFieldDef    *FieldDefinition // __schema field
var TypeMetaFieldDef      *FieldDefinition // __type field
var TypeNameMetaFieldDef  *FieldDefinition // __typename field

Name Validation

var NameRegExp = regexp.MustCompile("^[_a-zA-Z][_a-zA-Z0-9]*$")

InterfacesThunk / UnionTypesThunk

type InterfacesThunk func() []*Interface
type UnionTypesThunk func() []*Object

Use thunks in ObjectConfig.Interfaces and UnionConfig.Types to defer evaluation for circular references.

Install with Tessl CLI

npx tessl i tessl/golang-github-com--graphql-go--graphql

docs

reference

errors.md

execution.md

language.md

schema.md

validation.md

index.md

tile.json