where: Support String arguments

[seanpdoyle]

The problem

When a resource queries an "index"-like endpoint and receives a response
payload that relies on URL-based pagination, it can be tedious to
deconstruct the next page's URL and transform it into a subsequent
.where call.

For example, consider a Post payload like:

{
  "posts": { … },
  "next_page": "https://api.blog.com/posts?page=2"
}

In order to query the URL in the next_page property, the collection
parser must extract a { "page" => "2" } Hash and forward it to a
resource_class.where call:

def initialize(parsed = {})
  @elements = parsed["posts"]
  @next_page_uri = URI.parse(parsed["next_page"])
end

def next_page_params
  query_string = @next_page_uri.query

  URI.decode_www_form(query_string).to_h
end

def next_page
  resource_class.where(next_page_params)
end

collection.next_page_params # => { "page" => "2" }
collection.next_page        # => GET https://api.blog.com/posts?page=2

The process becomes complicated when there are other parameters
(including "array"-like keys):

{
  "posts": { … },
  "next_page": "https://api.blog.com/posts?tags[]=Ruby&tags[]=Rails&page=2"
}

In this scenario, the Array created by URI.decode_www_form will only
retain both tags[]-keyed values, but the Array#to_h call will
flatten that Array into a Hash that only contains the last key. In this
case, tags[]=Ruby will be omitted, and the resulting Hash would be { "tags[]" => "Rails", "page" => "2" }.

The proposal

Active Record's .where method supports both String and Array
arguments. In the context of Active Record, String and Array
arguments are in support of the underlying SQL queries to be executed.

In the context of Active Resource, the underlying format for a "query"
is an HTTP-compliant query that's encoded as an
application/x-www-form-urlencoded string.

This commit proposes adding support to Base.where to accept String
arguments.

This support would simplify the scenario above:

def initialize(parsed = {})
  @elements = parsed["posts"]
  @next_page_uri = URI.parse(parsed["next_page"])
end

def next_page
  resource_class.where(@next_page_uri.query)
end

collection.next_page # => GET https://api.blog.com/posts?page=2

When Active Resource is loaded alongside a Rails or Rack application,
rely on Rack::Utils.parse_nested_query to decode key-value pairs.
Otherwise, rely on URI.decode_www_form and Array#to_h.

[seanpdoyle]

While this is passing, it expands the surface area of the dependencies.

The favorable part of that trade-off is that the package gains more sophisticated query string parsing when it's available through Rack).

However, I wonder if the goals of the use case described in the PR could be achieved by expanding .where and .all to forward along String arguments as a find(:all, from: …) argument, rather than parsing them into Hash instances.

I'll explore that in a separate PR.