graphql 2.6.12 → 2.6.14

data/lib/graphql/pagination/relation_connection.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 require "graphql/pagination/connection"
 require "monitor"
 
@@ -6,6 +7,10 @@ module GraphQL
   module Pagination
     # A generic class for working with database query objects.
     class RelationConnection < Pagination::Connection
+      # Database limits and offsets must fit in a signed 64-bit integer.
+      MAX_OFFSET = (2**63) - 1
+      private_constant :MAX_OFFSET
+
       def nodes
         load_nodes
         @nodes
@@ -29,6 +34,12 @@ module GraphQL
       end
 
       def has_next_page
+        # If the query loads the page anyway, load it now so its extra row answers this
+        if @has_next_page.nil? && peek_next_page? &&
+            (lookahead.selects?(:nodes) || lookahead.selects?(:edges) ||
+              page_info_selection.selects?(:start_cursor) || page_info_selection.selects?(:end_cursor))
+          load_nodes
+        end
         if @has_next_page.nil?
           @has_next_page = if before_offset && before_offset > 0
             true
@@ -47,49 +58,112 @@ module GraphQL
 
       def cursor_for(item)
         load_nodes
-        # index in nodes + existing offset + 1 (because it's offset, not index)
-        offset = nodes.index(item) + 1 + (@paged_nodes_offset || 0) - (relation_offset(items) || 0)
-        encode(offset.to_s)
+        position = cursor_index_for(item, nodes)
+        offset_cursor_for_position(position)
+      end
+
+      def cursor_for_position(item, position) # :nodoc:
+        if self.class.custom_cursor_for?(RelationConnection)
+          super
+        else
+          offset_cursor_for_position(position)
+        end
       end
 
       private
 
-      # @param relation [Object] A database query object
-      # @param _initial_offset [Integer] The number of items already excluded from the relation
-      # @param size [Integer] The value against which we check the relation size
-      # @return [Boolean] True if the number of items in this relation is larger than `size`
+      def offset_cursor_for_position(position)
+        # position in nodes + existing offset + 1 (because it's offset, not index)
+        offset = position + 1 + (@paged_nodes_offset || 0) - (relation_offset(items) || 0)
+        encode(offset.to_s)
+      end
+
+      # **Parameters**
+      #
+      # - `relation` (`Object`) — A database query object
+      # - `_initial_offset` (`Integer`) — The number of items already excluded from the relation
+      # - `size` (`Integer`) — The value against which we check the relation size
+      #
+      # **Returns**
+      #
+      # - `Boolean` — True if the number of items in this relation is larger than `size`
+      #
+      # :call-seq:
+      #   relation_larger_than(Object relation, Integer _initial_offset, Integer size) -> bool
       def relation_larger_than(relation, _initial_offset, size)
-        relation_count(set_limit(relation, size + 1)) == size + 1
+        if (limit = relation_limit(relation)) && limit <= size
+          false
+        else
+          relation_count(set_limit(relation, size + 1)) == size + 1
+        end
       end
 
-      # @param relation [Object] A database query object
-      # @return [Integer, nil] The offset value, or nil if there isn't one
+      # **Parameters**
+      #
+      # - `relation` (`Object`) — A database query object
+      #
+      # **Returns**
+      #
+      # - `Integer, nil` — The offset value, or nil if there isn't one
+      #
+      # :call-seq:
+      #   relation_offset(Object relation) -> Integer | nil
       def relation_offset(relation)
         raise "#{self.class}#relation_offset(relation) must return the offset value for a #{relation.class} (#{relation.inspect})"
       end
 
-      # @param relation [Object] A database query object
-      # @return [Integer, nil] The limit value, or nil if there isn't one
+      # **Parameters**
+      #
+      # - `relation` (`Object`) — A database query object
+      #
+      # **Returns**
+      #
+      # - `Integer, nil` — The limit value, or nil if there isn't one
+      #
+      # :call-seq:
+      #   relation_limit(Object relation) -> Integer | nil
       def relation_limit(relation)
         raise "#{self.class}#relation_limit(relation) must return the limit value for a #{relation.class} (#{relation.inspect})"
       end
 
