graphql 2.6.9 → 2.6.14

data/lib/graphql/dataloader.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require "graphql/dataloader/null_dataloader"
 require "graphql/dataloader/request"
@@ -8,22 +9,27 @@ require "graphql/dataloader/active_record_association_source"
 require "graphql/dataloader/active_record_source"
 
 module GraphQL
-  # This plugin supports Fiber-based concurrency, along with {GraphQL::Dataloader::Source}.
+  # This plugin supports Fiber-based concurrency, along with [GraphQL::Dataloader::Source](rdoc-ref:GraphQL::Dataloader::Source).
   #
-  # @example Installing Dataloader
+  # **Examples**
   #
-  #   class MySchema < GraphQL::Schema
-  #     use GraphQL::Dataloader
-  #   end
+  # **Example: Installing Dataloader**
   #
-  # @example Waiting for batch-loaded data in a GraphQL field
+  # ```ruby
+  # class MySchema < GraphQL::Schema
+  #   use GraphQL::Dataloader
+  # end
+  # ```
   #
-  #   field :team, Types::Team, null: true
+  # **Example: Waiting for batch-loaded data in a GraphQL field**
   #
-  #   def team
-  #     dataloader.with(Sources::Record, Team).load(object.team_id)
-  #   end
+  # ```ruby
+  # field :team, Types::Team, null: true
   #
+  # def team
+  #   dataloader.with(Sources::Record, Team).load(object.team_id)
+  # end
+  # ```
   class Dataloader
     class << self
       attr_accessor :default_nonblocking, :default_fiber_limit
@@ -49,7 +55,7 @@ module GraphQL
     # then run all enqueued jobs and return the result of the block.
     def self.with_dataloading(&block)
       dataloader = self.new
-      result = nil
+      result = nil #: untyped
       dataloader.append_job {
         result = block.call(dataloader)
       }
@@ -69,7 +75,9 @@ module GraphQL
       @lazies_at_depth = Hash.new { |h, k| h[k] = [] }
     end
 
-    # @return [Integer, nil]
+    # **Returns**
+    #
+    # - `Integer, nil`
     attr_reader :fiber_limit
 
     def nonblocking?
@@ -79,7 +87,12 @@ module GraphQL
     # This is called before the fiber is spawned, from the parent context (i.e. from
     # the thread or fiber that it is scheduled from).
     #
-    # @return [Hash<Symbol, Object>] Current fiber-local variables
+    # **Returns**
+    #
+    # - `Hash<Symbol, Object>` — Current fiber-local variables
+    #
+    # :call-seq:
+    #   get_fiber_variables() -> Hash[Symbol, Object]
     def get_fiber_variables
       fiber_vars = {}
       Thread.current.keys.each do |fiber_var_key|
@@ -92,8 +105,16 @@ module GraphQL
     #
     # This is called within the fiber, right after it is spawned.
     #
-    # @param vars [Hash<Symbol, Object>] Fiber-local variables from {get_fiber_variables}
-    # @return [void]
+    # **Parameters**
+    #
+    # - `vars` (`Hash<Symbol, Object>`) — Fiber-local variables from [get_fiber_variables](rdoc-ref:get_fiber_variables)
+    #
+    # **Returns**
+    #
+    # - `void`
+    #
+    # :call-seq:
+    #   set_fiber_variables(Hash[Symbol, Object] vars) -> void
     def set_fiber_variables(vars)
       vars.each { |k, v| Thread.current[k] = v }
       nil
@@ -106,12 +127,17 @@ module GraphQL
 
     # Get a Source instance from this dataloader, for calling `.load(...)` or `.request(...)` on.
     #
