lighthouse-graphql 0.4.0 → 0.5.0

data/lib/lighthouse/directive_resolvers/first_resolver.rb

@@ -23,7 +23,7 @@ class Lighthouse::GraphQL::DirectiveResolvers::FirstDirectiveResolver < Lighthou
       args_h = arguments.respond_to?(:to_h) ? arguments.to_h : {}
       relation = resolver_instance.apply_scopes(model_class.all)
       relation = Lighthouse::GraphQL::DirectiveResolvers::BuilderApplier.apply(relation, field_ast_node, args_h, ctx, resolver_instance)
-      relation = resolver_instance.apply_where_filters(relation, args_h)
+      relation = resolver_instance.apply_where_filters(relation, args_h, ctx)
       relation.first
     end
 

data/lib/lighthouse/directive_resolvers/global_id_resolver.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# @globalId — Relay global ids, as PHP Lighthouse's directive: on a field it
+# encodes the value with the type's name (`id: ID! @globalId` answers
+# "VXNlcjox" for User 1); on an argument or input field it decodes what the
+# client sent (ArgumentTransformsResolver). Config.global_id does the encoding.
+class Lighthouse::GraphQL::DirectiveResolvers::GlobalIdDirectiveResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
+  NAME = 'globalId'
+
+  def self.directive_name = NAME
+
+  def self.definition
+    <<~GRAPHQL.chomp
+      """
+      Converts between IDs/types and global IDs.
+
+      When used upon a field, it encodes;
+      when used upon an argument, it decodes.
+      """
+      directive @globalId(
+        """
+        Decoding a global id produces a tuple of `$type` and `$id`.
+        This setting controls which of those is passed along.
+        """
+        decode: GlobalIdDecode = ARRAY
+      ) on FIELD_DEFINITION | INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
+    GRAPHQL
+  end
+
+  def self.type_definitions
+    {
+      'GlobalIdDecode' => <<~GRAPHQL.chomp
+        "Options for the `decode` argument of `@globalId`."
+        enum GlobalIdDecode {
+          "Return an array of `[$type, $id]`."
+          ARRAY
+          "Return just `$type`."
+          TYPE
+          "Return just `$id`."
+          ID
+        }
+      GRAPHQL
+    }
+  end
+
+  def define_resolver(target_type_class)
+    inner = capture_inner(target_type_class)
+    type_name = target_type_class.graphql_name
+
+    install(target_type_class, lambda do |obj, args, ctx|
+      id = inner.call(obj, args, ctx)
+      id.nil? ? nil : Lighthouse::Config.global_id.encode(type_name, id)
+    end)
+  end
+end

data/lib/lighthouse/directive_resolvers/lazy_load_resolver.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# @lazyLoad(relations: ["replies"]) — eager-load relations of the records a field
+# returns, as PHP Lighthouse's @lazyLoad does, so the fields the client selects on
+# them do not query once per record. Works on a list, a relation, and a @paginate
+# page; across every parent in the response at once, so a @hasMany's records for
+# all its parents load their relations together.
+#
+#   type Post {
+#     comments: [Comment!]! @hasMany @lazyLoad(relations: ["replies", "author"])
+#   }
+class Lighthouse::GraphQL::DirectiveResolvers::LazyLoadDirectiveResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
+  def self.directive_name = 'lazyLoad'
+
+  def self.definition
+    <<~GRAPHQL.chomp
+      """
+      Eager-load relations of the records the field returns.
+      """
+      directive @lazyLoad(
+        "The relations to load, nested with dots."
+        relations: [String!]!
+      ) repeatable on FIELD_DEFINITION
+    GRAPHQL
+  end
+
+  def define_resolver(target_type_class)
+    inner = capture_inner(target_type_class)
+    associations = Lighthouse::Support::Preload.associations(directive_arg('relations'))
+
+    install(target_type_class, lambda do |obj, args, ctx|
+      Lighthouse::GraphQL::DirectiveResolvers::LazyLoadDirectiveResolver.load(inner.call(obj, args, ctx), associations, ctx)
+    end)
+  end
+
+  # `result` with `associations` loaded into its records.
+  def self.load(result, associations, ctx)
+    return result.preload(*associations) if unloaded_relation?(result)
+
+    records = records_of(result).grep(::ActiveRecord::Base)
+    ctx.dataloader.with(Lighthouse::GraphQL::DataloaderSources::PreloadLoader, associations, []).load_all(records) if records.any?
+    result
+  end
+
+  # A query not run yet takes the preload itself. An association's records (what
+  # @hasMany returns, loaded for every parent at once) or a loaded relation
+  # are records already: they load their relations together, in the Dataloader.
+  def self.unloaded_relation?(result)
+    result.is_a?(::ActiveRecord::Relation) && !result.is_a?(::ActiveRecord::Associations::CollectionProxy) && !result.loaded?
+  end
+
+  def self.records_of(result)
+    case result
+    when Lighthouse::GraphQL::Pagination::LazyPage then result.items
+    when Hash then Array(result['data'] || result[:data])
+    else Array(result)
+    end
+  end
+end

