lighthouse-graphql 0.2.1 → 0.4.0

data/lib/lighthouse/complexity_analyzer.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+# A concern for a graphql-ruby analyzer that @complexity(resolver:) names. Its
+# one method, `complexity`, gives the fields naming the class their cost, as
+# graphql-ruby's `complexity` gives a field or a GraphQL::Schema::Resolver one:
+#
+#   class Analyzers::TagPostsComplexity < GraphQL::Analysis::QueryComplexity
+#     include Lighthouse::GraphQL::ComplexityAnalyzer
+#
+#     complexity ->(_context, _args, child_complexity) { 1 + (child_complexity * 25) }
+#   end
+#
+# A number is added to the cost of the field's selection; a proc is called with
+# (context, args, child_complexity) and returns the whole cost. Without
+# `complexity`, the field costs what a bare @complexity gives.
+#
+# The class stays an analyzer, installed on the schema like any class @complexity
+# names: a `result` of its own runs on every query, in graphql-ruby's analysis.
+# Without one it only gives costs, and graphql-ruby skips it.
+module Lighthouse::GraphQL::ComplexityAnalyzer
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Set the cost (a number or a proc taking context, args and child_complexity),
+    # or read it: the class's own, else its superclass's, else nil.
+    def complexity(new_complexity = nil)
+      return inherited_complexity if new_complexity.nil?
+
+      unless new_complexity.is_a?(Numeric) || (new_complexity.is_a?(Proc) && new_complexity.parameters.size == 3)
+        raise ArgumentError, "#{name}.complexity takes a number or a proc of (context, args, child_complexity), " \
+                             "got #{new_complexity.inspect}"
+      end
+
+      @complexity = new_complexity
+    end
+
+    private
+
+    def inherited_complexity
+      return @complexity if defined?(@complexity)
+
+      superclass.respond_to?(:complexity) ? superclass.complexity : nil
+    end
+  end
+
+  # Run in graphql-ruby's analysis only when the class has a `result` of its own.
+  def analyze?
+    self.class.instance_method(:result).owner != Lighthouse::GraphQL::ComplexityAnalyzer && super
+  end
+
+  def result
+    nil
+  end
+end

data/lib/lighthouse/config.rb

@@ -12,12 +12,15 @@ module Lighthouse
     # Where each kind of class a schema refers to by name is looked up. Query and
     # mutation fields resolve to GraphQL::Schema::Resolver / Mutation classes,
     # builders compose onto a relation, validators check arguments: distinct
-    # contracts, so distinct namespaces (app/graphql/queries, .../mutations, ...).
+    # contracts, so distinct namespaces (app/graphql/resolvers, .../mutations, ...).
     DEFAULT_NAMESPACES = {
-      queries: ['Queries'],
+      queries: ['Resolvers'],
       mutations: ['Mutations'],
       builders: ['Builders'],
-      validators: ['Validators']
+      validators: ['Validators'],
+      events: ['Events'],
+      subscriptions: ['Subscriptions'],
+      analyzers: ['Analyzers']
     }.freeze
 
     # Every setting reset! forgets, so the next read falls back to its default.
@@ -25,19 +28,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 +74,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 +100,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 +122,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 +151,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 +185,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 +200,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/convention_resolver.rb

@@ -4,14 +4,17 @@ require_relative 'base'
 
 # Resolves a Query or Mutation field that has no resolving directive by
 # convention, as PHP Lighthouse does: `Query.latestPosts` resolves to
-# `Queries::LatestPosts` (a GraphQL::Schema::Resolver), `Mutation.publishPost`
-# to `Mutations::PublishPost` (a GraphQL::Schema::Mutation), looked up in
+# `Resolvers::LatestPosts` (a GraphQL::Schema::Resolver, by graphql-ruby's
+# convention a Resolvers::BaseResolver), `Mutation.publishPost` to
+# `Mutations::PublishPost` (a GraphQL::Schema::Mutation), looked up in
 # Config.namespaces[:queries] / [:mutations] at call time so code reloading
 # keeps working. Not a directive: SchemaGenerator installs it.
 class Lighthouse::GraphQL::DirectiveResolvers::ConventionResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
-  def initialize(field_def, type_def, kind)
+  # `base`: the class the schema's base_types require the class to inherit from.
+  def initialize(field_def, type_def, kind, base = nil)
     super(field_def, type_def, nil)
     @kind = kind
+    @base = base
   end
 
   def define_resolver(target_type_class)
