graphql 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9cf6add0a41fbbf194c90bd12da917467ae612d7
-  data.tar.gz: b0e7b7f03eb0e6a9def2f7402f3349e69d07ec33
+  metadata.gz: a35f790dd696036b5c7ea909517a2108891d2732
+  data.tar.gz: 795e06d90a94be917cf6ffaf911d00e5c14faade
 SHA512:
-  metadata.gz: f5d0f097d277cdd8e40976ce87ef5d57edf365c2fadf821de5c90d7dad9f9d7819a21291c6b01a83ab05e1d7850617bbbe0382c492776b04e5fa619e186e8caa
-  data.tar.gz: ee252ea72993ee9c07ce9d69f6f25c0b6d13e9f7f2bf7cbbb419d8d2b01f48a9c7e57310c6cc05e051c833ee72b42494399bd5252813a4641d1ba3e88be17d16
+  metadata.gz: e62e25e0fedcbb6509d55d8f539f766d82429bafa3d278dde5fa3ca45420bc2a6cbbc3262b465a6f936ec76fcbb8296f4c7977cb8fdfd4581b818503570be372
+  data.tar.gz: e863e0d3699bb9233f96da31af72e42422cc18c0f1765f2446851f65e76c67a7c16bcd1862b863e048aced999fca335c0a7d1c6dfbbefb3a0981499c74bfa84a

data/lib/graph_ql/{types/input_value.rb → argument.rb}

@@ -1,4 +1,7 @@
-class GraphQL::InputValue
+# Used for defined arguments ({Field}, {InputObjectType})
+#
+# Created by {ArgumentDefiner}
+class GraphQL::Argument
   attr_reader :type, :description, :default_value
   attr_accessor :name
   def initialize(type:, description: nil, default_value: nil, name: nil)

data/lib/graph_ql/definition_helpers.rb

@@ -0,0 +1,10 @@
+module GraphQL
+  module DefinitionHelpers
+  end
+end
+require 'graph_ql/definition_helpers/argument_definer'
+require 'graph_ql/definition_helpers/definable'
+require 'graph_ql/definition_helpers/field_definer'
+require 'graph_ql/definition_helpers/non_null_with_bang'
+require 'graph_ql/definition_helpers/string_named_hash'
+require 'graph_ql/definition_helpers/type_definer'

data/lib/graph_ql/definition_helpers/argument_definer.rb

@@ -1,7 +1,10 @@
-class GraphQL::ArgumentDefiner
+# Some conveniences for definining arguments.
+#
+# Passed into initialization blocks, eg {InputObjectType#initialize}, {Field#initialize}
+class GraphQL::DefinitionHelpers::ArgumentDefiner
   include Singleton
 
   def build(type:, desc: "", default_value: nil)
-    GraphQL::InputValue.new(type: type, description: desc, default_value: default_value)
+    GraphQL::Argument.new(type: type, description: desc, default_value: default_value)
   end
 end

data/lib/graph_ql/definition_helpers/definable.rb

@@ -4,7 +4,7 @@
 # @example defining an object's name
 #   object.name("New name")
 #
-module GraphQL::Definable
+module GraphQL::DefinitionHelpers::Definable
   def attr_definable(*names)
     attr_accessor(*names)
     names.each do |name|

data/lib/graph_ql/definition_helpers/field_definer.rb

@@ -1,4 +1,7 @@
-class GraphQL::FieldDefiner
+# Some conveniences for definining fields on {ObjectType}s and {Interface}s.
+#
+# Passed into initialization blocks, eg {ObjectType#initialize}, {Field#initialize}
+class GraphQL::DefinitionHelpers::FieldDefiner
   include Singleton
 
   def build(type:, args: {}, property: nil, desc: "", deprecation_reason: nil)

data/lib/graph_ql/definition_helpers/non_null_with_bang.rb

@@ -2,7 +2,9 @@
 # @example required Int type
 #   !GraphQL::INT_TYPE
 #
