lighthouse-graphql 0.6.0 → 0.7.0

data/lib/lighthouse/directive_resolvers/builder_applier.rb

@@ -2,8 +2,11 @@
 
 require_relative 'base'
 
-# The field-level query directives, in SDL order: @builder classes, and
-# @whereAuth, which keeps the records the signed-in user owns. @builder on an
+# The field-level query directives, in SDL order, as PHP Lighthouse's field
+# builder directives: @builder classes, @whereAuth, which keeps the records the
+# signed-in user owns, and the registry's FieldBuilder directives (@orderBy on a
+# field). They apply after the argument directives (apply_where_filters), so
+# a builder's order breaks the ties of the client's orderBy. @builder on an
 # argument is applied with the other argument directives (apply_argument).
 #
 # A builder is `class:` and `method:` (default `call`), or PHP Lighthouse's
@@ -52,15 +55,27 @@ class Lighthouse::GraphQL::DirectiveResolvers::BuilderApplier
   def self.apply(relation, field_def_ast_node, args, ctx, resolver_instance)
     return relation unless field_def_ast_node&.directives
 
-    field_def_ast_node.directives.each do |directive_node|
+    registry = Lighthouse::DirectiveRegistry.default
+    field_def_ast_node.directives.reduce(relation) do |acc, directive_node|
       case directive_node.name
-      when 'builder' then relation = apply_directive(relation, directive_node, args, ctx, resolver_instance)
-      when 'whereAuth' then relation = where_auth(relation, directive_node, ctx)
+      when 'builder' then apply_directive(acc, directive_node, args, ctx, resolver_instance)
+      when 'whereAuth' then where_auth(acc, directive_node, ctx)
+      else field_builder(registry, acc, field_def_ast_node, directive_node)
       end
     end
+  end
 
-    relation
+  # Does the field carry a query directive of its own?
+  def self.any?(field_def_ast_node)
+    registry = Lighthouse::DirectiveRegistry.default
+    (field_def_ast_node&.directives || []).any? { |d| DEFINITIONS.key?(d.name) || registry.field_builder_class(d.name) }
+  end
+
+  def self.field_builder(registry, relation, field_def_ast_node, directive_node)
+    builder_class = registry.field_builder_class(directive_node.name)
+    builder_class ? builder_class.new(field_def_ast_node, directive_node).handle_field_builder(relation) : relation
   end
+  private_class_method :field_builder
 
   # The records whose `relation:` links them to the signed-in user; none for a guest.
   def self.where_auth(relation, directive_node, ctx)

data/lib/lighthouse/directive_resolvers/count_resolver.rb

@@ -43,7 +43,6 @@ class Lighthouse::GraphQL::DirectiveResolvers::CountDirectiveResolver < Lighthou
 
     args_h = arguments.respond_to?(:to_h) ? arguments.to_h : {}
     relation = apply_scopes(relation)
-    relation = Lighthouse::GraphQL::DirectiveResolvers::BuilderApplier.apply(relation, @field_def.ast_node, args_h, ctx, self)
     relation = apply_where_filters(relation, args_h, ctx)
     relation.count
   end

data/lib/lighthouse/directive_resolvers/first_resolver.rb

@@ -14,7 +14,6 @@ class Lighthouse::GraphQL::DirectiveResolvers::FirstDirectiveResolver < Lighthou
     method_name = "resolve_field_#{@field_def.name}"
     model_name_static = directive_arg('model') || field_type_name
     resolver_instance = self
-    field_ast_node = @field_def.ast_node
 
     resolver = lambda do |_obj, arguments, ctx|
       model_class = resolver_instance.constantize_model(model_name_static)
@@ -22,7 +21,6 @@ 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, ctx)
       relation.first
     end

data/lib/lighthouse/directive_resolvers/paginate_resolver.rb

@@ -72,10 +72,9 @@ class Lighthouse::GraphQL::DirectiveResolvers::PaginateDirectiveResolver < Light
 
   public
 
-  # `scopes:`, @builder and the argument filters, on one relation or a RelationBatch.
+  # `scopes:`, the argument filters and @builder, 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, ctx)
+    apply_where_filters(apply_scopes(relation), args, ctx)
   end
 
   protected

data/lib/lighthouse/directives/arguments/order_by.rb

@@ -2,47 +2,211 @@
 
 require_relative 'base'
 
-# @orderBy — sort the result by one or more columns.
+# @orderBy, as PHP Lighthouse's: on an argument, the client orders the result
+# by one or more clauses; on a field, the result is always in that order.
 #
