rails-graphql 1.0.0.beta → 1.0.0.rc1

data/lib/rails/graphql/config.rb

@@ -3,20 +3,22 @@
 module Rails
   module GraphQL
     configure do |config|
-      # This helps to keep track of when things were cached and registered.
-      # Cached objects with mismatching versions needs to be upgraded or simply
-      # reloaded. A good way to use this is to set to the commit hash, but
-      # beware to stick to 8 characters.
+      # This helps to keep track of when things were cached and registered. Cached
+      # objects with mismatching versions need to be upgraded or simply reloaded.
+      # An excellent way to use this is to set it to the commit hash. TypePap will
+      # always use only the first 8 characters for simplicity.
       config.version = nil
 
-      # This will be automatically mapped to +Rails.cache+. Manually setting
-      # this property means that the object in it complies with
-      # +ActiveSupport::Cache::Store+.
+      # The instance responsible for caching all the information generated by
+      # requests and all the other components. Manually setting this property
+      # means that the object in it complies with `ActiveSupport::Cache::Store`.
+      # This will map automatically to `Rails.cache` if kept as `nil`. This can
+      # also be set per Schema.
       config.cache = nil
 
-      # If Rails cache is not properly defined, by default it is set to a
-      # NullStore, than fallback to this option to get a memory store because
-      # cache is extremely important, especially for subscriptions
+      # If Rails cache is not properly defined or just set to use a NullStore,
+      # this fallback will set itself up with a memory store because cache is
+      # crucial, especially for subscriptions.
       config.cache_fallback = -> do
         ::ActiveSupport::Cache::MemoryStore.new(max_prune_time: nil)
       end
@@ -30,39 +32,44 @@ module Rails
       config.paths = %w[directives fields sources enums inputs interfaces object
         scalars unions].to_set
 
-      # This exposes the clean path from where a GraphQL request was started.
+      # This is very similar to `ActiveRecord` verbose logs, which simply show the
+      # path of the file that started a GraphQL request.
       config.verbose_logs = true
 
-      # The list of parameters to omit from logger when running a GraphQL
-      # request. Those values will be better displayed in the internal runtime
-      # logger controller.
+      # The list of parameters to omit from the logger when running a GraphQL
+      # request. Those values are displayed better in the internal runtime logger
+      # controller.
       config.omit_parameters = %w[query operationName operation_name variables graphql]
 
-      # This list will actually affect what is displayed in the logs. When it is
-      # set to nil, it will copy its value from Rails +filter_parameters+.
+      # Identical to the one available on a Rails application, but exclusive for
+      # GraphQL operations. The list of parameters to display as filtered in the
+      # logs. When it is nil, it will use the same as the Rails application.
       config.filter_parameters = nil
 
-      # A list of ActiveRecord adapters and their specific internal naming used
-      # to compound the accessors for direct query serialization.
+      # A list of all `ActiveRecord` adapters supported. When an adapter is
+      # supported, it will map the database types into GraphQL types using proper
+      # aliases. Plus, it will have the method to map models attributes to their
+      # equivalent fields.
       config.ar_adapters = {
         'Mysql2'     => { key: :mysql,  path: "#{__dir__}/adapters/mysql_adapter" },
         'PostgreSQL' => { key: :pg,     path: "#{__dir__}/adapters/pg_adapter" },
         'SQLite'     => { key: :sqlite, path: "#{__dir__}/adapters/sqlite_adapter" },
       }
 
-      # For all the input object type defined, auto add the following prefix to
-      # their name, so we don't have to define classes like +PointInputInput+.
+      # The suffix that is added automatically to all the Input type objects. This
+      # prevents situations like `PointInputInput`. If your inputs have a
+      # different suffix, change this value to it.
       config.auto_suffix_input_objects = 'Input'
 
-      # Introspection is enabled by default. Changing this will affect all the
-      # schemas off the application and reduce memory usage. This can also be
-      # set at per schema.
-      config.enable_introspection = true
+      # Introspection is enabled by default. It is recommended to only use
+      # introspection during development and tests, never in production.
+      # This can also be set per schema level.
+      config.enable_introspection = false
 
       # Define the names of the schema/operations types. The single "_" is a
