lighthouse-graphql 0.2.0 → 0.3.0

data/lib/lighthouse/broadcasting.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+# What @broadcast does once a mutation has resolved: trigger the subscription
+# field on the schema's subscriptions backend (`schema.subscriptions.trigger`),
+# inline or, when queued, in a Lighthouse::GraphQL::BroadcastJob. Also checks,
+# when the schema is built, that every @broadcast names a Subscription field.
+module Lighthouse::GraphQL::Broadcasting
+  module_function
+
+  # Broadcast `root` to the subscribers of the field `name`.
+  def broadcast(schema, name, root, context, should_queue: nil)
+    return unless backend?(schema, name)
+
+    klass = subscription_class(schema, name)
+    return unless triggerable?(schema, name, klass)
+
+    arguments = klass.respond_to?(:trigger_arguments) ? klass.trigger_arguments(root, context) : {}
+    scope = klass.respond_to?(:trigger_scope) ? klass.trigger_scope(root, context) : nil
+
+    if should_queue.nil? ? Lighthouse::Config.queue_broadcasts : should_queue
+      enqueue(schema, name, arguments, root, scope)
+    else
+      trigger(schema, name, arguments, root, scope)
+    end
+  end
+
+  # Can a trigger of `klass` reach anybody? graphql-ruby delivers to the
+  # subscribers whose arguments equal the trigger's. A class with exact-argument
+  # topics (a plain GraphQL::Schema::Subscription, or topic_by :arguments) that
+  # leaves `trigger_arguments` at the default `{}`, on a field with a required
+  # argument, therefore never reaches a single subscriber: each of them passed
+  # that argument. That is certain, so it is reported through Config.on_error
+  # (raised in a test environment, logged otherwise) and nothing is triggered.
+  # Arguments that are all optional are not reported: argument-less subscribers
+  # do match `{}`, which can be exactly what the class wants.
+  def triggerable?(schema, name, klass)
+    field = subscription_field(schema, name)
+    required = field ? required_arguments(field) : []
+    return true if required.empty? || trigger_arguments_defined?(klass)
+
+    Lighthouse::Config.handle_error(
+      Lighthouse::DefinitionError.new(
+        "@broadcast(subscription: #{name.inspect}) can reach nobody: #{klass} matches subscribers by exact arguments, " \
+        "but #{field.owner.graphql_name}.#{field.name} requires #{required.map { |arg| arg.graphql_name.inspect }.join(', ')} " \
+        'and the class defines no `self.trigger_arguments(root, context)` saying what to trigger with. ' \
+        "Define it, e.g. `def self.trigger_arguments(root, _context) = { #{required.first.graphql_name.underscore}: root.id.to_s }`, " \
+        'or include Lighthouse::GraphQL::Subscription for one topic per field, filtered by `filter?`.'
+      )
+    )
+    false
+  end
+
+  # Does a trigger of `klass` need its own trigger_arguments to match anyone?
+  # Not for the field-wide topic of a class including Lighthouse::GraphQL::Subscription.
+  def trigger_arguments_defined?(klass)
+    return true if klass < Lighthouse::GraphQL::Subscription && klass.topic_by == :field
+
+    klass.respond_to?(:trigger_arguments) && klass.method(:trigger_arguments).owner != Lighthouse::GraphQL::Subscription::ClassMethods
+  end
+
+  def required_arguments(field)
+    field.arguments.values.select { |arg| arg.type.non_null? && !arg.default_value? }
+  end
+
+  # Trigger the subscription now. Misuse (arguments the field does not take, a
+  # missing scope) goes through Config.on_error.
+  def trigger(schema, name, arguments, root, scope = nil)
+    schema.subscriptions.trigger(name, arguments, root, scope: scope)
+  rescue ::GraphQL::Subscriptions::InvalidTriggerError, ::GraphQL::Subscriptions::SubscriptionScopeMissingError => e
+    Lighthouse::Config.handle_error(e)
+  end
+
+  def enqueue(schema, name, arguments, root, scope)
+    if schema.name.nil?
+      raise Lighthouse::DefinitionError,
+            'A queued @broadcast reaches its schema by name, but this schema is anonymous: assign it to a constant ' \
+            '(AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema).'
+    end
+
+    job = broadcast_job
+    queue = Lighthouse::Config.broadcast_queue
+    (queue ? job.set(queue: queue) : job).perform_later(schema.name, name, arguments, root, scope)
+  end
+
+  def broadcast_job
+    Lighthouse::GraphQL::BroadcastJob
+  rescue LoadError
+    raise Lighthouse::DefinitionError, 'Queueing @broadcast needs ActiveJob: add the activejob gem, or set shouldQueue: false.'
+  end
+
+  # Is there a backend to trigger? Reported through Config.on_error when not.
+  def backend?(schema, name)
+    return true if schema.subscriptions
+
+    Lighthouse::Config.handle_error(
+      Lighthouse::DefinitionError.new(
+        "@broadcast(subscription: #{name.inspect}) has nowhere to broadcast: #{schema.name || 'the schema'} has no subscriptions backend. " \
+        'Install one, e.g. `use GraphQL::Subscriptions::ActionCableSubscriptions`, or pass ' \
+        '`options: { using: { GraphQL::Subscriptions::ActionCableSubscriptions => {} } }` to get_schema.'
+      )
+    )
+    false
+  end
+
+  # The Subscription field called `name` (as written in the SDL or in
+  # snake_case), or nil.
+  def subscription_field(schema, name)
+    fields = schema.subscription&.fields || {}
+    fields[name.to_s] || fields[name.to_s.camelize(:lower)]
+  end
+
+  # The class the field stands for (see SubscriptionDirectiveResolver).
+  def subscription_class(schema, name)
+    subscription_field(schema, name)&.resolver || Lighthouse::GraphQL::Subscription::Default
+  end
+
+  # Every @broadcast in the schema must name a field of its Subscription type.
+  def validate!(schema)
+    schema.types.each_value do |type|
+      next unless type.kind.object?
+
+      type.fields.each_value do |field_def|
+        broadcasts(field_def).each do |directive|
+          name = Lighthouse::Support::DirectiveArgs.literal(directive, 'subscription')
+          next if subscription_field(schema, name)
+
+          raise Lighthouse::DefinitionError, unknown_subscription(schema, type, field_def, name)
+        end
+      end
+    end
+  end
+
+  def broadcasts(field_def)
+    (field_def.ast_node&.directives || []).select { |directive| directive.name == 'broadcast' }
+  end
+
+  def unknown_subscription(schema, type, field_def, name)
+    where = "@broadcast on #{type.graphql_name}.#{field_def.name}"
+    return "#{where}: the schema has no Subscription type, so there is no subscription #{name.inspect}." unless schema.subscription
+
+    "#{where}: #{schema.subscription.graphql_name} has no field #{name.inspect}."
+  end
+end

