graphql 2.6.11 → 2.6.13

data/lib/graphql/subscriptions/action_cable_subscriptions.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Subscriptions
     # A subscriptions implementation that sends data
@@ -7,87 +8,100 @@ module GraphQL
     # Some things to keep in mind:
     #
     # - No queueing system; ActiveJob should be added
-    # - Take care to reload context when re-delivering the subscription. (see {Query#subscription_update?})
+    # - Take care to reload context when re-delivering the subscription. (see [Query#subscription_update?](rdoc-ref:Query#subscription_update?))
     # - Avoid the async ActionCable adapter and use the redis or PostgreSQL adapters instead. Otherwise calling #trigger won't work from background jobs or the Rails console.
     #
-    # @example Adding ActionCableSubscriptions to your schema
-    #   class MySchema < GraphQL::Schema
-    #     # ...
-    #     use GraphQL::Subscriptions::ActionCableSubscriptions
-    #   end
+    # See [GraphQL::Testing::MockActionCable](rdoc-ref:GraphQL::Testing::MockActionCable) for test helpers
     #
-    # @example Implementing a channel for GraphQL Subscriptions
-    #   class GraphqlChannel < ApplicationCable::Channel
-    #     def subscribed
-    #       @subscription_ids = []
-    #     end
+    # **Examples**
     #
-    #     def execute(data)
-    #       query = data["query"]
-    #       variables = ensure_hash(data["variables"])
-    #       operation_name = data["operationName"]
-    #       context = {
-    #         # Re-implement whatever context methods you need
-    #         # in this channel or ApplicationCable::Channel
-    #         # current_user: current_user,
-    #         # Make sure the channel is in the context
-    #         channel: self,
-    #       }
+    # **Example: Adding ActionCableSubscriptions to your schema**
     #
-    #       result = MySchema.execute(
-    #         query,
-    #         context: context,
-    #         variables: variables,
-    #         operation_name: operation_name
-    #       )
+    # ```ruby
+    # class MySchema < GraphQL::Schema
+    #   # ...
+    #   use GraphQL::Subscriptions::ActionCableSubscriptions
+    # end
+    # ```
     #
-    #       payload = {
-    #         result: result.to_h,
-    #         more: result.subscription?,
-    #       }
+    # **Example: Implementing a channel for GraphQL Subscriptions**
     #
-    #       # Track the subscription here so we can remove it
-    #       # on unsubscribe.
-    #       if result.context[:subscription_id]
-    #         @subscription_ids << result.context[:subscription_id]
-    #       end
+    # ```ruby
+    # class GraphqlChannel < ApplicationCable::Channel
+    #   def subscribed
+    #     @subscription_ids = []
+    #   end
     #
-    #       transmit(payload)
-    #     end
+    #   def execute(data)
+    #     query = data["query"]
+    #     variables = ensure_hash(data["variables"])
+    #     operation_name = data["operationName"]
+    #     context = {
+    #       # Re-implement whatever context methods you need
+    #       # in this channel or ApplicationCable::Channel
+    #       # current_user: current_user,
+    #       # Make sure the channel is in the context
+    #       channel: self,
+    #     }
+    #
+    #     result = MySchema.execute(
+    #       query,
+    #       context: context,
+    #       variables: variables,
+    #       operation_name: operation_name
+    #     )
     #
-    #     def unsubscribed
-    #       @subscription_ids.each { |sid|
-    #         MySchema.subscriptions.delete_subscription(sid)
-    #       }
+    #     payload = {
+    #       result: result.to_h,
+    #       more: result.subscription?,
+    #     }
+    #
+    #     # Track the subscription here so we can remove it
+    #     # on unsubscribe.
+    #     if result.context[:subscription_id]
+    #       @subscription_ids << result.context[:subscription_id]
     #     end
     #
-    #     private
+    #     transmit(payload)
+    #   end
     #
-    #       def ensure_hash(ambiguous_param)
-    #         case ambiguous_param
-    #         when String
-    #           if ambiguous_param.present?
-    #             ensure_hash(JSON.parse(ambiguous_param))
-    #           else
-    #             {}
-    #           end
-    #         when Hash, ActionController::Parameters
-    #           ambiguous_param
-    #         when nil
-    #           {}
+    #   def unsubscribed
+    #     @subscription_ids.each { |sid|
+    #       MySchema.subscriptions.delete_subscription(sid)
+    #     }
+    #   end
+    #
+    #   private
+    #
+    #     def ensure_hash(ambiguous_param)
+    #       case ambiguous_param
+    #       when String
+    #         if ambiguous_param.present?
+    #           ensure_hash(JSON.parse(ambiguous_param))
     #         else
-    #           raise ArgumentError, "Unexpected parameter: #{ambiguous_param}"
+    #           {}
     #         end
+    #       when Hash, ActionController::Parameters
+    #         ambiguous_param
+    #       when nil
+    #         {}
+    #       else
+    #         raise ArgumentError, "Unexpected parameter: #{ambiguous_param}"
     #       end
