lighthouse-graphql 0.1.0 → 0.2.0

data/lib/lighthouse/graphql_ruby_patches.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Lighthouse::GraphQL
+  # graphql-ruby (2.5/2.6) hands a directive application's `null` literal —
+  # `@paginate(maxCount: null)` — to the directive as a NullValue node instead
+  # of nil, and building the schema then fails to coerce it. Its own
+  # build_default_value already maps NullValue to nil; do the same here.
+  module NullDirectiveArguments
+    def args_to_kwargs(arg_owner, node)
+      node.is_a?(::GraphQL::Language::Nodes::NullValue) ? nil : super
+    end
+  end
+
+  # The builder is a private constant; if a graphql-ruby release reshapes it,
+  # skip the fix rather than fail to load (explicit nulls then fail as before).
+  builder = ::GraphQL::Schema::BuildFromDefinition.const_get(:Builder) if ::GraphQL::Schema::BuildFromDefinition.const_defined?(:Builder)
+  builder.prepend(NullDirectiveArguments) if builder && (builder.method_defined?(:args_to_kwargs) || builder.private_method_defined?(:args_to_kwargs))
+end

data/lib/lighthouse/ide_helper.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+# Writes the SDL an IDE needs to understand a Lighthouse schema, mirroring PHP
+# Lighthouse's `lighthouse:ide-helper`:
+#
+# - schema-directives.graphql — a definition for every registered directive
+#   (built-in and app-registered) the app's SDL does not declare itself, so
+#   the IDE can validate and autocomplete them.
+# - programmatic-types.graphql — the types the manipulation phase generates
+#   (Connection/Edge/Paginator types, PaginatorInfo, whereConditions inputs,
+#   ...), which exist in the executable schema but in no .graphql file.
+#
+# Point your IDE's graphql-config at both files next to your own SDL. Run it
+# with `bin/rails lighthouse:ide_helper`.
+module Lighthouse::IdeHelper
+  DIRECTIVES_FILE = 'schema-directives.graphql'
+  PROGRAMMATIC_TYPES_FILE = 'programmatic-types.graphql'
+
+  TYPE_DEFINITIONS = [
+    ::GraphQL::Language::Nodes::ObjectTypeDefinition,
+    ::GraphQL::Language::Nodes::InputObjectTypeDefinition,
+    ::GraphQL::Language::Nodes::InterfaceTypeDefinition,
+    ::GraphQL::Language::Nodes::UnionTypeDefinition,
+    ::GraphQL::Language::Nodes::EnumTypeDefinition,
+    ::GraphQL::Language::Nodes::ScalarTypeDefinition
+  ].freeze
+
+  PLACEHOLDER_SCALAR = %("Placeholder for an argument type Lighthouse generates, e.g. with @whereConditions."\nscalar _)
+
+  module_function
+
+  # Writes both files into `output_dir` and returns their paths.
+  def write(output_dir:, sdl_folder: Lighthouse::Config.sdl_folder, registry: Lighthouse::DirectiveRegistry.default)
+    sdl = sdl_folder && Dir.exist?(sdl_folder.to_s) ? Lighthouse::GraphQL::SDLLoader.load_from_folder(sdl_folder.to_s) : ''
+
+    FileUtils.mkdir_p(output_dir.to_s)
+    {
+      DIRECTIVES_FILE => directives_sdl(sdl, registry: registry),
+      PROGRAMMATIC_TYPES_FILE => programmatic_types_sdl(sdl, registry: registry)
+    }.map do |name, content|
+      path = File.join(output_dir.to_s, name)
+      File.write(path, content)
+      path
+    end
+  end
+
+  def directives_sdl(sdl = '', registry: Lighthouse::DirectiveRegistry.default)
+    generator = Lighthouse::GraphQL::SchemaGenerator
+    definitions = generator.missing_directive_definitions(sdl, registry: registry).sort.map { |_, definition| definition }
+    types = generator.missing_type_definitions(sdl, definitions, registry: registry).sort.map { |_, definition| definition }
+    render(
+      'Directive definitions contributed by Lighthouse and the directives your app registered.',
+      definitions + types
+    )
+  end
+
+  def programmatic_types_sdl(sdl, registry: Lighthouse::DirectiveRegistry.default)
+    original = type_names(sdl)
+    generated = parse(registry.manipulate_sdl(sdl)).definitions.select do |definition|
+      type_definition?(definition) && original.exclude?(definition.name)
+    end
+    generated_sdl = generated.sort_by(&:name).map(&:to_query_string)
+    generated_sdl.unshift(PLACEHOLDER_SCALAR) if undeclared_placeholder?(sdl, original, generated)
+
+    render(
+      'Types the manipulation phase generates (Connection/Paginator types, whereConditions inputs, ...).',
+      generated_sdl
+    )
+  end
+
+  # The manipulation phase replaces the `_` placeholder (`where: _ @whereConditions`),
+  # but the IDE reads the SDL as written, so it needs the placeholder declared.
+  def undeclared_placeholder?(sdl, original, generated)
+    sdl.to_s.match?(/:\s*\[?\s*_\b/) && original.exclude?('_') && generated.none? { |d| d.name == '_' }
+  end
+
+  def type_names(sdl)
+    parse(sdl).definitions.filter_map { |definition| definition.name if type_definition?(definition) }.to_set
+  end
+
+  def type_definition?(definition)
+    TYPE_DEFINITIONS.any? { |kind| definition.is_a?(kind) }
+  end
+
+  def parse(sdl)
+    ::GraphQL::Language::Parser.parse(sdl.to_s)
+  end
+
+  def render(summary, definitions)
+    header = <<~GRAPHQL
+      # Generated by `bin/rails lighthouse:ide_helper` — do not edit; rerun it after changing your schema.
+      # #{summary}
+    GRAPHQL
+    "#{header}\n#{definitions.join("\n\n")}\n"
+  end
+end

data/lib/lighthouse/namespaces.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# The namespaces the library's files live in. Every other file opens its class
+# or module compactly (`class Lighthouse::GraphQL::DirectiveResolvers::Base`),
+# which needs the enclosing namespaces to exist already, so they are defined
+# here, first.
+module Lighthouse
+  module Contracts; end
+  module Generators; end
+  module Support; end
+  module WhereConditions; end
+
+  module GraphQL
+    module DataloaderSources; end
+    module DirectiveResolvers; end
+
+    module Directives
+      module Arguments; end
+    end
+  end
+end

data/lib/lighthouse/nested_mutations/belongs_to_operations.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# belongsTo / morphTo operations: they set the foreign keys (and morph type)
+# of the record being saved, so they run before it is saved.
+module Lighthouse::GraphQL::NestedMutations::BelongsToOperations
+  private
+
+  def nest_belongs_to(record, reflection, operations, deferred_deletes)
+    association = record.association(reflection.name)
+    in_order(reflection, operations).each do |name, operation|
+      case name
+      when 'create', 'update', 'upsert' then association.writer(write(name, reflection.klass, operation.input, operation))
+      when 'connect' then connect_owner(record, reflection, operation.plain)
+      when 'disconnect' then association.writer(nil) if operation.truthy?
+      when 'delete' then delete_owner(record, reflection, operation, deferred_deletes)
+      end
+    end
+  end
+
+  def connect_owner(record, reflection, value)
+    if reflection.polymorphic?
+      model = morph_model(value[:type])
+      record[reflection.foreign_type] = model.polymorphic_name
+      record[reflection.foreign_key] = value[:id]
+    else
+      record[reflection.foreign_key] = value
+    end
+  end
+
+  # Unlinks the related record now and destroys it only after the record,
+  # no longer pointing at it, is saved (see Executor#save).
+  def delete_owner(record, reflection, operation, deferred_deletes)
+    return unless operation.truthy?
+
+    related = record.public_send(reflection.name)
+    record.association(reflection.name).writer(nil)
+    deferred_deletes << related if related
+  end
+
+  # The model a morphTo `connect` names: a class name, resolved like any
+  # model name, or an enum value such as TASK for Task.
+  def morph_model(type)
+    [type, type.to_s.downcase.camelize].uniq.each do |name|
+      model = Lighthouse::Support::ModelResolver.constantize(name)
+      return model if model.is_a?(Class) && model < ::ActiveRecord::Base
+    end
+
+    raise ::GraphQL::ExecutionError, "Unknown type #{type} to connect."
+  end
+end

data/lib/lighthouse/nested_mutations/executor.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+# Saves records from nested input: create, update and upsert each save one
+# record, running the operations its input carries on its associations.
+class Lighthouse::GraphQL::NestedMutations::Executor
+  include Lighthouse::GraphQL::NestedMutations::BelongsToOperations
+  include Lighthouse::GraphQL::NestedMutations::HasOperations
+  include Lighthouse::GraphQL::NestedMutations::ManyToManyOperations
+
+  def initialize(field_name)
+    @field_name = field_name
+  end
+
+  def create(model, input, link: nil)
+    save(model.new, partition(model, input), link)
+  end
+
+  def update(model, input, link: nil)
+    part = partition(model, input)
+    key, id = part.take_key(model)
+    raise ::GraphQL::ExecutionError, Lighthouse::GraphQL::NestedMutations::MISSING_PRIMARY_KEY if key.nil? || id.nil?
+
+    part.attributes.delete(key)
+    save(find!(model, id), part, link)
+  end
+
+  # The record identified by `identifying` columns, else by primary key,
+  # else `fallback`, else a new one — created with the given id, if any.
+  def upsert(model, input, link: nil, identifying: nil, fallback: nil)
+    part = partition(model, input)
+    record = identifying.nil? ? nil : find_identified(model, part, identifying)
+    record ||= find_by_given_key(model, part)
+    save(record || fallback || model.new, part, link)
+  end
+
+  def find!(model, id)
+    model.find_by(model.primary_key => id) ||
+      raise(::GraphQL::ExecutionError, "Couldn't find #{model.name} with '#{model.primary_key}'=#{id}")
+  end
+
+  # Assign, run the operations that set this record's foreign keys, save
+  # once, then run the operations on associations pointing back at it.
+  def save(record, part, link = nil)
+    record.assign_attributes(part.attributes)
+    deferred_deletes = []
+    before, after = part.operations.partition { |reflection, _| owner_side?(reflection) }
+
+    before.each { |reflection, operations| nest_belongs_to(record, reflection, operations, deferred_deletes) }
+    link&.before_save(record)
+    persist!(record, part.paths)
+    link&.after_save(record)
+    deferred_deletes.each(&:destroy!)
+    after.each { |reflection, operations| dependents(record, reflection, operations) }
+
+    part.operations.each_key { |reflection| record.association(reflection.name).reset }
+    record
+  end
+
+  def persist!(record, paths)
+    return record if record.save
+
+    messages = {}
+    record.errors.each do |error|
+      path = error.attribute == :base ? base_path(paths) : paths[error.attribute.to_s]
+      (messages[path] ||= []) << error.full_message
+    end
+    raise Lighthouse::ValidationError.new(@field_name, messages)
+  end
+
+  private
+
+  def partition(model, input)
+    Lighthouse::GraphQL::NestedMutations::Partitioner.new(model, input).call
+  end
+
+  def base_path(paths)
+    prefix = paths.default_proc.call({}, '').delete_suffix('.')
+    prefix.empty? ? @field_name : prefix
+  end
+
+  def find_identified(model, part, columns)
+    raise Lighthouse::DefinitionError, "@upsert's identifyingColumns must not be empty." if columns.empty?
+
+    values = columns.to_h { |column| [column.to_s, part.attributes[column.to_s]] }
+    raise ::GraphQL::ExecutionError, Lighthouse::GraphQL::NestedMutations::MISSING_IDENTIFYING_COLUMNS if values.values.any?(&:nil?)
+
+    model.find_by(values)
+  end
+
+  # The record the input's primary key (`id`, or the model's own) names. A
+  # blank key is dropped so the database assigns one; a key no record has
+  # becomes the new record's primary key.
+  def find_by_given_key(model, part)
+    key, id = part.take_key(model)
+    return nil if key.nil?
+
+    if id.nil? || id.to_s.empty?
+      part.attributes.delete(key)
+      return nil
+    end
+
+    record = model.find_by(model.primary_key => id)
+    part.attributes[model.primary_key] = part.attributes.delete(key) if record.nil? && key != model.primary_key
+    record
+  end
+
+  # ----------------------------------------------------------------------
+  # Operations (the relation kinds' own are in the *Operations modules)
+
+  def kind(reflection)
+    Lighthouse::GraphQL::NestedMutations.kind(reflection)
+  end
+
+  def owner_side?(reflection)
+    %i[belongs_to morph_to].include?(kind(reflection))
+  end
+
+  def dependents(record, reflection, operations)
+    case kind(reflection)
+    when :has_one then nest_has_one(record, reflection, operations)
+    when :has_many then nest_has_many(record, reflection, operations)
+    when :many_to_many then nest_many_to_many(record, reflection, operations)
+    end
+  end
+
+  # PHP Lighthouse's fixed order, whatever order the client wrote them in.
+  def in_order(reflection, operations)
+    Lighthouse::GraphQL::NestedMutations::OPERATIONS.fetch(kind(reflection)).filter_map do |name|
+      [name, operations[name]] if operations[name]
+    end
+  end
+
+  # The create, update or upsert operation `name` on one input; an upsert
+  # that identifies no record falls back to the one the block returns.
+  def write(name, model, input, operation, link: nil)
+    case name
+    when 'create' then create(model, input, link: link)
+    when 'update' then update(model, input, link: link)
+    when 'upsert'
+      fallback = yield if block_given?
+      # rubocop:disable-next Rails/SkipsModelValidations -- Executor#upsert, not ActiveRecord's: it saves through validations.
+      upsert(model, input, link: link, identifying: operation.identifying, fallback: fallback)
+    end
+  end
+
+  def write_each(name, model, operation, link)
+    operation.inputs.each { |input| write(name, model, input, operation, link: link) }
+  end
+end

data/lib/lighthouse/nested_mutations/has_operations.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# hasOne / morphOne and hasMany / morphMany operations: their records point
+# back at the saved owner, so they run after it is saved.
+module Lighthouse::GraphQL::NestedMutations::HasOperations
+  BOOLEANS = [true, false].freeze
+
+  private
+
+  def nest_has_one(record, reflection, operations)
+    model = reflection.klass
+    link = Lighthouse::GraphQL::NestedMutations::HasLink.new(record, reflection)
+    existing = -> { record.association(reflection.name).scope.first }
+
+    in_order(reflection, operations).each do |name, operation|
+      case name
+      when 'create'
+        refuse_second_child!(record, model, existing.call)
+        create(model, operation.input, link: link)
+      # An upsert that identifies no record updates the current one, if any.
+      when 'update', 'upsert' then write(name, model, operation.input, operation, link: link) { existing.call }
+      when 'delete' then delete_child(model, operation, existing)
+      end
+    end
+  end
+
+  def refuse_second_child!(record, model, existing)
+    return unless existing
+
+    raise ::GraphQL::ExecutionError,
+          "Cannot create a related model: a #{model.name.demodulize} already exists for this " \
+          "#{record.class.name.demodulize}. Use upsert to modify the existing model."
+  end
+
+  # An ID, or — as for any single relation — a Boolean meaning "the current one".
+  def delete_child(model, operation, existing)
+    if BOOLEANS.include?(operation.value)
+      existing.call&.destroy! if operation.value
+    else
+      model.where(model.primary_key => operation.plain).destroy_all
+    end
+  end
+
+  def nest_has_many(record, reflection, operations)
+    model = reflection.klass
+    link = Lighthouse::GraphQL::NestedMutations::HasLink.new(record, reflection)
+
+    in_order(reflection, operations).each do |name, operation|
+      case name
+      when 'create', 'update', 'upsert' then write_each(name, model, operation, link)
+      when 'connect' then relink(model, operation) { |child| link.before_save(child) }
+      when 'disconnect' then relink(model, operation) { |child| child[reflection.foreign_key] = nil }
+      when 'delete' then model.where(model.primary_key => operation.plain).destroy_all
+      end
+    end
+  end
+
+  # Re-points (or detaches) the existing children the operation names, and
+  # saves each through its validations, errors keyed by the operation's path.
+  def relink(model, operation)
+    model.where(model.primary_key => operation.plain).each do |child|
+      yield child
+      persist!(child, Hash.new { operation.path.join('.') })
+    end
+  end
+end

data/lib/lighthouse/nested_mutations/many_to_many_operations.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# belongsToMany / morphToMany operations: they run after the owner is saved
+# and change its join records (Lighthouse::GraphQL::NestedMutations::Pivot).
+module Lighthouse::GraphQL::NestedMutations::ManyToManyOperations
+  private
+
+  def nest_many_to_many(record, reflection, operations)
+    model = reflection.klass
+    pivot = Lighthouse::GraphQL::NestedMutations::Pivot.new(record, reflection)
+    link = Lighthouse::GraphQL::NestedMutations::AttachLink.new(pivot)
+
+    in_order(reflection, operations).each do |name, operation|
+      case name
+      when 'create', 'update', 'upsert' then write_each(name, model, operation, link)
+      when 'delete'
+        pivot.detach(operation.plain)
+        model.where(model.primary_key => operation.plain).destroy_all
+      else link_pivot(pivot, name, operation)
+      end
+    end
+    pivot.reset
+  end
+
+  # The operations that only add or remove join records.
+  def link_pivot(pivot, name, operation)
+    case name
+    when 'sync' then pivot.sync(pairs(operation), detaching: true)
+    when 'syncWithoutDetaching' then pivot.sync(pairs(operation), detaching: false)
+    when 'connect' then pairs(operation).each { |id, values| pivot.attach(id, values) }
+    when 'disconnect' then pivot.detach(operation.plain)
+    end
+  end
+
+  # [[id, pivot values], ...] from a list of IDs or of { id, ...pivot } inputs.
+  def pairs(operation)
+    Array(operation.plain).map do |item|
+      next [item, {}] unless item.is_a?(Hash)
+
+      values = item.transform_keys(&:to_s)
+      [values.delete('id'), values]
+    end
+  end
+end

data/lib/lighthouse/nested_mutations/partitioner.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# Splits one record's input into attributes and the operations on its
+# associations (a Lighthouse::GraphQL::NestedMutations::Partition).
+class Lighthouse::GraphQL::NestedMutations::Partitioner
+  def initialize(model, input)
+    @model = model
+    @input = input
+  end
+
+  def call
+    @part = Lighthouse::GraphQL::NestedMutations::Partition.new(argument_paths(@input.argument_defs, @input.path))
+    walk(@input)
+    @part
+  end
+
+  private
+
+  def walk(input)
+    by_keyword = Lighthouse::Support::Arguments.keyword_index(input.argument_defs)
+    input.args.each_pair do |key, value|
+      argument = by_keyword[key.to_sym]
+      path = input.path + [argument ? argument.graphql_name : key.to_s.camelize(:lower)]
+      attribute = (argument && renamed(argument)) || key.to_s
+      assign(attribute, value, path) unless argument && nest(argument, attribute, value, path)
+    end
+  end
+
+  # Takes the value of a @spread argument, of a nested operation argument
+  # (@create(relation:) ...) or of an association's operations; false when
+  # it is a plain attribute. A null for any of those is no operation at all.
+  def nest(argument, attribute, value, path)
+    if Lighthouse::Support::Arguments.spread?(argument)
+      walk(spread_input(argument, value, path)) unless value.nil?
+    elsif (directive = nested_directive(argument))
+      add_argument_operation(directive, attribute, Lighthouse::GraphQL::NestedMutations::Operation.new(value, argument, path))
+    elsif (reflection = relation_argument(attribute, argument))
+      @part.add(reflection, operations(reflection, argument, value, path)) unless value.nil?
+    else
+      return false
+    end
+    true
+  end
+
+  # A @spread input object is walked as if its fields were the parent's.
+  def spread_input(argument, value, path)
+    Lighthouse::GraphQL::NestedMutations::Input.new(Lighthouse::Support::Arguments.shallow(value), argument.type.unwrap.arguments, path)
+  end
+
+  def assign(attribute, value, path)
+    @part.attributes[attribute] = Lighthouse::Support::Arguments.plain(value)
+    @part.paths[attribute] ||= path.join('.')
+  end
+
+  # An argument with @create/@update/@upsert/@delete is one operation on the
+  # association its `relation:` names, else the one the argument is named after.
+  def add_argument_operation(directive, attribute, operation)
+    return if operation.value.nil?
+
+    reflection = reflection!(Lighthouse::Support::DirectiveArgs.literal(directive, 'relation') || attribute)
+    operation.identifying = identifying_columns(directive)
+    @part.add(reflection, Lighthouse::GraphQL::NestedMutations::ARGUMENT_DIRECTIVES[directive.name] => operation)
+  end
+
+  # @upsert(identifyingColumns:) — nil when the directive does not set them.
+  def identifying_columns(directive)
+    return nil unless directive.arguments.any? { |a| a.name == 'identifyingColumns' }
+
+    Array(Lighthouse::Support::DirectiveArgs.literal(directive, 'identifyingColumns'))
+  end
+
+  # An association-named argument whose type is an input object of operations.
+  def relation_argument(attribute, argument)
+    return nil unless argument.type.unwrap.kind.input_object?
+    return nil unless @model.respond_to?(:reflect_on_association)
+
+    @model.reflect_on_association(attribute.to_sym)
+  end
+
+  def operations(reflection, argument, value, path)
+    kind = Lighthouse::GraphQL::NestedMutations.kind(reflection)
+    allowed = Lighthouse::GraphQL::NestedMutations::OPERATIONS.fetch(kind)
+    by_keyword = Lighthouse::Support::Arguments.keyword_index(argument.type.unwrap.arguments)
+    Lighthouse::Support::Arguments.shallow(value).each_with_object({}) do |(key, operation_value), out|
+      next if operation_value.nil?
+
+      operation_argument = by_keyword[key.to_sym]
+      name = operation_argument&.graphql_name || key.to_s.camelize(:lower)
+      unless allowed.include?(name)
+        raise Lighthouse::DefinitionError,
+              "#{name} is not a nested operation on #{@model}##{reflection.name} (#{kind}): use #{allowed.join(', ')}."
+      end
+
+      out[name] = Lighthouse::GraphQL::NestedMutations::Operation.new(operation_value, operation_argument, path + [name])
+    end
+  end
+
+  def nested_directive(argument)
+    (argument.ast_node&.directives || []).find { |d| Lighthouse::GraphQL::NestedMutations::ARGUMENT_DIRECTIVES.key?(d.name) }
+  end
+
+  def reflection!(name)
+    @model.reflect_on_association(name.to_s.underscore.to_sym) ||
+      raise(Lighthouse::DefinitionError, "#{@model} has no association #{name} for a nested mutation.")
+  end
+
+  def renamed(argument)
+    directive = (argument.ast_node&.directives || []).find { |d| d.name == 'rename' }
+    directive && Lighthouse::Support::DirectiveArgs.literal(directive, 'attribute')
+  end
+
+  # { attribute => "argument.path" } for every argument the type defines —
+  # also those the client left out, where e.g. a presence error belongs.
+  def argument_paths(argument_defs, prefix)
+    paths = Hash.new { |_, attribute| (prefix + [attribute.to_s.camelize(:lower)]).join('.') }
+    (argument_defs || {}).each_value do |argument|
+      if Lighthouse::Support::Arguments.spread?(argument)
+        paths.merge!(argument_paths(argument.type.unwrap.arguments, prefix + [argument.graphql_name]))
+      else
+        paths[renamed(argument) || argument.keyword.to_s] = (prefix + [argument.graphql_name]).join('.')
+      end
+    end
+    paths
+  end
+end