Extract Entity DSL and refactor :with to keyword argument

- Move entity-related methods (present, entity_class_for_obj, entity_representation_for)
  from InsideRoute into a new Grape::DSL::Entity module
- Convert options[:with] hash pattern to explicit `with:` keyword argument in
  error_formatter, rescue_from, represent, and error_formatter/base#present

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ericproulx

lib/grape/dsl/entity.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    module Entity
+      # Allows you to make use of Grape Entities by setting
+      # the response body to the serializable hash of the
+      # entity provided in the `:with` option. This has the
+      # added benefit of automatically passing along environment
+      # and version information to the serialization, making it
+      # very easy to do conditional exposures. See Entity docs
+      # for more info.
+      #
+      # @param args [Array] either `(object)` or `(key, object)` where key is a Symbol
+      #   used to nest the representation under that key in the response body.
+      # @param root [Symbol, String, nil] wraps the representation under this root key.
+      # @param with [Class, nil] the entity class to use for representation.
+      #   If omitted, the entity class is inferred from the object via {#entity_class_for_obj}.
+      # @param options [Hash] additional options forwarded to the entity's `represent` call.
+      #
+      # @example
+      #
+      #   get '/users/:id' do
+      #     present User.find(params[:id]),
+      #       with: API::Entities::User,
+      #       admin: current_user.admin?
+      #   end
+      def present(*args, root: nil, with: nil, **options)
+        key, object = args.count == 2 && args.first.is_a?(Symbol) ? args : [nil, args.first]
+        entity_class = with || entity_class_for_obj(object)
+        representation = entity_class ? entity_representation_for(entity_class, object, options) : object
+        representation = { root => representation } if root
+
+        if key
+          representation = (body || {}).merge(key => representation)
+        elsif entity_class.present? && body
+          raise ArgumentError, "Representation of type #{representation.class} cannot be merged." unless representation.respond_to?(:merge)
+
+          representation = body.merge(representation)
+        end
+
+        body representation
+      end
+
+      # Attempt to locate the Entity class for a given object, if not given
+      # explicitly. This is done by looking for the presence of Klass::Entity,
+      # where Klass is the class of the `object` parameter, or one of its
+      # ancestors.
+      # @param object [Object] the object to locate the Entity class for
+      # @return [Class] the located Entity class, or nil if none is found
+      def entity_class_for_obj(object)
+        object_class =
+          if object.respond_to?(:klass)
+            object.klass
+          elsif object.respond_to?(:first)
+            object.first.class
+          else
+            object.class
+          end
+
+        representations = inheritable_setting.namespace_stackable_with_hash(:representations)
+        if representations
+          potential = object_class.ancestors.detect { |potential| representations.key?(potential) }
+          return representations[potential] if potential && representations[potential]
+        end
+
+        return unless object_class.const_defined?(:Entity)
+
+        entity = object_class.const_get(:Entity)
+        entity if entity.respond_to?(:represent)
+      end
+
+      private
+
+      # @param entity_class [Class] the entity class to use for representation.
+      # @param object [Object] the object to represent.
+      # @param options [Hash] additional options forwarded to the entity's `represent` call.
+      # @return the representation of the given object as done through the given entity_class.
+      def entity_representation_for(entity_class, object, options)
+        embeds = env.key?(Grape::Env::API_VERSION) ? { env:, version: env[Grape::Env::API_VERSION] } : { env: }
+        entity_class.represent(object, **embeds, **options)
+      end
+    end
+  end
+end

lib/grape/dsl/inside_route.rb

@@ -4,6 +4,7 @@ module Grape
   module DSL
     module InsideRoute
       include Declared
+      include Entity
 
       # Backward compatibility: alias exception class to previous location
       MethodNotYetAvailable = Declared::MethodNotYetAvailable
@@ -184,50 +185,6 @@ def stream(value = nil)
         end
       end
 