data/lib/lighthouse/directive_resolvers/limit_resolver.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# @limit on an argument — the client caps how many results the field returns,
+# as PHP Lighthouse's directive: `posts(limit: Int @limit): [Post!]! @all`. The
+# argument must be an Int; null leaves the results alone. A query not run yet
+# gets a LIMIT; a list already loaded (a @hasMany's records, loaded for every
+# parent at once) is cut in memory, so one parent's limit never cuts another's.
+# With `builder: true` it is a LIMIT on the field's query instead, through the
+# argument directives (Arguments::Limit): for root fields, as PHP Lighthouse
+# warns, since a relation batched for many parents would be cut as a whole.
+# PHP Lighthouse also allows @limit on the field, where it marks the field the
+# argument limits; it is accepted there and changes nothing. Not a directive
+# resolver: FieldResolverStack installs it on a field whose arguments carry
+# @limit, around whatever resolves the field.
+class Lighthouse::GraphQL::DirectiveResolvers::LimitResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
+  # The keyword of the argument whose @limit cuts the results, or nil; every
+  # argument carrying @limit must be an Int.
+  def self.keyword(field_def)
+    limiting = field_def.arguments.each_value.select { |argument| directive(argument) }
+    limiting.each { |argument| validate!(field_def, argument) }
+    limiting.find { |argument| !Lighthouse::Support::DirectiveArgs.literal(directive(argument), 'builder') }&.keyword
+  end
+
+  def self.directive(argument)
+    (argument.ast_node&.directives || []).find { |d| d.name == 'limit' }
+  end
+
+  def self.validate!(field_def, argument)
+    return if argument.type.unwrap.graphql_name == 'Int'
+
+    raise Lighthouse::DefinitionError,
+          "The @limit directive must only be used on arguments of type Int, got #{field_def.name}.#{argument.graphql_name} of type " \
+          "#{argument.type.unwrap.graphql_name}."
+  end
+
+  def define_resolver(target_type_class)
+    keyword = self.class.keyword(@field_def)
+    inner = capture_inner(target_type_class)
+
+    install(target_type_class, lambda do |obj, args, ctx|
+      limit = args.is_a?(Hash) ? args[keyword] : nil
+      result = inner.call(obj, args, ctx)
+      limit.nil? ? result : Lighthouse::GraphQL::DirectiveResolvers::LimitResolver.cut(result, limit)
+    end)
+  end
+
+  def self.cut(result, limit)
+    raise ::GraphQL::ExecutionError, "The limit must be positive, got #{limit}." if limit.negative?
+
+    case result
+    when ::ActiveRecord::Associations::CollectionProxy then result.to_a.first(limit)
+    when ::ActiveRecord::Relation then result.loaded? ? result.to_a.first(limit) : result.limit(limit)
+    when Array then result.first(limit)
+    else result
+    end
+  end
+end

data/lib/lighthouse/directive_resolvers/method_resolver.rb

@@ -8,6 +8,12 @@ require_relative 'base'
 #
 #   labels: [String!]! @method(name: "label_list")
 #   canReply: Boolean   @method(name: "can_reply?")
+#   excerpt(length: Int = 80): String @method
+#
+# The field's arguments reach the method: as snake_case keywords when it takes
+# keywords (`def excerpt(length:)`), else positionally in the order the SDL
+# declares them, as PHP Lighthouse passes them (`def excerpt(length)`). A method
+# taking no parameters is called without them.
 class Lighthouse::GraphQL::DirectiveResolvers::MethodDirectiveResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
   def self.directive_name = 'method'
   def self.definition = 'directive @method(name: String) on FIELD_DEFINITION'