-      # @param relation [Object] A database query object
-      # @return [Integer, nil] The number of items in this relation (hopefully determined without loading all records into memory!)
+      # **Parameters**
+      #
+      # - `relation` (`Object`) — A database query object
+      #
+      # **Returns**
+      #
+      # - `Integer, nil` — The number of items in this relation (hopefully determined without loading all records into memory!)
+      #
+      # :call-seq:
+      #   relation_count(Object relation) -> Integer | nil
       def relation_count(relation)
         raise "#{self.class}#relation_count(relation) must return the count of records for a #{relation.class} (#{relation.inspect})"
       end
 
-      # @param relation [Object] A database query object
-      # @return [Object] A modified query object which will return no records
+      # **Parameters**
+      #
+      # - `relation` (`Object`) — A database query object
+      #
+      # **Returns**
+      #
+      # - `Object` — A modified query object which will return no records
+      #
+      # :call-seq:
+      #   null_relation(Object relation) -> Object
       def null_relation(relation)
         raise "#{self.class}#null_relation(relation) must return an empty relation for a #{relation.class} (#{relation.inspect})"
       end
 
-      # @return [Integer]
+      # **Returns**
+      #
+      # - `Integer`
+      #
+      # :call-seq:
+      #   offset_from_cursor(cursor) -> Integer
       def offset_from_cursor(cursor)
-        offset = Integer(decode(cursor), 10, exception: false)
-        if offset.nil? || offset <= 0
+        offset = Integer(decode(cursor), 10, exception: false) #: Integer?
+        if offset.nil? || offset <= 0 || offset > MAX_OFFSET ||
+            offset + (relation_offset(items) || 0) > MAX_OFFSET
           raise GraphQL::ExecutionError, "Invalid cursor: #{cursor.inspect}"
         end
         offset
@@ -126,20 +200,21 @@ module GraphQL
 
           if after_offset
             next_offset += after_offset
+            relation_limit = [relation_limit - after_offset, 0].max if relation_limit
           end
 
           if before_offset && after_offset
             if after_offset < before_offset
               # Get the number of items between the two cursors
               space_between = before_offset - after_offset - 1
-              relation_limit = space_between
+              relation_limit = [relation_limit, space_between].compact.min
             else
               # The cursors overextend one another to an empty set
               @sliced_nodes_null_relation = true
             end
           elsif before_offset
             # Use limit to cut off the tail of the relation
-            relation_limit = before_offset - 1
+            relation_limit = [relation_limit, before_offset - 1].compact.min
           end
 
           @sliced_nodes_limit = relation_limit
@@ -157,25 +232,35 @@ module GraphQL
           if @sliced_nodes_null_relation
             paginated_nodes = null_relation(paginated_nodes)
           else
-            if @sliced_nodes_limit
-              paginated_nodes = set_limit(paginated_nodes, @sliced_nodes_limit)
-            end
-
             if @sliced_nodes_offset
               paginated_nodes = set_offset(paginated_nodes, @sliced_nodes_offset)
             end
+
+            if @sliced_nodes_limit
+              paginated_nodes = set_limit(paginated_nodes, @sliced_nodes_limit)
+            end
           end
 
           paginated_nodes
         end
       end
 
-      # @return [Integer, nil]
+      # **Returns**
+      #
+      # - `Integer, nil`
+      #
+      # :call-seq:
+      #   before_offset() -> Integer | nil
       def before_offset
         @before_offset ||= before && offset_from_cursor(before)
       end
 
-      # @return [Integer, nil]
+      # **Returns**
+      #
+      # - `Integer, nil`
+      #
+      # :call-seq:
+      #   after_offset() -> Integer | nil
       def after_offset
         @after_offset ||= after && offset_from_cursor(after)
       end
