graphql 0.18.4 → 0.18.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 45a2831bb2cf4c54f83f856f5e614a64b4e2a06e
-  data.tar.gz: ca550cdf4e4e9772f0facd364295754bf2bc1440
+  metadata.gz: 9d69978a50350e058883fa1f9fdfc5c6e5dcc80b
+  data.tar.gz: 97cc2fdfc3778f6b75cf34a2b9d5dcf6354a1a28
 SHA512:
-  metadata.gz: 3b52b0fd7948401ad258096f00611d63d7576d83981bd7efbda85a5d34fb7e3938ec661f357d92ab7d8bcf158a3e56ccc2be60a8402249746a9f14cda3edc601
-  data.tar.gz: 06cab8b10aa6f6d1fd03049e24cdca3f97c014801d16fbc127d6adb6f81b55bad57797c35cfeacf4e0958834cd5e74e9e8925ca304b9e70439028ae31e1f9ba7
+  metadata.gz: c6177a5c17291fc6f95f0f2d8e14f3831ebc9af7f46addd15bc3283a63310151c8fc7fbfc1acc332a181ab808060afb399fd87ce83db6e0088c093adabd8b35b
+  data.tar.gz: b0464b86095e2aafa933d4dc5b6e5491ef2354df6025943967a78d36d63d7f7c2111e6bfaefe3b11abd5d8937c1ba14e160b5fe9d255cc7b5501d56b0f8e92a1

data/lib/graphql.rb

@@ -1,7 +1,6 @@
 require "json"
 require "set"
 require "singleton"
-require "forwardable"
 
 module GraphQL
   class Error < StandardError
@@ -18,7 +17,7 @@ module GraphQL
   end
 
   # Turn a query string into an AST
-  # @param [String] a GraphQL query string
+  # @param query_string [String] a GraphQL query string
   # @return [GraphQL::Language::Nodes::Document]
   def self.parse(query_string)
     parse_with_racc(query_string)

data/lib/graphql/argument.rb

@@ -9,9 +9,9 @@ module GraphQL
   #     argument :favoriteFood, types.String, "Favorite thing to eat", default_value: "pizza"
   #   end
   #
-  # @example defining an input field for an {InputObjectType}
+  # @example defining an argument for an {InputObjectType}
   #   GraphQL::InputObjectType.define do
-  #     input_field :newName, !types.String
+  #     argument :newName, !types.String
   #   end
   #
   class Argument

data/lib/graphql/base_type.rb

@@ -49,6 +49,17 @@ module GraphQL
     end
 
     module HasPossibleTypes
+
+      # If a (deprecated) `resolve_type` function was provided, call that and warn.
+      # Otherwise call `schema.resolve_type` (the proper behavior)
+      def legacy_resolve_type(object, ctx)
+        if @resolve_type_proc
+          resolve_type(object, ctx)
+        else
+          ctx.schema.resolve_type(object, ctx)
+        end
+      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!
@@ -58,6 +69,7 @@ module GraphQL
       # @return [GraphQL::ObjectType] the type which should expose `object`
       def resolve_type(object, ctx)
         ensure_defined
+        warn_resolve_type_deprecated
         instance_exec(object, ctx, &(@resolve_type_proc || DEFAULT_RESOLVE_TYPE))
       end
 
@@ -69,8 +81,13 @@ module GraphQL
       }
 
       def resolve_type=(new_proc)
+        warn_resolve_type_deprecated
         @resolve_type_proc = new_proc || DEFAULT_RESOLVE_TYPE
       end
+
+      def warn_resolve_type_deprecated
+        warn("#{self.name}.resolve_type is deprecated; define Schema.resolve_type instead")
+      end
     end
 
     # Print the human-readable name of this type using the query-string naming pattern

data/lib/graphql/define.rb

@@ -19,7 +19,7 @@ module GraphQL
     #   # After definition, read the key from metadata
     #   PostType.metadata[:resolves_to_class_names] # => [...]
     #
-    # @param [Object] the key to assign in metadata
+    # @param key [Object] the key to assign in metadata
     # @return [#call(defn, value)] an assignment for `.accepts_definitions` which writes `key` to `#metadata`
     def self.assign_metadata_key(key)
       GraphQL::Define::InstanceDefinable::AssignMetadataKey.new(key)

data/lib/graphql/directive.rb

@@ -1,4 +1,10 @@
 module GraphQL