-    #   end
-    #
-    # @see GraphQL::Testing::MockActionCable for test helpers
+    #     end
+    # end
+    # ```
     class ActionCableSubscriptions < GraphQL::Subscriptions
       SUBSCRIPTION_PREFIX = "graphql-subscription:"
       EVENT_PREFIX = "graphql-event:"
 
-      # @param serializer [<#dump(obj), #load(string)] Used for serializing messages before handing them to `.broadcast(msg)`
-      # @param namespace [string] Used to namespace events and subscriptions (default: '')
+      # **Parameters**
+      #
+      # - `serializer` (`<#dump(obj), #load(string)>`) — Used for serializing messages before handing them to `.broadcast(msg)`
+      # - `namespace` (`string`) — Used to namespace events and subscriptions (default: '')
+      #
+      # :call-seq:
+      #   initialize(#dump(obj), #load(string) serializer:, string namespace:, action_cable:, action_cable_coder:, **rest)
       def initialize(serializer: Serialize, namespace: '', action_cable: ActionCable, action_cable_coder: ActiveSupport::JSON, **rest)
         # A per-process map of subscriptions to deliver.
         # This is provided by Rails, so let's use it
@@ -170,7 +184,7 @@ module GraphQL
         event_stream = stream_event_name(initial_event)
         channel.stream_from(event_stream, coder: @action_cable_coder) do |message|
           events_by_fingerprint = @events[topic]
-          object = nil
+          object = nil #: untyped
           events_by_fingerprint.each do |_fingerprint, events|
             if !events.empty? && events.first == initial_event
               # The fingerprint has told us that this response should be shared by all subscribers,
@@ -194,8 +208,14 @@ module GraphQL
 
       # This is called to turn an ActionCable-broadcasted string (JSON)
       # into a query-ready application object.
-      # @param message [String] n ActionCable-broadcasted string (JSON)
-      # @param context [GraphQL::Query::Context] the context of the first event for a given subscription fingerprint
+      #
+      # **Parameters**
+      #
+      # - `message` (`String`) — n ActionCable-broadcasted string (JSON)
+      # - `context` (`GraphQL::Query::Context`) — the context of the first event for a given subscription fingerprint
+      #
+      # :call-seq:
+      #   load_action_cable_message(String message, GraphQL::Query::Context context)
       def load_action_cable_message(message, context)
         if @serialize_with_context
           @serializer.load(message, context)

data/lib/graphql/subscriptions/broadcast_analyzer.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Subscriptions
@@ -7,9 +8,8 @@ module GraphQL
     # - Is completely broadcastable
     #
     # Assign the result to `context.namespace(:subscriptions)[:subscription_broadcastable]`
-    # @api private
-    # @see Subscriptions#broadcastable? for a public API
-    class BroadcastAnalyzer < GraphQL::Analysis::Analyzer
+    # See [Subscriptions#broadcastable?](rdoc-ref:Subscriptions#broadcastable?) for a public API
+    class BroadcastAnalyzer < GraphQL::Analysis::Analyzer # :nodoc:
       def initialize(subject)
         super
         @default_broadcastable = subject.schema.subscriptions.default_broadcastable
@@ -45,7 +45,13 @@ module GraphQL
 
       # Assign the result to context.
       # (This method is allowed to return an error, but we don't need to)
-      # @return [void]
+      #
+      # **Returns**
+      #
+      # - `void`
+      #
+      # :call-seq:
+      #   result() -> void
       def result
         query.context.namespace(:subscriptions)[:subscription_broadcastable] = @subscription_broadcastable
         nil

data/lib/graphql/subscriptions/default_subscription_resolve_extension.rb

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

data/lib/graphql/subscriptions/event.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Subscriptions
     # This thing can be:
@@ -6,16 +7,24 @@ module GraphQL
     # - Triggered by `MySchema.subscriber.trigger(name, arguments, obj)`
     #
     class Event
-      # @return [String] Corresponds to the Subscription root field name
+      # **Returns**
+      #
+      # - `String` — Corresponds to the Subscription root field name
       attr_reader :name
 
-      # @return [GraphQL::Execution::Interpreter::Arguments]
+      # **Returns**
+      #
+      # - `GraphQL::Execution::Interpreter::Arguments`
       attr_reader :arguments
 
-      # @return [GraphQL::Query::Context]
+      # **Returns**
+      #
+      # - `GraphQL::Query::Context`
       attr_reader :context
 
-      # @return [String] An opaque string which identifies this event, derived from `name` and `arguments`
+      # **Returns**
+      #
+      # - `String` — An opaque string which identifies this event, derived from `name` and `arguments`
       attr_reader :topic
 
       def initialize(name:, arguments:, field: nil, context: nil, scope: nil)
@@ -36,7 +45,12 @@ module GraphQL
         @topic = self.class.serialize(name, arguments, field, scope: scope_val, context: context)
       end
 