data/lib/lighthouse/cache_control.rb

@@ -18,8 +18,11 @@
 # read the result with CacheControl.header(result) and set it on the
 # response (see `apply`).
 module Lighthouse::GraphQL::CacheControl
-  DEFINITION = 'directive @cacheControl(maxAge: Int! = 0, scope: CacheControlScope! = PUBLIC, ' \
-               'inheritMaxAge: Boolean! = false) on FIELD_DEFINITION | OBJECT | INTERFACE | UNION'
+  # Arguments with a default are nullable, not `Type! = default` as in PHP: graphql-ruby
+  # 2.5 does not fill in a directive argument's default, so a non-null one would be
+  # refused wherever it is left out. Left out or null, it takes its default.
+  DEFINITION = 'directive @cacheControl(maxAge: Int = 0, scope: CacheControlScope = PUBLIC, ' \
+               'inheritMaxAge: Boolean = false) on FIELD_DEFINITION | OBJECT | INTERFACE | UNION'
 
   TYPE_DEFINITIONS = {
     'CacheControlScope' => <<~GRAPHQL.chomp

data/lib/lighthouse/config.rb

@@ -17,7 +17,9 @@ module Lighthouse
       queries: ['Queries'],
       mutations: ['Mutations'],
       builders: ['Builders'],
-      validators: ['Validators']
+      validators: ['Validators'],
+      events: ['Events'],
+      subscriptions: ['Subscriptions']
     }.freeze
 
     # Every setting reset! forgets, so the next read falls back to its default.
@@ -25,19 +27,23 @@ module Lighthouse
       sdl_folder resolver_namespaces namespaces cache_store transactional_mutations pagination_default_count pagination_max_count
       schema_cache schema_cache_path watch_sdl persisted_queries persisted_queries_store persisted_queries_ttl
       persisted_queries_manifest persisted_queries_only on_error directive_map authenticated_user policy_user authorizer
+      feature_checker feature_actor
+      convert_empty_strings_to_null
+      soft_deletes
+      queue_broadcasts broadcast_queue
     ].freeze
 
     class << self
       attr_writer :sdl_folder, :resolver_namespaces, :on_error, :authenticated_user, :policy_user, :authorizer, :cache_store,