+  # Directives are server-defined hooks for modifying execution.
+  #
+  # Two directives are included out-of-the-box:
+  # - `@skip(if: ...)` Skips the tagged field if the value of `if` is true
+  # - `@include(if: ...)` Includes the tagged field _only_ if `if` is true
+  #
   class Directive
     include GraphQL::Define::InstanceDefinable
     accepts_definitions :locations, :name, :description, :include_proc, argument: GraphQL::Define::AssignArgument

data/lib/graphql/enum_type.rb

@@ -1,9 +1,15 @@
 module GraphQL
-  # A finite set of possible values, represented in query strings with
-  # SCREAMING_CASE_NAMES
+  # Represents a collection of related values.
+  # By convention, enum names are `SCREAMING_CASE_NAMES`,
+  # but other identifiers are supported too.
   #
-  # @example An enum of programming languages
+  # You can use as return types _or_ as inputs.
+  #
+  # By default, enums are passed to `resolve` functions as
+  # the strings that identify them, but you can provide a
+  # custom Ruby value with the `value:` keyword.
   #
+  # @example An enum of programming languages
   #   LanguageEnum = GraphQL::EnumType.define do
   #     name "Languages"
   #     description "Programming languages for Web projects"
@@ -11,6 +17,44 @@ module GraphQL
   #     value("RUBY", "A very dynamic language aimed at programmer happiness")
   #     value("JAVASCRIPT", "Accidental lingua franca of the web")
   #   end
+  #
+  # @example Using an enum as a return type
+  #    field :favoriteLanguage, LanguageEnum, "This person's favorite coding language"
+  #    # ...
+  #    # In a query:
+  #    Schema.execute("{ coder(id: 1) { favoriteLanguage } }")
+  #    # { "data" => { "coder" => { "favoriteLanguage" => "RUBY" } } }
+  #
+  # @example Defining an enum input
+  #    field :coders, types[CoderType] do
+  #      argument :knowing, types[LanguageType]
+  #      resolve -> (obj, args, ctx) {
+  #        Coder.where(language: args[:knowing])
+  #      }
+  #    end
+  #
+  # @example Using an enum as input
+  #   {
+  #     # find coders who know Python and Ruby
+  #     coders(knowing: [PYTHON, RUBY]) {
+  #       name
+  #       hourlyRate
+  #     }
+  #   }
+  #
+  # @example Enum whose values are different in Ruby-land
+  #   GraphQL::EnumType.define do
+  #     # ...
+  #     # use the `value:` keyword:
+  #     value("RUBY", "Lisp? Smalltalk?", value: :rb)
+  #   end
+  #
+  #   # Now, resolve functions will receive `:rb` instead of `"RUBY"`
+  #   field :favoriteLanguage, LanguageEnum
+  #   resolve -> (obj, args, ctx) {
+  #     args[:favoriteLanguage] # => :rb
+  #   }
+  #
   class EnumType < GraphQL::BaseType
     accepts_definitions value: GraphQL::Define::AssignEnumValue
 
@@ -78,7 +122,7 @@ module GraphQL
 
     # A value within an {EnumType}
     #
-    # Created with {EnumType#value}
+    # Created with the `value` helper
     class EnumValue
       attr_accessor :name, :description, :deprecation_reason, :value
       def initialize(name:, description:, deprecation_reason:, value:)

data/lib/graphql/field.rb

@@ -5,40 +5,88 @@ module GraphQL
   #
   # They're usually created with the `field` helper. If you create it by hand, make sure {#name} is a String.
   #
-  # @example creating a field
+  # A field must have a return type, but if you want to defer the return type calculation until later,
+  # you can pass a proc for the return type. That proc will be called when the schema is defined.
+  #
+  # @example Lazy type resolution
+  #   # If the field's type isn't defined yet, you can pass a proc
+  #   field :city, -> { TypeForModelName.find("City") }
+  #
+  # For complex field definition, you can pass a block to the `field` helper, eg `field :name do ... end`.
+  # This block is equivalent to calling `GraphQL::Field.define { ... }`.
+  #
+  # @example Defining a field with a block
+  #   field :city, CityType do
+  #     # field definition continues inside the block
+  #   end
+  #
+  # ## Resolve
+  #
+  # Fields have `resolve` functions to determine their values at query-time.
+  # The default implementation is to call a method on the object based on the field name.
+  #
+  # @example Create a field which calls a method with the same name.
   #   GraphQL::ObjectType.define do
   #     field :name, types.String, "The name of this thing "
   #   end
   #
-  # @example handling a circular reference
-  #   # If the field's type isn't defined yet, you have two options:
+  # You can specify a custom proc with the `resolve` helper.
   #