-      # Allows you to make use of Grape Entities by setting
-      # the response body to the serializable hash of the
-      # entity provided in the `:with` option. This has the
-      # added benefit of automatically passing along environment
-      # and version information to the serialization, making it
-      # very easy to do conditional exposures. See Entity docs
-      # for more info.
-      #
-      # @example
-      #
-      #   get '/users/:id' do
-      #     present User.find(params[:id]),
-      #       with: API::Entities::User,
-      #       admin: current_user.admin?
-      #   end
-      def present(*args, **options)
-        key, object = if args.count == 2 && args.first.is_a?(Symbol)
-                        args
-                      else
-                        [nil, args.first]
-                      end
-        entity_class = entity_class_for_obj(object, options)
-
-        root = options.delete(:root)
-
-        representation = if entity_class
-                           entity_representation_for(entity_class, object, options)
-                         else
-                           object
-                         end
-
-        representation = { root => representation } if root
-
-        if key
-          representation = (body || {}).merge(key => representation)
-        elsif entity_class.present? && body
-          raise ArgumentError, "Representation of type #{representation.class} cannot be merged." unless representation.respond_to?(:merge)
-
-          representation = body.merge(representation)
-        end
-
-        body representation
-      end
-
       # Returns route information for the current request.
       #
       # @example
@@ -240,43 +197,6 @@ def route
         env[Grape::Env::GRAPE_ROUTING_ARGS][:route_info]
       end
 
-      # Attempt to locate the Entity class for a given object, if not given
-      # explicitly. This is done by looking for the presence of Klass::Entity,
-      # where Klass is the class of the `object` parameter, or one of its
-      # ancestors.
-      # @param object [Object] the object to locate the Entity class for
-      # @param options [Hash]
-      # @option options :with [Class] the explicit entity class to use
-      # @return [Class] the located Entity class, or nil if none is found
-      def entity_class_for_obj(object, options)
-        entity_class = options.delete(:with)
-        return entity_class if entity_class
-
-        # entity class not explicitly defined, auto-detect from relation#klass or first object in the collection
-        object_class = if object.respond_to?(:klass)
-                         object.klass
-                       else
-                         object.respond_to?(:first) ? object.first.class : object.class
-                       end
-
-        representations = inheritable_setting.namespace_stackable_with_hash(:representations)
-        if representations
-          potential = object_class.ancestors.detect { |potential| representations.key?(potential) }
-          entity_class = representations[potential] if potential
-        end
-
-        entity_class = object_class.const_get(:Entity) if !entity_class && object_class.const_defined?(:Entity) && object_class.const_get(:Entity).respond_to?(:represent)
-        entity_class
-      end
-
-      # @return the representation of the given object as done through
-      #   the given entity_class.
-      def entity_representation_for(entity_class, object, options)
-        embeds = { env: }
-        embeds[:version] = env[Grape::Env::API_VERSION] if env.key?(Grape::Env::API_VERSION)
-        entity_class.represent(object, **embeds, **options)
-      end
-
       def http_version
         env.fetch('HTTP_VERSION') { env[Rack::SERVER_PROTOCOL] }
       end

lib/grape/dsl/request_response.rb

@@ -44,13 +44,8 @@ def default_error_formatter(new_formatter_name = nil)
         inheritable_setting.namespace_inheritable[:default_error_formatter] = new_formatter
       end
 
-      def error_formatter(format, options)
-        formatter = if options.is_a?(Hash) && options.key?(:with)
-                      options[:with]
-                    else
-                      options
-                    end
-
+      def error_formatter(format, options = nil, with: nil)
+        formatter = with || options
         inheritable_setting.namespace_stackable[:error_formatters] = { format.to_sym => formatter }
       end
 
@@ -93,16 +88,8 @@ def default_error_status(new_status = nil)
       #   @option options [Boolean] :rescue_subclasses Also rescue subclasses of exception classes
       #   @param [Proc] handler Execution proc to handle the given exception as an
       #     alternative to passing a block.
-      def rescue_from(*args, **options, &block)
-        if args.last.is_a?(Proc)
-          handler = args.pop
-        elsif block
-          handler = block
-        end
-
-        raise ArgumentError, 'both :with option and block cannot be passed' if block && options.key?(:with)
-
-        handler ||= extract_with(options)
+      def rescue_from(*args, with: nil, **options, &block)
+        handler = extract_handler(args, with:, block:)
 
         if args.include?(:all)
           inheritable_setting.namespace_inheritable[:rescue_all] = true
@@ -146,22 +133,23 @@ def rescue_from(*args, **options, &block)
       #
       # @param model_class [Class] The model class that will be represented.
       # @option options [Class] :with The entity class that will represent the model.
-      def represent(model_class, options)
-        raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless options[:with].is_a?(Class)
+      def represent(model_class, with:)
+        raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless with.is_a?(Class)
 
-        inheritable_setting.namespace_stackable[:representations] = { model_class => options[:with] }
+        inheritable_setting.namespace_stackable[:representations] = { model_class => with }
       end
 
       private
 