@@ -17,13 +23,42 @@ class Lighthouse::GraphQL::DirectiveResolvers::MethodDirectiveResolver < Lightho
     target_method = (Lighthouse::Support::DirectiveArgs.literal(@directive_node, 'name') ||
                      Lighthouse::Support::Naming.attribute(@field_def.name)).to_s
 
-    resolver = lambda do |obj, _arguments, _ctx|
-      next nil if obj.nil?
+    field_def = @field_def
+    resolver = lambda do |obj, arguments, ctx|
+      next nil if obj.nil? || !obj.respond_to?(target_method)
 
-      obj.respond_to?(target_method) ? obj.public_send(target_method) : nil
+      Lighthouse::GraphQL::DirectiveResolvers::MethodDirectiveResolver.call_method(obj.method(target_method), field_def, arguments, ctx)
     end
 
     target_type_class.define_singleton_method(resolver_method, &resolver)
     @field_def.resolve_proc = resolver if @field_def.respond_to?(:resolve_proc=)
   end
+
+  KEYWORDS = %i[key keyreq keyrest].freeze
+  NAMED_KEYWORDS = %i[key keyreq].freeze
+
+  # Call `method` with the field's arguments, as the method takes them.
+  def self.call_method(method, field_def, arguments, ctx)
+    params = method.parameters
+    return method.call if field_def.arguments.empty? || params.empty?
+
+    values = Lighthouse::Support::Arguments.prepare(field_def, arguments, ctx)
+    return method.call(**keywords(params, values)) if params.any? { |type, _| KEYWORDS.include?(type) }
+
+    method.call(*positional(params, field_def, values))
+  end
+
+  # The values in the order the SDL declares the arguments, as many as the
+  # method takes; all of them when it takes *rest.
+  def self.positional(params, field_def, values)
+    ordered = field_def.arguments.each_value.map { |arg| values[arg.keyword] }
+    params.any? { |type, _| type == :rest } ? ordered : ordered.first(params.size)
+  end
+
+  # The values the method's keywords name; all of them when it takes **keywords.
+  def self.keywords(params, values)
+    return values if params.any? { |type, _| type == :keyrest }
+
+    values.slice(*params.filter_map { |type, name| name if NAMED_KEYWORDS.include?(type) })
+  end
 end

data/lib/lighthouse/directive_resolvers/model_mutation_resolver.rb

@@ -196,7 +196,7 @@ module Lighthouse::GraphQL::DirectiveResolvers
       args = Lighthouse::Support::Arguments.shallow(args)
       raise ::GraphQL::ExecutionError, WOULD_MODIFY_ALL unless filtered?(args)
 
-      records = apply_where_filters(records_of(model), args).to_a
+      records = apply_where_filters(records_of(model), args, ctx).to_a
       records.each do |record|
         next if modify(record)
 

data/lib/lighthouse/directive_resolvers/namespaced_resolver.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# @namespaced — a field that only groups others, as PHP Lighthouse's
+# directive: it resolves to `true`, and the fields of its type resolve with
+# their own directives.
+#
+#   type Query { post: PostQueries! @namespaced }
+#   type PostQueries {
+#     find(id: ID! @eq): Post @find
+#     list: [Post!]! @paginate
+#   }
+#
+# `{ post { find(id: 1) { title } } }`. Works on Mutation too.
+class Lighthouse::GraphQL::DirectiveResolvers::NamespacedDirectiveResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
+  def self.directive_name = 'namespaced'
+
+  def self.definition
+    <<~GRAPHQL.chomp
+      """
+      A no-op field resolver that allows nesting of queries and mutations.
+      """
+      directive @namespaced on FIELD_DEFINITION
+    GRAPHQL
+  end
+
+  def define_resolver(target_type_class)
+    install(target_type_class, ->(_obj, _args, _ctx) { true })
+  end
+end

data/lib/lighthouse/directive_resolvers/paginate_resolver.rb

@@ -75,7 +75,7 @@ class Lighthouse::GraphQL::DirectiveResolvers::PaginateDirectiveResolver < Light
   # `scopes:`, @builder and the argument filters, on one relation or a RelationBatch.
   def decorate_relation(relation, args, ctx)
     relation = Lighthouse::GraphQL::DirectiveResolvers::BuilderApplier.apply(apply_scopes(relation), @field_def.ast_node, args, ctx, self)
-    apply_where_filters(relation, args)
+    apply_where_filters(relation, args, ctx)
   end
 
   protected

data/lib/lighthouse/directive_resolvers/resolution.rb