+  # There are some shortcuts for common `resolve` implementations:
+  #   - Provide `property:` to call a method with a different name than the field name
+  #   - Provide `hash_key:` to resolve the field by doing a key lookup, eg `obj[:my_hash_key]`
+  #
+  # @example Create a field that calls a different method on the object
   #   GraphQL::ObjectType.define do
-  #     # If you pass a Proc, it will be evaluated at schema build-time
-  #     field :city, -> { CityType }
-  #     # If you pass a String, it will be looked up in the global namespace at schema build-time
-  #     field :country, "CountryType"
+  #     # use the `property` keyword:
+  #     field :firstName, types.String, property: :first_name
   #   end
   #
-  # @example creating a field that accesses a different property on the object
+  # @example Create a field looks up with `[hash_key]`
   #   GraphQL::ObjectType.define do
-  #     # use the `property` option:
-  #     field :firstName, types.String, property: :first_name
+  #     # use the `hash_key` keyword:
+  #     field :firstName, types.String, hash_key: :first_name
   #   end
   #
-  # @example defining a field, then attaching it to a type
-  #   name_field = GraphQL::Field.define do
-  #     name("Name")
-  #     type(!types.String)
-  #     description("The name of this thing")
-  #     resolve -> (object, arguments, context) { object.name }
+  # ## Arguments
+  #
+  # Fields can take inputs; they're called arguments. You can define them with the `argument` helper.
+  #
+  # @example Create a field with an argument
+  #   field :students, types[StudentType] do
+  #     argument :grade, types.Int
+  #     resolve -> (obj, args, ctx) {
+  #       Student.where(grade: args[:grade])
+  #     }
   #   end
   #
-  #   NamedType = GraphQL::ObjectType.define do
-  #     # use the `field` option:
-  #     field :name, field: name_field
+  # They can have default values which will be provided to `resolve` if the query doesn't include a value.
+  #
+  # @example Argument with a default value
+  #   field :events, types[EventType] do
+  #     # by default, don't include past events
+  #     argument :includePast, types.Boolean, default_value: false
+  #     resolve -> (obj, args, ctx) {
+  #       args[:includePast] # => false if no value was provided in the query
+  #       # ...
+  #     }
   #   end
   #
+  # Only certain types maybe used for inputs:
+  #
+  # - Scalars
+  # - Enums
+  # - Input Objects
+  # - Lists of those types
+  #
+  # Input types may also be non-null -- in that case, the query will fail
+  # if the input is not present.
+  #
+  # ## Complexity
+  #
+  # Fields can have _complexity_ values which describe the computation cost of resolving the field.
+  # You can provide the complexity as a constant with `complexity:` or as a proc, with the `complexity` helper.
+  #
   # @example Custom complexity values
   #   # Complexity can be a number or a proc.
   #
@@ -57,12 +105,26 @@ module GraphQL
   #     complexity -> (ctx, args, child_complexity) { child_complexity * args[:limit] }
   #   end
   #
+  # @example Creating a field, then assigning it to a type
+  #   name_field = GraphQL::Field.define do
+  #     name("Name")
+  #     type(!types.String)
+  #     description("The name of this thing")
+  #     resolve -> (object, arguments, context) { object.name }
+  #   end
+  #
+  #   NamedType = GraphQL::ObjectType.define do
+  #     # The second argument may be a GraphQL::Field
+  #     field :name, name_field
+  #   end
+  #
   class Field
     include GraphQL::Define::InstanceDefinable
     accepts_definitions :name, :description, :resolve, :type, :property, :deprecation_reason, :complexity, :hash_key, argument: GraphQL::Define::AssignArgument
 
     lazy_defined_attr_accessor :deprecation_reason, :description, :property, :hash_key
 
+    # @return [<#call(obj, args,ctx)>] A proc-like object which can be called to return the field's value
     attr_reader :resolve_proc
 
     # @return [String] The name of this field on its {GraphQL::ObjectType} (or {GraphQL::InterfaceType})

data/lib/graphql/field/resolve.rb

@@ -4,7 +4,7 @@ module GraphQL
     module Resolve
       module_function
 
-      # @param [GraphQL::Field] A field that needs a resolve proc
+      # @param field [GraphQL::Field] A field that needs a resolve proc
       # @return [Proc] A resolver for this field, based on its config
       def create_proc(field)
         if field.property

data/lib/graphql/input_object_type.rb

@@ -1,13 +1,27 @@
 module GraphQL
-  # A complex input type for a field argument.
+  # {InputObjectType}s are key-value inputs for fields.
+  #
+  # Input objects have _arguments_ which are identical to {GraphQL::Field} arguments.
+  # They map names to types and support default values.
+  # Their input types can be any input types, including {InputObjectType}s.
   #
   # @example An input type with name and number
   #   PlayerInput = GraphQL::InputObjectType.define do
   #     name("Player")