@@ -246,12 +331,35 @@ module GraphQL
           # `AsyncDataloader` may resolve sibling fields (eg, `edges` and `pageInfo`)
           # in separate Fibers, so several callers can get here before `@nodes` is set.
           (@load_monitor ||= Monitor.new).synchronize do
-            @nodes ||= limited_nodes.to_a
+            # Not `||=`: Sorbet assumes `@nodes` is still falsy in this block
+            @nodes = load_page unless @nodes
           end
         else
-          @nodes = limited_nodes.to_a
+          @nodes = load_page
         end
       end
+
+      # Fetch one row past `first` so `has_next_page` needs no extra query.
+      # Skips arrays (no query to save) and slices limited to `first` or fewer rows (no next page).
+      def load_page
+        page = limited_nodes
+        return page.to_a if page.is_a?(Array) || !peek_next_page? || relation_limit(page) != first ||
+          (@sliced_nodes_limit && @sliced_nodes_limit <= first)
+
+        rows = set_limit(page, first + 1).to_a
+        @has_next_page = rows.size > first
+        rows.first(first)
+      end
+
+      # Peek on forward pages that select `hasNextPage`; `last` and `before` keep the separate check
+      def peek_next_page?
+        return @peek_next_page if defined?(@peek_next_page)
+        @peek_next_page = first&.positive? && last.nil? && before.nil? && page_info_selection.selects?(:has_next_page)
+      end
+
+      def page_info_selection
+        @page_info_selection ||= (lookahead || GraphQL::Execution::Lookahead::NULL_LOOKAHEAD).selection(:page_info)
+      end
     end
   end
 end

data/lib/graphql/pagination/sequel_dataset_connection.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 require "graphql/pagination/relation_connection"
 
 module GraphQL

data/lib/graphql/pagination.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 require "graphql/pagination/array_connection"
 require "graphql/pagination/active_record_relation_connection"
 require "graphql/pagination/connections"

data/lib/graphql/parse_error.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class ParseError < GraphQL::Error
     attr_reader :line, :col, :query

data/lib/graphql/query/context/scoped_context.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Query
     class Context
@@ -13,7 +14,7 @@ module GraphQL
           if @scoped_contexts.nil?
             GraphQL::EmptyObjects::EMPTY_HASH
           else
-            merged_ctx = {}
+            merged_ctx = {} #: untyped
             each_present_path_ctx do |path_ctx|
               merged_ctx = path_ctx.merge(merged_ctx)
             end

data/lib/graphql/query/context.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Query
@@ -31,18 +32,30 @@ module GraphQL
       extend Forwardable
       include Schema::Member::HasDataloader
 
-      # @return [Array<GraphQL::ExecutionError>] errors returned during execution
+      # **Returns**
+      #
+      # - `Array<GraphQL::ExecutionError>` — errors returned during execution
       attr_reader :errors
 
-      # @return [GraphQL::Query] The query whose context this is
+      # **Returns**
+      #
+      # - `GraphQL::Query` — The query whose context this is
       attr_reader :query
 
-      # @return [GraphQL::Schema]
+      # **Returns**
+      #
+      # - `GraphQL::Schema`
       attr_reader :schema
 
       # Make a new context which delegates key lookup to `values`
-      # @param query [GraphQL::Query] the query who owns this context
-      # @param values [Hash] A hash of arbitrary values which will be accessible at query-time
+      #
+      # **Parameters**
+      #
+      # - `query` (`GraphQL::Query`) — the query who owns this context
+      # - `values` (`Hash`) — A hash of arbitrary values which will be accessible at query-time
+      #
+      # :call-seq:
+      #   initialize(GraphQL::Query query:, schema:, Hash values:)
       def initialize(query:, schema: query.schema, values:)
         @query = query
         @schema = schema
@@ -55,7 +68,13 @@ module GraphQL
       end
 
       # Modify this hash to return extensions to client.