-                  :transactional_mutations, :schema_cache, :watch_sdl, :persisted_queries, :persisted_queries_store, :persisted_queries_only
+                  :transactional_mutations, :schema_cache, :watch_sdl, :persisted_queries, :persisted_queries_store, :persisted_queries_only,
+                  :queue_broadcasts,
+                  :convert_empty_strings_to_null, :feature_checker, :feature_actor
 
       def sdl_folder
         @sdl_folder ||= (defined?(Rails) && Rails.respond_to?(:root) ? Rails.root.join('graphql').to_s : nil)
       end
 
-      def directive_map
-        @directive_map ||= {}
-      end
+      def directive_map = @directive_map ||= {}
 
       # Namespaces tried (in order) when resolving a class name from a directive
       # argument, e.g. `@field(resolver: "ContactPerson")` or `@all(model: "X")`.
@@ -67,6 +73,15 @@ module Lighthouse
           end
       end
 
+      # --- Subscriptions (used by @broadcast) ----------------------------------
+      #
+      # queue_broadcasts  perform @broadcast triggers in a Lighthouse::GraphQL::BroadcastJob
+      #                   (ActiveJob) instead of inline; a directive's shouldQueue overrides it
+      # broadcast_queue   the job's queue name; nil: ActiveJob's default
+      attr_accessor :broadcast_queue
+
+      def queue_broadcasts = @queue_broadcasts || false
+
       # --- Scale options: all off by default ----------------------------------
       #
       # schema_cache          cache the built schema document in tmp/cache (SchemaCache)
@@ -84,6 +99,10 @@ module Lighthouse
       def persisted_queries = @persisted_queries || false
       def persisted_queries_only = @persisted_queries_only || false
 
+      # Make every field behave as if it carried @convertEmptyStringsToNull. Read
+      # when the schema is built, so set it in an initializer.
+      def convert_empty_strings_to_null = @convert_empty_strings_to_null || false
+
       def persisted_queries_store
         @persisted_queries_store || cache_store
       end
@@ -102,7 +121,7 @@ module Lighthouse
       # re-raising in test (so failures surface) and logging otherwise. Override
       # via `Lighthouse.configure { |c| c.on_error = ->(e, ctx) { ... } }`.
       def on_error
-        @on_error ||= default_on_error
+        @on_error ||= Defaults.on_error
       end
 
       def handle_error(error, context = nil)
@@ -131,9 +150,28 @@ module Lighthouse
       # `record` may be a model class (@canModel). `args` carries the @can*
       # `args:` values and, with `injectArgs: true`, the field's arguments first.
       # Defaults to Pundit: `Pundit.policy!(user, record).<ability>?(*args)`.
-      def authorizer
-        @authorizer ||= default_authorizer
-      end
+      def authorizer = @authorizer ||= Defaults.authorizer
+
+      # --- Feature flags (used by @feature) ------------------------------------
+
+      # Is a feature on? `->(name, actor, ctx) { true/false }`, with the feature's
+      # name as written in the SDL. Defaults to Flipper: `Flipper.enabled?(name.to_sym, actor)`.
+      def feature_checker = @feature_checker ||= Lighthouse::GraphQL::FeatureDirective.default_checker
+
+      # The actor features are checked for: `->(ctx) { actor }` (a Flipper actor
+      # answers `flipper_id`; nil checks the feature globally). Defaults to the
+      # authenticated user.
+      def feature_actor = @feature_actor ||= ->(ctx) { authenticated_user.call(ctx) }
+
+      # --- Soft deletes (used by @softDeletes, @trashed, @restore, @forceDelete) ---
+
+      # Teaches Lighthouse what "trashed" means. Any object answering
+      # `soft_deletes?(model)`, `only_trashed(relation)`, `with_trashed(relation)`,
+      # `without_trashed(relation)`, `restore(record)` and `force_delete(record)`.
+      # Defaults to detecting paranoia, then discard, then a `deleted_at` column
+      # per model (Support::SoftDeletes::Auto); `Support::SoftDeletes::Column.new(:archived_at)`
+      # is one for another column.
+      attr_accessor :soft_deletes
 
       def configure
         yield(self) if block_given?
@@ -146,10 +184,13 @@ module Lighthouse
       def reset!
         SETTINGS.each { |setting| instance_variable_set("@#{setting}", nil) }
       end
+    end
 
