rails-graphql 0.1.0

data/lib/rails/graphql/directive.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Rails # :nodoc:
+  module GraphQL # :nodoc:
+    # = GraphQL Directive
+    #
+    # This is the base object for directives definition.
+    # See: http://spec.graphql.org/June2018/#DirectiveDefinition
+    #
+    # Whenever you want to use a directive, you can use the ClassName(...)
+    # shortcut (which is the same as ClassName.new(...)).
+    #
+    # Directives works as event listener and trigger, which means that some
+    # actions will trigger directives events, and the directive can listen to
+    # these events and perform an action
+    #
+    # ==== Examples
+    #
+    #   argument :test, :boolean, directives: FlagDirective()
+    #
+    #   # On defining an enum value
+    #   add :old_value, directives: DeprecatedDirective(reason: 'not used anymore')
+    class Directive
+      extend ActiveSupport::Autoload
+      extend Helpers::InheritedCollection
+      extend Helpers::WithEvents
+      extend Helpers::WithCallbacks
+      extend Helpers::WithArguments
+      extend Helpers::Registerable
+
+      VALID_LOCATIONS = Rails::GraphQL::Type::Enum::DirectiveLocationEnum
+        .values.to_a.map { |value| value.downcase.to_sym }.freeze
+
+      EXECUTION_LOCATIONS  = VALID_LOCATIONS[0..6].freeze
+      DEFINITION_LOCATIONS = VALID_LOCATIONS[7..17].freeze
+
+      class << self
+        def kind # :nodoc
+          :directive
+        end
+
+        def gql_name # :nodoc:
+          return @gql_name if defined?(@gql_name)
+          @gql_name = super.camelize(:lower)
+        end
+
+        # Get the list of locations of a the directive
+        def locations
+          @locations ||= Set.new
+        end
+
+        # A secure way to specify the locations of a the directive
+        def placed_on(*list)
+          validate_locations!(list)
+          @locations = (superclass.try(:locations)&.dup || Set.new) \
+            unless defined?(@locations)
+
+          @locations.merge(list)
+        end
+
+        # This method overrides the locations of a the directive
+        def placed_on!(*list)
+          validate_locations!(list)
+          @locations = list.to_set
+        end
+
+        def eager_load! # :nodoc:
+          super
+
+          TypeMap.loaded! :Directive
+        end
+
+        def inspect # :nodoc:
+          return '#<GraphQL::Directive>' if eql?(GraphQL::Directive)
+
+          args = arguments.each_value.map(&:inspect)
+          args = args.presence && "(#{args.join(', ')})"
+          "#<GraphQL::Directive @#{gql_name}#{args}>"
+        end
+
+        private
+
+          # Check if the given list the locations are valid
+          def validate_locations!(list)
+            list.flatten!
+            list.map! { |item| item.to_s.underscore.to_sym }
+
+            invalid = list - VALID_LOCATIONS
+            raise ArgumentError, <<~MSG.squish unless invalid.empty?
+              Invalid locations for @#{gql_name}: #{invalid.to_sentence}.
+            MSG
+          end
+
+          # Provide a nice way to use a directive without calling
+          # +Directive.new+, like the +DeprecatedDirective+ can be initialized
+          # using +GraphQL::DeprecatedDirective(*args)+
+          def inherited(subclass)
+            subclass.abstract = false
+            super if defined? super
+
+            return if subclass.anonymous?
+            method_name = subclass.name.demodulize
+            subclass.module_parent.define_singleton_method(method_name) do |*args, &block|
+              subclass.new(*args, &block)
+            end
+          end
+
+          # Allows checking value existence
+          def respond_to_missing?(method_name, *)
+            (const_defined?(method_name) rescue nil) || autoload?(method_name) || super
+          end
+
+          # Allow fast creation of values
+          def method_missing(method_name, *args, **xargs, &block)
+            const_get(method_name)&.new(*args, **xargs, &block) || super
+          rescue ::NameError
+            super
+          end
+      end
+
+      self.abstract = true
+
+      eager_autoload do
+        autoload :DeprecatedDirective
+        autoload :IncludeDirective
+        autoload :SkipDirective
+      end
+
+      delegate :locations, :gql_name, to: :class
+
+      array_sanitizer = ->(setting) do
+        Array.wrap(setting)
+      end
+
+      object_sanitizer = ->(setting) do
+        Array.wrap(setting).map! do |item|
+          next item unless item.is_a?(String) || item.is_a?(Symbol)
+          GraphQL.type_map.fetch(item, namespaces: namespaces) ||
+            ::GraphQL.const_get(item)
+        end
+      end
+
+      event_filter(:for, object_sanitizer) do |options, event|
+        options.any?(&event.source.method(:of_type?))
+      end
+
+      event_filter(:on, object_sanitizer) do |options, event|
+        event.respond_to?(:on?) && options.any?(&event.method(:on?))
+      end
+
+      event_filter(:during, array_sanitizer) do |options, event|
+        event.key?(:phase) && options.include?(event[:phase])
+      end
+
+      attr_reader :args
+
+      def initialize(args = nil, **xargs)
+        @args = args || OpenStruct.new(xargs.transform_keys { |key| key.to_s.underscore })
+        @args.freeze
+      end
+
+      # Once the directive is correctly prepared, we need to assign the owner
+      def assing_owner!(owner)
+        raise ArgumentError, <<~MSG.squish if defined?(@owner)
+          Owner already assigned for @#{gql_name} directive.
+        MSG
+
+        @owner = owner
+      end
+
+      # When fetching all the events, embed the actual instance as the context
+      # of the callback
+      def all_events
+        @all_events ||= self.class.all_events.transform_values do |events|
+          events.map { |item| Callback.set_context(item, self) }
+        end
+      end
+
+      # Checks if all the arguments provided to the directive instance are valid
+      def validate!(*)
+        invalid = all_arguments.reject { |name, arg| arg.valid?(@args[name]) }
+        return if invalid.empty?
+
+        invalid = invalid.map { |name, _| <<~MSG }
+          Invalid value "#{@args[name].inspect}" for #{name} argument.
+        MSG
+
+        raise ArgumentError, <<~MSG.squish
+          Invalid usage of @#{gql_name} directive: #{invalid.to_sentence}.
+        MSG
+      end
+
+      def inspect # :nodoc:
+        args = all_arguments.map do |name, arg|
+          "#{arg.gql_name}: #{@args[name].inspect}" unless @args[name].nil?
+        end.compact
+
+        args = args.presence && "(#{args.join(', ')})"
+        "@#{gql_name}#{args}"
+      end
+    end
+  end
+end