-# The client value is a list of clauses, each `{ column:, order: }`
-# (also accepts `{ field:, direction: }`). Clauses apply in order, so
-# `[{column: NAME, order: ASC}, {column: AGE, order: DESC}]` sorts by
-# name then age.
+#   type Query {
+#     posts(orderBy: _ @orderBy(columns: ["posted_at", "title"])): [Post!]! @all
+#     users(orderBy: _ @orderBy(relations: [{ relation: "posts" }])): [User!]! @all
+#     latestPosts: [Post!]! @all @orderBy(column: "posted_at", direction: DESC)
+#   }
+#
+#   { posts(orderBy: [{ column: POSTED_AT, order: DESC }, { column: TITLE, order: ASC }]) { title } }
+#   { users(orderBy: [{ posts: { aggregate: COUNT }, order: DESC }]) { name } }
+#
+# An argument written with the `_` placeholder gets the types generated for
+# it (Query.posts(orderBy:) -> [QueryPostsOrderByOrderByClause!]):
+#
+# - no `columns:` / `columnsEnum:` / `relations:`: the shared OrderByClause, any column;
+# - `columns:` / `columnsEnum:`: <QualifiedArgType>OrderByClause, its column one of the enum;
+# - `relations:`: <QualifiedArgType>RelationOrderByClause, whose clauses name
+#   either a column or a relation's aggregate (COUNT, or AVG/MIN/MAX/SUM of a column).
+#
+# A relation's aggregate is computed per record in a LEFT JOIN on a grouped
+# subquery, so records without related ones are ordered too (a COUNT of 0).
 class Lighthouse::GraphQL::Directives::Arguments::OrderBy < Lighthouse::GraphQL::Directives::Arguments::Base
+  include Lighthouse::Contracts::ArgManipulator
+  include Lighthouse::Contracts::FieldBuilder
+
+  # The Arel node of each OrderByRelation*AggregateFunction value (Arel::Nodes::<name>).
+  AGGREGATES = { 'count' => :Count, 'avg' => :Avg, 'min' => :Min, 'max' => :Max, 'sum' => :Sum }.freeze
+
+  DEFINITION = <<~GRAPHQL.chomp
+    """
+    Sort a result list by one or more given columns.
+    """
+    directive @orderBy(
+      """
+      Restrict the allowed column names to a well-defined list.
+      This improves introspection capabilities and security.
+      Mutually exclusive with `columnsEnum`.
+      Only used when the directive is added on an argument.
+      """
+      columns: [String!]
+
+      """
+      Use an existing enumeration type to restrict the allowed columns to a predefined list.
+      This allows you to re-use the same enum for multiple fields.
+      Mutually exclusive with `columns`.
+      Only used when the directive is added on an argument.
+      """
+      columnsEnum: String
+
+      """
+      Allow clients to sort by aggregates on relations.
+      Only used when the directive is added on an argument.
+      """
+      relations: [OrderByRelation!]
+
+      """
+      The database column for which the order by clause will be applied on.
+      Only used when the directive is added on a field.
+      """
+      column: String
+
+      """
+      The direction of the order by clause.
+      Only used when the directive is added on a field.
+      """
+      direction: OrderByDirection = ASC
+    ) on ARGUMENT_DEFINITION | FIELD_DEFINITION
+  GRAPHQL
+
+  TYPE_DEFINITIONS = {
+    'OrderByDirection' => <<~GRAPHQL.chomp,
+      """
+      Options for the `direction` argument of `@orderBy`.
+      """
+      enum OrderByDirection {
+        """
+        Sort in ascending order.
+        """
+        ASC
+
+        """
+        Sort in descending order.
+        """
+        DESC
+      }
+    GRAPHQL
+    'OrderByRelation' => <<~GRAPHQL.chomp
+      """
+      Options for the `relations` argument of `@orderBy`.
+      """
+      input OrderByRelation {
+        """
+        Name of the relation.
+        """
+        relation: String!
+
+        """
+        Restrict the allowed column names to a well-defined list.
+        This improves introspection capabilities and security.
+        Mutually exclusive with `columnsEnum`.
+        """
+        columns: [String!]
+
+        """
+        Use an existing enumeration type to restrict the allowed columns to a predefined list.
+        This allows you to re-use the same enum for multiple fields.
+        Mutually exclusive with `columns`.
+        """
+        columnsEnum: String
+      }
+    GRAPHQL
+  }.freeze
+
   def self.directive_name = 'orderBy'