-module GraphQL::NonNullWithBang
+module GraphQL::DefinitionHelpers::NonNullWithBang
+  # Make the type non-null
+  # @return [GraphQL::NonNullType] a non-null type which wraps the original type
   def !
     GraphQL::NonNullType.new(of_type: self)
   end

data/lib/graph_ql/definition_helpers/string_named_hash.rb

@@ -1,8 +1,14 @@
 # Accepts a hash with symbol keys.
 # - convert keys to strings
 # - if the value responds to `name=`, then assign the hash key as `name`
-class GraphQL::StringNamedHash
+#
+# Used by {ObjectType#fields}, {Field#arguments} and others.
+class GraphQL::DefinitionHelpers::StringNamedHash
+  # Normalized hash for the input
+  # @return [Hash] Hash with string keys
   attr_reader :to_h
+
+  # @param input_hash [Hash] Hash to be normalized
   def initialize(input_hash)
     @to_h = input_hash
       .reduce({}) { |memo, (key, value)| memo[key.to_s] = value; memo }

data/lib/graph_ql/definition_helpers/type_definer.rb

@@ -1,4 +1,7 @@
-class GraphQL::TypeDefiner
+# Some conveniences for definining return & argument types.
+#
+# Passed into initialization blocks, eg {ObjectType#initialize}, {Field#initialize}
+class GraphQL::DefinitionHelpers::TypeDefiner
   include Singleton
 
   def Int;      GraphQL::INT_TYPE;      end
@@ -7,6 +10,15 @@ class GraphQL::TypeDefiner
   def Boolean;  GraphQL::BOOLEAN_TYPE;  end
   def ID;       GraphQL::ID_TYPE;       end
 
+  # Make a {ListType} which wraps the input type
+  #
+  # @example making a list type
+  #   list_of_strings = types[types.String]
+  #   list_of_strings.inspect
+  #   # => "[String]"
+  #
+  # @param type [Type] A type to be wrapped in a ListType
+  # @return [GraphQL::ListType] A ListType wrapping `type`
   def [](type)
     GraphQL::ListType.new(of_type: type)
   end

data/lib/graph_ql/directive.rb

@@ -1,5 +1,9 @@
+# This implementation of `Directive` is ... not robust.
+# It seems like this area of the spec is still getting worked out, so
+# {Directive} & {DirectiveChain} implement `@skip` and `@include` with
+# minimal impact on query execution.
 class GraphQL::Directive