@@ -18,15 +18,30 @@ module Lighthouse::GraphQL::DirectiveResolvers::Resolution
         original_singleton.call(obj, arguments, ctx)
       elsif original_proc
         original_proc.call(obj, arguments, ctx)
-      elsif obj.respond_to?(field_name)
-        obj.public_send(field_name)
       else
-        snake = Lighthouse::Support::Naming.attribute(field_name)
-        obj.respond_to?(snake) ? obj.public_send(snake) : nil
+        Lighthouse::GraphQL::DirectiveResolvers::Resolution.read(obj, field_name)
       end
     end
   end
 
+  # The default reader: a Hash's key, else the object's method of the field's
+  # name or its snake_case.
+  def read(obj, field_name)
+    return read_hash(obj, field_name) if obj.is_a?(Hash)
+    return obj.public_send(field_name) if obj.respond_to?(field_name)
+
+    snake = Lighthouse::Support::Naming.attribute(field_name)
+    obj.respond_to?(snake) ? obj.public_send(snake) : nil
+  end
+
+  # A Hash's value for the field, as the default reader finds it: by the field's
+  # name or its snake_case, as a String or a Symbol key.
+  def read_hash(hash, field_name)
+    snake = Lighthouse::Support::Naming.attribute(field_name)
+    key = [field_name.to_s, field_name.to_sym, snake, snake.to_sym].find { |candidate| hash.key?(candidate) }
+    key.nil? ? nil : hash[key]
+  end
+
   # graphql-ruby's SDL builder defines `resolve_field_*` methods of its own
   # (with a different arity); only ours, defined under lib/lighthouse/, count.
   def lighthouse_singleton(target_type_class, method_name)

data/lib/lighthouse/directive_resolvers/subscription_resolver.rb

@@ -32,7 +32,8 @@ class Lighthouse::GraphQL::DirectiveResolvers::SubscriptionDirectiveResolver < L
     @field_def.define_singleton_method(:subscription_scope) { me.subscription_class.subscription_scope }
 
     install(target_type_class, lambda do |obj, args, ctx|
-      Lighthouse::GraphQL::ResolverDispatch.call(me.subscription_class, me.field_def, obj, args, ctx)
+      info = Lighthouse::GraphQL::ResolveInfo.for(me.field_def, target_type_class, obj, args, ctx)
+      Lighthouse::GraphQL::ResolverDispatch.call(me.subscription_class, info)
     end)
   end
 

data/lib/lighthouse/directive_resolvers/throttle_resolver.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# @throttle — rate-limit a field per client, as PHP Lighthouse's directive (and
+# Laravel's ThrottleRequests): at most `maxAttempts` calls every `decayMinutes`,
+# counted in Config.cache_store. A client is the signed-in user, else the
+# context's :remote_ip (Lighthouse::GraphQL::Controller sets it), else "guest".
+# Past the limit the field fails with "Rate limit for Query.x exceeded. Try
+# again later." Outermost: refused calls never reach @guard or the resolver.
+#
+#   type Mutation {
+#     login(email: String!, password: String!): User @throttle(maxAttempts: 5)
+#     search(term: String!): [Post!]! @throttle(name: "search", maxAttempts: 30, decayMinutes: 0.5)
+#   }
+class Lighthouse::GraphQL::DirectiveResolvers::ThrottleDirectiveResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
+  def self.directive_name = 'throttle'
+
+  def self.definition
+    <<~GRAPHQL.chomp
+      """
+      Sets rate limit to access the field. Does the same as ThrottleRequests Laravel Middleware.
+      """
+      directive @throttle(
+        "A name shared by the fields that count together. Defaults to the field."
+        name: String
+        "Maximum number of attempts in a specified time interval."
+        maxAttempts: Int = 60
+        "Time in minutes to reset attempts."
+        decayMinutes: Float = 1.0
+        "Prefix to distinguish several field groups."
+        prefix: String
+      ) on FIELD_DEFINITION
+    GRAPHQL
+  end
+
+  def define_resolver(target_type_class)
+    me = self
+    inner = capture_inner(target_type_class)
+    location = "#{target_type_class.graphql_name}.#{@field_def.name}"
+    bucket = "#{directive_arg('prefix')}#{directive_arg('name') || location}"
+    max_attempts = directive_arg('maxAttempts') || 60
+    decay = ((directive_arg('decayMinutes') || 1.0) * 60).ceil
+
+    install(target_type_class, lambda do |obj, args, ctx|
+      me.hit!(bucket, ctx, max_attempts, decay, location)
+      inner.call(obj, args, ctx)
+    end)
+  end
+
+  def hit!(bucket, ctx, max_attempts, decay, location)
+    key = "lighthouse:throttle:#{bucket}:#{client(ctx)}"
+    store = Lighthouse::GraphQL::Caching.store
+    self.class.warn_null_store(location) if store.is_a?(::ActiveSupport::Cache::NullStore)
+    attempts = store.increment(key, 1, expires_in: decay) || (store.write(key, 1, expires_in: decay) && 1)
+    raise ::GraphQL::ExecutionError, "Rate limit for #{location} exceeded. Try again later." if attempts > max_attempts
+  end
+
+  # A :null_store keeps no count, so the limit never applies: say so, once per field.
+  def self.warn_null_store(location)
+    @warned ||= Set.new
+    return unless @warned.add?(location)
+
+    message = "Lighthouse: @throttle on #{location} counts nothing, as the cache store is a :null_store. Set Config.cache_store."
+    defined?(Rails) && Rails.logger ? Rails.logger.warn(message) : warn(message)
+  end
+
+  private
+
+  def client(ctx)
+    user = Lighthouse::Support::Authorization.authenticated_user(ctx)
+    return "user:#{user.respond_to?(:id) ? user.id : user}" if user
+
+    ip = ctx.respond_to?(:[]) ? ctx[:remote_ip] : nil
+    ip ? "ip:#{ip}" : 'guest'
+  end
+end