-      # suggestion so that in an application that has, most likely, a
-      # Subscription type, it does not generate a conflict. Plus, it is easy to
-      # spot that it is something internal.
+      # suggestion. In an application that has a Subscription object, it will
+      # prevent the conflict. Plus, it is easy to spot that it is something
+      # internal. This can also be set per Schema.
       config.schema_type_names = {
         query: '_Query',
         mutation: '_Mutation',
@@ -71,13 +78,15 @@ module Rails
 
       # For performance purposes, this gem implements a
       # {JsonCollector}[rdoc-ref:Rails::GraphQL::Collectors::JsonCollector].
-      # If you prefer to use the normal hash to string serialization, you can
-      # disable this option.
+      # You can disable this option if you prefer to use the standard
+      # hash-to-string serialization provided by `ActiveSupport`.
+      # This can also be set per Schema.
       config.enable_string_collector = true
 
       # Set what is de default expected output type of GraphQL requests. String
-      # combined with the previous setting has the best performance. On console,
-      # it will automatically shift to hash.
+      # combined with the previous setting has the best performance. On the
+      # console, it will automatically shift to Hash. This can also be set per
+      # Schema.
       config.default_response_format = :string
 
       # Specifies if the results of operations should be encoded with
@@ -85,60 +94,63 @@ module Rails
       # See also https://github.com/rails/rails/blob/master/activesupport/lib/active_support/json/encoding.rb
       config.encode_with_active_support = false
 
-      # Enable the ability of a callback to dynamically inject arguments to the
+      # Enable the ability of a callback to inject arguments dynamically into the
       # calling method.
       config.callback_inject_arguments = true
 
-      # Enable the ability of a callback to dynamically inject named arguments
-      # to the calling method.
+      # Enable the ability of a callback to inject named arguments dynamically
+      # into the calling method.
       config.callback_inject_named_arguments = true
 
-      # When importing fields into other places, if the given class is
-      # incompatible it will display an warning. This can make such warning be
-      # silenced.
+      # When importing fields from modules or other objects, a warning is
+      # displayed for any given element that was not able to be correctly
+      # imported. You can silence such warnings by changing this option.
       config.silence_import_warnings = false
 
-      # Enable the ability to active custom descriptions using i18n
-      config.enable_i18n_descriptions = true
+      # Enable the ability to define the description of any object, field, or
+      # argument using I18n. It is recommended for multi-language documentation.
+      config.enable_i18n_descriptions = false
 
-      # Specify the scopes for I18n translations
+      # The list of scopes that will be used to locate the descriptions.
       config.i18n_scopes = [
         'graphql.%{namespace}.%{kind}.%{parent}.%{name}',
         'graphql.%{namespace}.%{kind}.%{name}',
         'graphql.%{namespace}.%{name}',
         'graphql.%{kind}.%{parent}.%{name}',
         'graphql.%{kind}.%{name}',
-        'graphql.%{name}'
+        'graphql.%{name}',
       ]
 
-      # A list of execution strategies. Each application can add their own by
-      # simply append a class name, preferable as string, in this list.
+      # A list of execution strategies. Each application can add its own by
+      # appending a class, preferably as a string, in this list. This can also be
+      # set per Schema.
       config.request_strategies = [
         'Rails::GraphQL::Request::Strategy::MultiQueryStrategy',
         'Rails::GraphQL::Request::Strategy::SequencedStrategy',
         # 'Rails::GraphQL::Request::Strategy::CachedStrategy',
       ]
 
-      # A list of all possible rails-graphql-compatible sources.
+      # A list of all possible ruby-to-graphql compatible sources.
       config.sources = [
         'Rails::GraphQL::Source::ActiveRecordSource',
       ]
 
-      # A list of all available subscription providers which bases on
-      # Rails::GraphQL::SubscriptionProvider::Base
+      # A list of all available subscription providers.
       config.subscription_providers = [
         'Rails::GraphQL::Subscription::Provider::ActionCable',
       ]
 
-      # The default subscription provider for all the schemas
+      # The default subscription provider for all schemas. This can also be set
+      # per Schema.
       config.default_subscription_provider = config.subscription_providers.first
 
-      # The default value for fields about their ability of being broadcasted
+      # The default value for fields about their ability to be broadcasted. This
+      # can also be set per Schema.
       config.default_subscription_broadcastable = nil
 
       # A list of known dependencies that can be requested and included in any
-      # schema. This is the best place for other gems to add their own
-      # dependencies and allow users to pick them.
+      # Schema. This is the best place for other gems to add their own resources
+      # and allow users to enable them.
       config.known_dependencies = {
         scalar: {
           any:       "#{__dir__}/type/scalar/any_scalar",
@@ -150,18 +162,22 @@ module Rails
           time:      "#{__dir__}/type/scalar/time_scalar",
           json:      "#{__dir__}/type/scalar/json_scalar",
         },
+        enum:      {},
+        input:     {},
+        interface: {},
+        object:    {},
+        union:     {},
         directive: {
           # cached:    "#{__dir__}/directive/cached_directive",
         },
       }
 
-      # The method that should be used to parse literal input values when they
-      # are provided as hash. +JSON.parse+ only supports keys wrapped in quotes,
-      # to support keys without quotes, you can use +Psych.method(:safe_load)+,
-      # which behaves closer to YAML, but the received value is ensure to be
-      # wrapped in "{}". If that produces unexpected results, you can assign a
-      # proc and then parse the value in any other way, like
-      # +->(value) { anything }+
+      # The method that should be used to parse literal input values when they are
+      # provided as Hash. `JSON.parse` only supports keys wrapped in quotes. You
+      # can use `Psych.method(:safe_load)` to support keys without quotes, which
+      # behaves closer to YAML. The received value is ensured to be wrapped in
+      # "{}". If that produces unexpected results, you can assign a proc and then
+      # parse the value in any other way.
       config.literal_input_parser = JSON.method(:parse)
 
       # TODO: To be implemented

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

@@ -16,7 +16,6 @@ module Rails
         When false, the underlying element will be automatically marked as null.
       DESC
 
-      # TODO: On attach does not covers default value per operation variable scenario
       on(:attach) do |source|
         source.skip! unless args[:if]
       end

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

@@ -16,7 +16,6 @@ module Rails
         When true, the underlying element will be automatically marked as null.
       DESC
 
-      # TODO: On attach does not covers default value per operation variable scenario
       on(:attach) do |source|
         source.skip! if args[:if]
       end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Rails
+  module GraphQL
+    # = GraphQL Spec Specified By Directive
+    #
+    # Provides a scalar specification URL for specifying the behavior of
+    # custom scalar types.
+    class Directive::SpecifiedByDirective < Directive
+      self.spec_object = true
+
+      placed_on :scalar
+
+      desc <<~DESC
+        A built-in directive used within the type system definition language to provide
+        a scalar specification URL for specifying the behavior of custom scalar types.
+      DESC
+
+      argument :url, :string, null: false, desc: <<~DESC
+        Point to a human-readable specification of the data format.
+      DESC
+    end
+  end
+end

data/lib/rails/graphql/directive.rb

@@ -44,6 +44,13 @@ module Rails
           :directive
         end
 
+        # Ensure to return the directive class
+        def base_type
+          GraphQL::Directive
+        end
+
+        alias gid_base_class base_type
+
         # Return the name of the object as a GraphQL name, ensure to use the
         # first letter as lower case when being auto generated
         def gql_name
@@ -71,11 +78,6 @@ module Rails
           @locations = list.to_set
         end
 
-        # Ensure to return the directive class
-        def gid_base_class
-          GraphQL::Directive
-        end
-
         # A helper method that allows directives to be initialized while
         # correctly parsing the arguments
         def build(**xargs)
@@ -97,10 +99,11 @@ module Rails
         def inspect
           return super if eql?(GraphQL::Directive)
 
+          repeatable = ' [repeatable]' if repeatable?
           args = all_arguments&.each_value&.map(&:inspect)
           args = args.force if args.respond_to?(:force)
           args = args.presence && "(#{args.join(', ')})"
-          +"#<GraphQL::Directive @#{gql_name}#{args}>"
+          +"#<GraphQL::Directive @#{gql_name}#{repeatable}#{args}>"
         end
 
         private
@@ -141,30 +144,23 @@ module Rails
               Invalid locations for @#{gql_name}: #{invalid.force.to_sentence}.
             MSG
           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
 
+      # Marks if the directive may be used repeatedly at a single location
+      class_attribute :repeatable, instance_accessor: false, default: false
+
       self.abstract = true
 
       autoload :DeprecatedDirective
       autoload :IncludeDirective
       autoload :SkipDirective
+      autoload :SpecifiedByDirective
 
       autoload :CachedDirective
 
-      delegate :locations, :gql_name, :gid_base_class, to: :class
+      delegate :locations, :gql_name, :gid_base_class, :repeatable?, to: :class
 
+      # TODO: This filters are a bit confusing now, but `for` is working for @deprecated
       event_filter(:for) do |options, event|
         sanitize_objects(options).any?(&event.source.method(:of_type?))
       end
@@ -177,7 +173,7 @@ module Rails
         event.key?(:phase) && GraphQL.enumerate(options).include?(event[:phase])
       end
 
-      attr_reader :args
+      attr_reader :args, :event
 
       def initialize(args = nil, **xargs)
         @args = args || OpenStruct.new(xargs.transform_keys { |key| key.to_s.underscore })
@@ -211,10 +207,11 @@ module Rails
 
       # When fetching all the events, embed the actual instance as the context
       # of the callback
+      # TODO: Maybe add a soft cached, based on the total number of events
       def all_events
         return unless self.class.events?
 
-        @all_events ||= self.class.all_events.transform_values do |events|
+        self.class.all_events.transform_values do |events|
           events.map { |item| Callback.set_context(item, self) }
         end
       end
@@ -237,18 +234,27 @@ module Rails
         MSG
       end
 
+      # This allows combining directives
+      def +(other)
+        [self, other].flatten
+      end
+
+      alias_method :&, :+
+
       def inspect
-        args = all_arguments&.map do |name, arg|
+        args = all_arguments&.filter_map do |name, arg|
           +"#{arg.gql_name}: #{@args[name].inspect}" unless @args[name].nil?
-        end&.compact
+        end
 
         args = args.presence && +"(#{args.join(', ')})"
+        repeatable = ' [repeatable]' if repeatable?
         unbound = ' # unbound' unless defined?(@owner)
-        +"@#{gql_name}#{args}#{unbound}"
+        +"@#{gql_name}#{repeatable}#{args}#{unbound}"
       end
 
       %i[to_global_id to_gid to_gid_param].each do |method_name|
         define_method(method_name) do
+          # TODO: The option is kind of broken, because they should always be a Hash
           self.class.public_send(method_name, args_as_json&.compact || '')
         end
       end

data/lib/rails/graphql/event.rb

@@ -7,7 +7,7 @@ module Rails
     # This class is responsible for triggering events. It also contains the
     # +data+ that can be used on the event handlers.
     class Event
-      attr_reader :source, :data, :name, :object, :last_result
+      attr_reader :source, :data, :event_name, :object, :last_result
 
       alias event itself
 
@@ -34,7 +34,7 @@ module Rails
         @collect = data.delete(:collect?)
         @reverse = data.delete(:reverse?)
 
-        @name = name
+        @event_name = name
         @data = data
         @source = source
         @layers = []
@@ -42,9 +42,10 @@ module Rails
 
       # Check if the provided +other+ is equal to the source of the event. If
       # other is a directive, then check if the source is using that directive
+      # TODO: Other cannot be an instance
       def same_source?(other)
         if other.is_a?(Directive) || (other.is_a?(Module) && other < Directive)
-          source.using?(other)
+          event_name == :attach || source.using?(other)
         else
           source == other
         end
@@ -81,6 +82,8 @@ module Rails
         end
       end
 
+      alias on_instance set_on
+
       # From the list of all given objects, run the +trigger_object+
       def trigger_all(*objects)
         catchable(:stack) do
@@ -102,7 +105,7 @@ module Rails
         old_items, old_object, old_result, @object = @items, @object, @last_result, object
 
         catchable(:object) do
-          events ||= object.all_events.try(:[], name)
+          events ||= object.all_events.try(:[], event_name)
           stop if events.blank?
 
           @items = @reverse ? events.reverse_each : events.each
@@ -136,8 +139,6 @@ module Rails
         # Do not do anything when missing next/super
       end
 
-      alias call_super call_next
-
       protected
 
         alias args_source itself

data/lib/rails/graphql/field/authorized_field.rb

@@ -16,11 +16,6 @@ module Rails
         end
       end
 
-      # Just add the callbacks setup to the field
-      def self.included(other)
-        other.event_types(:authorize, append: true)
-      end
-
       # Add either settings for authorization or a block to be executed. It
       # returns +self+ for chain purposes
       def authorize(*args, **xargs, &block)

data/lib/rails/graphql/field/input_field.rb

@@ -28,11 +28,6 @@ module Rails
         @default = deserialize(@default) if @default.is_a?(::GQLParser::Token)
       end
 
-      # Prevent input fields from being further configured using a block
-      def configure
-        raise ArgumentError, +'Input fields can\'t be further configured using blocks'
-      end
-
       # Allow change the default value for the input
       def apply_changes(**xargs, &block)
         @default = xargs[:default] if xargs.key?(:default)

data/lib/rails/graphql/field/mutation_field.rb

@@ -5,7 +5,7 @@ module Rails
     # = GraphQL Mutation Field
     #
     # This is an extension of a normal output field, which just add extra
-    # validation and ensurance that the +perform+ step can be executed
+    # validation and insurance that the +perform+ step can be executed
     #
     # ==== Options
     #
@@ -58,17 +58,16 @@ module Rails
       # Get the performer that can be already defined or used through the
       # +method_name+ if that is callable
       def performer
-        @performer ||= callable?(perform_method_name) \
-          ? Callback.new(self, :perform, perform_method_name) \
-          : false
+        return @performer if defined?(@performer)
+
+        @performer = callable?(perform_method_name)
+        @performer = Callback.new(self, :perform, perform_method_name) if @performer
       end
 
       # Ensures that the performer is defined
       def validate!(*)
         super if defined? super
 
-        binding.pry unless performer.present?
-
         raise ValidationError, (+<<~MSG).squish unless performer.present?
           The "#{gql_name}" mutation field must have a perform action through a given
           block or a method named #{method_name} on #{owner.class.name}.

data/lib/rails/graphql/field/output_field.rb

@@ -29,10 +29,12 @@ module Rails
       include Field::TypedField
 
       module Proxied # :nodoc: all
+        Field.proxyable_methods %w[broadcastable?], klass: self
+
         def all_arguments
           inherited = field.all_arguments
           return inherited unless defined?(@arguments)
-          inherited.blank? ? super : inherited + super
+          inherited.blank? ? super : inherited.merge(super)
         end
 
         def has_argument?(name)
@@ -43,12 +45,17 @@ module Rails
           super || field.arguments?
         end
 
+        # TODO: Break events into directive/type/local
+        # because type events should only be added
+        # from the proxy
         def all_events
           if (inherited = super).nil?
             field.all_events
           elsif (proxied = field.all_events).nil?
             inherited
           else
+            # The order is reversed because events from
+            # the proxy must come first
             Helpers.merge_hash_array(proxied, inherited)
           end
         end
@@ -163,6 +170,10 @@ module Rails
         defined?(@broadcastable) && @broadcastable
       end
 
+      def entry_point?
+        owner.is_a?(Helpers::WithSchemaFields)
+      end
+
       protected
 
         # Check if the given +value+ is a valid array as output
@@ -177,7 +188,7 @@ module Rails
 
         # Properly display the owner section when the field is owned by a Schema
         def inspect_owner
-          owner.is_a?(Helpers::WithSchemaFields) ? +"#{owner.name}[:#{schema_type}]" : super
+          entry_point? ? +"#{owner.name}[:#{schema_type}]" : super
         end
 
         def proxied

data/lib/rails/graphql/field/proxied_field.rb

@@ -25,10 +25,9 @@ module Rails
     # * <tt>:alias</tt> - Same as the +:as+ key (defaults to nil).
     module Field::ProxiedField
       delegate_missing_to :field
-      delegate :leaf_type?, :array?, :internal?, :valid_input?, :valid_output?,
-        :to_json, :as_json, :deserialize, :valid?, :proxied_owner, to: :field
+      delegate :leaf_type?, :array?, :internal?, :proxied_owner, to: :field
 
-      Field.proxyable_methods %w[name gql_name method_name resolver description
+      Field.proxyable_methods %w[name gql_name method_name description
         null? nullable? enabled?], klass: self
 
       def initialize(field, owner:, **xargs, &block)
@@ -49,7 +48,7 @@ module Rails
         super || field == other
       end
 
-      # Allow chaging most of the general kind-independent initialize settings
+      # Allow changing most of the general kind-independent initialize settings
       def apply_changes(**xargs, &block)
         if (deprecated = xargs[:deprecated])
           xargs[:directives] = ::Array.wrap(xargs[:directives])
@@ -62,7 +61,8 @@ module Rails
         @directives = GraphQL.directives_to_set(xargs[:directives], source: self) \
           if xargs.key?(:directives)
 
-        @desc    = xargs[:desc]&.strip_heredoc&.chomp if xargs.key?(:desc)
+        self.description = xargs[:desc] if xargs.key?(:desc)
+        self.description = xargs[:description] if xargs.key?(:description)
         @enabled = xargs.fetch(:enabled, !xargs.fetch(:disabled, false)) \
           if xargs.key?(:enabled) || xargs.key?(:disabled)
 

data/lib/rails/graphql/field/resolved_field.rb

@@ -18,7 +18,7 @@ module Rails
 
       # Just add the callbacks setup to the field
       def self.included(other)
-        other.event_types(:prepare, :finalize, append: true, expose: true)
+        other.send(:expose_events!, :organized, :finalize, :prepared, :prepare)
         other.alias_method(:before_resolve, :prepare)
         other.alias_method(:after_resolve, :finalize)
       end