-  extend GraphQL::Definable
+  extend GraphQL::DefinitionHelpers::Definable
   attr_definable :on, :arguments, :name, :description
 
   LOCATIONS = [
@@ -15,7 +19,12 @@ class GraphQL::Directive
   def initialize
     @arguments = {}
     @on = []
-    yield(self, GraphQL::TypeDefiner.instance, GraphQL::FieldDefiner.instance, GraphQL::ArgumentDefiner.instance)
+    yield(
+      self,
+      GraphQL::DefinitionHelpers::TypeDefiner.instance,
+      GraphQL::DefinitionHelpers::FieldDefiner.instance,
+      GraphQL::DefinitionHelpers::ArgumentDefiner.instance
+    )
   end
 
   def resolve(proc_or_arguments, proc=nil)
@@ -29,7 +38,7 @@ class GraphQL::Directive
 
   def arguments(new_arguments=nil)
     if !new_arguments.nil?
-      @arguments = GraphQL::StringNamedHash.new(new_arguments).to_h
+      @arguments = GraphQL::DefinitionHelpers::StringNamedHash.new(new_arguments).to_h
     end
     @arguments
   end
@@ -39,6 +48,5 @@ class GraphQL::Directive
   end
 end
 
-require 'graph_ql/directives/directive_chain'
-require 'graph_ql/directives/include_directive'
-require 'graph_ql/directives/skip_directive'
+require 'graph_ql/directive/include_directive'
+require 'graph_ql/directive/skip_directive'

data/lib/graph_ql/{directives → directive}/include_directive.rb

@@ -1,4 +1,4 @@
-GraphQL::IncludeDirective = GraphQL::Directive.new do |d, type, field, arg|
+GraphQL::Directive::IncludeDirective = GraphQL::Directive.new do |d, type, field, arg|
   d.name "include"
   d.description "Include this part of the query if `if` is true"
   d.on([GraphQL::Directive::ON_FIELD, GraphQL::Directive::ON_FRAGMENT])

data/lib/graph_ql/{directives → directive}/skip_directive.rb

@@ -1,4 +1,4 @@
-GraphQL::SkipDirective = GraphQL::Directive.new do |d, type, field, arg|
+GraphQL::Directive::SkipDirective = GraphQL::Directive.new do |d, type, field, arg|
   d.name "skip"
   d.description "Ignore this part of the query if `if` is true"
   d.on([GraphQL::Directive::ON_FIELD, GraphQL::Directive::ON_FRAGMENT])

data/lib/graph_ql/enum_type.rb

@@ -0,0 +1,66 @@
+# A finite set of possible values, represented in query strings with
+# SCREAMING_CASE_NAMES
+#
+# @example An enum of programming languages
+#
+#   LanguageEnum = GraphQL::EnumType.new do |e|
+#     e.name("Languages")
+#     e.descriptions("Programming languages for Web projects")
+#     e.value("PYTHON", "A dynamic, function-oriented language")
+#     e.value("RUBY", "A very dynamic language aimed at programmer happiness")
+#     e.value("JAVASCRIPT", "Accidental lingua franca of the web")
+#   end
+class GraphQL::EnumType
+  include GraphQL::DefinitionHelpers::NonNullWithBang
+  extend GraphQL::DefinitionHelpers::Definable
+  attr_definable :name, :description
+  attr_reader :values
+  def initialize
+    @values = {}
+    yield(
+      self,
+      GraphQL::DefinitionHelpers::TypeDefiner.instance,
+      GraphQL::DefinitionHelpers::FieldDefiner.instance,
+      GraphQL::DefinitionHelpers::ArgumentDefiner.instance
+    )
+  end
+
+  # Define a value within this enum
+  #
+  # @param name [String] the string representation of this value
+  # @param description [String]
+  # @param deprecation_reason [String] if provided, `deprecated?` will be true
+  # @param value [Object] the underlying value for this enum value
+  def value(name, description=nil, deprecation_reason: nil, value: name)
+    @values[name] = EnumValue.new(name: name, description: description, deprecation_reason: deprecation_reason, value: value)
+  end
+
+  def kind
+    GraphQL::TypeKinds::ENUM
+  end
+
+  # Get the underlying value for this enum value
+  #
+  # @example get episode value from Enum
+  #   episode = EpisodeEnum.coerce("NEWHOPE")
+  #   episode # => 6
+  #
+  # @param value_name [String] the string representation of this enum value
+  # @return [Object] the underlying value for this enum value
+  def coerce(value_name)
+    @values[value_name].value
+  end
+
+  # A value within an {EnumType}
+  #
+  # Created with {EnumType#value}
+  class EnumValue
+    attr_reader :name, :description, :deprecation_reason, :value
+    def initialize(name:, description:, deprecation_reason:, value:)
+      @name = name
+      @description = description
+      @deprecation_reason = deprecation_reason
+      @value = value
+    end
+  end
+end

data/lib/graph_ql/field.rb

@@ -1,11 +1,28 @@
+# These are valid values for a type's `fields` hash.
+#
+# You can also use {FieldDefiner#build} to create fields.
+#
+# @example creating a field
+#   name_field = GraphQL::Field.new do |f, types|
+#     f.name("Name")
+#     f.type(!types.String)
+#     f.description("The name of this thing")
+#     f.resolve -> (object, arguments, context) { object.name }
+#   end
+#
 class GraphQL::Field
-  extend GraphQL::Definable
+  extend GraphQL::DefinitionHelpers::Definable
   attr_definable(:arguments, :deprecation_reason, :name, :description, :type)
 
   def initialize
     @arguments = {}
     @resolve_proc = -> (o, a, c) { GraphQL::Query::DEFAULT_RESOLVE }
-    yield(self, GraphQL::TypeDefiner.instance, GraphQL::FieldDefiner.instance, GraphQL::ArgumentDefiner.instance)
+    yield(
+      self,
+      GraphQL::DefinitionHelpers::TypeDefiner.instance,
+      GraphQL::DefinitionHelpers::FieldDefiner.instance,
+      GraphQL::DefinitionHelpers::ArgumentDefiner.instance
+    )
   end
 
   def arguments(new_arguments=nil)
@@ -15,25 +32,44 @@ class GraphQL::Field
     @arguments
   end
 
+  # Define the arguments for this field using {StringNamedHash}
   def arguments=(new_arguments)
-    @arguments = GraphQL::StringNamedHash.new(new_arguments).to_h
+    @arguments = GraphQL::DefinitionHelpers::StringNamedHash.new(new_arguments).to_h
   end
 
-
-  # Used when defining:
-  #   resolve -> (obj, args, ctx) { obj.get_value }
-  # Also used when executing queries:
-  #   field.resolve(obj, args, ctx)
-  def resolve(proc_or_object, arguments=nil, ctx=nil)
-    if arguments.nil? && ctx.nil?
+  # @overload resolve(definition_proc)
+  #   Define this field to return a value with `definition_proc`
+  #   @example defining the resolve method
+  #     field.resolve -> (obj, args, ctx) { obj.get_value }
+  #   @param definition_proc [Proc] The proc to evaluate to get a value
+  #
+  # @overload resolve(object, arguments, context)
+  #   Get a value for this field
+  #   @example resolving a field value
+  #     field.resolve(obj, args, ctx)
+  #
+  #   @param object [Object] The object this field belongs to
+  #   @param arguments [Hash] Arguments declared in the query
+  #   @param context [GraphQL::Query::Context]
+  def resolve(proc_or_object, arguments=nil, context=nil)
+    if arguments.nil? && context.nil?
       @resolve_proc = proc_or_object
     else
-      @resolve_proc.call(proc_or_object, arguments, ctx)
+      @resolve_proc.call(proc_or_object, arguments, context)
     end
   end
 
-  # You can pass a proc which will cause the type to be lazy-evaled,
-  # That's nice if you have load-order issues
+  # @overload type(return_type)
+  #   Define the return type for this field
+  #   @param return_type [GraphQL::ObjectType, GraphQL::ScalarType] The type this field returns
+  #
+  # @overload type(return_type_proc)
+  #   Wrap the return type in a proc,which will cause the type to be lazy-evaled,
+  #
+  #   That's nice if you have load-order issues.
+  #   @example lazy-evaled return type
+  #      field.type(-> { MyCircularDependentType })
+  #   @param return_type_proc [Proc] A proc which returns the return type for this field
   def type(type_or_proc=nil)
     if !type_or_proc.nil?
       @type = type_or_proc

data/lib/graph_ql/input_object_type.rb

@@ -0,0 +1,33 @@
+# A complex input type for a field argument.
+#
+# @example An input type with name and number
+#   PlayerInput = GraphQL::InputObjectType.new do |i, types, fields, args|
+#     i.name("Player")
+#     i.input_fields({
+#       name: args.build(type: !types.String)
+#       number: args.build(type: !types.Int)
+#     })
+#   end
+#
+class GraphQL::InputObjectType < GraphQL::ObjectType
+  attr_definable :input_fields
+
+  # @overload input_fields(new_fields)
+  #   Define allowed fields, normalized with {StringNamedHash}
+  #   @param new_fields [Hash] allowed fields for this input object type
+  #
+  # @overload input_fields()
+  #   Read the defined fields for this input type
+  #   @return [Hash] allowed fields for this input object type
+  #
+  def input_fields(new_fields=nil)
+    if !new_fields.nil?
+      @new_fields = GraphQL::DefinitionHelpers::StringNamedHash.new(new_fields).to_h
+    end
+    @new_fields
+  end
+
+  def kind
+    GraphQL::TypeKinds::INPUT_OBJECT
+  end
+end

data/lib/graph_ql/interface_type.rb

@@ -0,0 +1,33 @@
+# A collection of types which implement the same fields
+#
+# @example An interface with three required fields
+#   DeviceInterface = GraphQL::InterfaceType.new do |i, types, fields|
+#     i.name("Device")
+#     i.description("Hardware devices for computing")
+#     i.fields({
+#       ram:          fields.build(type: types.String),
+#       processor:    fields.build(type: ProcessorType),
+#       release_year: fields.build(type: types.Int),
+#     })
+#   end
+#
+class GraphQL::InterfaceType < GraphQL::ObjectType
+  def kind
+    GraphQL::TypeKinds::INTERFACE
+  end
+
+  # @return [Array<GraphQL::ObjectType>] Types which declare that they implement this interface
+  def possible_types
+    @possible_types ||= []
+  end
+
+  # Return the implementing type for `object`.
+  # The default implementation assumes that there's a type with the same name as `object.class.name`.
+  # Maybe you'll need to override this in your own interfaces!
+  #
+  # @param object [Object] the object which needs a type to expose it
+  # @return [GraphQL::ObjectType] the type which should expose `object`
+  def resolve_type(object)
+    @possible_types.find {|t| t.name == object.class.name }
+  end
+end

data/lib/graph_ql/introspection/field_type.rb

@@ -10,6 +10,7 @@ GraphQL::Introspection::FieldType = GraphQL::ObjectType.new do |t, type, field|
       f.description "Is this field deprecated?"
       f.resolve -> (obj, a, c) { !!obj.deprecation_reason }
     },