-  def self.definition = 'directive @orderBy(columns: [String!], relations: [String!]) on ARGUMENT_DEFINITION | FIELD_DEFINITION'
+
+  def self.definition = DEFINITION
+
+  def self.type_definitions = TYPE_DEFINITIONS
+
+  # --- Schema: the argument's types (Lighthouse::OrderBy::Types) ------------
+
+  def manipulate_arg_definition(document_ast, field, type)
+    Lighthouse::OrderBy::Types.new(document_ast, @directive_node, @arg_node, field, type).argument
+  end
+
+  # --- Runtime --------------------------------------------------------------
 
   def handle_builder(relation, value)
-    normalize(value).reduce(relation) do |rel, clause|
-      col = Lighthouse::Support::Naming.column(clause[:column], rel)
-      next rel if col.blank?
+    Array(value).each_with_index.reduce(relation) { |ordered, (clause, index)| order_by(ordered, symbolized(clause), index) }
+  end
 
-      direction = clause[:order].to_s.downcase == 'desc' ? :desc : :asc
-      rel.order(col => direction)
-    end
+  # On a field: `column:` in `direction:`.
+  def handle_field_builder(relation)
+    column = Lighthouse::Support::DirectiveArgs.literal(@directive_node, 'column')
+    return relation unless column
+
+    direction = Lighthouse::Support::DirectiveArgs.literal(@directive_node, 'direction').to_s.casecmp?('DESC') ? :desc : :asc
+    relation.order(column_attribute(relation, column).public_send(direction))
   end
 
   private
 
-  def normalize(value)
-    list = value.is_a?(Array) ? value : [value]
-    list.filter_map { |item| clause(item) }
+  def relations
+    @relations ||= Array(Lighthouse::Support::DirectiveArgs.literal(@directive_node, 'relations')).map { |relation| relation.transform_keys(&:to_s) }
   end
 
-  # One `{ column:, order: }` clause, or nil when the item names no column.
-  def clause(item)
-    symbolized = symbolized_hash(item)
-    return nil unless symbolized
+  def order_by(relation, clause, index)
+    direction = clause[:order].to_s.casecmp?('DESC') ? :desc : :asc
+    aggregated = clause.except(:column, :order).compact
+    unless clause[:column].nil? ^ aggregated.empty?
+      raise ::GraphQL::ExecutionError, "An order by clause takes exactly one of: column, #{relations.pluck('relation').join(', ')}."
+    end
+    return relation.order(column_attribute(relation, clause[:column]).public_send(direction)) if clause[:column]
+
+    relation_name, aggregate = aggregated.first
+    order_by_aggregate(relation, relation_name, symbolized(aggregate), direction, index)
+  end
 
-    col = symbolized[:column] || symbolized[:field]
-    return nil if col.nil?
+  # LEFT JOIN (SELECT owner.id, AGGREGATE(related.column) FROM owner LEFT JOIN related ... GROUP BY owner.id)
+  # and ORDER BY the aggregate.
+  def order_by_aggregate(relation, relation_name, aggregate, direction, index)
+    owner = relation.klass
+    reflection = reflection(owner, relation_name)
+    key = owner.arel_table[owner.primary_key]
+    table = ::Arel::Table.new("lighthouse_order_#{index}_#{reflection.name}")
+    totals = owner.unscoped.left_joins(reflection.name).group(key)
+                  .select(key.as('lighthouse_key'), aggregate_node(reflection.klass, aggregate).as('lighthouse_aggregate'))
+
+    relation.joins(left_join(owner, totals, table, key)).order(table[:lighthouse_aggregate].public_send(direction))
+  end
+
+  def left_join(owner, totals, table, key)
+    subquery = ::Arel::Nodes::TableAlias.new(::Arel::Nodes::Grouping.new(totals.arel), table.name)
+    owner.arel_table.join(subquery, ::Arel::Nodes::OuterJoin).on(table[:lighthouse_key].eq(key)).join_sources
+  end
+
+  def aggregate_node(related, aggregate)
+    function = aggregate[:aggregate].to_s.downcase
+    ::Arel::Nodes.const_get(AGGREGATES.fetch(function)).new([aggregated_attribute(related, function, aggregate[:column])])
+  end
+
+  # COUNT counts the related records (their primary key); the other aggregates need a column.
+  def aggregated_attribute(related, function, column)
+    return column_attribute(related.all, column, as: function == 'count' ? :sort : :numeric) if column
+    raise ::GraphQL::ExecutionError, "Ordering by the #{function.upcase} of a relation needs a column." unless function == 'count'
+
+    related.arel_table[related.primary_key]
+  end
+
+  def reflection(owner, name)
+    candidates = [name.to_s, name.to_s.camelize(:lower), name.to_s.underscore].uniq
+    configured = relations.pluck('relation')
+    found = candidates.find { |candidate| configured.include?(candidate) } || name.to_s
+    owner.reflect_on_association(found.to_sym) || owner.reflect_on_association(found.underscore.to_sym) ||
+      raise(Lighthouse::DefinitionError, "@orderBy(relations:): #{owner.name} has no relation #{found}")
+  end
 