-  #     input_field :name, !types.String
-  #     input_field :number, !types.Int
+  #     argument :name, !types.String
+  #     argument :number, !types.Int
   #   end
   #
+  # In a `resolve` function, you can access the values by making nested lookups on `args`.
+  #
+  # @example Accessing input values in a resolve function
+  #   resolve -> (obj, args, ctx) {
+  #     args[:player][:name]    # => "Tony Gwynn"
+  #     args[:player][:number]  # => 19
+  #     args[:player].to_h      # { "name" => "Tony Gwynn", "number" => 19 }
+  #     # ...
+  #   }
+  #
   class InputObjectType < GraphQL::BaseType
     accepts_definitions(
       input_field: GraphQL::Define::AssignArgument,

data/lib/graphql/interface_type.rb

@@ -1,7 +1,12 @@
 module GraphQL
-  # A collection of types which implement the same fields
+  # An Interface contains a collection of types which implement some of the same fields.
   #
-  # @example An interface with three required fields
+  # Interfaces can have fields, defined with `field`, just like an object type.
+  #
+  # Objects which implement this field _inherit_ field definitions from the interface.
+  # An object type can override the inherited definition by redefining that field.
+  #
+  # @example An interface with three fields
   #   DeviceInterface = GraphQL::InterfaceType.define do
   #     name("Device")
   #     description("Hardware devices for computing")
@@ -11,6 +16,11 @@ module GraphQL
   #     field :release_year, types.Int
   #   end
   #
+  # @example Implementing an interface with an object type
+  #   Laptoptype = GraphQL::ObjectType.define do
+  #     interfaces [DeviceInterface]
+  #   end
+  #
   class InterfaceType < GraphQL::BaseType
     include GraphQL::BaseType::HasPossibleTypes
     accepts_definitions :resolve_type, field: GraphQL::Define::AssignObjectField

data/lib/graphql/list_type.rb

@@ -1,7 +1,28 @@
 module GraphQL
-  # A list type wraps another type.
+  # A list type modifies another type.
+  #
+  # List types can be created with the type helper (`types[InnerType]`)
+  # or {BaseType#to_list_type} (`InnerType.to_list_type`)
+  #
+  # For return types, it says that the returned value will be a list of the modified.
+  #
+  # @example A field which returns a list of items
+  #   field :items, types[ItemType]
+  #   # or
+  #   field :items, ItemType.to_list_type
+  #
+  # For input types, it says that the incoming value will be a list of the modified type.
+  #
+  # @example A field which accepts a list of strings
+  #   field :newNames do
+  #     # ...
+  #     argument :values, types[types.String]
+  #     # or
+  #     argument :values, types.String.to_list_type
+  #   end
+  #
+  # Given a list type, you can always get the underlying type with {#unwrap}.
   #
-  # Get the underlying type with {#unwrap}
   class ListType < GraphQL::BaseType
     include GraphQL::BaseType::ModifiesAnotherType
     attr_reader :of_type, :name
@@ -31,12 +52,10 @@ module GraphQL
       result
     end
 
-
     def coerce_non_null_input(value)
       ensure_array(value).map{ |item| of_type.coerce_input(item) }
     end
 
-
     private
 
     def ensure_array(value)

data/lib/graphql/non_null_type.rb

@@ -1,7 +1,32 @@
 module GraphQL
-  # A non-null type wraps another type.
+  # A non-null type modifies another type.
+  #
+  # Non-null types can be created with `!` (`InnerType!`)
+  # or {BaseType#to_non_null_type} (`InnerType.to_non_null_type`)
+  #
+  # For return types, it says that the returned value will _always_ be present.
+  #
+  # @example A field which _always_ returns an error
+  #   field :items, !ItemType
+  #   # or
+  #   field :items, ItemType.to_non_null_type
+  #
+  # (If the application fails to return a value, {InvalidNullError} will be raised.)
+  #
+  # For input types, it says that the incoming value _must_ be provided by the query.
+  #
+  # @example A field which _requires_ a string input
+  #   field :newNames do
+  #     # ...
+  #     argument :values, !types.String
+  #     # or
+  #     argument :values, types.String.to_non_null_type
+  #   end
+  #
+  # (If a value isn't provided, {Query::VariableValidationError} will be raised).
+  #
+  # Given a non-null type, you can always get the underlying type with {#unwrap}.
   #
-  # Get the underlying type with {#unwrap}
   class NonNullType < GraphQL::BaseType
     include GraphQL::BaseType::ModifiesAnotherType