-      private
+    # The callables the authorizer and on_error settings fall back to.
+    module Defaults
+      module_function
 
-      def default_authorizer
+      def authorizer
         lambda do |user, record, ability, args = []|
           raise 'Lighthouse: configure `Config.authorizer` to use the @can* directives (Pundit not detected).' unless defined?(::Pundit)
 
@@ -158,7 +199,7 @@ module Lighthouse
         end
       end
 
-      def default_on_error
+      def on_error
         lambda do |error, _context|
           if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.test?
             raise error

data/lib/lighthouse/controller.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
+require 'json'
+
+# A Rails controller concern that serves a Lighthouse schema: include it, name
+# the schema, route to `execute`.
+#
+#   class GraphqlController < ApplicationController
+#     include Lighthouse::GraphQL::Controller
+#
+#     lighthouse_schema AppSchema   # or 'AppSchema', or { AppSchema }, resolved per request
+#
+#     private
+#
+#     def graphql_context = { current_user: current_user }
+#   end
+#
+# `execute` dispatches StartRequest, reads the variables (a JSON String, a Hash
+# or parameters), runs the operation through PersistedQueries.execute (or
+# PersistedQueries.multiplex for a batch, a JSON array body), sets the
+# Cache-Control header the selected fields' @cacheControl hints allow, renders
+# the JSON and dispatches EndRequest. In development an error renders as JSON.
+#
+# Hooks, private so they are not actions: `graphql_context` (default:
+# `{ current_user: current_user }` when the controller has a current_user, else
+# `{}`), `graphql_schema` and `graphql_variables(param)`. A controller with an
+# action of its own wraps it in `lighthouse_request { ... }` to get the request
+# events; a nested call dispatches them once.
+module Lighthouse::GraphQL::Controller
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :lighthouse_schema_source, instance_writer: false
+  end
+
+  class_methods do
+    # The schema `execute` runs: a schema class, its name (a String, constantized
+    # per request so code reloading works) or a block (evaluated in the
+    # controller, per request).
+    def lighthouse_schema(schema = nil, &block)
+      self.lighthouse_schema_source = schema || block
+    end
+  end
+
+  def execute
+    lighthouse_request do
+      batch = params[:_json]
+      if batch.is_a?(Array)
+        render json: lighthouse_batch(batch)
+      else
+        result = lighthouse_operation
+        Lighthouse::GraphQL::CacheControl.apply(response, result)
+        render json: result
+      end
+    end
+  rescue StandardError => e
+    raise e unless defined?(::Rails) && ::Rails.env.development?
+
+    lighthouse_development_error(e)
+  end
+
+  private
+
+  # Dispatch StartRequest, run the block, dispatch EndRequest with the
+  # response. Only the outermost call dispatches.
+  def lighthouse_request
+    return yield if @lighthouse_request_started
+
+    @lighthouse_request_started = true
+    Lighthouse::Events.dispatch(Lighthouse::Events::StartRequest.new(request))
+    result = yield
+    Lighthouse::Events.dispatch(Lighthouse::Events::EndRequest.new(response))
+    result
+  end
+
+  # The context of the operation: what @guard and the @can* directives read.
+  def graphql_context
+    respond_to?(:current_user, true) ? { current_user: current_user } : {}
+  end
+
+  def graphql_schema
+    source = lighthouse_schema_source
+    case source
+    when nil then raise Lighthouse::DefinitionError, "#{self.class}: name the schema with `lighthouse_schema AppSchema`"
+    when String, Symbol then source.to_s.constantize
+    when Proc then instance_exec(&source)
+    else source
+    end
+  end
+
+  # Variables arrive as a JSON string (GET or form posts) or as parameters.
+  def graphql_variables(param)
+    case param
+    when String then param.present? ? JSON.parse(param) || {} : {}
+    when Hash then param
+    when nil then {}
+    else
+      raise ArgumentError, "Unexpected parameter: #{param}" unless param.respond_to?(:to_unsafe_h)
+
+      param.to_unsafe_h
+    end
+  end
+
+  def lighthouse_operation
+    Lighthouse::GraphQL::PersistedQueries.execute(
+      graphql_schema,
+      query: params[:query], extensions: params[:extensions],
+      variables: graphql_variables(params[:variables]), operation_name: params[:operationName], context: graphql_context
+    )
+  end
+
+  # Each operation gets its own context: `schema.multiplex`'s `context:` is the
+  # multiplex's, which the queries' resolvers never see.
+  def lighthouse_batch(operations)
+    operations = operations.map do |operation|
+      { query: operation[:query], extensions: operation[:extensions], variables: graphql_variables(operation[:variables]),
+        operation_name: operation[:operationName], context: graphql_context }
+    end
+    Lighthouse::GraphQL::PersistedQueries.multiplex(graphql_schema, operations)
+  end
+
+  def lighthouse_development_error(error)
+    logger.error(error.message)
+    logger.error(error.backtrace.join("\n"))
+
+    render json: { errors: [{ message: error.message, backtrace: error.backtrace }], data: {} },
+           status: :internal_server_error
+  end
+end