-      # @return [Hash] A hash that will be added verbatim to the result hash, as `"extensions" => { ... }`
+      #
+      # **Returns**
+      #
+      # - `Hash` — A hash that will be added verbatim to the result hash, as `"extensions" => { ... }`
+      #
+      # :call-seq:
+      #   response_extensions() -> Hash
       def response_extensions
         namespace(:__query_result_extensions__)
       end
@@ -64,14 +83,11 @@ module GraphQL
         @dataloader ||= self[:dataloader] || (query.multiplex ? query.multiplex.dataloader : schema.dataloader_class.new)
       end
 
-      # @api private
-      attr_writer :interpreter
+      attr_writer :interpreter # :nodoc:
 
-      # @api private
-      attr_writer :value
+      attr_writer :value # :nodoc:
 
-      # @api private
-      attr_reader :scoped_context
+      attr_reader :scoped_context # :nodoc:
 
       def []=(key, value)
         @provided_values[key] = value
@@ -86,10 +102,9 @@ module GraphQL
       attr_writer :types
 
       RUNTIME_METADATA_KEYS = Set.new([:current_object, :current_arguments, :current_field, :current_path]).freeze
-      # @!method []=(key, value)
-      #   Reassign `key` to the hash passed to {Schema#execute} as `context:`
+      # **Method:** `[]=(key, value)` — Reassign `key` to the hash passed to [Schema#execute](rdoc-ref:Schema#execute) as `context:`
 
-      # Lookup `key` from the hash passed to {Schema#execute} as `context:`
+      # Lookup `key` from the hash passed to [Schema.execute](rdoc-ref:GraphQL::Schema.execute) as `context:`
       def [](key)
         if @scoped_context.key?(key)
           @scoped_context[key]
@@ -116,8 +131,17 @@ module GraphQL
       end
 
       # Add error at query-level.
-      # @param error [GraphQL::ExecutionError] an execution error
-      # @return [void]
+      #
+      # **Parameters**
+      #
+      # - `error` (`GraphQL::ExecutionError`) — an execution error
+      #
+      # **Returns**
+      #
+      # - `void`
+      #
+      # :call-seq:
+      #   add_error(GraphQL::ExecutionError error) -> void
       def add_error(error)
         if !error.is_a?(GraphQL::RuntimeError)
           raise TypeError, "expected error to be a GraphQL::RuntimeError, but was #{error.class}"
@@ -126,16 +150,34 @@ module GraphQL
         nil
       end
 
-      # @param value [Object] Any object to be inserted directly into the final response
-      # @return [GraphQL::Execution::Interpreter::RawValue] Return this from the field
+      # **Parameters**
+      #
+      # - `value` (`Object`) — Any object to be inserted directly into the final response
+      #
+      # **Returns**
+      #
+      # - `GraphQL::Execution::Interpreter::RawValue` — Return this from the field
+      #
+      # :call-seq:
+      #   raw_value(Object value) -> GraphQL::Execution::Interpreter::RawValue
       def raw_value(value)
         GraphQL::Execution::Interpreter::RawValue.new(value)
       end
 
-      # @example Print the GraphQL backtrace during field resolution
-      #   puts ctx.backtrace
+      # **Examples**
       #
-      # @return [GraphQL::Backtrace] The backtrace for this point in query execution
+      # **Example: Print the GraphQL backtrace during field resolution**
+      #
+      # ```ruby
+      # puts ctx.backtrace
+      # ```
+      #
+      # **Returns**
+      #
+      # - `GraphQL::Backtrace` — The backtrace for this point in query execution
+      #
+      # :call-seq:
+      #   backtrace() -> GraphQL::Backtrace
       def backtrace
         GraphQL::Backtrace.new(self)
       end
@@ -217,17 +259,30 @@ module GraphQL
         @scoped_context.key?(key) || @provided_values.key?(key)
       end
 
-      # @return [GraphQL::Schema::Warden]
+      # **Returns**
+      #
+      # - `GraphQL::Schema::Warden`
+      #
+      # :call-seq:
+      #   warden() -> GraphQL::Schema::Warden
       def warden
         @warden ||= (@query && @query.warden)
       end
 
