flattery 0.0.3 → 0.0.4

data/README.md

@@ -7,14 +7,14 @@ The two main reasons you might want to do this are probably:
 
 Hence flattery - a gem that provides a simple declarative method for caching and maintaining such values.
 
-Flattery is primarily intended for use with relational Active::Record storage, and is only tested with sqlite and PostgreSQL.
+Flattery is primarily intended for use with relational ActiveRecord storage, and is only tested with sqlite and PostgreSQL.
 If you are using NoSQL, you probably wouldn't design your schema in a way for which flattery adds any value - but if you find a situation where this makes sense, then feel free to fork and add the support .. or lobby for it's inclusion!
 
 ## Requirements
 
 * Ruby 1.9 or 2
 * Rails 3.x/4.x
-* ActiveRecord (only sqlite and PostgreQL tested. Others _should_ work; raise an issue if you find problems)
+* ActiveRecord (only sqlite and PostgreSQL tested. Others _should_ work; raise an issue if you find problems)
 
 ## Installation
 
@@ -34,7 +34,7 @@ Or install it yourself as:
 
 ### How to cache values from a :belongs_to association
 
-Given a model with a :belongs_to association, you want to store a (copy/cached) value from the associated record.
+Given a model with a :belongs_to association, you want to store a (copy/cached) value from the associated record. The <tt>Flattery::ValueCache</tt> module is used to define the behaviour.
 
     class Category < ActiveRecord::Base
       has_many :notes, :inverse_of => :category
@@ -48,14 +48,14 @@ Given a model with a :belongs_to association, you want to store a (copy/cached)
     end
 
 In this case, when you save an instance of Note, it will store the instance.category.name value as instance.category_name.
-The :category_name attribute is inferred from the relationship, and is assumed to be present in the schema.
-So before you can use this, you must add a migration to add the :category_name column to the notes table (with the same type as the :name column on the Category table).
+The <tt>:category_name</tt> attribute is inferred from the relationship, and is assumed to be present in the schema.
+So before you can use this, you must add a migration to add the <tt>:category_name</tt> column to the notes table (with the same type as the <tt>:name</tt> column on the Category table).
 
 
 ### How to cache the value in a specific column name
 
-In the usual case, the cache column name is inferred from the association (e.g. category_name in the example above).
-If you want to store in another column name, use the :as option on the +flatten_value+ call:
+In the usual case, the cache column name is inferred from the association (e.g. <tt>:category_name</tt> in the example above).
+If you want to store in another column name, use the <tt>:as</tt> option on the <tt>flatten_value</tt> call:
 
     class Note < ActiveRecord::Base
       belongs_to :category
@@ -68,8 +68,7 @@ Again, you must make sure the column is correctly defined in your schema.
 
 ### How to push updates to cached values from the source model
 
-Given the example above, we have a problem if Category records are updated - the :category_name value stored in Notes gets out of sync.
-The Flattery::ValueProvider module fixes this by propagating changes accordingly.
+Given the example above, we have a problem if Category records are updated - the <tt>:category_name</tt> value stored in Notes gets out of sync. The <tt>Flattery::ValueProvider</tt> module fixes this by propagating changes accordingly.
 
     class Category < ActiveRecord::Base
       has_many :notes
@@ -78,13 +77,13 @@ The Flattery::ValueProvider module fixes this by propagating changes accordingly
       push_flattened_values_for :name => :notes
     end
 
-This will push changes to Category :name to Notes records (by inference, updating the :category_name value in Notes).
+This will push changes to Category <tt>:name</tt> to Notes records (by inference, updating the <tt>:category_name</tt> value in Notes).
 
 ### How to push updates to cached values from the source model to a specific cache column name
 
 If the cache column name cannot be inferred correctly, an error will be raised. Inference errors can occur if the inverse association relation cannot be determined.
 
-To 'help' flattery figure out the correct column name, specify the column name with an :as option:
+To help flattery figure out the correct column name, specify the column name with an <tt>:as</tt> option:
 
     class Category < ActiveRecord::Base
       has_many :notes
