Allow retrieving a plural representation of JSON.

Refactor root keys in the DSL.

.gitignore

@@ -20,3 +20,4 @@ tmp
 *.o
 *.a
 mkmf.log
+.pairs

README.md

@@ -36,6 +36,17 @@ user = User.new(name: 'Bobby Tables')
 json_for_create = UserMapping.representation_for(:create, user)
 ```
 
+### Rendering Collections as JSON
+
+```ruby
+user = User.new(name: 'Bobby Tables')
+users = Array.new(10, user)
+
+json = UserMapping.represent_collection_for(:read, users)
+```
+
+---
+
 Some API's will give you the created resource back as JSON as well on a successful create. For that, you may do something like this:
 
 ```ruby
@@ -93,7 +104,7 @@ class UserMapping
 
   kartograph do
     mapping User
-    root_key singular: 'user', plural: 'users' scopes: [:read]
+    root_key singular: 'user', plural: 'users', scopes: [:read]
     property :id, scopes: [:read]
   end
 end

lib/kartograph/dsl.rb

@@ -18,12 +18,15 @@ def kartograph(&block)
       def representation_for(scope, object, dumper = JSON)
         drawed = Artist.new(object, @kartograph_map).draw(scope)
 
-        retrieve_root_key(scope, :singular) do |root_key|
-          # Reassign drawed if a root key exists
-          drawed = { root_key => drawed }
+        dumper.dump(prepend_root_key(scope, :singular, drawed))
+      end
+
+      def represent_collection_for(scope, objects, dumper = JSON)
+        drawed_objects = objects.map do |object|
+          Artist.new(object, @kartograph_map).draw(scope)
         end
 
-        dumper.dump(drawed)
+        dumper.dump(prepend_root_key(scope, :plural, drawed_objects))
       end
 
       def extract_single(content, scope, loader = JSON)
@@ -51,12 +54,21 @@ def extract_collection(content, scope, loader = JSON)
       end
 
       private
+      def prepend_root_key(scope, plurality, payload)
+        retrieve_root_key(scope, plurality) do |root_key|
+          # Reassign drawed if a root key exists
+          payload = { root_key => payload }
+        end
+
+        payload
+      end
 
       def retrieve_root_key(scope, type, &block)
         if root_key = @kartograph_map.root_key_for(scope, type)
           yield root_key
         end
       end
+
     end
   end
 end

spec/lib/kartograph/dsl_spec.rb

@@ -48,6 +48,49 @@
     end
   end
 
+  describe '.represent_collection_for' do
+    include_context 'DSL Objects'
+
+    let(:users) { Array.new(3, object) }
+
+    subject(:parsed) do
+      json = mapped.represent_collection_for(:read, users)
+      JSON.parse(json)
+    end
+
+    it 'returns the objects as a collection' do
+      json = mapped.represent_collection_for(:read, users)
+      parsed = JSON.parse(json)
+
+      expect(parsed).to be_an(Array)
+      expect(parsed.size).to be(3)
+
+      expect(parsed[0]['id']).to   eq(users[0].id)
+      expect(parsed[0]['name']).to eq(users[0].name)
+      expect(parsed[1]['id']).to   eq(users[1].id)
+      expect(parsed[1]['name']).to eq(users[1].name)
+    end
+
+    context 'with a root key' do
+      it "includes the root key" do
+        root_key_name = "the_root_key"
+
+        mapped.kartograph do
+          root_key plural: root_key_name, scopes: [:read]
+        end
+
+        expect(parsed).to be_an(Hash)
+        expect(parsed.keys.first).to eq(root_key_name)
+
+        parsed_array = parsed[root_key_name]
+        expect(parsed_array[0]['id']).to   eq(users[0].id)
+        expect(parsed_array[0]['name']).to eq(users[0].name)
+        expect(parsed_array[1]['id']).to   eq(users[1].id)
+        expect(parsed_array[1]['name']).to eq(users[1].name)
+      end
+    end
+  end
+
   describe '.extract_single' do
     include_context 'DSL Objects'
     let(:json) do