data/lib/lighthouse/directive_resolvers/broadcast_resolver.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# @broadcast — on a mutation (or any field), trigger a subscription once the
+# field resolved successfully: its result is the root the subscribers'
+# updates are resolved from, each passing through the subscription's
+# `filter?`. A nil result or a GraphQL::ExecutionError (a failed mutation)
+# broadcasts nothing; repeat the directive to trigger several subscriptions.
+# See Lighthouse::GraphQL::Broadcasting for how it is triggered, and queued.
+class Lighthouse::GraphQL::DirectiveResolvers::BroadcastDirectiveResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
+  def self.directive_name = 'broadcast'
+
+  def self.definition
+    'directive @broadcast(subscription: String!, shouldQueue: Boolean) repeatable on FIELD_DEFINITION'
+  end
+
+  def define_resolver(target_type_class)
+    subscription = directive_arg('subscription')
+    should_queue = directive_arg('shouldQueue')
+    inner = capture_inner(target_type_class)
+
+    install(target_type_class, lambda do |obj, args, ctx|
+      result = inner.call(obj, args, ctx)
+      unless result.nil? || result.is_a?(::GraphQL::ExecutionError)
+        Lighthouse::GraphQL::Broadcasting.broadcast(ctx.schema, subscription, result, ctx, should_queue: should_queue)
+      end
+      result
+    end)
+  end
+end