data/lib/lighthouse/directive_resolvers/type_method_resolver.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# Resolves a field of an object type through a method of the type's class, in
+# graphql-ruby's folder structure: `Post.readingTime` calls
+# `Types::PostType#reading_time` when that class includes Lighthouse::GraphQL::Type
+# and defines it. The SDL still declares the field; the class only says how it
+# resolves, as a graphql-ruby type's method does: an instance per parent, with
+# `object` (the parent), `context`, the `dataload*` helpers, and the field's
+# arguments as snake_case keywords. A field with a resolving directive never
+# reaches it, and one whose name the class does not define is read off the
+# object as before. Not a directive: FieldResolverStack installs it on types
+# other than the root ones.
+class Lighthouse::GraphQL::DirectiveResolvers::TypeMethodResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
+  # The class of the SDL type `type_name` (`Types::PostType` for `Post`) in
+  # Config.namespaces[:types], when it includes Lighthouse::GraphQL::Type; nil
+  # otherwise, so a type class that does not opt in is left alone. It must
+  # inherit from the schema's base_types[:object] (in `bases`, ResolverBases)
+  # when one is given.
+  def self.type_class(type_name, bases = {})
+    klass = lookup(type_name)
+    return unless klass
+
+    Lighthouse::GraphQL::ResolverBases.check!(klass, bases.dig(:types, :object), "the #{type_name} type")
+    klass
+  end
+
+  def self.lookup(type_name)
+    Lighthouse::GraphQL::Type.class_for(type_name, :object)
+  end
+
+  # The method of `klass` that resolves `field_def` (`reading_time` for
+  # `readingTime`), or nil. Methods every GraphQL::Schema::Object has
+  # (`object`, `context`, Object's own) never count.
+  def self.method_for(klass, field_def)
+    name = Lighthouse::Support::Naming.attribute(field_def.name)
+    name if klass.public_method_defined?(name) && !::GraphQL::Schema::Object.public_method_defined?(name)
+  end
+
+  def initialize(field_def, type_def, method_name)
+    super(field_def, type_def, nil)
+    @method_name = method_name
+  end
+
+  def define_resolver(target_type_class)
+    Lighthouse::GraphQL::ResolveInfo.request_lookahead(@field_def)
+    me = self
+    inner = capture_inner(target_type_class)
+
+    install(target_type_class, lambda do |obj, args, ctx|
+      me.send(:resolve_with_type, inner, obj, args, ctx)
+    end)
+  end
+
+  private
+
+  # The class is looked up on each call, so code reloading keeps working; when
+  # it no longer defines the method, the field is read as before. A parent that
+  # is not a record of the type's @model is reported, and the field resolves to nil.
+  def resolve_with_type(inner, obj, args, ctx)
+    klass = self.class.lookup(@type_def.graphql_name)
+    return inner.call(obj, args, ctx) unless klass&.public_method_defined?(@method_name)
+
+    model = Lighthouse::GraphQL::Directives::ModelDirective.declared_model(@type_def)
+    return wrong_parent(klass, model, obj, ctx) if model && !obj.is_a?(model)
+
+    info = Lighthouse::GraphQL::ResolveInfo.for(@field_def, @type_def, obj, args, ctx)
+    instance = Lighthouse::GraphQL::ResolveInfo.attach(klass.send(:new, obj, ctx), info)
+    kwargs = Lighthouse::Support::Arguments.prepare(@field_def, args, ctx)
+    kwargs.empty? ? instance.public_send(@method_name) : instance.public_send(@method_name, **kwargs)
+  end
+
+  def wrong_parent(klass, model, obj, ctx)
+    error = Lighthouse::DefinitionError.new(
+      "#{@type_def.graphql_name}.#{@field_def.name} resolves with #{klass}, but its parent is a #{obj.class}, not a #{model} (@model)."
+    )
+    Lighthouse::Config.handle_error(error, ctx)
+    nil
+  end
+end