-      # @return [String] an identifier for this unit of subscription
+      # **Returns**
+      #
+      # - `String` — an identifier for this unit of subscription
+      #
+      # :call-seq:
+      #   serialize(_name, arguments, field, scope:, context:) -> String
       def self.serialize(_name, arguments, field, scope:, context: GraphQL::Query::NullContext.instance)
         subscription = field.resolver || GraphQL::Schema::Subscription
         arguments = arguments_without_field_extras(field: field, arguments: arguments)
@@ -44,7 +58,12 @@ module GraphQL
         subscription.topic_for(arguments: normalized_args, field: field, scope: scope)
       end
 
-      # @return [String] a logical identifier for this event. (Stable when the query is broadcastable.)
+      # **Returns**
+      #
+      # - `String` — a logical identifier for this event. (Stable when the query is broadcastable.)
+      #
+      # :call-seq:
+      #   fingerprint() -> String
       def fingerprint
         @fingerprint ||= begin
           # When this query has been flagged as broadcastable,

data/lib/graphql/subscriptions/serialize.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
+# typed: true
 require "date"
 require "set"
 module GraphQL
   class Subscriptions
     # Serialization helpers for passing subscription data around.
-    # @api private
-    module Serialize
+    module Serialize # :nodoc:
       GLOBALID_KEY = "__gid__"
       SYMBOL_KEY = "__sym__"
       SYMBOL_KEYS_KEY = "__sym_keys__"
@@ -16,26 +16,49 @@ module GraphQL
       HASH_KEY = "__graphql_hash__"
       RESERVED_KEYS = [GLOBALID_KEY, SYMBOL_KEY, SYMBOL_KEYS_KEY, TIMESTAMP_KEY, OPEN_STRUCT_KEY, HASH_KEY].freeze
 
-      module_function
-
-      # @param str [String] A serialized object from {.dump}
-      # @return [Object] An object equivalent to the one passed to {.dump}
-      def load(str)
+      # **Parameters**
+      #
+      # - `str` (`String`) — A serialized object from [.dump](rdoc-ref:.dump)
+      #
+      # **Returns**
+      #
+      # - `Object` — An object equivalent to the one passed to [.dump](rdoc-ref:.dump)
+      #
+      # :call-seq:
+      #   load(String str) -> Object
+      def self.load(str)
         parsed_obj = JSON.parse(str)
         load_value(parsed_obj)
       end
 
-      # @param obj [Object] Some subscription-related data to dump
-      # @return [String] The stringified object
-      def dump(obj)
+      # **Parameters**
+      #
+      # - `obj` (`Object`) — Some subscription-related data to dump
+      #
+      # **Returns**
+      #
+      # - `String` — The stringified object
+      #
+      # :call-seq:
+      #   dump(Object obj) -> String
+      def self.dump(obj)
         JSON.generate(dump_value(obj))
       end
 
       # This is for turning objects into subscription scopes.
       # It's a one-way transformation, can't reload this :'(
-      # @param obj [Object]
-      # @return [String]
-      def dump_recursive(obj)
+      #
+      # **Parameters**
+      #
+      # - `obj` (`Object`)
+      #
+      # **Returns**
+      #
+      # - `String`
+      #
+      # :call-seq:
+      #   dump_recursive(Object obj) -> String
+      def self.dump_recursive(obj)
         case
         when obj.is_a?(Array)
           obj.map { |i| dump_recursive(i) }.join(':')
@@ -55,8 +78,16 @@ module GraphQL
       class << self
         private
 
-        # @param value [Object] A parsed JSON object
-        # @return [Object] An object that load Global::Identification recursive
+        # **Parameters**
+        #
+        # - `value` (`Object`) — A parsed JSON object
+        #
+        # **Returns**
+        #
+        # - `Object` — An object that load Global::Identification recursive
+        #
+        # :call-seq:
+        #   load_value(Object value) -> Object
         def load_value(value)
           if value.is_a?(Array)
             is_gids = !value.empty? && value.all? { |v| v.is_a?(Hash) && v.size == 1 && v[GLOBALID_KEY] }
@@ -126,8 +157,16 @@ module GraphQL
           end
         end
 
-        # @param obj [Object] Some subscription-related data to dump
-        # @return [Object] The object that converted Global::Identification
+        # **Parameters**
+        #
+        # - `obj` (`Object`) — Some subscription-related data to dump
+        #
+        # **Returns**
+        #
+        # - `Object` — The object that converted Global::Identification
+        #
+        # :call-seq:
+        #   dump_value(Object obj) -> Object
         def dump_value(obj)
           if obj.is_a?(Array)
             obj.map{|item| dump_value(item)}
@@ -138,8 +177,8 @@ module GraphQL
                 HASH_KEY => obj.map { |k, v| [dump_value(k.is_a?(Symbol) ? k : k.to_s), dump_value(v)] },
               }
             end
-            symbol_keys = nil
-            symbol_key_values = nil
+            symbol_keys = nil #: Set[String]?
+            symbol_key_values = nil #: Hash[String, untyped]?
             dumped_h = {}
             obj.each do |k, v|
               dumped_v = dump_value(v)