-      def extract_with(options)
-        return unless options.key?(:with)
+      def extract_handler(args, with:, block:)
+        raise ArgumentError, 'both :with option and block cannot be passed' if block && with
 
-        with_option = options.delete(:with)
-        return with_option if with_option.instance_of?(Proc)
-        return with_option.to_sym if with_option.instance_of?(Symbol) || with_option.instance_of?(String)
+        return args.pop if args.last.is_a?(Proc)
+        return block if block
+        return with if with.instance_of?(Proc) || with.instance_of?(Symbol)
+        return with.to_sym if with.instance_of?(String)
 
-        raise ArgumentError, "with: #{with_option.class}, expected Symbol, String or Proc"
+        raise ArgumentError, "with: #{with.class}, expected Symbol, String or Proc" if with
       end
     end
   end

lib/grape/error_formatter/base.rb

@@ -17,35 +17,25 @@ def call(message, backtrace, options = {}, env = nil, original_exception = nil)
           format_structured_message(wrapped_message)
         end
 
-        def present(message, env)
-          present_options = {}
-          presented_message = message
-          if presented_message.is_a?(Hash)
-            presented_message = presented_message.dup
-            present_options[:with] = presented_message.delete(:with)
-          end
-
-          presenter = env[Grape::Env::API_ENDPOINT].entity_class_for_obj(presented_message, present_options)
+        def present(message, env, with: nil)
+          presenter = with || env[Grape::Env::API_ENDPOINT].entity_class_for_obj(message)
 
           unless presenter || env[Grape::Env::GRAPE_ROUTING_ARGS].nil?
             # env['api.endpoint'].route does not work when the error occurs within a middleware
             # the Endpoint does not have a valid env at this moment
             http_codes = env[Grape::Env::GRAPE_ROUTING_ARGS][:route_info].http_codes || []
-
             found_code = http_codes.find do |http_code|
               (http_code[0].to_i == env[Grape::Env::API_ENDPOINT].status) && http_code[2].respond_to?(:represent)
             end if env[Grape::Env::API_ENDPOINT].request
 
             presenter = found_code[2] if found_code
           end
 
-          if presenter
-            embeds = { env: }
-            embeds[:version] = env[Grape::Env::API_VERSION] if env.key?(Grape::Env::API_VERSION)
-            presented_message = presenter.represent(presented_message, embeds).serializable_hash
-          end
+          return message unless presenter
 
-          presented_message
+          embeds = { env: }
+          embeds[:version] = env[Grape::Env::API_VERSION] if env.key?(Grape::Env::API_VERSION)
+          presenter.represent(message, embeds).serializable_hash
         end
 
         def wrap_message(message)

lib/grape/validations/params_scope.rb

@@ -492,13 +492,6 @@ def validate_value_coercion(coerce_type, *values_list)
         end
       end
 
-      def extract_message_option(attrs)
-        return nil unless attrs.is_a?(Array)
-
-        opts = attrs.last.is_a?(Hash) ? attrs.pop : {}
-        opts.key?(:message) && !opts[:message].nil? ? opts.delete(:message) : nil
-      end
-
       def options_key?(type, key, validations)
         validations[type].respond_to?(:key?) && validations[type].key?(key) && !validations[type][key].nil?
       end

spec/grape/api_spec.rb

@@ -112,7 +112,7 @@
 
   describe '.represent' do
     it 'requires a :with option' do
-      expect { subject.represent Object, {} }.to raise_error(Grape::Exceptions::InvalidWithOptionForRepresent)
+      expect { subject.represent Object, with: 1 }.to raise_error(Grape::Exceptions::InvalidWithOptionForRepresent)
     end
 
     it 'adds the association to the :representations setting' do

spec/grape/dsl/parameters_spec.rb

@@ -49,13 +49,6 @@ def new_group_scope(group)
         yield
         @group = prev_group
       end
-
-      def extract_message_option(attrs)
-        return nil unless attrs.is_a?(Array)
-
-        opts = attrs.last.is_a?(Hash) ? attrs.pop : {}
-        opts.key?(:message) && !opts[:message].nil? ? opts.delete(:message) : nil
-      end
     end
   end
 

spec/grape/middleware/error_spec.rb

@@ -1,16 +1,6 @@
 # frozen_string_literal: true
 
 describe Grape::Middleware::Error do
-  let(:error_entity) do
-    Class.new(Grape::Entity) do
-      expose :code
-      expose :static
-
-      def static
-        'static text'
-      end
-    end
-  end
   let(:err_app) do
     Class.new do
       class << self