cistern 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 51b4a1fc74578d0a0a8f89bb9b041501ab850ac9
-  data.tar.gz: 3f24e1b8145497a84d6f6b0fa449aa11b7d5e7f1
+  metadata.gz: 2f58960f3c738abbdd7203d8973981f71c370a65
+  data.tar.gz: 94a23880c49416884ece0e3615ca7e170bba7234
 SHA512:
-  metadata.gz: 2f7a72df05bb6c95d5176a36b8e8d0d17f9c9bd3179cec7424e4fc66e216e24f148bff977e4ba19f1bcee0d5afad60757e193a83bf926401a9d40be70e75a223
-  data.tar.gz: f2221f974e0817e5410e88a8d4586f28881756fcbea1836e52d8440ec97f50dfe689ae3758820e1225c2de006bfcfb0dbc0065ab70cbc0980fc2fda2f8a96b78
+  metadata.gz: 56fd5780ad10f6c44ff6704743cf927bb50600b3c45a00d1aa1afe8c2d4e237f5413bdc416e282255f924763c3fc19d2bc0afd11c52bcfb7ecf7e2f3e6c39fbd
+  data.tar.gz: aee0f212eb1923eb92131faa80a5a8fa1c8ae021e0fd1c485fb5b9ac653fba99558d71757d77fdd9baf9558dbdf27d24b72d11c5ce1cd55e52f6c2aee1fbc771

data/CHANGELOG.md

@@ -2,7 +2,18 @@
 
 ## [Unreleased](https://github.com/lanej/cistern/tree/HEAD)
 