-    { column: col, order: symbolized[:order] || symbolized[:direction] || 'ASC' }
+  # A JSON path orders by its JSON value; an aggregate takes it as a number.
+  def column_attribute(relation, column, as: :sort)
+    Lighthouse::WhereConditions::Columns.attribute(relation.klass, column, as: as)
   end
 
-  # The item as a symbol-keyed hash, or nil when it is not hash-like.
-  def symbolized_hash(item)
-    hash = item.respond_to?(:to_h) ? item.to_h : item
-    hash.transform_keys { |k| k.to_s.to_sym } if hash.is_a?(Hash)
+  def symbolized(value)
+    hash = value.respond_to?(:to_h) ? value.to_h : value
+    hash.is_a?(Hash) ? hash.transform_keys { |key| key.to_s.underscore.to_sym } : {}
   end
 end

data/lib/lighthouse/directives/arguments/where_conditions.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'where_conditions_base'
+
+# @whereConditions: the client's conditions on the field's records.
+#
+#   people(where: _ @whereConditions(columns: ["age", "type"])): [Person!]! @all
+#   { people(where: { column: AGE, operator: GT, value: 37 }) { name } }
+class Lighthouse::GraphQL::Directives::Arguments::WhereConditions < Lighthouse::GraphQL::Directives::Arguments::WhereConditionsBase
+  SUFFIX = 'WhereConditions'
+  DESCRIPTION = 'Filter results by field conditions.'
+
+  DEFINITION = <<~GRAPHQL.chomp
+    """
+    Add a dynamically client-controlled WHERE condition to a fields query.
+    """
+    directive @whereConditions(
+    #{COLUMN_ARGUMENTS.gsub(/^/, '  ')}
+    ) on ARGUMENT_DEFINITION
+  GRAPHQL
+
+  def self.directive_name = 'whereConditions'
+
+  def self.definition = DEFINITION
+end

data/lib/lighthouse/directives/arguments/where_conditions_base.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# What @whereConditions and @whereHasConditions share, as PHP Lighthouse's
+# WhereConditionsBaseDirective: an argument written with the `_` placeholder
+# gets the input types the directive generates (Lighthouse::WhereConditions::Types),
+# and the client's value becomes WHERE conditions on the field's query
+# (Lighthouse::WhereConditions::Handler).
+#
+#   type Query {
+#     people(where: _ @whereConditions(columns: ["age", "type"])): [Person!]! @all
+#     users(hasPosts: _ @whereHasConditions(columns: ["title"])): [User!]! @all
+#   }
+#
+# `columns:` restricts the columns to an enum generated from them,
+# `columnsEnum:` to an enum of the schema's; without either the column is any
+# identifier the client sends.
+class Lighthouse::GraphQL::Directives::Arguments::WhereConditionsBase < Lighthouse::GraphQL::Directives::Arguments::Base
+  include Lighthouse::Contracts::ArgManipulator
+
+  GeneratedTypes = Lighthouse::GraphQL::Directives::GeneratedTypes
+
+  COLUMN_ARGUMENTS = <<~GRAPHQL.chomp
+    """
+    Restrict the allowed column names to a well-defined list.
+    This improves introspection capabilities and security.
+    Mutually exclusive with `columnsEnum`.
+    """
+    columns: [String!]
+
+    """
+    Use an existing enumeration type to restrict the allowed columns to a predefined list.
+    This allows you to re-use the same enum for multiple fields.
+    Mutually exclusive with `columns`.
+    """
+    columnsEnum: String
+
+    """
+    A class that applies the client given conditions to the query: `call(relation, conditions)`
+    answers the relation. "Class@method" names another method. Looked up in the builders namespaces.
+    """
+    handler: String
+  GRAPHQL
+
+  # The argument, typed with the conditions input generated for it.
+  def manipulate_arg_definition(document_ast, field, type)
+    path = "the `#{@arg_node.name}` argument of #{type.name}.#{field.name}"
+    arg = GeneratedTypes.describe(@arg_node, self.class::DESCRIPTION)
+    types = Lighthouse::WhereConditions::Types
+    unless GeneratedTypes.allowed_columns?(@directive_node)
+      types.define_default(document_ast)
+      return GeneratedTypes.replace_placeholder(arg, types::DEFAULT)
+    end
+
+    name = GeneratedTypes.qualified_arg_type(@arg_node, field, type) + self.class::SUFFIX
+    types.define(document_ast, name, GeneratedTypes.columns_enum(document_ast, @directive_node, @arg_node, field, type), path)
+    GeneratedTypes.replace_placeholder(arg, name)
+  end
+
+  def handle_builder(relation, value)
+    return relation if value.nil?
+
+    handler.call(relation, conditions(value)) || relation
+  end
+
+  private
+
+  def conditions(value) = value
+
+  # Lighthouse::WhereConditions::Handler, or the class (or instance) `handler:` names.
+  def handler
+    reference = Lighthouse::Support::DirectiveArgs.literal(@directive_node, 'handler')
+    return Lighthouse::WhereConditions::Handler unless reference
+
+    class_name, method_name = reference.to_s.split('@', 2)
+    klass = Lighthouse::Support::ModelResolver.constantize(class_name, namespaces: Lighthouse::Config.namespaces[:builders])
+    raise Lighthouse::DefinitionError, "@#{@directive_node.name}(handler: \"#{reference}\"): no class #{class_name}" unless klass
+
+    method_name = method_name.presence || 'call'
+    receiver = klass.respond_to?(method_name) ? klass : klass.new
+    receiver.method(method_name)
+  end
+end