+    args:  GraphQL::Introspection::ArgumentsField,
     deprecationReason: field.build(type: type.String, property: :deprecation_reason, desc: "Why this field was deprecated"),
   })
 end

data/lib/graph_ql/introspection/fields_field.rb

@@ -5,6 +5,7 @@ GraphQL::Introspection::FieldsField = GraphQL::Field.new do |f, type, field, arg
     includeDeprecated: arg.build({type: GraphQL::BOOLEAN_TYPE, default_value: false})
   })
   f.resolve -> (object, arguments, context) {
+    return nil if !object.kind.fields?
     fields = object.fields.values
     if !arguments["includeDeprecated"]
       fields = fields.select {|f| !f.deprecation_reason }

data/lib/graph_ql/introspection/input_value_type.rb

@@ -1,5 +1,5 @@
 GraphQL::Introspection::InputValueType = GraphQL::ObjectType.new do |t, type, field|
-  t.name "InputValue"
+  t.name "__InputValue"
   t.description "An input for a field or InputObject"
   t.fields({
     name:         field.build(type: !type.String, desc: "The key for this value"),

data/lib/graph_ql/introspection/introspection_query.rb

@@ -0,0 +1,77 @@
+# The introspection query to end all introspection queries, copied from
+# https://github.com/graphql/graphql-js/blob/master/src/utilities/introspectionQuery.js
+GraphQL::Introspection::INTROSPECTION_QUERY = "
+query IntrospectionQuery {
+  __schema {
+    queryType { name }
+    mutationType { name }
+    types {
+      ...FullType
+    }
+    directives {
+      name
+      description
+      args {
+        ...InputValue
+      }
+      onOperation
+      onFragment
+      onField
+    }
+  }
+}
+fragment FullType on __Type {
+  kind
+  name
+  description
+  fields {
+    name
+    description
+    args {
+      ...InputValue
+    }
+    type {
+      ...TypeRef
+    }
+    isDeprecated
+    deprecationReason
+  }
+  inputFields {
+    ...InputValue
+  }
+  interfaces {
+    ...TypeRef
+  }
+  enumValues {
+    name
+    description
+    isDeprecated
+    deprecationReason
+  }
+  possibleTypes {
+    ...TypeRef
+  }
+}
+fragment InputValue on __InputValue {
+  name
+  description
+  type { ...TypeRef }
+  defaultValue
+}
+fragment TypeRef on __Type {
+  kind
+  name
+  ofType {
+    kind
+    name
+    ofType {
+      kind
+      name
+      ofType {
+        kind
+        name
+      }
+    }
+  }
+}
+"