-[Full Changelog](https://github.com/lanej/cistern/compare/v2.4.1...HEAD)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.5.0...HEAD)
+
+**Implemented enhancements:**
+
+- Associations [\#66](https://github.com/lanej/cistern/pull/66) ([lanej](https://github.com/lanej))
+
+**Fixed bugs:**
+
+- fix\(model\): \#has\_many is not loaded without records present [\#67](https://github.com/lanej/cistern/pull/67) ([lanej](https://github.com/lanej))
+
+## [v2.5.0](https://github.com/lanej/cistern/tree/v2.5.0) (2016-07-19)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.4.1...v2.5.0)
 
 **Implemented enhancements:**
 

data/README.md

@@ -404,14 +404,62 @@ class Blog::Posts < Blog::Collection
 end
 ```
 
+### Associations
+
+Associations allow the use of a resource's attributes to reference other resources.  They act as lazy loaded attributes
+and push any loaded data into the resource's `attributes`.
+
+There are two types of associations available.
+
+* `belongs_to` references a specific resource and defines a reader.
+* `has_many` references a collection of resources and defines a reader / writer.
+
+```ruby
+class Blog::Tag < Blog::Model
+  identity :id
+  attribute :author_id
+
+  has_many :posts -> { cistern.posts(tag_id: identity) }
+  belongs_to :creator -> { cistern.authors.get(author_id) }
+end
+```
+
+Relationships store the collection's attributes within the resources' attributes on write / load.
+
+```ruby
+tag = blog.tags.get('ruby')
+tag.posts = blog.posts.load({'id' => 1, 'author_id' => '2'}, {'id' => 2, 'author_id' => 3})
+tag.attributes[:posts] #=> {'id' => 1, 'author_id' => '2'}, {'id' => 2, 'author_id' => 3}
+
+tag.creator = blogs.author.get(name: 'phil')
+tag.attributes[:creator] #=> { 'id' => 2, 'name' => 'phil' }
+```
+
+Foreign keys can be updated with association writing by overwriting the writer.
+
+```ruby
+Blog::Tag.class_eval do
+  alias cistern_creator= creator=
+  def creator=(creator)
+    self.cistern_creator = creator
+    self.author_id = attributes[:creator][:id]
+  end
+end
+
+tag = blog.tags.get('ruby')
+tag.author_id = 4
+tag.creator = blogs.author.get(name: 'phil') #=> #<Blog::Author id=2 name='phil'>
+tag.author_id #=> 2
+```
+
 #### Data
 
 A uniform interface for mock data is mixed into the `Mock` class by default.
 
 ```ruby
 Blog.mock!
-client = Blog.new     # Blog::Mock
-client.data                  # Cistern::Data::Hash
+client = Blog.new # Blog::Mock
+client.data       # Cistern::Data::Hash
 client.data["posts"] += ["x"] # ["x"]
 ```
 
@@ -426,7 +474,7 @@ Blog::Mock.data["posts"] # ["x"]
 ```ruby
 client.data.object_id # 70199868585600
 client.reset!
-client.data["posts"]   # []
+client.data["posts"]  # []
 client.data.object_id # 70199868566840
 ```
 

data/lib/cistern.rb

@@ -13,6 +13,7 @@ module Cistern
   require 'cistern/hash_support'
   require 'cistern/string'
   require 'cistern/mock'
+  require 'cistern/associations'
   require 'cistern/wait_for'
   require 'cistern/attributes'
   require 'cistern/collection'

data/lib/cistern/associations.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+module Cistern::Associations
+
+  # Lists the associations defined on the resource
+  # @return [Hash{Symbol=>Array}] mapping of association type to name
+  def associations
+    @associations ||= Hash.new { |h,k| h[k] = [] }
+  end
+
+  # Define an assocation that references a collection.
+  # @param name [Symbol] name of association and corresponding reader and writer.
+  # @param scope [Proc] returning {Cistern::Collection} instance to load models into. {#scope} is evaluated within the
+  #   context of the model.
+  # @return [Cistern::Collection] as defined by {#scope}
+  # @example
+  #   class Firm < Law::Model
+  #     identity :registration_id
+  #     has_many :lawyers, -> { cistern.associates(firm_id: identity) }
+  #    end
+  def has_many(name, scope)
+    name_sym = name.to_sym
+
+    reader_method = name
+    writer_method = "#{name}="
+
+    attribute name, type: :array
+
+    define_method reader_method do
+      collection = instance_exec(&scope)
+      records = attributes[name_sym] || []
+
+      collection.load(records) if records.any?
+      collection
+    end
+
+    define_method writer_method do |models|
+      attributes[name] = Array(models).map do |model|
+        model.respond_to?(:attributes) ? model.attributes : model
+      end
+    end
+
+    associations[:has_many] << name_sym
+  end
+
+  # Define an assocation that references a model.
+  # @param name [Symbol] name of association and corresponding reader.
+  # @param scope [Proc] returning a {Cistern::Model} that is evaluated within the context of the model.
+  # @return [Cistern::Model] as defined by {#scope}
+  # @example
+  #   class Firm < Law::Model
+  #     identity :registration_id
+  #     belongs_to :leader, -> { cistern.employees.get(:ceo) }
+  #    end
+  def belongs_to(name, block)
+    name_sym = name.to_sym
+
+    reader_method = name
+    writer_method = "#{name}="
+
+    attribute name_sym
+
+    define_method reader_method do
+      model = instance_exec(&block)
+      attributes[name_sym] = model.attributes
+      model
+    end
+
+    define_method writer_method do |model|
+      data = model.respond_to?(:attributes) ? model.attributes : model
+      attributes[name_sym] = data
+      model
+    end
+
+    associations[:belongs_to] << name_sym
+  end
+end

data/lib/cistern/collection.rb

@@ -55,6 +55,7 @@ module Cistern::Collection
   alias_method :build, :initialize
 
   def initialize(attributes = {})
+    @loaded = false
     merge_attributes(attributes)
   end
 

data/lib/cistern/model.rb

@@ -6,6 +6,7 @@ module Cistern::Model
     klass.send(:extend, Cistern::Attributes::ClassMethods)
     klass.send(:include, Cistern::Attributes::InstanceMethods)
     klass.send(:extend, Cistern::Model::ClassMethods)
+    klass.send(:extend, Cistern::Associations)
   end
 
   def self.cistern_model(cistern, klass, name)

data/lib/cistern/version.rb

@@ -1,3 +1,3 @@
 module Cistern
-  VERSION = '2.5.0'
+  VERSION = '2.6.0'
 end

data/spec/associations_spec.rb

@@ -0,0 +1,155 @@
+require 'spec_helper'
+
+describe Cistern::Associations do
+  subject { Class.new(Sample::Model) }
+
+  describe '#associations' do
+    before {
+      Sample::Associate = Class.new(Sample::Model) do
+        identity :id
+
+        belongs_to :association, -> { [] }
+        has_many :associates, -> { [] }
+      end
+    }
+
+    it 'returns a mapping of associations types to names' do
+      expect(Sample::Associate.associations).to eq(
+        {
+          :belongs_to => [:association],
+          :has_many => [:associates],
+        }
+      )
+    end
+  end
+
+  describe '#belongs_to' do
+    before {
+      Sample::Associate = Class.new(Sample::Model) do
+        identity :id
+      end
+
+      subject.class_eval do
+        identity :id
+        attribute :associate_id
+
+        belongs_to :associate, -> { Sample::Associate.new(id: associate_id) }
+      end
+    }
+
+    it 'returns an associated model' do
+      sample = subject.new(id: 1, associate_id: 2)
+
+      belongs_to = Sample::Associate.new(id: 2)
+
+      expect(sample.associate).to eq(belongs_to)
+    end
+
+    describe '{belongs_to}=' do
+      it 'accepts a model' do
+        sample = subject.new(id: 1, associate_id: 2)
+
+        belongs_to = Sample::Associate.new(id: 2)
+
+        expect(sample.associate).to eq(belongs_to)
+        expect(sample.attributes[:associate]).to eq(id: 2)
+      end
+
+      it 'accepts raw data' do
+        sample = subject.new
+        sample.associate = { id: 2 }
+
+        expect(sample.attributes[:associate]).to eq(id: 2)
+      end
+
+      it 'allows for overrides' do
+        subject.class_eval do
+          alias cistern_associate= associate=
+          def associate=(associate)
+            self.cistern_associate = associate
+            self.associate_id = attributes[:associate][:id]
+          end
+        end
+
+        sample = subject.new(id: 1, associate_id: 3)
+
+        belongs_to = Sample::Associate.new(id: 2)
+
+        expect {
+          sample.associate = belongs_to
+        }.to change(sample, :associate_id).to(2)
+      end
+    end
+  end
+
+  describe '#has_many' do
+    before {
+      Sample::Associate = Class.new(Sample::Model) do
+        identity :id
+      end
+
+      Sample::Associates = Class.new(Sample::Collection) do
+
+        attribute :associate_id
+
+        model Sample::Associate
+
+        def all
+          load([{id: associate_id + 1}])
+        end
+      end
+
+      subject.class_eval do
+        identity :id
+        attribute :associate_id
+
+        has_many :associates, -> { Sample::Associates.new(associate_id: associate_id) }
+      end
+    }
+
+    it 'returns associated models' do
+      expected = Sample::Associates.new(associate_id: 2).load([{id: 3}])
+
+      expect(subject.new(associate_id: 2).associates.all).to eq(expected)
+    end
+
+    it 'does not consider the associated collection loaded without records' do
+      model = subject.new(associate_id: 2)
+      model.associates = []
+
+      expect(model.associates.loaded).to eq(false)
+    end
+
+    it 'considers the associated collection loaded with records' do
+      model = subject.new(associate_id: 2)
+      model.associates = Sample::Associates.new(associate_id: 2).load([{id: 3}])
+
+      expect(model.associates.loaded).to eq(true)
+      expect(model.associates.records).to contain_exactly(Sample::Associate.new(id: 3))
+    end
+
+    describe '{has_many}=' do
+      it 'accepts models' do
+        model = subject.new(associate_id: 2)
+        associates_data = [ { id: 1 }, { id: 2 }]
+        associates = Sample::Associates.new.load(associates_data)
+
+        model.associates = [ Sample::Associate.new(id: 1), Sample::Associate.new(id: 2) ]
+
+        expect(model.attributes[:associates]).to eq(associates_data)
+        expect(model.associates).to eq(associates)
+      end
+
+      it 'accepts raw data' do
+        model = subject.new(associate_id: 2)
+        associates_data = [ { id: 1 }, { id: 2 }]
+        associates = Sample::Associates.new.load(associates_data)
+
+        model.associates = associates_data
+
+        expect(model.attributes[:associates]).to eq(associates_data)
+        expect(model.associates).to eq(associates)
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cistern
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Josh Lane
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-19 00:00:00.000000000 Z
+date: 2016-07-26 00:00:00.000000000 Z
 dependencies: []
 description: API client framework extracted from Fog
 email:
@@ -31,6 +31,7 @@ files:
 - cistern.gemspec
 - gemfiles/ruby_lt_2.0.gemfile
 - lib/cistern.rb
+- lib/cistern/associations.rb
 - lib/cistern/attributes.rb
 - lib/cistern/client.rb
 - lib/cistern/collection.rb
@@ -53,6 +54,7 @@ files:
 - lib/cistern/timeout.rb
 - lib/cistern/version.rb
 - lib/cistern/wait_for.rb
+- spec/associations_spec.rb
 - spec/attributes_spec.rb
 - spec/client_spec.rb
 - spec/collection_spec.rb
@@ -93,6 +95,7 @@ signing_key:
 specification_version: 4
 summary: API client framework
 test_files:
+- spec/associations_spec.rb
 - spec/attributes_spec.rb
 - spec/client_spec.rb
 - spec/collection_spec.rb