@@ -31,6 +34,12 @@ class Lighthouse::GraphQL::DirectiveResolvers::ConventionResolver < Lighthouse::
     ROOT_KINDS[type.respond_to?(:graphql_name) ? type.graphql_name : type.to_s]
   end
 
+  # The class a root field resolves to, without its namespace: `LatestPosts`
+  # for `latestPosts`.
+  def self.class_name_for(field_def)
+    field_def.name.to_s.camelize
+  end
+
   private
 
   def resolve_by_convention(inner, obj, args, ctx)
@@ -43,6 +52,7 @@ class Lighthouse::GraphQL::DirectiveResolvers::ConventionResolver < Lighthouse::
             "#{klass} resolves #{location}, so it must inherit from GraphQL::Schema::Resolver " \
             '(or GraphQL::Schema::Mutation).'
     end
+    Lighthouse::GraphQL::ResolverBases.check!(klass, @base, location)
 
     Lighthouse::GraphQL::ResolverDispatch.call(klass, @field_def, obj, args, ctx)
   end
@@ -61,7 +71,7 @@ class Lighthouse::GraphQL::DirectiveResolvers::ConventionResolver < Lighthouse::
   end
 
   def class_name
-    @class_name ||= @field_def.name.to_s.camelize
+    @class_name ||= self.class.class_name_for(@field_def)
   end
 
   def location

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, Resolvers::/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

data/lib/lighthouse/directive_resolvers/model_mutation_resolver.rb

@@ -181,34 +181,38 @@ module Lighthouse::GraphQL::DirectiveResolvers
     end
   end
 
-  # @delete — destroy the models the field's argument filters select
-  # (@whereKey, @eq, ...), running their callbacks, and return them: a list
-  # for a list field, else the first or null. Refuses to run without a
-  # filter argument, which would delete every row.
-  class DeleteDirectiveResolver < ModelMutationResolver
-    def self.directive_name = 'delete'
-    def self.definition = "directive @delete(#{ARGUMENTS}, scopes: [String!]) on #{LOCATIONS}"
-
+  # The shared shape of @delete, @forceDelete and @restore: act on each record
+  # the field's argument filters (@whereKey, @eq, ...) select, and return them:
+  # a list for a list field, else the first or null. Refuses to run without a
+  # filter argument, which would modify every row.
+  class ModifyModelsResolver < ModelMutationResolver
     WOULD_MODIFY_ALL = 'Would modify all models, use an argument to filter.'
 
     protected
 
-    # A record whose callbacks refuse the destroy is reported as an error next
-    # to the data, as PHP Lighthouse does; the others are still deleted.
+    # A record whose callbacks refuse the action is reported as an error next
+    # to the data, as PHP Lighthouse does; the others are still modified.
     def mutate(model, _obj, args, ctx)
       args = Lighthouse::Support::Arguments.shallow(args)
       raise ::GraphQL::ExecutionError, WOULD_MODIFY_ALL unless filtered?(args)
 
-      relation = Array(directive_arg('scopes')).reduce(model.all) { |acc, scope| acc.public_send(scope) }
-      records = apply_where_filters(relation, args).to_a
+      records = apply_where_filters(records_of(model), args).to_a
       records.each do |record|
-        next if record.destroy
+        next if modify(record)
 
         ctx.add_error(::GraphQL::ExecutionError.new("Could not modify model #{model.name} with ID #{record.id}."))
       end
       @field_def.type.list? ? records : records.first
     end
 
+    # The relation the filters narrow down: the model's, narrowed by `scopes:`.
+    def records_of(model) = apply_scopes(model.all)
+
+    # Act on one record; false when its callbacks refused.
+    def modify(_record)
+      raise NotImplementedError
+    end
+
     def filtered?(args)
       registry = Lighthouse::DirectiveRegistry.default
       (@field_def.ast_node.arguments || []).any? do |argument|
@@ -216,4 +220,15 @@ module Lighthouse::GraphQL::DirectiveResolvers
       end
     end
   end
+
+  # @delete — destroy the models the field's argument filters select
+  # (@whereKey, @eq, ...), running their callbacks, and return them.
+  class DeleteDirectiveResolver < ModifyModelsResolver
+    def self.directive_name = 'delete'
+    def self.definition = "directive @delete(#{ARGUMENTS}, scopes: [String!]) on #{LOCATIONS}"
+
+    protected
+
+    def modify(record) = record.destroy
+  end
 end