data/lib/lighthouse/directives/arguments/where_has_conditions.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'where_conditions_base'
+
+# @whereHasConditions: the records with a related record matching the
+# client's conditions.
+#
+#   users(hasPosts: _ @whereHasConditions(columns: ["title"])): [User!]! @all
+#   { users(hasPosts: { column: TITLE, value: "Notes" }) { name } }
+class Lighthouse::GraphQL::Directives::Arguments::WhereHasConditions < Lighthouse::GraphQL::Directives::Arguments::WhereConditionsBase
+  SUFFIX = 'WhereHasConditions'
+  DESCRIPTION = 'Filter results by related records conditions.'
+
+  DEFINITION = <<~GRAPHQL.chomp
+    """
+    Allows clients to filter a query based on the existence of a related model, using
+    a dynamically controlled `WHERE` condition that applies to the relationship.
+    """
+    directive @whereHasConditions(
+      """
+      The relationship that the conditions will be applied to.
+      This argument can be omitted if the argument name follows the naming
+      convention `has{$RELATION}`. For example, if the relationship
+      is named `posts`, the argument name must be `hasPosts`.
+      """
+      relation: String
+
+    #{COLUMN_ARGUMENTS.gsub(/^/, '  ')}
+    ) on ARGUMENT_DEFINITION
+  GRAPHQL
+
+  def self.directive_name = 'whereHasConditions'
+
+  def self.definition = DEFINITION
+
+  private
+
+  # The records with at least one related record matching the value (`{}`: any related record).
+  def conditions(value)
+    condition = value.respond_to?(:to_h) ? value.to_h : value
+    {
+      has: {
+        relation: relation_name,
+        operator: Lighthouse::WhereConditions::Types::DEFAULT_HAS_OPERATOR,
+        amount: Lighthouse::WhereConditions::Types::DEFAULT_HAS_AMOUNT,
+        condition: condition.presence
+      }
+    }
+  end
+
+  # `relation:`, else the argument name without its `has` prefix: hasPosts -> posts.
+  def relation_name
+    Lighthouse::Support::DirectiveArgs.literal(@directive_node, 'relation') ||
+      @arg_node.name.sub(/\Ahas(?=[A-Z_])/, '').then { |name| name[0].downcase + name[1..] }
+  end
+end

data/lib/lighthouse/directives/definitions.rb

@@ -31,7 +31,6 @@ module Lighthouse::GraphQL::Directives::Definitions
       graphql::Directives::NodeDirective::DEFINITIONS,
       graphql::Directives::ModelDirective::DEFINITIONS,
       graphql::Directives::VisibilityDirective::DEFINITIONS,