-    # @param source_class [Class<GraphQL::Dataloader::Source]
-    # @param batch_parameters [Array<Object>]
-    # @return [GraphQL::Dataloader::Source] An instance of {source_class}, initialized with `self, *batch_parameters`,
-    #   and cached for the lifetime of this {Multiplex}.
+    # **Parameters**
+    #
+    # - `source_class` (`Class<GraphQL::Dataloader::Source>`) — The source class to load
+    # - `batch_parameters` (`Array<Object>`)
+    #
+    # **Returns**
+    #
+    # - `GraphQL::Dataloader::Source` — An instance of [source_class](rdoc-ref:source_class), initialized with `self, *batch_parameters`, and cached for the lifetime of this [Multiplex](rdoc-ref:Multiplex).
     if (RUBY_ENGINE == "ruby" && RUBY_VERSION < "3") || RUBY_ENGINE == "truffleruby" # truffle-ruby wasn't doing well with the implementation below
-      def with(source_class, *batch_args)
+      # `define_method` so that Sorbet doesn't see this as a conflicting definition of `#with`
+      define_method(:with) do |source_class, *batch_args|
         batch_key = source_class.batch_key_for(*batch_args)
         @source_cache[source_class][batch_key] ||= begin
           source = source_class.new(*batch_args)
@@ -133,7 +159,12 @@ module GraphQL
     #
     # Dataloader will resume the fiber after the requested data has been loaded (by another Fiber).
     #
-    # @return [void]
+    # **Returns**
+    #
+    # - `void`
+    #
+    # :call-seq:
+    #   yield(source:) -> void
     def yield(source = Fiber[:__graphql_current_dataloader_source])
       trace = Fiber[:__graphql_current_multiplex]&.current_trace
       trace&.dataloader_fiber_yield(source)
@@ -142,24 +173,28 @@ module GraphQL
       nil
     end
 
-    # @api private Nothing to see here
-    def append_job(callable = nil, &job)
+    def append_job(callable = nil, &job) # :nodoc:
       # Given a block, queue it up to be worked through when `#run` is called.
       # (If the dataloader is already running, then a Fiber will pick this up later.)
       @pending_jobs.push(callable || job)
       nil
     end
 
-    # @api private
-    def queue_pending_source(source)
+    def queue_pending_source(source) # :nodoc:
       if @pending_source_set.add?(source)
         @pending_sources << source
       end
       nil
     end
 
-    # Clear any already-loaded objects from {Source} caches
-    # @return [void]
+    # Clear any already-loaded objects from [Source](rdoc-ref:Source) caches
+    #
+    # **Returns**
+    #
+    # - `void`
+    #
+    # :call-seq:
+    #   clear_cache() -> void
     def clear_cache
       @source_cache.each do |_source_class, batched_sources|
         batched_sources.each_value(&:clear_cache)
@@ -185,7 +220,7 @@ module GraphQL
       end
 
       @pending_jobs = []
