graphql 2.6.12 → 2.6.14

data/lib/graphql/schema/built_in_types.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     BUILT_IN_TYPES = {

data/lib/graphql/schema/directive/deprecated.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member

data/lib/graphql/schema/directive/feature.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member
@@ -12,27 +13,35 @@ module GraphQL
       #
       # To use it, you have to implement `.enabled?`, for example:
       #
-      # @example Implementing the Feature directive
-      #   # app/graphql/directives/feature.rb
-      #   class Directives::Feature < GraphQL::Schema::Directive::Feature
-      #     def self.enabled?(flag_name, _obj, context)
-      #       # Translate some GraphQL data for Ruby:
-      #       flag_key = flag_name.underscore
-      #       current_user = context[:viewer]
-      #       # Check the feature flag however your app does it:
-      #       MyFeatureFlags.enabled?(current_user, flag_key)
-      #     end
+      # **Examples**
+      #
+      # **Example: Implementing the Feature directive**
+      #
+      # ```ruby
+      # # app/graphql/directives/feature.rb
+      # class Directives::Feature < GraphQL::Schema::Directive::Feature
+      #   def self.enabled?(flag_name, _obj, context)
+      #     # Translate some GraphQL data for Ruby:
+      #     flag_key = flag_name.underscore
+      #     current_user = context[:viewer]
+      #     # Check the feature flag however your app does it:
+      #     MyFeatureFlags.enabled?(current_user, flag_key)
       #   end
+      # end
+      # ```
       #
-      # @example Flagging a part of the query
-      #   viewer {
-      #     # This field only runs if `.enabled?("recommendationEngine", obj, context)`
-      #     # returns true. Otherwise, it's treated as if it didn't exist.
-      #     recommendations @feature(flag: "recommendationEngine") {
-      #       name
-      #       rating
-      #     }
+      # **Example: Flagging a part of the query**
+      #
+      # ```ruby
+      # viewer {
+      #   # This field only runs if `.enabled?("recommendationEngine", obj, context)`
+      #   # returns true. Otherwise, it's treated as if it didn't exist.
+      #   recommendations @feature(flag: "recommendationEngine") {
+      #     name
+      #     rating
       #   }
+      # }
+      # ```
       class Feature < Schema::Directive
         description "Directs the executor to run this only if a certain server-side feature is enabled."
 
@@ -53,10 +62,18 @@ module GraphQL
 
         # Override this method in your app's subclass of this directive.
         #
-        # @param flag_name [String] The client-provided string of a feature to check
-        # @param object [GraphQL::Schema::Objct] The currently-evaluated GraphQL object instance
-        # @param context [GraphQL::Query::Context]
-        # @return [Boolean] If truthy, execution will continue
+        # **Parameters**
+        #
+        # - `flag_name` (`String`) — The client-provided string of a feature to check
+        # - `object` (`GraphQL::Schema::Objct`) — The currently-evaluated GraphQL object instance
+        # - `context` (`GraphQL::Query::Context`)
+        #
+        # **Returns**
+        #
+        # - `Boolean` — If truthy, execution will continue
+        #
+        # :call-seq:
+        #   enabled?(String flag_name, GraphQL::Schema::Objct object, GraphQL::Query::Context context) -> bool
         def self.enabled?(flag_name, object, context)
           raise GraphQL::RequiredImplementationMissingError, "Implement `.enabled?(flag_name, object, context)` to return true or false for the feature flag (#{flag_name.inspect})"
         end

data/lib/graphql/schema/directive/flagged.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member
-      # This is _similar_ to {Directive::Feature}, except it's prescribed by the server, not the client.
+      # This is _similar_ to [Directive::Feature](rdoc-ref:Directive::Feature), except it's prescribed by the server, not the client.
       #
       # In this case, the server hides types and fields _entirely_, unless the current context has certain `:flags` present.
       class Flagged < GraphQL::Schema::Directive
@@ -39,6 +40,10 @@ module GraphQL
 
         repeatable(true)
 
+        #--
+
+        # @requires_ancestor: GraphQL::Schema::Member::HasDirectives
+
         module VisibleByFlag
           def self.included(schema_class)
             schema_class.extend(self)

data/lib/graphql/schema/directive/include.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member

data/lib/graphql/schema/directive/one_of.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member

data/lib/graphql/schema/directive/skip.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member

data/lib/graphql/schema/directive/specified_by.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member

data/lib/graphql/schema/directive/transform.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member
@@ -8,15 +9,23 @@ module GraphQL
       # and if the named transform is whitelisted and applies to the return value,
       # it's applied by calling a method with that name.
       #
-      # @example Installing the directive
-      #   class MySchema < GraphQL::Schema
-      #     directive(GraphQL::Schema::Directive::Transform)
-      #   end
+      # **Examples**
       #
-      # @example Transforming strings
-      #   viewer {
-      #     username @transform(by: "upcase")
-      #   }
+      # **Example: Installing the directive**
+      #
+      # ```ruby
+      # class MySchema < GraphQL::Schema
+      #   directive(GraphQL::Schema::Directive::Transform)
+      # end
+      # ```
+      #
+      # **Example: Transforming strings**
+      #
+      # ```ruby
+      # viewer {
+      #   username @transform(by: "upcase")
+      # }
+      # ```
       class Transform < Schema::Directive
         description "Directs the executor to run named transform on the return value."
 

data/lib/graphql/schema/directive.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
-    # Subclasses of this can influence how {GraphQL::Execution::Interpreter} runs queries.
+    # Subclasses of this can influence how [GraphQL::Execution::Interpreter](rdoc-ref:GraphQL::Execution::Interpreter) runs queries.
     #
-    # - {.include?}: if it returns `false`, the field or fragment will be skipped altogether, as if it were absent
-    # - {.resolve}: Wraps field resolution (so it should call `yield` to continue)
+    # - [.include?](rdoc-ref:.include?): if it returns `false`, the field or fragment will be skipped altogether, as if it were absent
+    # - [.resolve](rdoc-ref:.resolve): Wraps field resolution (so it should call `yield` to continue)
     class Directive < GraphQL::Schema::Member
       extend GraphQL::Schema::Member::HasArguments
       extend GraphQL::Schema::Member::HasArguments::HasDirectiveArguments
@@ -31,7 +32,7 @@ module GraphQL
 
         def locations(*new_locations)
           if !new_locations.empty?
-            is_runtime = false
+            is_runtime = false #: bool
             new_locations.each do |new_loc|
               loc_sym = new_loc.to_sym
               if !LOCATIONS.include?(loc_sym)
@@ -69,7 +70,7 @@ module GraphQL
           static_include?(arguments, context)
         end
 
-        # Determines whether {Execution::Lookahead} considers the field to be selected
+        # Determines whether [Execution::Lookahead](rdoc-ref:Execution::Lookahead) considers the field to be selected
         def static_include?(_arguments, _context)
           true
         end
@@ -113,6 +114,10 @@ module GraphQL
           @repeatable = new_value
         end
 
+        # When this is a Hash, instances with equal, statically coercible arguments reuse the first instance's coerced arguments.
+        # BuildFromDefinition uses this while it builds a schema, then removes it.
+        attr_accessor :coerced_arguments_cache # :nodoc:
+
         private
 
         def inherited(subclass)
@@ -123,14 +128,19 @@ module GraphQL
             @locations = parent_class.locations
             @is_runtime = parent_class.runtime?
             @repeatable = false
+            @coerced_arguments_cache = nil
           end
         end
       end
 
-      # @return [GraphQL::Schema::Field, GraphQL::Schema::Argument, Class, Module]
+      # **Returns**
+      #
+      # - `GraphQL::Schema::Field, GraphQL::Schema::Argument, Class, Module`
       attr_reader :owner
 
-      # @return [GraphQL::Interpreter::Arguments]
+      # **Returns**
+      #
+      # - `GraphQL::Interpreter::Arguments`
       attr_reader :arguments
 
       class InvalidArgumentError < GraphQL::Error
@@ -139,6 +149,14 @@ module GraphQL
       def initialize(owner, **arguments)
         @owner = owner
         assert_valid_owner
+        if (arguments_cache = self.class.coerced_arguments_cache)
+          if !self.class.arguments_statically_coercible?
+            arguments_cache = nil
+          elsif (cached_arguments = arguments_cache[arguments])
+            @arguments = cached_arguments
+            return
+          end
+        end
         # It's be nice if we had the real context here, but we don't. What we _would_ get is:
         # - error handling
         # - lazy resolution
@@ -190,6 +208,9 @@ module GraphQL
         if @arguments.is_a?(GraphQL::ExecutionError)
           raise @arguments
         end
+        if arguments_cache
+          arguments_cache[arguments] = @arguments
+        end
       end
 
       def graphql_name

data/lib/graphql/schema/enum.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
@@ -7,18 +8,22 @@ module GraphQL
     # By default, GraphQL enum values are translated into Ruby strings.
     # You can provide a custom value with the `value:` keyword.
     #
-    # @example
-    #   # equivalent to
-    #   # enum PizzaTopping {
-    #   #   MUSHROOMS
-    #   #   ONIONS
-    #   #   PEPPERS
-    #   # }
-    #   class PizzaTopping < GraphQL::Schema::Enum
-    #     value :MUSHROOMS
-    #     value :ONIONS
-    #     value :PEPPERS
-    #   end
+    # **Examples**
+    #
+    # **Example: # equivalent to**
+    #
+    # ```ruby
+    # # enum PizzaTopping {
+    # #   MUSHROOMS
+    # #   ONIONS
+    # #   PEPPERS
+    # # }
+    # class PizzaTopping < GraphQL::Schema::Enum
+    #   value :MUSHROOMS
+    #   value :ONIONS
+    #   value :PEPPERS
+    # end
+    # ```
     class Enum < GraphQL::Schema::Member
       extend GraphQL::Schema::Member::ValidatesInput
 
@@ -29,7 +34,7 @@ module GraphQL
       #
       # In either case, the field should be modified so that the invalid value isn't returned.
       #
-      # {GraphQL::Schema::Enum} subclasses get their own subclass of this error, so that bug trackers can better show where they came from.
+      # [GraphQL::Schema::Enum](rdoc-ref:GraphQL::Schema::Enum) subclasses get their own subclass of this error, so that bug trackers can better show where they came from.
       class UnresolvedValueError < GraphQL::Error
         def initialize(value:, enum:, context:, authorized:)
           fix_message = if authorized == false
@@ -46,7 +51,7 @@ module GraphQL
         end
       end
 
-      # Raised when a {GraphQL::Schema::Enum} is defined to have no values.
+      # Raised when a [GraphQL::Schema::Enum](rdoc-ref:GraphQL::Schema::Enum) is defined to have no values.
       # This can also happen when all values return false for `.visible?`.
       class MissingValuesError < GraphQL::Error
         def initialize(enum_type)
@@ -57,15 +62,27 @@ module GraphQL
 
       class << self
         # Define a value for this enum
-        # @option kwargs [String, Symbol] :graphql_name the GraphQL value for this, usually `SCREAMING_CASE`
-        # @option kwargs [String] :description, the GraphQL description for this value, present in documentation
-        # @option kwargs [String] :comment, the GraphQL comment for this value, present in documentation
-        # @option kwargs [::Object] :value the translated Ruby value for this object (defaults to `graphql_name`)
-        # @option kwargs [::Object] :value_method, the method name to fetch `graphql_name` (defaults to `graphql_name.downcase`)
-        # @option kwargs [String] :deprecation_reason if this object is deprecated, include a message here
-        # @param value_method [Symbol, false] A method to generate for this value, or `false` to skip generation
-        # @return [void]
-        # @see {Schema::EnumValue} which handles these inputs by default
+        # See [Schema::EnumValue](rdoc-ref:Schema::EnumValue) which handles these inputs by default
+        #
+        # **Options**
+        #
+        # - `kwargs.:graphql_name` (`String, Symbol`) — the GraphQL value for this, usually `SCREAMING_CASE`
+        # - `kwargs.:description,` (`String`) — the GraphQL description for this value, present in documentation
+        # - `kwargs.:comment,` (`String`) — the GraphQL comment for this value, present in documentation
+        # - `kwargs.:value` (`::Object`) — the translated Ruby value for this object (defaults to `graphql_name`)
+        # - `kwargs.:value_method,` (`::Object`) — the method name to fetch `graphql_name` (defaults to `graphql_name.downcase`)
+        # - `kwargs.:deprecation_reason` (`String`) — if this object is deprecated, include a message here
+        #
+        # **Parameters**
+        #
+        # - `value_method` (`Symbol, false`) — A method to generate for this value, or `false` to skip generation
+        #
+        # **Returns**
+        #
+        # - `void`
+        #
+        # :call-seq:
+        #   value(*args, Symbol | false value_method:, **kwargs, &block) -> void
         def value(*args, value_method: nil, **kwargs, &block)
           kwargs[:owner] = self
           value = enum_value_class.new(*args, **kwargs, &block)
@@ -89,13 +106,18 @@ module GraphQL
           value
         end
 
-        # @return [Array<GraphQL::Schema::EnumValue>] Possible values of this enum
+        # **Returns**
+        #
+        # - `Array<GraphQL::Schema::EnumValue>` — Possible values of this enum
+        #
+        # :call-seq:
+        #   enum_values(context:) -> Array[GraphQL::Schema::EnumValue]
         def enum_values(context = GraphQL::Query::NullContext.instance)
           inherited_values = superclass.respond_to?(:enum_values) ? superclass.enum_values(context) : nil
           visible_values = []
           types = Warden.types_from_context(context)
           own_values.each do |key, values_entry|
-            visible_value = nil
+            visible_value = nil #: GraphQL::Schema::EnumValue?
             if values_entry.is_a?(Array)
               values_entry.each do |v|
                 if types.visible_enum_value?(v, context)
@@ -126,7 +148,12 @@ module GraphQL
           visible_values
         end
 
-        # @return [Array<Schema::EnumValue>] An unfiltered list of all definitions
+        # **Returns**
+        #
+        # - `Array<Schema::EnumValue>` — An unfiltered list of all definitions
+        #
+        # :call-seq:
+        #   all_enum_value_definitions() -> Array[Schema::EnumValue]
         def all_enum_value_definitions
           all_defns = if superclass.respond_to?(:all_enum_value_definitions)
             superclass.all_enum_value_definitions
@@ -145,12 +172,22 @@ module GraphQL
           all_defns
         end
 
-        # @return [Hash<String => GraphQL::Schema::EnumValue>] Possible values of this enum, keyed by name.
+        # **Returns**
+        #
+        # - `Hash<String => GraphQL::Schema::EnumValue>` — Possible values of this enum, keyed by name.
+        #
+        # :call-seq:
+        #   values(context:) -> Hash[String, GraphQL::Schema::EnumValue]
         def values(context = GraphQL::Query::NullContext.instance)
           enum_values(context).each_with_object({}) { |val, obj| obj[val.graphql_name] = val }
         end
 
-        # @return [Class] for handling `value(...)` inputs and building `GraphQL::Enum::EnumValue`s out of them
+        # **Returns**
+        #
+        # - `Class` — for handling `value(...)` inputs and building `GraphQL::Enum::EnumValue`s out of them
+        #
+        # :call-seq:
+        #   enum_value_class(new_enum_value_class) -> Class
         def enum_value_class(new_enum_value_class = nil)
           if new_enum_value_class
             @enum_value_class = new_enum_value_class
@@ -191,11 +228,23 @@ module GraphQL
         end
 
         # Called by the runtime when a field returns a value to give back to the client.
-        # This method checks that the incoming {value} matches one of the enum's defined values.
-        # @param value [Object] Any value matching the values for this enum.
-        # @param ctx [GraphQL::Query::Context]
-        # @raise [GraphQL::Schema::Enum::UnresolvedValueError] if {value} doesn't match a configured value or if the matching value isn't authorized.
-        # @return [String] The GraphQL-ready string for {value}
+        # This method checks that the incoming [value](rdoc-ref:value) matches one of the enum's defined values.
+        #
+        # **Parameters**
+        #
+        # - `value` (`Object`) — Any value matching the values for this enum.
+        # - `ctx` (`GraphQL::Query::Context`)
+        #
+        # **Raises**
+        #
+        # - `GraphQL::Schema::Enum::UnresolvedValueError` — if [value](rdoc-ref:value) doesn't match a configured value or if the matching value isn't authorized.
+        #
+        # **Returns**
+        #
+        # - `String` — The GraphQL-ready string for [value](rdoc-ref:value)
+        #
+        # :call-seq:
+        #   coerce_result(Object value, GraphQL::Query::Context ctx) -> String
         def coerce_result(value, ctx)
           types = ctx.types
           all_values = types ? types.enum_values(self) : values.each_value
@@ -203,16 +252,28 @@ module GraphQL
           if enum_value && (was_authed = enum_value.authorized?(ctx))
             enum_value.graphql_name
           else
-            raise self::UnresolvedValueError.new(enum: self, value: value, context: ctx, authorized: was_authed)
+            raise const_get(:UnresolvedValueError).new(enum: self, value: value, context: ctx, authorized: was_authed)
           end
         end
 
         # Called by the runtime with incoming string representations from a query.
         # It will match the string to a configured by name or by Ruby value.
-        # @param value_name [String, Object] A string from a GraphQL query, or a Ruby value matching a `value(..., value: ...)` configuration
-        # @param ctx [GraphQL::Query::Context]
-        # @raise [GraphQL::UnauthorizedEnumValueError] if an {EnumValue} matches but returns false for `.authorized?`. Goes to {Schema.unauthorized_object}.
-        # @return [Object] The Ruby value for the matched {GraphQL::Schema::EnumValue}
+        #
+        # **Parameters**
+        #
+        # - `value_name` (`String, Object`) — A string from a GraphQL query, or a Ruby value matching a `value(..., value: ...)` configuration
+        # - `ctx` (`GraphQL::Query::Context`)
+        #
+        # **Raises**
+        #
+        # - `GraphQL::UnauthorizedEnumValueError` — if an [EnumValue](rdoc-ref:EnumValue) matches but returns false for `.authorized?`. Goes to [Schema.unauthorized_object](rdoc-ref:Schema.unauthorized_object).
+        #
+        # **Returns**
+        #
+        # - `Object` — The Ruby value for the matched [GraphQL::Schema::EnumValue](rdoc-ref:GraphQL::Schema::EnumValue)
+        #
+        # :call-seq:
+        #   coerce_input(String | Object value_name, GraphQL::Query::Context ctx) -> Object
         def coerce_input(value_name, ctx)
           all_values = ctx.types ? ctx.types.enum_values(self) : values.each_value
 

data/lib/graphql/schema/enum_value.rb

@@ -1,24 +1,30 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
-    # A possible value for an {Enum}.
+    # A possible value for an [Enum](rdoc-ref:Enum).
     #
     # You can extend this class to customize enum values in your schema.
     #
-    # @example custom enum value class
-    #   # define a custom class:
-    #   class CustomEnumValue < GraphQL::Schema::EnumValue
-    #     def initialize(*args)
-    #       # arguments to `value(...)` in Enum classes are passed here
-    #       super
-    #     end
-    #   end
+    # **Examples**
+    #
+    # **Example: custom enum value class**
     #
-    #   class BaseEnum < GraphQL::Schema::Enum
-    #     # use it for these enums:
-    #     enum_value_class CustomEnumValue
+    # ```ruby
+    # # define a custom class:
+    # class CustomEnumValue < GraphQL::Schema::EnumValue
+    #   def initialize(*args)
+    #     # arguments to `value(...)` in Enum classes are passed here
+    #     super
     #   end
+    # end
+    #
+    # class BaseEnum < GraphQL::Schema::Enum
+    #   # use it for these enums:
+    #   enum_value_class CustomEnumValue
+    # end
+    # ```
     class EnumValue < GraphQL::Schema::Member
       include GraphQL::Schema::Member::HasPath
       include GraphQL::Schema::Member::HasAstNode
@@ -27,7 +33,9 @@ module GraphQL
 
       attr_reader :graphql_name
 
-      # @return [Class] The enum type that owns this value
+      # **Returns**
+      #
+      # - `Class` — The enum type that owns this value
       attr_reader :owner
 
       def initialize(graphql_name, desc = nil, owner:, ast_node: nil, directives: nil, description: nil, comment: nil, value: NOT_CONFIGURED, deprecation_reason: nil, &block)

data/lib/graphql/schema/field/connection_extension.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
     class Field
       class ConnectionExtension < GraphQL::Schema::FieldExtension
+        extras [:lookahead]
+
         def apply
           field.argument :after, "String", "Returns the elements in the list that come after the specified cursor.", required: false
           field.argument :before, "String", "Returns the elements in the list that come before the specified cursor.", required: false
@@ -18,13 +21,18 @@ module GraphQL
           next_args.delete(:last)
           next_args.delete(:before)
           next_args.delete(:after)
-          yield(object || objects, next_args, arguments)
+          # Keep the extension's extras (`:lookahead`) out of `connection.arguments`
+          original_arguments = added_extras ? arguments.reject { |k, _v| added_extras.include?(k) } : arguments
+          yield(object || objects, next_args, original_arguments)
         end
 
         def after_resolve(value:, object:, arguments:, context:, memo:)
           original_arguments = memo
+          lookahead = arguments[:lookahead]
           context.query.after_lazy(value) do |resolved_value|
-            context.schema.connections.populate_connection(field, object.object, resolved_value, original_arguments, context)
+            connection = context.schema.connections.populate_connection(field, object.object, resolved_value, original_arguments, context)
+            connection.lookahead ||= lookahead if connection.is_a?(GraphQL::Pagination::Connection)
+            connection
           end
         end
       end

data/lib/graphql/schema/field/scope_extension.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema