graphql 2.6.11 → 2.6.13

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
+            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