-      # @api private
-      attr_writer :warden
+      attr_writer :warden # :nodoc:
 
       # Get an isolated hash for `ns`. Doesn't affect user-provided storage.
-      # @param ns [Object] a usage-specific namespace identifier
-      # @return [Hash] namespaced storage
+      #
+      # **Parameters**
+      #
+      # - `ns` (`Object`) — a usage-specific namespace identifier
+      #
+      # **Returns**
+      #
+      # - `Hash` — namespaced storage
+      #
+      # :call-seq:
+      #   namespace(Object ns) -> Hash
       def namespace(ns)
         if ns == :interpreter
           self
@@ -236,7 +291,12 @@ module GraphQL
         end
       end
 
-      # @return [Boolean] true if this namespace was accessed before
+      # **Returns**
+      #
+      # - `Boolean` — true if this namespace was accessed before
+      #
+      # :call-seq:
+      #   namespace?(ns) -> bool
       def namespace?(ns)
         @storage.key?(ns)
       end
@@ -261,13 +321,24 @@ module GraphQL
       # Use this when you need to do a scoped set _inside_ a lazy-loaded (or batch-loaded)
       # block of code.
       #
-      # @example using scoped context inside a promise
-      #   scoped_ctx = context.scoped
-      #   SomeBatchLoader.load(...).then do |thing|
-      #     # use a scoped_ctx which was created _before_ dataloading:
-      #     scoped_ctx.set!(:thing, thing)
-      #   end
-      # @return [Context::Scoped]
+      # **Examples**
+      #
+      # **Example: using scoped context inside a promise**
+      #
+      # ```ruby
+      # scoped_ctx = context.scoped
+      # SomeBatchLoader.load(...).then do |thing|
+      #   # use a scoped_ctx which was created _before_ dataloading:
+      #   scoped_ctx.set!(:thing, thing)
+      # end
+      # ```
+      #
+      # **Returns**
+      #
+      # - `Context::Scoped`
+      #
+      # :call-seq:
+      #   scoped() -> Context::Scoped
       def scoped
         Scoped.new(@scoped_context, current_path)
       end

data/lib/graphql/query/fingerprint.rb

@@ -1,17 +1,25 @@
 # frozen_string_literal: true
+# typed: true
 
 require 'digest/sha2'
 
 module GraphQL
   class Query
-    # @api private
-    # @see Query#query_fingerprint
-    # @see Query#variables_fingerprint
-    # @see Query#fingerprint
-    module Fingerprint
+    # The resulting hashes are exposed by `Query#operation_fingerprint`,
+    # `Query#variables_fingerprint`, and `Query#fingerprint`.
+    module Fingerprint # :nodoc:
       # Make an obfuscated hash of the given string (either a query string or variables JSON)
-      # @param string [String]
-      # @return [String] A normalized, opaque hash
+      #
+      # **Parameters**
+      #
+      # - `string` (`String`)
+      #
+      # **Returns**
+      #
+      # - `String` — A normalized, opaque hash
+      #
+      # :call-seq:
+      #   generate(input_str) -> String
       def self.generate(input_str)
         # Implemented to be:
         # - Short (and uniform) length

data/lib/graphql/query/input_validation_result.rb

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

data/lib/graphql/query/null_context.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 require "graphql/query/context"
 module GraphQL
   class Query

data/lib/graphql/query/partial.rb

@@ -1,24 +1,30 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Query
-    # This class is _like_ a {GraphQL::Query}, except it can run on an arbitrary path within a query string.
+    # This class is _like_ a [GraphQL::Query](rdoc-ref:GraphQL::Query), except it can run on an arbitrary path within a query string.
     #
-    # It depends on a "parent" {Query}.
+    # It depends on a "parent" [Query](rdoc-ref:Query).
     #
     # During execution, it calls query-related tracing hooks but passes itself as `query:`.
     #