-      graphql::Directives::WhereConditionsDirective::DEFINITIONS,
       graphql::Directives::SoftDeletesDirective::DEFINITIONS
     ].reduce(:merge)
   end

data/lib/lighthouse/directives/generated_types.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# What the argument manipulators that generate types share, as PHP
+# Lighthouse's ASTHelper and GeneratesColumnsEnum: the qualified name of an
+# argument's types, the enum of its allowed columns, and the `_` placeholder
+# the argument is written with.
+#
+#   type Query { posts(orderBy: _ @orderBy(columns: ["posted_at"])): [Post!]! @all }
+#
+# names Query.posts(orderBy:)'s types QueryPostsOrderBy..., its columns enum
+# QueryPostsOrderByColumn { POSTED_AT @enum(value: "posted_at") }.
+module Lighthouse::GraphQL::Directives::GeneratedTypes
+  PLACEHOLDER = '_'
+
+  module_function
+
+  # Studly(Type) + Studly(field) + Studly(argument): QueryPostsOrderBy.
+  def qualified_arg_type(arg, field, type)
+    [type.name, field.name, arg.name].map { |name| studly(name) }.join
+  end
+
+  def studly(name)
+    name.to_s.split(/[_\s-]+/).map { |part| part[0].to_s.upcase + part[1..].to_s }.join
+  end
+
+  # `argument` of the directive as a Ruby value (`columns: ["a"]` -> ["a"]), or nil.
+  def directive_value(directive, name)
+    Lighthouse::Support::DirectiveArgs.literal(directive, name)
+  end
+
+  def directive_argument?(directive, name)
+    directive.arguments.any? { |argument| argument.name == name }
+  end
+
+  # Raises unless at most one of `names` is given to the directive.
+  def mutually_exclusive!(directive, names)
+    given = names.select { |name| directive_argument?(directive, name) }
+    return if given.size <= 1
+
+    raise Lighthouse::DefinitionError,
+          "The @#{directive.name} directive can only have one of the following arguments: #{names.map { |n| "`#{n}`" }.join(', ')}."
+  end
+
+  # Does the directive restrict the columns (`columns:` or `columnsEnum:`)?
+  def allowed_columns?(directive)
+    mutually_exclusive!(directive, %w[columns columnsEnum])
+    directive_argument?(directive, 'columns') || directive_argument?(directive, 'columnsEnum')
+  end
+
+  # The enum of the allowed columns: `columnsEnum:`, or one generated from
+  # `columns:` as <QualifiedArgType>Column.
+  def columns_enum(document_ast, directive, arg, field, type)
+    enum = directive_value(directive, 'columnsEnum')
+    return enum if enum
+
+    name = "#{qualified_arg_type(arg, field, type)}Column"
+    define_columns_enum(document_ast, name, directive_value(directive, 'columns'), "#{type.name}.#{field.name}.#{arg.name}")
+    name
+  end
+
+  def define_columns_enum(document_ast, name, columns, path)
+    values = Array(columns).map { |column| %(  #{enum_value_name(column)} @enum(value: "#{column}")) }.uniq
+    document_ast.put_type(parse(<<~GRAPHQL))
+      "Allowed column names for #{path}."
+      enum #{name} {
+      #{values.join("\n")}
+      }
+    GRAPHQL
+  end
+
+  # `posted_at` -> POSTED_AT, `roles.id` -> ROLES_ID.
+  def enum_value_name(column)
+    name = column.to_s.gsub(/[^0-9A-Za-z_]/, '_').upcase
+    name.match?(/\A[0-9]/) ? "_#{name}" : name
+  end
+
+  # The argument with its type replaced by `type_string` ("[QueryPostsOrderByClause!]"),
+  # when it is written with the `_` placeholder. An argument given a type of
+  # its own keeps it.
+  def replace_placeholder(arg, type_string)
+    return arg unless placeholder?(arg.type)
+
+    arg.merge(type: parse_type(type_string))
+  end
+
+  def placeholder?(type)
+    type = type.of_type while type.respond_to?(:of_type)
+    type.name == PLACEHOLDER
+  end
+
+  # The argument with `description`, unless it has one.
+  def describe(arg, description)
+    arg.description.to_s.empty? ? arg.merge(description: description) : arg
+  end
+
+  def parse(sdl)
+    ::GraphQL::Language::Parser.parse(sdl).definitions.first
+  end
+
+  def parse_type(type_string)
+    parse("input LighthouseTypeReference { field: #{type_string} }").fields.first.type
+  end
+end