graphql 2.6.12 → 2.6.13

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
@@ -169,6 +180,7 @@ module GraphQL
                 end
               else
                 raise "Unexpected selection in partial path: #{sel.class}, #{sel.inspect}"
+                sel #: absurd
               end
             end
           end
@@ -176,7 +188,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?

data/lib/graphql/query/result.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Query
-    # A result from {Schema#execute}.
+    # A result from [Schema.execute](rdoc-ref:GraphQL::Schema.execute).
     # It provides the requested data and
-    # access to the {Query} and {Query::Context}.
+    # access to the [Query](rdoc-ref:GraphQL::Query) and [Query::Context](rdoc-ref:GraphQL::Query::Context).
     class Result
       extend Forwardable
 
@@ -13,10 +14,14 @@ module GraphQL
         @to_h = values
       end
 
-      # @return [GraphQL::Query] The query that was executed
+      # **Returns**
+      #
+      # - `GraphQL::Query` — The query that was executed
       attr_reader :query
 
-      # @return [Hash] The resulting hash of "data" and/or "errors"
+      # **Returns**
+      #
+      # - `Hash` — The resulting hash of "data" and/or "errors"
       attr_reader :to_h
 
       def_delegators :@query, :context, :mutation?, :query?, :subscription?
@@ -47,7 +52,12 @@ module GraphQL
       #
       # (The query is ignored for comparing result equality.)
       #
-      # @return [Boolean]
+      # **Returns**
+      #
+      # - `Boolean`
+      #
+      # :call-seq:
+      #   ==(other) -> bool
       def ==(other)
         case other
         when Hash

data/lib/graphql/query/validation_pipeline.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Query
     # Contain the validation pipeline and expose the results.
     #
-    # 0. Checks in {Query#initialize}:
+    # 0. Checks in the [GraphQL::Query](rdoc-ref:GraphQL::Query) constructor:
     #   - Rescue a ParseError, halt if there is one
     #   - Check for selected operation, halt if not found
     # 1. Validate the AST, halt if errors
     # 2. Validate the variables, halt if errors
     # 3. Run query analyzers, halt if errors
     #
-    # {#valid?} is false if any of the above checks halted the pipeline.
+    # [valid?](rdoc-ref:#valid?) is false if any of the above checks halted the pipeline.
     #
-    # @api private
-    class ValidationPipeline
+    class ValidationPipeline # :nodoc:
       attr_reader :max_depth, :max_complexity, :validate_timeout_remaining
 
       def initialize(query:, parse_error:, operation_name_error:, max_depth:, max_complexity:)
@@ -28,13 +28,23 @@ module GraphQL
         @has_validated = false
       end
 
-      # @return [Boolean] does this query have errors that should prevent it from running?
+      # **Returns**
+      #
+      # - `Boolean` — does this query have errors that should prevent it from running?
+      #
+      # :call-seq:
+      #   valid?() -> bool
       def valid?
         ensure_has_validated
         @valid
       end
 
-      # @return [Array<GraphQL::StaticValidation::Error, GraphQL::Query::VariableValidationError>] Static validation errors for the query string
+      # **Returns**
+      #
+      # - `Array<GraphQL::StaticValidation::Error, GraphQL::Query::VariableValidationError>` — Static validation errors for the query string
+      #
+      # :call-seq:
+      #   validation_errors() -> Array[GraphQL::StaticValidation::Error | GraphQL::Query::VariableValidationError]
       def validation_errors
         ensure_has_validated
         @validation_errors

data/lib/graphql/query/variable_validation_error.rb

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

data/lib/graphql/query/variables.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Query
     # Read-only access to query variables, applying default values if needed.
     class Variables
       extend Forwardable
 
-      # @return [Array<GraphQL::Query::VariableValidationError>]  Any errors encountered when parsing the provided variables and literal values
+      # **Returns**
+      #
+      # - `Array<GraphQL::Query::VariableValidationError>` — Any errors encountered when parsing the provided variables and literal values
       attr_reader :errors
 
       attr_reader :context