ngql

README

Noms GraphQL

An experimental bridge between noms and GraphQL

Status

• All Noms types are supported except

  • Blob
  • Type
  • Unions with non-Struct component types

• Noms collections (List, Set, Map) are expressed as graphql Structs with a list-valued elements field.

  • Lists support argumemts at and count to narrow the range of returned elements
  • Sets and Map support argument count which results in the first count values being returned
  • Map<K,V> is expressed as a list of "entry-struct", e.g.
  • Ref<T> is expressed as a graphql struct with a targetHash and targetValue field.

List:

type FooList {
  size: Float!
  elements: [Foo!]!
}

Set:

type FooSet {
  size: Float!
  elements: [Foo!]!
}

Map:

type StringFooMap {
  size: Float!
  elements: [StringFooEntry!]!
}

type StringFloatEntry {
  key: String!
  value: Float!
}

Ref:

type FooRef {
  targetHash: String!
  targetValue: Foo!
}

• Mutations not yet supported
• Higher-level operations (such as set-intersection/union) not yet supported.
• Perf has not been evaluated or addressed and is probably unimpresssive.

Documentation

Index

• func DefaultNameFunc(nomsType *types.Type, isInputType bool) string
• func Error(err error, w io.Writer)
• func GetInputTypeName(nomsType *types.Type) string
• func GetTypeName(nomsType *types.Type) string
• func InputToNomsValue(arg interface{}, nomsType *types.Type) types.Value
• func MaybeGetScalar(v types.Value) interface{}
• func NewContext(vr types.ValueReader) context.Context
• func NewRootQueryObject(rootValue types.Value, tm *TypeMap) *graphql.Object
• func NomsTypeToGraphQLInputType(nomsType *types.Type, tm *TypeMap) (graphql.Input, error)
• func NomsTypeToGraphQLType(nomsType *types.Type, boxedIfScalar bool, tm *TypeMap) graphql.Type
• func Query(rootValue types.Value, query string, vr types.ValueReader, w io.Writer)
• type NameFunc
• type TypeConverter
  • func NewTypeConverter() *TypeConverter
  • func (tc *TypeConverter) NewRootQueryObject(rootValue types.Value) *graphql.Object
  • func (tc *TypeConverter) NomsTypeToGraphQLInputType(nomsType *types.Type) (graphql.Input, error)
  • func (tc *TypeConverter) NomsTypeToGraphQLType(nomsType *types.Type) graphql.Type
• type TypeMap
  • func NewTypeMap() *TypeMap

Functions

func DefaultNameFunc

func DefaultNameFunc(nomsType *types.Type, isInputType bool) string

DefaultNameFunc returns the GraphQL type name for a Noms type.

func Error

func Error(err error, w io.Writer)

Error writes an error as a GraphQL error to a writer.

func GetInputTypeName

func GetInputTypeName(nomsType *types.Type) string

GetInputTypeName returns a type name that is unique and useful for GraphQL input types.

func GetTypeName

func GetTypeName(nomsType *types.Type) string

GetTypeName provides a unique type name that is used by GraphQL.

func InputToNomsValue

func InputToNomsValue(arg interface{}, nomsType *types.Type) types.Value

InputToNomsValue converts a GraphQL input value (as used in arguments and variables) to a Noms value.

func MaybeGetScalar

func MaybeGetScalar(v types.Value) interface{}

func NewContext

func NewContext(vr types.ValueReader) context.Context

NewContext creates a new context.Context with the extra data added to it that is required by ngql.

func NewRootQueryObject

func NewRootQueryObject(rootValue types.Value, tm *TypeMap) *graphql.Object

NewRootQueryObject creates a "root" query object that can be used to traverse the value tree of rootValue.

func NomsTypeToGraphQLInputType

func NomsTypeToGraphQLInputType(nomsType *types.Type, tm *TypeMap) (graphql.Input, error)

NomsTypeToGraphQLInputType creates a GraphQL input type from a Noms type. Input types may not be unions or cyclic structs. If we encounter those this returns an error.

func NomsTypeToGraphQLType

func NomsTypeToGraphQLType(nomsType *types.Type, boxedIfScalar bool, tm *TypeMap) graphql.Type

NomsTypeToGraphQLType creates a GraphQL type from a Noms type that knows how to resolve the Noms values.

func Query

func Query(rootValue types.Value, query string, vr types.ValueReader, w io.Writer)

Query takes |rootValue|, builds a GraphQL scheme from rootValue.Type() and executes |query| against it, encoding the result to |w|.

Types

type NameFunc

type NameFunc func(nomsType *types.Type, isInputType bool) string

NameFunc defines how to compute the GraphQL name for a Noms type.

type TypeConverter

type TypeConverter struct {
	NameFunc NameFunc
	// contains filtered or unexported fields
}

TypeConverter provides functions to convert between Noms types and GraphQL types.

func NewTypeConverter

func NewTypeConverter() *TypeConverter

NewTypeConverter creates a new TypeConverter.

func (*TypeConverter) NewRootQueryObject

func (tc *TypeConverter) NewRootQueryObject(rootValue types.Value) *graphql.Object

NewRootQueryObject creates a "root" query object that can be used to traverse the value tree of rootValue.

func (*TypeConverter) NomsTypeToGraphQLInputType

func (tc *TypeConverter) NomsTypeToGraphQLInputType(nomsType *types.Type) (graphql.Input, error)

NomsTypeToGraphQLInputType creates a GraphQL input type from a Noms type. Input types may not be unions or cyclic structs. If we encounter those this returns an error.

func (*TypeConverter) NomsTypeToGraphQLType

func (tc *TypeConverter) NomsTypeToGraphQLType(nomsType *types.Type) graphql.Type

NomsTypeToGraphQLType creates a GraphQL type from a Noms type that knows how to resolve the Noms values.

type TypeMap

type TypeMap map[typeMapKey]graphql.Type

TypeMap is used as a cache in NomsTypeToGraphQLType and NomsTypeToGraphQLInputType.

func NewTypeMap

func NewTypeMap() *TypeMap

NewTypeMap creates a new map that is used as a cache in NomsTypeToGraphQLType and NomsTypeToGraphQLInputType.