Support .serialize …, coder: … for Collections

Follow-up to [#420][]

Background
---

The introduction of `ActiveResource::Base.coder` and the
`ActiveResource::Coder` class added support for encoding and decoding
instances of `Base`.

However, collection-focused methods like `Base.where`, `Base.all`, and
`Base.find(:all)` return `ActiveResource::Collection` instances.

Problem
---

While some collection instances are equivalent to `Array` instances,
they are capable of being parsed into `Hash` values that include
additional metadata (for example, pagination URLs, total counts, etc.).
If applications were to dump results, there is a potential loss of that
metadata.

Proposal
---

First, this commit modifies the `ActiveResource::Coder` class to accept
a boolean `:collection` keyword to treat values as
`ActiveResource::Collection` instances.

Next, extend the `ActiveResource::Collection` class to retain the
originally parsed values as a new `#original_parsed` attribute. It also
defines the `#encode` method to rely on the resource class format for
encoding.

Additionally, extend the `ActiveResource::Serialization` module to also
define a `.collection_coder` class attribute to serve as a convenience
method for consumer to pass to `.serialize …, coder: …`:

```ruby
class Person < ActiveResource::Base
  # …
end

class Team < ApplicationRecord
  serialize :people, coder: Person.collection_coder
end
```

Like the instance-level coders, collection-level coders constructed with
`collection: true` also accept an encoder proc to transform the value
prior to dumping (for JSON/JSONB columns, for example):

```ruby
class Person < ActiveResource::Base
  # …
end

class Team < ApplicationRecord
  # pass a to_proc-ready method name
  serialize :people, coder: ActiveResource::Coder.new(Person, :original_parsed, collection: true)

  # pass a block
  serialize :people, coder: ActiveResource::Coder.new(Person, collection: true) do |collection|
    collection.original_parsed
  end
end
```

[#420]: #420

Author: seanpdoyle

lib/active_resource/base.rb

@@ -1162,6 +1162,14 @@ def exists?(id, options = {})
         false
       end
 
+      def instantiate_collection(collection, original_params = {}, prefix_options = {}) # :nodoc:
+        collection_parser.new(collection).tap do |parser|
+          parser.resource_class  = self
+          parser.original_params = original_params
+          parser.original_parsed = collection
+        end.collect! { |record| instantiate_record(record, prefix_options) }
+      end
+
       private
         def check_prefix_options(prefix_options)
           p_options = HashWithIndifferentAccess.new(prefix_options)
@@ -1212,13 +1220,6 @@ def find_single(scope, options)
           instantiate_record(format.decode(connection.get(path, headers).body), prefix_options)
         end
 
-        def instantiate_collection(collection, original_params = {}, prefix_options = {})
-          collection_parser.new(collection).tap do |parser|
-            parser.resource_class  = self
-            parser.original_params = original_params
-          end.collect! { |record| instantiate_record(record, prefix_options) }
-        end
-
         def instantiate_record(record, prefix_options = {})
           new(record, true).tap do |resource|
             resource.prefix_options = prefix_options

lib/active_resource/coder.rb

@@ -47,23 +47,56 @@ module ActiveResource
   #
   #   coder = ActiveResource::Coder.new(Person) { |person| person.serializable_hash }
   #   coder.dump(person) # => { "name" => "Matz" }
+  #
+  # === Collections
+  #
+  # To encode ActiveResource::Collection instances, construct an instance with +collection:
+  # true+.
+  #
+  #   class Team < ActiveRecord::Base
+  #     serialize :people, coder: ActiveResource::Coder.new(Person, collection: true)
+  #   end
+  #
+  #   team = Team.new
+  #   team.people = Person.all
+  #   team.people.map(&:attributes) # => [{ "id" => 1, "name" => "Matz" }]
+  #
+  # By default, <tt>#dump</tt> serializes the instance to a string value by
+  # calling Collection#encode:
+  #
+  #   team.people_before_type_cast # => "[{\"id\":1,\"name\":\"Matz\"}]"
+  #
+  # To customize serialization, pass a block that accepts the collection as the second argument:
+  #
+  #   people = Person.all
+  #
+  #   coder = ActiveResource::Coder.new(Person) { |collection| collection.original_parsed }
+  #   coder.dump(people) # => [{ "id" => 1, "name" => "Matz" }]
   class Coder
-    attr_accessor :resource_class, :encoder
+    attr_accessor :resource_class, :encoder, :collection
 
     # ==== Arguments
     # * <tt>resource_class</tt> Active Resource class that to be coded
     # * <tt>encoder_method</tt> the method to invoke on the instance to encode
     # it. Defaults to ActiveResource::Base#encode.
-    def initialize(resource_class, encoder_method = :encode, &block)
+    #
+    # ==== Options
+    #
+    # * <tt>:collection</tt> - Whether or not the values represent an
+    # ActiveResource::Collection Defaults to false.
+    def initialize(resource_class, encoder_method = :encode, collection: false, &block)
       @resource_class = resource_class
       @encoder = block || encoder_method
+      @collection = collection
     end
 
     # Serializes a resource value to a value that will be stored in the database.
     # Returns nil when passed nil
     def dump(value)
       return if value.nil?
-      raise ArgumentError.new("expected value to be #{resource_class}, but was #{value.class}") unless value.is_a?(resource_class)
+
+      expected_class = collection ? resource_class.collection_parser : resource_class
+      raise ArgumentError.new("expected value to be #{expected_class}, but was #{value.class}") unless value.is_a?(expected_class)
 
       value.yield_self(&encoder)
     end
@@ -73,10 +106,15 @@ def dump(value)
     def load(value)
       return if value.nil?
       value = resource_class.format.decode(value) if value.is_a?(String)
-      raise ArgumentError.new("expected value to be Hash, but was #{value.class}") unless value.is_a?(Hash)
-      value = Formats.remove_root(value) if value.keys.first.to_s == resource_class.element_name
 
-      resource_class.new(value, value[resource_class.primary_key])
+      if collection
+        raise ArgumentError.new("expected value to be Hash or Array, but was #{value.class}") unless value.is_a?(Hash) || value.is_a?(Array)
+        resource_class.instantiate_collection(value)
+      else
+        raise ArgumentError.new("expected value to be Hash, but was #{value.class}") unless value.is_a?(Hash)
+        value = Formats.remove_root(value) if value.keys.first.to_s == resource_class.element_name
+        resource_class.new(value, value[resource_class.primary_key])
+      end
     end
   end
 end

lib/active_resource/collection.rb

@@ -10,7 +10,7 @@ class Collection # :nodoc:
     delegate :to_yaml, :all?, *(Array.instance_methods(false) - SELF_DEFINE_METHODS), to: :to_a
 
     # The array of actual elements returned by index actions
-    attr_accessor :elements, :resource_class, :original_params
+    attr_accessor :elements, :resource_class, :original_params, :original_parsed
 
     # ActiveResource::Collection is a wrapper to handle parsing index responses that
     # do not directly map to Rails conventions.
@@ -90,5 +90,9 @@ def where(clauses = {})
       new_clauses = original_params.merge(clauses)
       resource_class.where(new_clauses)
     end
+
+    def encode
+      resource_class.format.encode(original_parsed)
+    end
   end
 end

lib/active_resource/serialization.rb

@@ -66,11 +66,25 @@ module ActiveResource
   #   user.person.name # => "Matz"
   #
   #   user.person_before_type_cast # => {"name"=>"Matz"}
+  #
+  # === Collections
+  #
+  # To encode ActiveResource::Collection instances, pass the resource class
+  # +collection_coder+ as the +:coder+ option:
+  #
+  #   class Team < ActiveRecord::Base
+  #     serialize :people, coder: Person.collection_coder
+  #   end
+  #
+  #   team = Team.new
+  #   team.people = Person.all
+  #   team.people.map(&:attributes) # => [{ "id" => 1, "name" => "Matz" }]
   module Serialization
     extend ActiveSupport::Concern
 
     included do
       class_attribute :coder, instance_accessor: false, instance_predicate: false
+      class_attribute :collection_coder, instance_accessor: false, instance_predicate: false
     end
 
     module ClassMethods
@@ -79,6 +93,7 @@ module ClassMethods
       def inherited(subclass) # :nodoc:
         super
         subclass.coder = Coder.new(subclass)
+        subclass.collection_coder = Coder.new(subclass, collection: true)
       end
     end
   end

lib/active_resource/where_clause.rb

@@ -2,6 +2,7 @@
 
 module ActiveResource
   class WhereClause < BasicObject # :nodoc:
+    delegate :==, to: :resources
     delegate_missing_to :resources
 
     def initialize(resource_class, options = {})