@@ -93,6 +92,54 @@ To 'help' flattery figure out the correct column name, specify the column name w
       push_flattened_values_for :name => :notes, :as => 'cat_name'
     end
 
+### How are cached values pushed from the source model?
+
+The default mechanism for performing the update of cached values is with the standard ActiveRecord <tt>:update_all</tt> method (scoped to only the affected records). This is done in the <tt>after_update</tt> phase of the [ActiveRecord callback lifecycle](http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html), and does not background the processing by default.
+
+This should be fine for modest applications, but if the update will affect many records - especially if there is a high likelihood of read/write contention - then it may need finessing. Flattery allows you to define your own update procedure for these cases - see the next section.
+
+### How to provide a custom method for updating cached values
+
+Use the <tt>:method</tt> option to declare the instance method to be used:
+
+    class Category < ActiveRecord::Base
+      has_many :notes
+
+      include Flattery::ValueProvider
+      push_flattened_values_for :name => :notes, :as => 'cat_name', :method => :my_custom_updater
+
+      # You custom update method definition. Parameters:
+      # * +attribute+ is the attribute name that the value is coming from e.g. :name
+      # * +new_value+ is the new value that has been set e.g. 'a value that was just set'
+      # * +association_name+ is the association that updates need to be pushed to set e.g. :notes
+      # * +target_attribute+ is the attribute name that needs to be updated   e.g. :cat_name
+      def my_custom_updater(attribute,new_value,association_name,target_attribute)
+        # implement your custom update algorithm here. It could do some funky batched SQL for example.
+        # For now here's just a simple update_all implementation:
+        self.send(association_name).update_all(target_attribute => new_value)
+      end
+    end
+
+### How can I get cached value updates pushed in the background?
+
+Flattery has support for getting updates done in the background. This is not the default behaviour, and must be defined for each <tt>Flattery::ValueProvider</tt> declaration.
+
+Currently only [Delayed::Job](https://github.com/collectiveidea/delayed_job) is supported. If you want to background with another queue technology, for now the best is to implement this inside a custom update method.
+
+#### How to background with Delayed::Job
+
+Use the <tt>:background_with</tt> option:
+
+    class Category < ActiveRecord::Base
+      has_many :notes
+
+      include Flattery::ValueProvider
+      push_flattened_values_for :name => :notes, :as => 'cat_name', :background_with => :delayed_job
+
+    end
+
+Note that Delayed::Job is not an explicit dependency of Flattery, so to use Delayed::Job you must have separately added and set it up in your project. Flattery will try to use it if available, and fallback to foreground processing if not.
+
 
 ## Contributing
 

data/flattery.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = Flattery::VERSION
   spec.authors       = ["Paul Gallagher"]
   spec.email         = ["paul@evendis.com"]
-  spec.description   = %q{Flatten/normalise values from ActiveModel associations}
-  spec.summary       = %q{Flatter your nicely normalised AR models}
+  spec.description   = %q{a gem to denormalize (flatten) selected ActiveRecord association attributes and automatically keep them in sync with the normal form}
+  spec.summary       = %q{Flatter your nicely normalized ActiveRecord models}
   spec.homepage      = "https://github.com/evendis/flattery"
   spec.license       = "MIT"
 

data/lib/flattery/settings.rb

@@ -27,6 +27,7 @@ class Flattery::Settings
     opt = options.symbolize_keys
     as_setting = opt.delete(:as).try(:to_s)
     method_setting = opt.delete(:method).try(:to_sym)
+    background_setting = opt.delete(:background_with).try(:to_sym)
 
     if from_entity = opt.keys.first
       cache_options[:from_entity] = from_entity
@@ -34,6 +35,7 @@ class Flattery::Settings
     end
     cache_options[:as] = as_setting
     cache_options[:method] = method_setting if method_setting
+    cache_options[:background_with] = background_setting if background_setting
 
     cache_options
   end

data/lib/flattery/value_cache.rb

@@ -2,8 +2,6 @@ module Flattery::ValueCache
   extend ActiveSupport::Concern
 
   included do
-    class_attribute :value_cache_options
-    self.value_cache_options = Settings.new(self)
     before_save Processor.new
   end
 
@@ -24,6 +22,18 @@ module Flattery::ValueCache
       self.value_cache_options.add_setting(options)
     end
 
+    # Returns the Flattery::ValueCache options value object.
+    # It will inherit settings from a parent class if a model hierarchy has been defined
+    def value_cache_options
+      @value_cache_options ||= if superclass.respond_to?(:value_cache_options)
+        my_settings = Settings.new(self)
+        my_settings.raw_settings = superclass.value_cache_options.raw_settings.dup
+        my_settings
+      else
+        Settings.new(self)
+      end
+    end
+
   end
 
 end

data/lib/flattery/value_provider.rb

@@ -2,9 +2,7 @@ module Flattery::ValueProvider
   extend ActiveSupport::Concern
 
   included do
-    class_attribute :value_provider_options
-    self.value_provider_options = Settings.new(self)
-    before_update Processor.new
+    after_update Processor.new
   end
 
   module ClassMethods
@@ -24,6 +22,18 @@ module Flattery::ValueProvider
       self.value_provider_options.add_setting(options)
     end
 
+    # Returns the Flattery::ValueProvider options value object.
+    # It will inherit settings from a parent class if a model hierarchy has been defined
+    def value_provider_options
+      @value_provider_options ||= if superclass.respond_to?(:value_provider_options)
+        my_settings = Settings.new(self)
+        my_settings.raw_settings = superclass.value_provider_options.raw_settings.dup
+        my_settings
+      else
+        Settings.new(self)
+      end
+    end
+
   end
 
 end

data/lib/flattery/value_provider/processor.rb

@@ -1,14 +1,18 @@
 class Flattery::ValueProvider::Processor
 
   # Command: pushes cache updates for related changed attributes
-  def before_update(record)
+  def after_update(record)
     resolved_options!(record.class).each do |key,options|
       if record.changed.include?(key)
-        if cache_column = options[:as]
-          case options[:method]
-          when :update_all
-            new_value = record.send(key)
-            record.send(options[:to_entity]).update_all({cache_column => new_value})
+        if target_attribute = options[:as]
+          method = options[:method]
+          attribute = key.to_sym
+          new_value = record.send(key)
+          association_name = options[:to_entity]
+          if options[:background_with] == :delayed_job && self.respond_to?(:delay)
+            self.delay.apply_push(record,method,attribute,new_value,association_name,target_attribute)
+          else
+            apply_push(record,method,attribute,new_value,association_name,target_attribute)
           end
         else
           raise Flattery::CacheColumnInflectionError.new("#{record.class.name} #{key}: #{options}")
@@ -18,6 +22,16 @@ class Flattery::ValueProvider::Processor
     true
   end
 
+  # Command: performs an update for a specific cache setting
+  def apply_push(record,method,attribute,new_value,association_name,target_attribute)
+    case method
+    when :update_all
+      record.send(association_name).update_all({target_attribute => new_value})
+    else # it is a custom update method
+      record.send(method,attribute,new_value,association_name,target_attribute)
+    end
+  end
+
   # Command: resolves value provider options for +klass+ if required, and returns resolved options
   def resolved_options!(klass)
     klass.value_provider_options.settings

data/lib/flattery/value_provider/settings.rb

@@ -26,6 +26,7 @@ class Flattery::ValueProvider::Settings < Flattery::Settings
       to_entity = setting[:to_entity]
 
       push_method = setting[:method]
+      background_with = setting[:background_with]
       attribute_name = "#{from_entity}"
 
       assoc = klass.reflect_on_association(to_entity)
@@ -50,7 +51,8 @@ class Flattery::ValueProvider::Settings < Flattery::Settings
         {
           to_entity: to_entity,
           as: cached_attribute_name,
-          method: push_method
+          method: push_method,
+          background_with: background_with
         }
       end
 

data/lib/flattery/version.rb

@@ -1,3 +1,3 @@
 module Flattery
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/spec/support/active_record_fixtures.rb

@@ -8,7 +8,10 @@ ActiveRecord::Migration.suppress_messages do
       t.string :name;
       t.belongs_to :category;
       t.string :category_name;
+      t.string :category_description;
       t.string :cat_name;
+      t.belongs_to :country;
+      t.string :country_name;
       t.string :person_name;
       t.string :person_email;
       t.string :user_email;
@@ -16,6 +19,11 @@ ActiveRecord::Migration.suppress_messages do
 
     create_table(:categories, :force => true) do |t|
       t.string :name;
+      t.string :description;
+    end
+
+    create_table(:countries, :force => true) do |t|
+      t.string :name;
     end
 
     create_table(:people, :force => true) do |t|
@@ -29,6 +37,7 @@ end
 # Basic models for testing
 class Note < ActiveRecord::Base
   belongs_to :category
+  belongs_to :country
   belongs_to :person, primary_key: "username", foreign_key: "person_name"
 end
 
@@ -36,6 +45,10 @@ class Category < ActiveRecord::Base
   has_many :notes
 end
 
+class Country < ActiveRecord::Base
+  has_many :notes
+end
+
 class Person < ActiveRecord::Base
   has_many :notes, primary_key: "username", foreign_key: "person_name", inverse_of: :person
 end
@@ -51,7 +64,9 @@ module ArHelper
 
   def clear_harness_classes
     Object.send(:remove_const, :ValueProviderHarness) if Object.constants.include?(:ValueProviderHarness)
+    Object.send(:remove_const, :ChildValueProviderHarness) if Object.constants.include?(:ChildValueProviderHarness)
     Object.send(:remove_const, :ValueCacheHarness) if Object.constants.include?(:ValueCacheHarness)
+    Object.send(:remove_const, :ChildValueCacheHarness) if Object.constants.include?(:ChildValueCacheHarness)
   end
 
 end

data/spec/unit/settings_spec.rb

@@ -76,9 +76,16 @@ describe Flattery::Settings do
     end
 
     context "when optional :method specified as Symbols" do
-      before { settings.add_setting({category: :name, method: :update_all}) }
+      before { settings.add_setting({category: :name, method: :my_custom_updater}) }
       its(:raw_settings) { should eql([
-        { from_entity: :category, to_entity: :name, as: nil, method: :update_all }
+        { from_entity: :category, to_entity: :name, as: nil, method: :my_custom_updater }
+      ]) }
+    end
+
+    context "when optional :background_with specified as Symbols" do
+      before { settings.add_setting({category: :name, background_with: :delayed_job}) }
+      its(:raw_settings) { should eql([
+        { from_entity: :category, to_entity: :name, as: nil, background_with: :delayed_job }
       ]) }
     end
 

data/spec/unit/value_cache/settings_spec.rb

@@ -29,4 +29,53 @@ describe Flattery::ValueCache::Settings do
     end
   end
 
+  context "with inherited model definitions and ValueCache defined in the parent" do
+    let!(:parent_cache_class) do
+      class ::ValueCacheHarness < Note
+        include Flattery::ValueCache
+        flatten_value category: :name
+      end
+      ValueCacheHarness
+    end
+    let!(:child_cache_class) do
+      class ::ChildValueCacheHarness < ::ValueCacheHarness
+        flatten_value country: :name
+      end
+      ChildValueCacheHarness
+    end
+    context "before resolution" do
+      describe "parent" do
+        let(:settings) { parent_cache_class.value_cache_options }
+        its(:raw_settings) { should eql([
+          {from_entity: :category, to_entity: :name, as: nil}
+        ]) }
+      end
+      describe "child" do
+        let(:settings) { child_cache_class.value_cache_options }
+        its(:raw_settings) { should eql([
+          {from_entity: :category, to_entity: :name, as: nil},
+          {from_entity: :country, to_entity: :name, as: nil}
+        ]) }
+      end
+    end
+    context "after resolution" do
+      before { parent_cache_class.value_cache_options.settings && child_cache_class.value_cache_options.settings}
+      describe "parent" do
+        let(:settings) { parent_cache_class.value_cache_options }
+        its(:resolved) { should be_true }
+        its(:settings) { should eql({
+          "category_name"=>{from_entity: :category, to_entity: :name, changed_on: ["category_id"]}
+        }) }
+      end
+      describe "child" do
+        let(:settings) { child_cache_class.value_cache_options }
+        its(:resolved) { should be_true }
+        its(:settings) { should eql({
+          "category_name"=>{from_entity: :category, to_entity: :name, changed_on: ["category_id"]},
+          "country_name"=>{from_entity: :country, to_entity: :name, changed_on: ["country_id"]}
+        }) }
+      end
+    end
+  end
+
 end

data/spec/unit/value_provider/processor_spec.rb

@@ -2,6 +2,7 @@ require 'spec_helper.rb'
 
 # Test caching in a range of actual scenarios
 describe Flattery::ValueProvider::Processor do
+  let(:processor_class) { Flattery::ValueProvider::Processor }
 
   context "with provider having simple has_many association and explicit cache_column name" do
     let(:provider_class) do
@@ -127,4 +128,115 @@ describe Flattery::ValueProvider::Processor do
     end
   end
 
+  context "with a custom update method" do
+    let(:provider_class) do
+      class ::ValueProviderHarness < Category
+        include Flattery::ValueProvider
+        push_flattened_values_for name: :notes, as: :category_name, method: :my_updater_method
+        def my_updater_method(attribute,new_value,association_name,target_attribute)
+          self.send(association_name).update_all(target_attribute => "#{new_value} (set by my_updater_method)")
+        end
+      end
+      ValueProviderHarness
+    end
+
+    let(:cache_class) do
+      class ::ValueCacheHarness < Note
+        include Flattery::ValueCache
+        flatten_value category: :name
+      end
+      ValueCacheHarness
+    end
+
+    let!(:resource)       { provider_class.create(name: 'category_a') }
+    let!(:target_a)       { cache_class.create(category_id: resource.id) }
+    let!(:target_other_a) { cache_class.create }
+    context "when cached value is updated" do
+      it "should push the new cache value" do
+        expect {
+          resource.update_attributes(name: 'new category name')
+        }.to change {
+          target_a.reload.category_name
+        }.from('category_a').to('new category name (set by my_updater_method)')
+      end
+    end
+  end
+
+  context "with delayed job support stubbed" do
+    before do
+      processor_class.any_instance.stub(:delay)
+    end
+
+    context "and background processing requested" do
+
+      let(:provider_class) do
+        class ::ValueProviderHarness < Category
+          include Flattery::ValueProvider
+          push_flattened_values_for name: :notes, as: :category_name, background_with: :delayed_job
+        end
+        ValueProviderHarness
+      end
+
+      let(:cache_class) do
+        class ::ValueCacheHarness < Note
+          include Flattery::ValueCache
+          flatten_value category: :name
+        end
+        ValueCacheHarness
+      end
+
+      let!(:resource)       { provider_class.create(name: 'category_a') }
+      let!(:target_a)       { cache_class.create(category_id: resource.id) }
+      let!(:target_other_a) { cache_class.create }
+
+      it "should update via delay" do
+        processor = double()
+        processor.should_receive(:apply_push)
+        processor_class.any_instance.should_receive(:delay).and_return(processor)
+        resource.update_attributes(name: 'new category name')
+      end
+    end
+  end
+
+  context "with delayed job support mocked" do
+    before do
+      processor_class.send(:define_method,:delay) { self }
+    end
+    after do
+      processor_class.send(:undef_method,:delay)
+    end
+
+    context "and background processing requested" do
+
+      let(:provider_class) do
+        class ::ValueProviderHarness < Category
+          include Flattery::ValueProvider
+          push_flattened_values_for name: :notes, as: :category_name, background_with: :delayed_job
+        end
+        ValueProviderHarness
+      end
+
+      let(:cache_class) do
+        class ::ValueCacheHarness < Note
+          include Flattery::ValueCache
+          flatten_value category: :name
+        end
+        ValueCacheHarness
+      end
+
+      let!(:resource)       { provider_class.create(name: 'category_a') }
+      let!(:target_a)       { cache_class.create(category_id: resource.id) }
+      let!(:target_other_a) { cache_class.create }
+
+      it "should push the new cache value" do
+        expect {
+          resource.update_attributes(name: 'new category name')
+        }.to change {
+          target_a.reload.category_name
+        }.from('category_a').to('new category name')
+      end
+
+    end
+  end
+
 end

data/spec/unit/value_provider/settings_spec.rb

@@ -25,10 +25,58 @@ describe Flattery::ValueProvider::Settings do
       before { settings.settings }
       its(:resolved) { should be_true }
       its(:settings) { should eql({
-        "name"=>{to_entity: :notes, as: :category_name, method: :update_all}
+        "name"=>{to_entity: :notes, as: :category_name, method: :update_all, background_with: nil}
       }) }
     end
   end
 
+  context "with inherited model definitions and ValueProvider defined in the parent" do
+    let!(:parent_provider_class) do
+      class ::ValueProviderHarness < Category
+        include Flattery::ValueProvider
+        push_flattened_values_for name: :notes, as: :category_name
+      end
+      ValueProviderHarness
+    end
+    let!(:child_provider_class) do
+      class ::ChildValueProviderHarness < ::ValueProviderHarness
+        push_flattened_values_for description: :notes, as: :category_description
+      end
+      ChildValueProviderHarness
+    end
+    context "before resolution" do
+      describe "parent" do
+        let(:settings) { parent_provider_class.value_provider_options }
+        its(:raw_settings) { should eql([
+          {from_entity: :name, to_entity: :notes, as: 'category_name', method: :update_all}
+        ]) }
+      end
+      describe "child" do
+        let(:settings) { child_provider_class.value_provider_options }
+        its(:raw_settings) { should eql([
+          {from_entity: :name, to_entity: :notes, as: 'category_name', method: :update_all},
+          {from_entity: :description, to_entity: :notes, as: 'category_description', method: :update_all}
+        ]) }
+      end
+    end
+    context "after resolution" do
+      before { parent_provider_class.value_provider_options.settings && child_provider_class.value_provider_options.settings}
+      describe "parent" do
+        let(:settings) { parent_provider_class.value_provider_options }
+        its(:resolved) { should be_true }
+        its(:settings) { should eql({
+          "name"=>{to_entity: :notes, as: :category_name, method: :update_all, background_with: nil}
+        }) }
+      end
+      describe "child" do
+        let(:settings) { child_provider_class.value_provider_options }
+        its(:resolved) { should be_true }
+        its(:settings) { should eql({
+          "name"=>{to_entity: :notes, as: :category_name, method: :update_all, background_with: nil},
+          "description"=>{to_entity: :notes, as: :category_description, method: :update_all, background_with: nil}
+        }) }
+      end
+    end
+  end
 
 end

data/spec/unit/value_provider_spec.rb

@@ -14,15 +14,15 @@ describe Flattery::ValueProvider do
   its(:included_modules) { should include(Flattery::ValueProvider) }
   its(:value_provider_options) { should be_a(Flattery::ValueProvider::Settings) }
 
-  describe "#before_update" do
+  describe "#after_update" do
     let(:processor_class) { Flattery::ValueProvider::Processor }
     it "should not be called when record created" do
-      processor_class.any_instance.should_receive(:before_update).never
+      processor_class.any_instance.should_receive(:after_update).never
       provider_class.create!
     end
     it "should be called when record updated" do
       instance = provider_class.create!
-      processor_class.any_instance.should_receive(:before_update).and_return(true)
+      processor_class.any_instance.should_receive(:after_update).and_return(true)
       instance.save
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flattery
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-10 00:00:00.000000000 Z
+date: 2013-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -155,7 +155,8 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 1.3.2
-description: Flatten/normalise values from ActiveModel associations
+description: a gem to denormalize (flatten) selected ActiveRecord association attributes
+  and automatically keep them in sync with the normal form
 email:
 - paul@evendis.com
 executables: []
@@ -215,7 +216,7 @@ rubyforge_project:
 rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
-summary: Flatter your nicely normalised AR models
+summary: Flatter your nicely normalized ActiveRecord models
 test_files:
 - spec/spec_helper.rb
 - spec/support/active_record_fixtures.rb