cartograph 1.0.0

data/spec/lib/cartograph/dsl_spec.rb

@@ -0,0 +1,257 @@
+require 'spec_helper'
+
+describe Cartograph::DSL do
+  describe 'Inclusion' do
+    it 'gives you a class method for .cartograph' do
+      klass = Class.new
+      expect { klass.send(:include, described_class) }.to change { klass.respond_to?(:cartograph) }.to(true)
+    end
+  end
+
+  describe '.cartograph' do
+    subject(:mapping) { Class.new { include Cartograph::DSL } }
+
+    it 'yields a Cartograph::Map instance' do
+      expect {|b| mapping.cartograph(&b) }.to yield_with_args(Cartograph::Map.new)
+    end
+
+    it 'returns the map instance' do
+      expect(mapping.cartograph).to be_kind_of(Cartograph::Map)
+    end
+  end
+
+  describe '.hash_for' do
+    include_context 'DSL Objects'
+
+    it 'returns the hash representation for an object' do
+      hash = mapped.hash_for(:create, object)
+      expect(hash).to eq({ 'name' => object.name })
+    end
+
+    context 'with a root key for the scope' do
+      it 'returns the hash with the root key' do
+        mapped.cartograph do
+          root_key singular: 'user', scopes: [:create]
+        end
+        hash = mapped.hash_for(:create, object)
+
+        expect(hash).to eq(
+          {
+            'user' => {
+              'name' => object.name
+            }
+          }
+        )
+      end
+    end
+  end
+
+  describe '.hash_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 of hashes' do
+      collection = mapped.hash_collection_for(:read, users)
+
+      expect(collection).to be_an(Array)
+      expect(collection.size).to be(3)
+
+      expect(collection[0]['id']).to   eq(users[0].id)
+      expect(collection[0]['name']).to eq(users[0].name)
+      expect(collection[1]['id']).to   eq(users[1].id)
+      expect(collection[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.cartograph do
+          root_key plural: root_key_name, scopes: [:read]
+        end
+
+        collection = mapped.hash_collection_for(:read, users)
+
+        expect(collection).to be_an(Hash)
+        expect(collection.keys.first).to eq(root_key_name)
+
+        collection_array = collection[root_key_name]
+        expect(collection_array[0]['id']).to   eq(users[0].id)
+        expect(collection_array[0]['name']).to eq(users[0].name)
+        expect(collection_array[1]['id']).to   eq(users[1].id)
+        expect(collection_array[1]['name']).to eq(users[1].name)
+      end
+    end
+  end
+
+  describe '.representation_for' do
+    include_context 'DSL Objects'
+
+    it 'returns the JSON representation for an object' do
+      json = mapped.representation_for(:create, object)
+      expect(json).to eq(
+        { name: object.name }.to_json
+      )
+    end
+
+    context 'with a root key for the scope' do
+      it 'returns the json with the root key' do
+        mapped.cartograph do
+          root_key singular: 'user', scopes: [:create]
+        end
+        json = mapped.representation_for(:create, object)
+
+        expect(json).to eq(
+          {
+            user: {
+              name: object.name
+            }
+          }.to_json
+        )
+      end
+    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.cartograph 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
+      { id: 1337, name: 'Paul the octopus' }
+    end
+
+    it 'returns a populated object from a JSON representation' do
+      extracted = mapped.extract_single(json.to_json, :read)
+
+      expect(extracted.id).to eq(1337)
+      expect(extracted.name).to eq('Paul the octopus')
+    end
+
+    context 'with a root key in the JSON' do
+      let(:json) { { test: super() } }
+
+      before do
+        mapped.cartograph do
+          root_key singular: 'test', scopes: [:read]
+        end
+      end
+
+      it 'traverses into the key and pulls the object from there' do
+        extracted = mapped.extract_single(json.to_json, :read)
+
+        expect(extracted.id).to eq(1337)
+        expect(extracted.name).to eq('Paul the octopus')
+      end
+    end
+  end
+
+  describe '.extract_into_object' do
+    include_context 'DSL Objects'
+    let(:json) do
+      { id: 1337, name: 'Paul the octopus' }
+    end
+
+    it 'returns a populated object from a JSON representation' do
+      object = DummyUser.new
+      mapped.extract_into_object(object, json.to_json, :read)
+
+      expect(object.id).to eq(1337)
+      expect(object.name).to eq('Paul the octopus')
+    end
+  end
+
+  describe '.extract_collection' do
+    include_context 'DSL Objects'
+    let(:json) do
+      [
+        { id: 1337, name: 'Paul the octopus' },
+        { id: 1338, name: 'Hank the octopus' }
+      ]
+    end
+
+    it 'returns a collection of objects from the json' do
+      extracted = mapped.extract_collection(json.to_json, :read)
+
+      expect(extracted.size).to be(2)
+      expect(extracted).to all(be_kind_of(DummyUser))
+
+      expect(extracted[0].id).to eq(json[0][:id])
+      expect(extracted[0].name).to eq(json[0][:name])
+
+      expect(extracted[1].id).to eq(json[1][:id])
+      expect(extracted[1].name).to eq(json[1][:name])
+    end
+
+    context 'for a nested key' do
+      let(:json) { { users: super() } }
+
+      before do
+        mapped.cartograph do
+          root_key plural: 'users', scopes: [:read]
+        end
+      end
+
+      it 'returns a collection of objects from the json' do
+        extracted = mapped.extract_collection(json.to_json, :read)
+
+        expect(extracted.size).to be(2)
+        expect(extracted).to all(be_kind_of(DummyUser))
+
+        scoped = json[:users]
+
+        expect(extracted[0].id).to eq(scoped[0][:id])
+        expect(extracted[0].name).to eq(scoped[0][:name])
+
+        expect(extracted[1].id).to eq(scoped[1][:id])
+        expect(extracted[1].name).to eq(scoped[1][:name])
+      end
+    end
+  end
+end

data/spec/lib/cartograph/map_spec.rb

@@ -0,0 +1,160 @@
+require 'spec_helper'
+
+describe Cartograph::Map do
+  subject(:map) { Cartograph::Map.new }
+
+  describe '#property' do
+    it 'adds a property to the map' do
+      map.property :attribute_name, scopes: [:read]
+      expect(map.properties.size).to be(1)
+      expect(map.properties.first).to be_kind_of(Cartograph::Property)
+    end
+
+    context 'defining multiple properties' do
+      it 'adds multiple properties at the same time for the scope' do
+        map.property :attribute1, :attribute2, scopes: [:read]
+
+        expect(map.properties.size).to be(2)
+        expect(map.properties).to all(be_kind_of(Cartograph::Property))
+
+        expect(map.properties[0].name).to eq(:attribute1)
+        expect(map.properties[0].scopes).to eq([:read])
+
+        expect(map.properties[1].name).to eq(:attribute2)
+        expect(map.properties[1].scopes).to eq([:read])
+      end
+    end
+  end
+
+  describe '#properties' do
+    it 'returns a PropertyCollection object' do
+      properties = map.properties
+      expect(properties).to be_kind_of(Cartograph::PropertyCollection)
+    end
+  end
+
+  describe '#mapping' do
+    it 'sets the class we\'re mapping' do
+      map.mapping Class
+      expect(map.mapping).to be(Class)
+    end
+  end
+
+  describe '#root_key' do
+    it 'sets the root keys' do
+      map.root_key singlular: 'test', scopes: [:read]
+      map.root_key singlular: 'test', scopes: [:create]
+
+      expect(map.root_keys.size).to be(2)
+      expect(map.root_keys).to all(be_kind_of(Cartograph::RootKey))
+    end
+  end
+
+  describe '#root_key_for' do
+    it 'returns the first root key for the scope and type' do
+      map.root_key singular: 'test', scopes: [:read]
+      key = map.root_key_for(:read, :singular)
+
+      expect(key).to eq('test')
+    end
+  end
+
+  describe '#dup' do
+    it 'performs a safe duplication of the map' do
+      mapped_class = Class.new
+
+      prop1 = map.property :name, scopes: [:read, :write]
+      prop2 = map.property :id, scopes: [:read]
+      map.mapping mapped_class
+      map.root_key singular: 'woot', plural: 'woots', scopes: [:read]
+
+      cache_key = Proc.new {}
+      map.cache 'hello'
+      map.cache_key &cache_key
+
+      new_map = map.dup
+
+      expect(new_map.properties[0]).to_not be(prop1)
+      expect(new_map.properties[1]).to_not be(prop2)
+
+      expect(new_map.properties).to all(be_kind_of(Cartograph::Property))
+      expect(new_map.properties[0].name).to eq(:name)
+      expect(new_map.properties[1].name).to eq(:id)
+
+      expect(new_map.mapping).to eq(mapped_class)
+      expect(new_map.root_keys).to eq(map.root_keys)
+
+      expect(new_map.cache).to eq(map.cache)
+      expect(new_map.cache_key).to eq(cache_key)
+    end
+  end
+
+  describe '#cache' do
+    it "stores the caching method" do
+      cacher = double
+      map.cache cacher
+
+      expect(map.cache).to be(cacher)
+    end
+
+    it 'returns the cartograph cache if set' do
+      cacher = double('cache')
+      Cartograph.default_cache = cacher
+
+      expect(map.cache).to be(cacher)
+    end
+
+    it 'goes straight to the object if cache is overridden with false' do
+      cacher = double('cache')
+      Cartograph.default_cache = cacher
+
+      property = Cartograph::Property.new(:bunk) do
+        cache false
+      end
+
+      map.properties << property
+
+      expect(property.map.cache).to be(false)
+    end
+  end
+
+  describe '#cache_key' do
+    it 'stores the cache key block' do
+      cache_key = Proc.new {}
+      map.cache_key(&cache_key)
+
+      expect(map.cache_key).to be(cache_key)
+    end
+
+    it 'returns the cartograph cache_key if set' do
+      cache_key = double('cache key')
+      Cartograph.default_cache_key = cache_key
+
+      expect(map.cache_key).to be(cache_key)
+    end
+  end
+
+  describe 'Equality' do
+    specify 'duplicated maps are equal to eachother' do
+      map1 = Cartograph::Map.new
+      map1.property :something, scopes: [:read]
+
+      map2 = map1.dup
+
+      expect(map1).to eq(map2)
+    end
+  end
+
+  describe '#scoped' do
+    it 'adds properties with the scopes defined on the block instantiation' do
+      map.scoped :read, :write do
+        property :name
+        property :something
+      end
+
+      expect(map.properties.size).to eq(2)
+      expect(map.properties.filter_by_scope(:read).map(&:name)).to eq([:name, :something])
+      expect(map.properties.filter_by_scope(:write).map(&:name)).to eq([:name, :something])
+    end
+  end
+end

data/spec/lib/cartograph/property_collection_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+describe Cartograph::PropertyCollection do
+  describe '#filter_by_scope' do
+    it 'only returns properties with a certain scope attached' do
+      collection = Cartograph::PropertyCollection.new
+      collection << Cartograph::Property.new(:hello, scopes: [:read, :create])
+      collection << Cartograph::Property.new(:id, scopes: [:read])
+
+      filtered = collection.filter_by_scope(:create)
+      expect(filtered.size).to be(1)
+      expect(filtered.first.name).to eq(:hello)
+    end
+  end
+end

data/spec/lib/cartograph/property_spec.rb

@@ -0,0 +1,235 @@
+require 'spec_helper'
+
+describe Cartograph::Property do
+  describe '#initialize' do
+    it 'initializes with an attribute name and options' do
+      name = :hey
+      options = { lol: 'whut' }
+
+      property = Cartograph::Property.new(name, options)
+      expect(property.name).to eq(name)
+      expect(property.options).to eq(options)
+      expect(property.key).to eq('hey')
+    end
+
+    context 'with a key' do
+      it 'sets the key' do
+        name = :hey
+        options = { key: 'Hey' }
+        property = Cartograph::Property.new(name, options)
+
+        expect(property.key).to eq('Hey')
+      end
+    end
+
+    context 'with a block' do
+      it 'yields a map instance for the property' do
+        expect {|b| Cartograph::Property.new(:hello, &b) }.to yield_with_args(Cartograph::Map.new)
+      end
+    end
+
+    context 'with an include' do
+      it 'sets the map to the included mapped class' do
+        klass = Class.new do
+          include Cartograph::DSL
+          cartograph do
+            property :lol, scopes: [:read]
+          end
+        end
+
+        property = Cartograph::Property.new(:id, scopes: [:read], include: klass)
+        expect(property.map).to eq(klass.cartograph)
+      end
+    end
+  end
+
+  describe '#scopes' do
+    it 'returns the scopes that the property is for' do
+      property = Cartograph::Property.new(:name, scopes: [:read, :create])
+      expect(property.scopes).to include(:read, :create)
+    end
+
+    it 'returns an empty array when no scopes are provided' do
+      property = Cartograph::Property.new(:name)
+      expect(property.scopes).to eq( [] )
+    end
+
+    it 'always casts to an array' do
+      property = Cartograph::Property.new(:name, scopes: :read)
+      expect(property.scopes).to eq [:read]
+    end
+  end
+
+  describe '#plural?' do
+    it 'returns true when set to plural' do
+      property = Cartograph::Property.new(:name, scopes: [:read], plural: true)
+      expect(property).to be_plural
+    end
+
+    it 'returns false when not set' do
+      property = Cartograph::Property.new(:name, scopes: [:read])
+      expect(property).to_not be_plural
+    end
+  end
+
+  describe '#value_for' do
+    it 'returns the value when passed an object' do
+      property = Cartograph::Property.new(:sammy)
+      object = double('object', sammy: 'cephalopod')
+
+      expect(property.value_for(object)).to eq('cephalopod')
+    end
+
+    context 'for a nested property set' do
+      it 'returns nested properties' do
+        top_level = Cartograph::Property.new(:sammy) do
+          property :cephalopod
+        end
+
+        child = double('child', cephalopod: 'I will ink you')
+        root = double('root', sammy: child)
+
+        expect(top_level.value_for(root)).to eq('cephalopod' => child.cephalopod)
+      end
+
+      context 'when it is plural' do
+        it 'returns a pluralized representation' do
+          top_level = Cartograph::Property.new(:sammy, plural: true) do
+            property :cephalopod
+          end
+
+          child1 = double('child', cephalopod: 'I will ink you')
+          child2 = double('child', cephalopod: 'I wont because im cool')
+
+          root = double('root', sammy: [child1, child2])
+
+          expect(top_level.value_for(root)).to eq([
+            { 'cephalopod' => child1.cephalopod },
+            { 'cephalopod' => child2.cephalopod }
+          ])
+        end
+      end
+
+      context 'when the value for the root object is nil' do
+        it 'returns nil' do
+          top_level = Cartograph::Property.new(:sammy) do
+            property :cephalopod
+          end
+
+          root = double(sammy: nil)
+
+          expect(top_level.value_for(root)).to be_nil
+        end
+      end
+    end
+  end
+
+  describe '#value_from' do
+    let(:hash) { { hello: 'world' } }
+
+    it 'retrieves the value from a hash for the property' do
+      property = Cartograph::Property.new(:hello)
+      expect(property.value_from(hash)).to eq('world')
+    end
+
+    context 'for a nil object' do
+      it 'bails and does not try to retrieve' do
+        property = Cartograph::Property.new(:hello)
+        value = property.value_from(nil)
+        expect(value).to be_nil
+      end
+    end
+
+    context 'string and symbol agnostic' do
+      let(:hash) { { 'hello' => 'world' } }
+
+      it 'retrieves the value from a hash for the property' do
+        property = Cartograph::Property.new(:hello)
+        expect(property.value_from(hash)).to eq('world')
+      end
+    end
+
+    context 'for a nested property set' do
+      it 'returns an object with the properties set on it' do
+        dummy_class = OpenStruct
+
+        nested_property = Cartograph::Property.new(:hello) do
+          mapping dummy_class
+          property :id
+          property :name
+        end
+
+        hash = { hello: {
+          'id' => 555,
+          'name' => 'Buckstar'
+        }}
+
+        value = nested_property.value_from(hash)
+        expect(value).to be_kind_of(dummy_class)
+        expect(value.id).to eq(hash[:hello]['id'])
+        expect(value.name).to eq(hash[:hello]['name'])
+      end
+
+      it 'returns a collection of objects when set to plural' do
+        dummy_class = OpenStruct
+
+        nested_property = Cartograph::Property.new(:hello, plural: true) do
+          mapping dummy_class
+
+          property :id
+          property :name
+        end
+
+        hash = {
+          hello: [{
+            'id' => 555,
+            'name' => 'Buckstar'
+          }, {
+            'id' => 556,
+            'name' => 'Starbuck'
+          }]
+        }
+
+        value = nested_property.value_from(hash)
+        expect(value).to be_kind_of(Array)
+        expect(value.size).to be(2)
+
+        expect(value[0].id).to eq(hash[:hello][0]['id'])
+        expect(value[0].name).to eq(hash[:hello][0]['name'])
+
+        expect(value[1].id).to eq(hash[:hello][1]['id'])
+        expect(value[1].name).to eq(hash[:hello][1]['name'])
+      end
+
+      context 'when set to plural but the key is nil' do
+        it 'returns an empty array' do
+          dummy_class = Struct.new(:id, :name)
+
+          nested_property = Cartograph::Property.new(:hello, plural: true) do
+            mapping dummy_class
+
+            property :id
+            property :name
+          end
+
+          hash = { hello: nil }
+          value = nested_property.value_from(hash)
+
+          expect(value).to eq([])
+        end
+      end
+    end
+  end
+
+  describe '#dup' do
+    it 'copies the name, options, and map into another property' do
+      instance = Cartograph::Property.new(:id, scopes: [:read])
+      duped = instance.dup
+
+      expect(duped).to be_kind_of(Cartograph::Property)
+      expect(duped.name).to eq(:id)
+      expect(duped.options).to_not be(instance.options)
+      expect(duped.options).to eq(instance.options)
+    end
+  end
+end