-    # The {Partial} will use your {Schema.resolve_type} hook to find the right GraphQL type to use for
+    # The [Partial](rdoc-ref:Partial) will use your [Schema.resolve_type](rdoc-ref:Schema.resolve_type) hook to find the right GraphQL type to use for
     # `object` in some cases.
     #
-    # @see Query#run_partials Run via {Query#run_partials}
+    # Run via [Query#run_partials](rdoc-ref:Query#run_partials).
     class Partial
       include Query::Runnable
 
-      # @param path [Array<String, Integer>] A path in `query.query_string` to start executing from
-      # @param object [Object] A starting object for execution
-      # @param query [GraphQL::Query] A full query instance that this partial is based on. Caches are shared.
-      # @param context [Hash] Extra context values to merge into `query.context`, if provided
-      # @param fragment_node [GraphQL::Language::Nodes::InlineFragment, GraphQL::Language::Nodes::FragmentDefinition]
+      # **Parameters**
+      #
+      # - `path` (`Array<String, Integer>`) — A path in `query.query_string` to start executing from
+      # - `object` (`Object`) — A starting object for execution
+      # - `query` (`GraphQL::Query`) — A full query instance that this partial is based on. Caches are shared.
+      # - `context` (`Hash`) — Extra context values to merge into `query.context`, if provided
+      # - `fragment_node` (`GraphQL::Language::Nodes::InlineFragment, GraphQL::Language::Nodes::FragmentDefinition`)
+      #
+      # :call-seq:
+      #   initialize(Array[String | Integer] path:, Object object:, GraphQL::Query query:, Hash context:, GraphQL::Language::Nodes::InlineFragment | GraphQL::Language::Nodes::FragmentDefinition fragment_node:, type:)
       def initialize(path: nil, object:, query:, context: nil, fragment_node: nil, type: nil)
         @path = path
         @object = object
@@ -65,7 +71,12 @@ module GraphQL
           @query.path
         end
 
-        # @return [GraphQL::Query::Partial]
+        # **Returns**
+        #
+        # - `GraphQL::Query::Partial`
+        #
+        # :call-seq:
+        #   partial() -> GraphQL::Query::Partial
         def partial
           @query
         end
@@ -138,9 +149,9 @@ module GraphQL
       private
 
       def set_type_info_from_path
-        selections = [@query.selected_operation]
+        selections = [@query.selected_operation] #: Array[GraphQL::Language::Nodes::OperationDefinition | GraphQL::Language::Nodes::Field]
         type = @query.root_type
-        field_defn = nil
+        field_defn = nil #: GraphQL::Schema::Field?
 
         @path.each do |name_in_doc|
           if name_in_doc.is_a?(Integer)
@@ -152,9 +163,9 @@ module GraphQL
             end
           end
 
-          next_selections = []
+          next_selections = [] #: Array[GraphQL::Language::Nodes::Field]
           selections.each do |selection|
-            selections_to_check = []
+            selections_to_check = [] #: Array[GraphQL::Language::Nodes::Field | GraphQL::Language::Nodes::InlineFragment | GraphQL::Language::Nodes::FragmentSpread]
             selections_to_check.concat(selection.selections)
             while (sel = selections_to_check.shift)
               case sel
@@ -168,7 +179,7 @@ module GraphQL
                   next_selections << sel
                 end
               else
-                raise "Unexpected selection in partial path: #{sel.class}, #{sel.inspect}"
+                raise "Unexpected selection in partial path: #{sel.class}, #{sel.inspect}" #: absurd(sel)
               end
             end
           end
@@ -176,7 +187,8 @@ module GraphQL
           if next_selections.empty?
             raise ArgumentError, "Path `#{@path.inspect}` is not present in this query. `#{name_in_doc.inspect}` was not found. Try a different path or rewrite the query to include it."
           end
-          field_name = next_selections.first.name
+          first_selection = next_selections.first #: as !nil
+          field_name = first_selection.name
           field_defn = @schema.get_field(type, field_name, @query.context) || raise("Invariant: no field called #{field_name} on #{type.graphql_name}")
           type = field_defn.type
           if type.non_null?