Support JSON as a first class group parameter type

[dblock]

Today Grape supports Hash and Array as a group parameter type and raises UnsupportedGroupTypeError for everything else. We would like to be able to do type: JSON, like so:

   resource :reticulated_splines do
      params do
        requires :splines, type: JSON do
          requires :id, type: Integer
          requires :reticulated, type: Boolean
        end
      end
      get do
        params[:splines].map do |spline|
          spline.merge(reticulated: !spline[:reticulated])
        end
      end
    end

Today you have to workaround this, see ruby-grape/grape-on-rack@0f904bf:

   resource :reticulated_splines do
      before do
        params.each_pair do |k, v|
          params[k] = JSON.parse(v) rescue v
        end
      end
      params do
        requires :splines, type: Array do
          requires :id, type: Integer
          requires :reticulated, type: Boolean
        end
      end
      get do
        params[:splines].map do |spline|
          spline.merge(reticulated: !spline[:reticulated])
        end
      end
    end

Note that the JSON itself can be an array or a hash. So maybe we can just generalize:

requires :splines, type: Array, coerce_type: JSON do

requires :splines, type: Array, coerce_method: ->(val) { JSON.parse(val) }

requires :splines, type: Array, coerce_method: JSON.method(:parse) 

[dslh]

Here's my attempt. I've gone with a generalized solution to support both hashes and arrays, but it seemed natural to support simple types as well so things like type: Time, coerce_using: Chronic are also possible.

At the moment it cannot be supplied without a type or coerce parameter. You could drop this constraint by either implicitly setting type to String, which the documentation already gives as the default type. Or with some adjustments it could bypass type checking altogether, but I don't know if that's good flexible API design or an invitation to lazy programmers.

I called it coerce_using to cover both classes and methods. Maybe that's confusing given the using parameter? coerce_with maybe?

[dblock]

Very nice work @dslh! I just commented on coerce_with vs. coerce_using in the PR, so sounds like we both think it's more natural to do coerce_with. LMK when you have updated it.

[dblock]

So after #1161 is merged can I write type: JSON, since JSON.parse exists or do we need to do more work? I think type: Hash/Array, coerce_using: JSON should be equivalent to type: JSON where we are able to JSON.parse the value and if we get an array treat it like type: Array, coerce_using: JSON and if not treat it as type: Hash, coerce_using: JSON. I realize this is an interesting special case, but I think we really want JSON to be a first-class type in Grape parameter coercion and validation.

[dslh]

I've updated the name to coerce_with. type: JSON will be extra work I believe, it would be passed to Virtus::Attribute.build as the type, and even if that somehow works I think it will fail in the last clause of CoerceValidator::_valid_single_type?.

I'm tempted to say implement it as type: Array, coerce_with: ->(json) { Array.wrap JSON.parse(json, symbolize_names: true) }. It might seem a bit hackish but I think it saves implementers from type checking every time. I think it's probably neater in terms of changes to CoerceValidator also. Let me know and I can either revise this patch or submit another building on it.

[dblock]

I merged that PR, it's awesome. Lets leave this open until we can do type: JSON. Want to give an implementation a try?

[dslh]

Sure. Any objection to wrapping hashes in an array?

it 'allows JSON as type' do
  subject.params do
    requires :ints, type: JSON do
      requires :int, Integer
    end
  end
  subject.get '/' do
    'json works' if params[:ints].first[:int] == 1
  end

  get '/', ints: '{"int":1}'
  expect(last_response.status).to eq(200)
  expect(last_response.body).to eq('json works')

  get '/', ints: '[{"int":1},{"int":2}]'
  expect(last_response.status).to eq(200)
  expect(last_response.body).to eq('json works')
end

[dblock]

You mean always wrapping them into an array? Maybe instead we could have JSON and Array[JSON]? Is that crazy?