ngql

README

Noms GraphQL

An experimental bridge between Noms and GraphQL

This is to be used with https://github.com/attic-labs/graphql which is a fork of https://github.com/graphql-go/graphql to handle Noms values. It disables some validations that do not work for Noms due to Noms being schemaless (or more precisely the schema is a function of the value in the dataset).

ngql provides an API to convert Noms types/values to and from GraphQL types/values, as well as some functions that can be used to implement a GraphQL endpoint using https://github.com/attic-labs/graphql.

Status

• All Noms types are supported except
  • Blob
  • Type
  • Unions with non-Struct component types
  • GraphQL does not support unions in input types which limits the input types that can be used.

Type conversion rules

Value

Allmost all Noms values can be represented by GraphQL. All Noms values except the primitives (Bool, Number & String) are represented by a GraphQL struct.

Bool

Is represented by a non nullable Bool

Number

Is represented by a non nullable Float

String

Is represented by a non nullable String

List

Noms lists are expressed as a GraphQL struct with the fields

• values - The values in the list.
• size - The number of values in the list.

Lists takes a few optional arguments:

• at - The index to start at, defaults to 0.
• count - The number of values to return, defaults to all of the values.

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

Set

Noms sets are expressed as a GraphQL struct with the fields

• values - The values in the set.
• size - The number of values in the set.

Sets takes a few optional arguments:

• at - The index to start at, defaults to 0.
• count - The number of values to return, defaults to all of the values.
• key - The value to start at.
• through - The value to end at (inclusive).
• keys - When provided only values that matches the keys are included in the result.

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

Map

Noms maps are expressed as a GraphQL struct with the fields

• values - The values in the map.
• keys - The keys in the map.
• entries - The entries in the map. An entry is a struct with key and value fields.
• size - The number of values in the map.

Sets takes a few optional arguments:

• at - The index to start at, defaults to 0
• count - The number of elements to return, defaults to all of the elements.
• key - The value to start at
• through - The value to end at (inclusive)
• keys - When provided only values/keys/entries that matches the keys are included in the result.

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

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

Struct

Noms structs are expressed as GraphQL structs, with an extra hash field.

If the field in the Noms struct is optional then the GraphQL type for that field is nullable.

Ref

Noms refs are expressed as a GraphQL struct with a targetHash and targetValue field.

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

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(vrw types.ValueReadWriter, arg interface{}, nomsType *types.Type) types.Value
• func MaybeGetScalar(v types.Value) interface{}
• func NewContext(vrw 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, vrw types.ValueReadWriter, 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(vrw types.ValueReadWriter, 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(vrw 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, vrw types.ValueReadWriter, 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.