-      res = nil
+      res = nil #: untyped
       # Make sure the block is inside a Fiber, so it can `Fiber.yield`
       append_job {
         res = yield
@@ -195,7 +230,8 @@ module GraphQL
     ensure
       @pending_jobs = prev_queue
       @lazies_at_depth = prev_lazies_at_depth
-      prev_pending_keys.each do |source_instance, pending|
+      prev_pending_keys #: as !nil
+        .each do |source_instance, pending|
         pending.each do |key, value|
           next if source_instance.results.key?(key)
 
@@ -205,7 +241,12 @@ module GraphQL
       end
     end
 
-    # @param trace_query_lazy [nil, Execution::Multiplex]
+    # **Parameters**
+    #
+    # - `trace_query_lazy` (`nil, Execution::Multiplex`)
+    #
+    # :call-seq:
+    #   run(nil | Execution::Multiplex trace_query_lazy:)
     def run(trace_query_lazy: nil)
       trace = Fiber[:__graphql_current_multiplex]&.current_trace
       jobs_fiber_limit, total_fiber_limit = calculate_fiber_limit
@@ -213,7 +254,7 @@ module GraphQL
       next_job_fibers = []
       source_fibers = []
       next_source_fibers = []
-      first_pass = true
+      first_pass = true #: bool
       manager = spawn_fiber do
         trace&.begin_dataloader(self)
         while first_pass || !job_fibers.empty?
@@ -255,26 +296,37 @@ module GraphQL
       f.resume
     end
 
-    # @api private
-    def lazy_at_depth(depth, lazy)
+    def lazy_at_depth(depth, lazy) # :nodoc:
       @lazies_at_depth[depth] << lazy
     end
 
     def spawn_fiber
       fiber_vars = get_fiber_variables
-      Fiber.new(blocking: !@nonblocking) {
+      Fiber.new(blocking: !@nonblocking) do
+        # Fibers inherit the spawning fiber's storage; give each one its own execution state.
+        Fiber[:__graphql_runtime_info] = nil
         set_fiber_variables(fiber_vars)
         yield
+      ensure
         cleanup_fiber
-      }
+      end
     end
 
     # Pre-warm the Dataloader cache with ActiveRecord objects which were loaded elsewhere.
-    # These will be used by {Dataloader::ActiveRecordSource}, {Dataloader::ActiveRecordAssociationSource} and their helper
+    # These will be used by [Dataloader::ActiveRecordSource](rdoc-ref:Dataloader::ActiveRecordSource), [Dataloader::ActiveRecordAssociationSource](rdoc-ref:Dataloader::ActiveRecordAssociationSource) and their helper
     # methods, `dataload_record` and `dataload_association`.
-    # @param records [Array<ActiveRecord::Base>] Already-loaded records to warm the cache with
-    # @param index_by [Symbol] The attribute to use as the cache key. (Should match `find_by:` when using {ActiveRecordSource})
-    # @return [void]
+    #
+    # **Parameters**
+    #
+    # - `records` (`Array<ActiveRecord::Base>`) — Already-loaded records to warm the cache with
+    # - `index_by` (`Symbol`) — The attribute to use as the cache key. (Should match `find_by:` when using [ActiveRecordSource](rdoc-ref:ActiveRecordSource))
+    #
+    # **Returns**
+    #
+    # - `void`
+    #
+    # :call-seq:
+    #   merge_records(Array[ActiveRecord::Base] records, Symbol index_by:) -> void
     def merge_records(records, index_by: :id)
       records_by_class = Hash.new { |h, k| h[k] = {} }
       records.each do |r|
@@ -314,11 +366,11 @@ module GraphQL
       join_queues(job_fibers, next_job_fibers)
 
       while (!source_fibers.empty? || !@pending_sources.empty?)
-        while (f = source_fibers.shift || (((job_fibers.size + source_fibers.size + next_source_fibers.size + next_job_fibers.size) < total_fiber_limit) && spawn_source_fiber(trace)))
-          if f.alive?
-            finished = run_fiber(f)
-            if !finished
-              next_source_fibers << f
+        while (source_f = source_fibers.shift || (((job_fibers.size + source_fibers.size + next_source_fibers.size + next_job_fibers.size) < total_fiber_limit) && spawn_source_fiber(trace)))
+          if source_f.alive?
+            source_finished = run_fiber(source_f)
+            if !source_finished
+              next_source_fibers << source_f
             end
           end
         end
@@ -359,6 +411,7 @@ module GraphQL
           while job = @pending_jobs.shift
             job.call
           end
+        ensure
           trace&.dataloader_fiber_exit
         end
       end
@@ -392,6 +445,7 @@ module GraphQL
             source.run_pending_keys
             trace&.end_dataloader_source(source)
           end
+        ensure
           trace&.dataloader_fiber_exit
         end
       end

data/lib/graphql/date_encoding_error.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   # This error is raised when `Types::ISO8601Date` is asked to return a value
   # that cannot be parsed to a Ruby Date.
   #
-  # @see GraphQL::Types::ISO8601Date which raises this error
+  # See [GraphQL::Types::ISO8601Date](rdoc-ref:GraphQL::Types::ISO8601Date) which raises this error
   class DateEncodingError < GraphQL::RuntimeTypeError
     # The value which couldn't be encoded
     attr_reader :date_value

data/lib/graphql/dig.rb

@@ -1,13 +1,22 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module Dig
     # implemented using the old activesupport #dig instead of the ruby built-in
     # so we can use some of the magic in Schema::InputObject and Interpreter::Arguments
     # to handle stringified/symbolized keys.
     #
-    # @param own_key [String, Symbol] A key to retrieve
-    # @param rest_keys [Array<[String, Symbol>] Retrieves the value object corresponding to the each key objects repeatedly
-    # @return [Object]
+    # **Parameters**
+    #
+    # - `own_key` (`String, Symbol`) — A key to retrieve
+    # - `rest_keys` (`Array<[String, Symbol]>`) — Keys to use for retrieving nested values
+    #
+    # **Returns**
+    #
+    # - `Object`
+    #
+    # :call-seq:
+    #   dig(String | Symbol own_key, Array[[String, Symbol]] *rest_keys) -> Object
     def dig(own_key, *rest_keys)
       val = self[own_key]
       if val.nil? || rest_keys.empty?

data/lib/graphql/duration_encoding_error.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   # This error is raised when `Types::ISO8601Duration` is asked to return a value
   # that cannot be parsed as an ISO8601-formatted duration by ActiveSupport::Duration.
   #
-  # @see GraphQL::Types::ISO8601Duration which raises this error
+  # See [GraphQL::Types::ISO8601Duration](rdoc-ref:GraphQL::Types::ISO8601Duration) which raises this error
   class DurationEncodingError < GraphQL::RuntimeTypeError
     # The value which couldn't be encoded
     attr_reader :duration_value

data/lib/graphql/execution/directive_checks.rb

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module Execution
     # Boolean checks for how an AST node's directives should
     # influence its execution
-    # @api private
-    module DirectiveChecks
+    module DirectiveChecks # :nodoc:
       SKIP = "skip"
       INCLUDE = "include"
 
       module_function
 
-      # @return [Boolean] Should this node be included in the query?
+      # **Returns**
+      #
+      # - `Boolean` — Should this node be included in the query?
+      #
+      # :call-seq:
+      #   include?(directive_ast_nodes, query) -> bool
       def include?(directive_ast_nodes, query)
         directive_ast_nodes.each do |directive_ast_node|
           name = directive_ast_node.name

data/lib/graphql/execution/errors.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   module Execution
@@ -6,10 +7,18 @@ module GraphQL
       # Register this handler, updating the
       # internal handler index to maintain least-to-most specific.
       #
-      # @param error_class [Class<Exception>]
-      # @param error_handlers [Hash]
-      # @param error_handler [Proc]
-      # @return [void]
+      # **Parameters**
+      #
+      # - `error_class` (`Class<Exception>`)
+      # - `error_handlers` (`Hash`)
+      # - `error_handler` (`Proc`)
+      #
+      # **Returns**
+      #
+      # - `void`
+      #
+      # :call-seq:
+      #   register_rescue_from(Class[Exception] error_class, Hash error_handlers, Proc error_handler) -> void
       def self.register_rescue_from(error_class, error_handlers, error_handler)
         subclasses_handlers = {}
         this_level_subclasses = []
@@ -52,10 +61,15 @@ module GraphQL
         nil
       end
 
-      # @return [Proc, nil] The handler for `error_class`, if one was registered on this schema or inherited
+      # **Returns**
+      #
+      # - `Proc, nil` — The handler for `error_class`, if one was registered on this schema or inherited
+      #
+      # :call-seq:
+      #   find_handler_for(schema, error_class) -> Proc | nil
       def self.find_handler_for(schema, error_class)
         handlers = schema.error_handlers[:subclass_handlers]
-        handler = nil
+        handler = nil #: untyped
         while (handlers) do
           _err_class, next_handler = handlers.find { |err_class, handler| error_class <= err_class }
           if next_handler