data/lib/lighthouse/directive_resolvers/with_count_resolver.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# @withCount(relation: "posts", scopes: [...]) — count a relation of the parent
+# before the field resolves, as PHP Lighthouse's @withCount does: the count is not
+# the field's value, it is kept on the parent as `<relation>_count`
+# (`user.posts_count`) for whatever resolves the field to read. Every parent in
+# the response is counted in one query.
+#
+#   type User {
+#     activity: String! @withCount(relation: "posts") @method(name: "activity_label")
+#     postsCount: Int! @withCount(relation: "posts")   # the default reader reads posts_count
+#   }
+class Lighthouse::GraphQL::DirectiveResolvers::WithCountDirectiveResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
+  def self.directive_name = 'withCount'
+
+  def self.definition
+    <<~GRAPHQL.chomp
+      """
+      Count a relation of the parent before the field resolves, for every parent at once,
+      and keep the count on it as `<relation>_count`.
+      """
+      directive @withCount(
+        "The relation to count."
+        relation: String!
+        "Model scopes that narrow the counted records."
+        scopes: [String!]
+      ) repeatable on FIELD_DEFINITION
+    GRAPHQL
+  end
+
+  def define_resolver(target_type_class)
+    inner = capture_inner(target_type_class)
+    relation = directive_arg('relation')
+    scopes = Array(directive_arg('scopes'))
+
+    install(target_type_class, lambda do |obj, args, ctx|
+      ctx.dataloader.with(Lighthouse::GraphQL::DataloaderSources::RelationCountsLoader, relation, scopes).load(obj) if obj.is_a?(::ActiveRecord::Base)
+      inner.call(obj, args, ctx)
+    end)
+  end
+end

data/lib/lighthouse/directive_resolvers/with_resolver.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# @with(relation: "tasks", scopes: [...]) — eager-load a relation of the parent
+# before the field resolves, as PHP Lighthouse's @with does: for a field computed
+# from it (a @method, a type class method, the default reader of a method that
+# reads it), so it is loaded once for every parent in the response, not once per
+# parent. `relation` defaults to the field's (snake_case) name, and may be nested
+# ("tasks.assignee"); `scopes` narrow the loaded records.
+#
+#   type User {
+#     taskSummary: String! @with(relation: "tasks") @method(name: "task_summary")
+#   }
+class Lighthouse::GraphQL::DirectiveResolvers::WithDirectiveResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
+  def self.directive_name = 'with'
+
+  def self.definition
+    <<~GRAPHQL.chomp
+      """
+      Eager-load a relation of the parent before the field resolves, for every parent at once.
+      """
+      directive @with(
+        "The relation to load, nested with dots. Defaults to the field's name."
+        relation: String
+        "Model scopes that narrow the loaded records."
+        scopes: [String!]
+      ) repeatable on FIELD_DEFINITION
+    GRAPHQL
+  end
+
+  def define_resolver(target_type_class)
+    inner = capture_inner(target_type_class)
+    associations = Lighthouse::Support::Preload.associations(directive_arg('relation') || Lighthouse::Support::Naming.attribute(@field_def.name))
+    scopes = Array(directive_arg('scopes'))
+
+    install(target_type_class, lambda do |obj, args, ctx|
+      ctx.dataloader.with(Lighthouse::GraphQL::DataloaderSources::PreloadLoader, associations, scopes).load(obj) if obj.is_a?(::ActiveRecord::Base)
+      inner.call(obj, args, ctx)
+    end)
+  end
+end