data/lib/lighthouse/directive_resolvers/convert_empty_strings_resolver.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# @convertEmptyStringsToNull — replace incoming empty strings with null, as
+# PHP Lighthouse's directive of the same name does.
+#
+#   type Mutation {
+#     createPost(title: String @convertEmptyStringsToNull): Post!   # this argument
+#     createUser(input: UserInput!): User! @convertEmptyStringsToNull   # every input of the field
+#   }
+#   input UserInput { name: String @convertEmptyStringsToNull, bio: String }
+#
+# On a field it applies to all the field's inputs, nested input objects and
+# lists included, but leaves a non-null input (`String!`) alone: only placing
+# the directive on that argument or input field itself forces the conversion.
+# On an input field it applies wherever the input type is used. Setting
+# Config.convert_empty_strings_to_null makes every field behave as if it
+# carried the directive.
+#
+# The conversion is a wrapper around the field's resolver (outermost, order
+# 6), so every kind of resolver — directives, @field, Queries::/Mutations::
+# classes, the default reader — and @validator see the converted arguments,
+# and other fields sharing an input type are unaffected. SchemaGenerator
+# installs it too, without the directive on the field, when an argument or
+# input type it takes carries the directive, or the setting is on.
+class Lighthouse::GraphQL::DirectiveResolvers::ConvertEmptyStringsToNullDirectiveResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
+  NAME = 'convertEmptyStringsToNull'
+
+  def self.directive_name = NAME
+
+  def self.definition
+    <<~GRAPHQL.chomp
+      """
+      Replaces incoming empty strings `""` with `null`.
+
+      When used upon fields, empty strings for non-nullable inputs will pass unchanged.
+      Only explicitly placing this on non-nullable inputs will force the conversion.
+      """
+      directive @convertEmptyStringsToNull on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | FIELD_DEFINITION
+    GRAPHQL
+  end
+
+  # Does a field without the directive still convert? Yes when the setting is
+  # on, or when an argument or input type it takes carries the directive.
+  def self.implicit?(field_def)
+    return false if field_def.arguments.empty?
+
+    Lighthouse::Config.convert_empty_strings_to_null || carried?(field_def.arguments)
+  end
+
+  def self.explicit?(argument)
+    (argument.ast_node&.directives || []).any? { |d| d.name == NAME }
+  end
+
+  # Does any argument, at any depth of input types, carry the directive?
+  def self.carried?(argument_defs, seen = Set.new)
+    argument_defs.each_value.any? do |argument|
+      type = argument.type.unwrap
+      explicit?(argument) || (type.kind.input_object? && seen.add?(type.graphql_name) && carried?(type.arguments, seen))
+    end
+  end
+
+  def initialize(field_def, type_def, directive_node, opts = {})
+    super
+    @active = !directive_node.nil? || Lighthouse::Config.convert_empty_strings_to_null
+  end
+
+  def define_resolver(target_type_class)
+    me = self
+    inner = capture_inner(target_type_class)
+
+    install(target_type_class, lambda do |obj, args, ctx|
+      inner.call(obj, me.convert_arguments(args), ctx)
+    end)
+  end
+
+  # The field's arguments (a Hash keyed by snake_case symbols) with the empty
+  # strings replaced. Input objects that change are copied, never mutated.
+  def convert_arguments(args)
+    return args unless args.is_a?(Hash)
+
+    convert_hash(@field_def.arguments, args, @active)
+  end
+
+  private
+
+  def convert_hash(argument_defs, values, active)
+    by_keyword = Lighthouse::Support::Arguments.keyword_index(argument_defs)
+    values.to_h { |key, value| [key, convert_argument(by_keyword[key.to_sym], value, active)] }
+  end
+
+  def convert_argument(argument, value, active)
+    return value if argument.nil? || value.nil?
+
+    explicit = self.class.explicit?(argument)
+    convert_value(argument.type, value, active || explicit, explicit)
+  end
+
+  # `active`: the enclosing field or argument converts its nullable inputs.
+  # `force`: this argument itself carries the directive, so non-null ones too.
+  def convert_value(type, value, active, force)
+    nullable = !type.kind.non_null?
+    type = type.of_type unless nullable
+    case type.kind.name
+    when 'LIST' then convert_list(type.of_type, value, active, force)
+    when 'INPUT_OBJECT' then convert_input(type, value, active)
+    when 'SCALAR' then convert_scalar(value, force || (active && nullable))
+    else value
+    end
+  end
+
+  def convert_scalar(value, convert)
+    convert && value == '' ? nil : value
+  end
+
+  def convert_list(item_type, value, active, force)
+    return value unless value.is_a?(Array)
+
+    items = value.map { |item| convert_value(item_type, item, active, force) }
+    items.zip(value).all? { |new, old| new.equal?(old) } ? value : items
+  end
+
+  def convert_input(type, value, active)
+    values = value.respond_to?(:to_kwargs) ? value.to_kwargs : value
+    return value unless values.is_a?(Hash)
+
+    converted = convert_hash(type.arguments, values, active)
+    return value if converted.all? { |key, new| new.equal?(values[key]) }
+    return converted unless value.respond_to?(:to_kwargs)
+
+    value.dup.tap { |copy| copy.instance_variable_set(:@ruby_style_hash, converted) }
+  end
+end

data/lib/lighthouse/directive_resolvers/event_resolver.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# @event(dispatch: "OrderShipped") — dispatch an event once the field has
+# resolved: the class is built with the resolved value and handed to
+# Lighthouse::Events.dispatch. The value is returned unchanged; if the field
+# raises, nothing is dispatched. Repeatable: each @event dispatches its own.
+#
+# The class is looked up in Config.namespaces[:events] (a fully-qualified
+# name is used as-is); a name that is no class fails the schema build.
+class Lighthouse::GraphQL::DirectiveResolvers::EventDirectiveResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
+  def self.directive_name = 'event'
+  def self.definition = 'directive @event(dispatch: String!) repeatable on FIELD_DEFINITION'
+
+  def define_resolver(target_type_class)
+    name = directive_arg('dispatch')
+    self.class.event_class(name, "#{@type_def.graphql_name}.#{@field_def.name}")
+    inner = capture_inner(target_type_class)
+
+    install(target_type_class, lambda do |obj, args, ctx|
+      result = inner.call(obj, args, ctx)
+      Lighthouse::Events.dispatch(Lighthouse::GraphQL::DirectiveResolvers::EventDirectiveResolver.event_class(name).new(result))
+      result
+    end)
+  end
+
+  # The event class `name` names. Looked up on every dispatch, so a reloaded
+  # class is the one built.
+  def self.event_class(name, location = nil)
+    klass = Lighthouse::Support::ModelResolver.constantize(name, namespaces: Lighthouse::Config.namespaces[:events])
+    return klass if klass.respond_to?(:new)
+
+    raise Lighthouse::DefinitionError,
+          "@event on #{location}: no event class #{name} (looked in #{Lighthouse::Config.namespaces[:events].join(', ')})"
+  end
+end