data/lib/rails/graphql/directive/deprecated_directive.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Rails # :nodoc:
+  module GraphQL # :nodoc:
+    # = GraphQL Spec Deprecated Directive
+    #
+    # Mark fields or enum values as deprecated which will include an error
+    # message when they are requested or returned
+    class Directive::DeprecatedDirective < Directive
+      self.spec_object = true
+
+      placed_on :field_definition, :enum_value
+
+      desc <<~DESC
+        Indicate deprecated portions of a GraphQL service’s schema, such as deprecated
+        fields on a type or deprecated enum values.
+      DESC
+
+      argument :reason, :string, desc: <<~DESC
+        Explain why the underlying element was marked as deprecated. If possible,
+        indicate what element should be used instead. This description is formatted
+        using Markdown syntax (as specified by [CommonMark](http://commonmark.org/)).
+      DESC
+
+      on :organized do |event|
+        report_for_field(event)
+      end
+
+      on :finalize, for: Type::Enum do |event|
+        report_for_enum_value(event)
+      end
+
+      private
+
+        # Check if the requested field is marked as deprecated
+        def report_for_field(event)
+          return unless event.field.using?(self.class)
+          item = "#{event.source.gql_name} field"
+          event.request.report_error(build_message(item))
+        end
+
+        # Check if the resolved enum value is marked as deprecated
+        def report_for_enum_value(event)
+          return unless event.current_value.deprecated?
+
+          value = event.current_value.to_s
+          item = "#{value} value for the #{event.source.gql_name} field"
+          event.request.report_error(build_message(item))
+        end
+
+        # Build the error message to display on the result
+        def build_message(item)
+          result = "The #{item} is deprecated"
+          result += ", reason: #{args.reason}" if args.reason.present?
+          result + '.'
+        end
+    end
+  end
+end

data/lib/rails/graphql/directive/include_directive.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Rails # :nodoc:
+  module GraphQL # :nodoc:
+    # = GraphQL Spec Include Directive
+    #
+    # Allow including fields only +if+ condition is true
+    class Directive::IncludeDirective < Directive
+      self.spec_object = true
+
+      placed_on :field, :fragment_spread, :inline_fragment
+
+      desc 'Allows for conditional inclusion during execution as described by the if argument.'
+
+      argument :if, :boolean, null: false, desc: <<~DESC
+        When false, the underlying element will be automatically marked as null.
+      DESC
+
+      on :attach do |source|
+        source.invalidate! unless args[:if]
+      end
+    end
+  end
+end

data/lib/rails/graphql/directive/skip_directive.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Rails # :nodoc:
+  module GraphQL # :nodoc:
+    # = GraphQL Spec Skip Directive
+    #
+    # Allow skipping fields given an +if+ condition
+    class Directive::SkipDirective < Directive
+      self.spec_object = true
+
+      desc 'Allows for conditional exclusion during execution as described by the if argument.'
+
+      placed_on :field, :fragment_spread, :inline_fragment
+
+      argument :if, :boolean, null: false, desc: <<~DESC
+        When true, the underlying element will be automatically marked as null.
+      DESC
+
+      on :attach do |source|
+        source.invalidate! if args[:if]
+      end
+    end
+  end
+end

data/lib/rails/graphql/errors.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Rails # :nodoc:
+  module GraphQL # :nodoc:
+    # Error class tha wrappes all the other error classes
+    StandardError = Class.new(::StandardError)
+
+    # Error class related to problems during the definition process
+    DefinitionError = Class.new(StandardError)
+
+    # Error class related to validation of a value
+    ValidationError = Class.new(StandardError)
+
+    # Errors that can happen related to the arguments given to a method
+    ArgumentError = Class.new(DefinitionError)
+
+    # Errors related to the name of the objects
+    NameError = Class.new(DefinitionError)
+
+    # Errors related to duplciated objects
+    DuplicatedError = Class.new(NameError)
+
+    # Error class related to problems during the execution process
+    ExecutionError = Class.new(StandardError)
+
+    # Error related to the parsing process
+    ParseError = Class.new(ExecutionError)
+
+    # Error class related to problems that happened during execution of fields
+    FieldError = Class.new(ExecutionError)
+
+    # Error class related to when a field was not found on the requested object
+    MissingFieldError = Class.new(FieldError)
+
+    # Error class related to when a field was found but is marked as disabled
+    DisabledFieldError = Class.new(FieldError)
+
+    # Error class related to when the captured output value is invalid due to
+    # type checking
+    InvalidValueError = Class.new(FieldError)
+  end
+end

data/lib/rails/graphql/event.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Rails # :nodoc:
+  module GraphQL # :nodoc:
+    # = GraphQL Event
+    #
+    # This class is responsible for trigerring events. It also contains the
+    # +data+ that can be used on the event handlers.
+    class Event
+      attr_reader :source, :data, :name, :object, :last_result
+
+      alias event itself
+
+      # List of trigger types used on +trigger+ shortcut
+      TRIGGER_TYPES = {
+        all?: :trigger_all,
+        stack?: :trigger_all,
+        object?: :trigger_object,
+        single?: :trigger,
+      }.freeze
+
+      # Event trigger shortcut that can perform any mode of trigger
+      def self.trigger(event_name, object, source, **xargs, &block)
+        extra = xargs.slice!(*TRIGGER_TYPES.keys)
+        fallback = extra.delete(:fallback_trigger!) || :trigger
+        method_name = xargs.find { |k, v| break TRIGGER_TYPES[k] if v } || fallback
+
+        instance = new(event_name, source, **extra)
+        instance.instance_variable_set(:@object, object) if block.present?
+        instance.public_send(method_name, block || object)
+      end
+
+      def initialize(name, source, **data)
+        @collect = data.delete(:collect?)
+        @reverse = data.delete(:reverse?)
+
+        @name = name
+        @data = data
+        @source = source
+        @layers = []
+      end
+
+      # Return a given +name+ information from the event
+      def parameter(name)
+        respond_to?(name) ? public_send(name) : data[name]
+      end
+
+      alias [] parameter
+
+      # Check if the event has a given +name+ information
+      def parameter?(name)
+        respond_to?(name) || data.key?(name)
+      end
+
+      alias key? parameter?
+
+      # Temporarily attach the event into an instance ensuring to set the
+      # previous value back
+      def set_on(instance, &block)
+        send_args = block.arity.eql?(1) ? [instance] : []
+        old_event = instance.instance_variable_get(:@event) \
+          if instance.instance_variable_defined?(:@event)
+
+        return block.call(*send_args) if old_event === self
+
+        begin
+          instance.instance_variable_set(:@event, self)
+          block.call(*send_args)
+        ensure
+          instance.instance_variable_set(:@event, old_event)
+        end
+      end
+
+      # From the list of all given objects, run the +trigger_object+
+      def trigger_all(*objects)
+        catchable(:stack) do
+          iterator = @collect ? :map : :each
+          objects.flatten.send(iterator, &method(:trigger_object))
+        end
+      end
+
+      # Fetch all the events from the object, get only the ones that are from
+      # the same name as the instance of this class and call +trigger+. It runs
+      # in reverse order, so first in first out. Since events can sometimes be
+      # cached, using +events+ avoid calculating the +all_events+
+      def trigger_object(object, events = nil)
+        @items ||= nil
+        @object ||= nil
+        @last_result ||= nil
+
+        old_items, old_object, old_result, @object = @items, @object, @last_result, object
+
+        catchable(:object) do
+          events ||= object.all_events[name]
+          stop if events.blank?
+
+          @items = @reverse ? events.reverse_each : events.each
+          call_next while @items.peek
+        rescue StopIteration
+          # TODO: Make sure that the +@collect+ works
+          return @last_result
+        end
+      ensure
+        @items = old_items
+        @object = old_object
+        @last_result = old_result
+      end
+
+      # Call a given block and send the event as reference
+      def trigger(block)
+        catchable(:item) { @last_result = block.call(self) }
+      end
+
+      # Stop the execution of an event using a given +layer+. The default is to
+      # get the last activated layer and stop it
+      def stop(*result, layer: nil)
+        layer = @layers[layer] if layer.is_a?(Numeric)
+        throw(layer || @layers.first, *result)
+      end
+
+      # Call the next item on the queue and return its result
+      def call_next
+        trigger(@items.next)
+      rescue StopIteration
+        # Do not do anything when missing next/super
+      end
+
+      alias call_super call_next
+
+      private
+
+        # Add the layer, exec the block and remove the layer
+        def catchable(layer)
+          @layers.unshift(layer)
+          catch(layer) { yield }
+        ensure
+          @layers.pop
+        end
+    end
+  end
+end