arid_cache 1.3.0 → 1.3.1

data/README.rdoc

@@ -8,6 +8,7 @@ AridCache simplifies caching by supporting auto-expiring cache keys - as well as
 
 == Changes
 
+v1.3.1: Support proxies which allow you to control how your objects get serialized and unserialized
 v1.3.0: Support limits, ordering and pagination on cached Enumerables
 v1.2.0: Fix Rails 3 ActiveRecord hooks & remove some Rails dependencies
 v1.0.5: Support <tt>:raw</tt> and <tt>:clear</tt> options.
@@ -42,11 +43,12 @@ Then
 * Supports limits, ordering & pagination of cached Enumerables and ActiveRecord collections
 * Define caches and their options on your class using +instance_caches+ and +class_caches+
 * Counts for free - if you have already cached the result, you get the count for free
-* Supports eager-loading and other options to <tt>ActiveRecord::Base#find</tt> like
-:conditions, :include, :joins, :select, :readonly, :group, :having, :from
+* Smart counts - if you only ask for the count it will only calculate the count; useful when the result is an Association Reflection or a named scope.
+* Supports eager-loading and other options to <tt>ActiveRecord::Base#find</tt> like <tt>:conditions</tt>, <tt>:include</tt>, <tt>:joins</tt>, <tt>:select</tt>, <tt>:readonly</tt>, <tt>:group</tt>, <tt>:having</tt>, <tt>:from</tt>
 * Provides methods to clear caches individually, at the instance-level, class-level and globally
 * Preserves the order of your cached ActiveRecord collections
 * Optimized to make as few cache and database accesses as absolutely neccessary
+* Define your own cache proxy to serialize your objects as they go to and from the cache
 
 == Introduction
 
@@ -63,10 +65,25 @@ The way you interact with the cache via your model methods is to prepend the met
 
 You can also define caches that use compositions of methods or named scopes, or other complex queries, without having to add a new method to your class.  This way you can also create different caches that all use the same method.  For example,
 
-  User.cached_most_active_users do
-    active.find(:order => 'activity DESC', :limit => 5)
+  class User
+    named_scope :active, :conditions => { :active => true }
+    class_caches do
+      most_active_users(:limit => 5) do
+        active.find(:order => 'activity DESC')
+      end
+    end
   end
 
+This defines a cache +most_active_users+ on the User class which we can call with:
+
+  User.cached_most_active_users
+  >> [#<User>, #<User>]
+
+This will return up to five users, but there may be many more in the cache, because we didn't apply a limit in our call to <tt>active.find()</tt>.  We can also pass options to the call to override the stored options:
+
+  User.cached_most_active_users(:limit => 1)
+  >> [#<User>]
+
 === ActiveRecord Collections
 
 If the result of your <tt>cached_</tt> call is an array of ActiveRecords, AridCache only stores the IDs in the cache (because it's a bad idea to store records in the cache).
@@ -358,6 +375,65 @@ In some circumstances - like when you are querying on a named scope - if you hav
         :ids => [2, 235, 236, 237]  # the ids array is seeded before returning
     }
 
+== Proxies
+
+Proxies allow you to do anything you want to your objects as they go into - and come out of - the cache.  They are most useful for serializing your objects, for example if you want to store JSON, or hashes.
+
+The <tt>:proxy</tt> option should be a Symbol giving the name of a class method.  The method is passed the result of your cache block (or method) as the first parameter, and in future may also pass a Hash of options.  The method is called on the class that calls +cached_+.
+
+A simple example of a proxy which stores hashes of ActiveRecord attributes:
+
+  class User
+    has_many :companies
+
+    instance_caches do
+      companies(:proxy => :serializing_proxy)
+    end
+
+    def self.serializing_proxy(records, *args)
+      return records if records.empty?
+      records.first.is_a?(ActiveRecord::Base) ? records.collect(&:attributes) : records.collect { |r| Company.find_by_id(r['id']) }
+    end
+  end
+
+Now when we first call <tt>User.first.cached_companies<tt> the cache is empty, so the cache method (<tt>companies</tt>) is called and the result is passed to <tt>User.serializing_proxy</tt> which converts the records to Hashes.  The result of the proxy is stored in the cache.  The next time we call <tt>User.first.cached_companies<tt> the cached result is retrieved and passed to <tt>User.serializing_proxy</tt> which converts the hashes to records, so we get ActiveRecords back.
+
+  @user = User.first
+  @user.cached_companies
+  >> [#<Company id: 1>, #<Company id: 2>]
+
+  @user.cached_companies(:raw => true)
+  >> [{ 'id' => 1 }, { 'id' => 2 }]
+
+The <tt>:raw</tt> option bypasses the proxy on the way out of the cache because we are asking for a raw result.  The <tt>:raw</tt> option works a bit differently from the default behaviour (which is to return a <tt>CachedResult</tt> object if the cached result is an ActiveRecord collection) because you can use options to do limiting, pagination and in-memory ordering with <tt>:raw</tt> to get different views of your cached enumerable.
+
+Proxies still support limits, pagination and ordering, which is applied to the cached result.  For example:
+
+Limits:
+
+  @user.cached_companies(:limit => 2, :offset => 1)
+  >> [#<Company id: 2>]
+
+Pagination returns a <tt>WillPaginate::Collection</tt>:
+
+  result = @user.cached_companies(:page => 2, :per_page => 1)
+  >> [#<Company id: 2>]
+  result.total_entries
+  >> 1
+  result.current_page
+  >> 2
+
+Order by:
+
+  @user.cached_companies(:order => Proc.new { |a, b| b['id'] <=> a['id'] })
+  >> [#<Company id: 2>, #<Company id: 1>]
+
+The above Proc orders by id reversed.  We can also combine all the options.  The order by will be applied first, then the limits and finally the pagination.
+
+All of the above calls work with <tt>raw => true</tt>.  With that option the results would be same but instead of returning records, it returns hashes.
+
+In practice you probably want to define your proxy method on <tt>ActiveRecord::Base</tt> so that it is available to all your models.  In future AridCache will probably have some built-in proxies that you can make use of.
+
 == Efficiency
 
 * AridCache intercepts calls to <tt>cached_</tt> methods using <tt>method_missing</tt> then defines those methods on your models as they are called, so they bypass method missing on subsequent calls.
@@ -383,7 +459,7 @@ For Ruby < 1.8.7 you probably want to include the following to extend the Array
 == Known Issues
 
 1. <b>Caches that contains duplicate records will only return unique records on subsequent calls</b>.  This is because of the way <tt>find</tt> works when selecting multiple ids.  For example, if your query returns <tt>[#<User id: 1>, #<User id: 1>, #<User id: 1>]</tt>, the IDs are cached as <tt>[1,1,1]</tt>.  On the next call to the cache we load the IDs using <tt>User.find_all_by_id([1,1,1])</tt> which returns <tt>[#<User id: 1>]</tt>, not <tt>[#<User id: 1>, #<User id: 1>, #<User id: 1>]</tt> as you might have expected.
-2. <b>You can't cache polymorphic arrays</b> e.g. [#<User id: 1>, #<Pet id: 5>] because it expects all ActiveRecords to be of the same class.  We could accept a <tt>:polymorphic => true</tt> option but I don't think this is a great idea because instantiating all the records would result in a lot of queries to the individual tables.
+2. <b>You can't cache polymorphic arrays</b> e.g. [#<User id: 1>, #<Pet id: 5>] because it expects all ActiveRecords to be of the same class.  If you need polymorphism consider using a proxy.
 
 == Contributors
 

data/VERSION

@@ -1 +1 @@
-1.3.0
+1.3.1

data/arid_cache.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{arid_cache}
-  s.version = "1.3.0"
+  s.version = "1.3.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Karl Varga"]
-  s.date = %q{2011-04-05}
+  s.date = %q{2011-04-06}
   s.description = %q{AridCache makes caching easy and effective.  AridCache supports caching on all your model named scopes, class methods and instance methods right out of the box.  AridCache prevents caching logic from cluttering your models and clarifies your logic by making explicit calls to cached result sets.
 AridCache is designed for handling large, expensive ActiveRecord collections but is equally useful for caching anything else as well.
 }

data/lib/arid_cache/active_record.rb

@@ -36,7 +36,9 @@ module AridCache
         elsif options[:auto_expire]
           self.cache_key
         else
-          "#{AridCache::Inflector.pluralize(self.class.name.downcase)}/#{self.id}"
+          result = "#{AridCache::Inflector.pluralize(self.class.name.downcase)}"
+          result += "/#{self[:id]}" if self.respond_to?(:[]) && !self[:id].nil?
+          result
         end
         'arid-cache-' + object_key + '-' + key.to_s
       end

data/lib/arid_cache/cache_proxy/options.rb

@@ -67,6 +67,10 @@ module AridCache
       
       def order_by_key?
         include?(:order) && (self[:order].is_a?(Symbol) || self[:order].is_a?(String))
+      end  
+      
+      def proxy?
+        include?(:proxy)
       end
     end
   end

data/lib/arid_cache/cache_proxy/result_processor.rb

@@ -6,6 +6,11 @@ module AridCache
     # Provides methods to introspect the result.  The contents could be a base type,
     # or an enumerable of sorts...any type really.  We are only concerned with enumerables,
     # and especially those containing active records.
+    #
+    # TODO: a lot of this logic should be encompassed in the CachedResult.  It's probably
+    # a good idea to always cache a CachedResult and move the result-related methods
+    # into that class.  We have to keep whatever is cached as small as possible tho,
+    # so it's probably best to cache a Hash and load it with CachedResult.
     class ResultProcessor
 
       def initialize(result, opts={})
@@ -54,23 +59,29 @@ module AridCache
         # Check if it's an association first, because it doesn't trigger the select if it's
         # a named scope.  Calling respond_to? on an association proxy will trigger a select
         # because it loads up the target and passes the respond_to? on to it.
-        @cached = if is_activerecord_reflection?
-          lazy_cache.klass = @result.proxy_reflection.klass if @result.respond_to?(:proxy_reflection)
-          if @options.count_only?
-            lazy_cache.count = @result.count
-          else
+        @cached =
+          if @options.proxy?
+            if is_activerecord_reflection?
+              @result = @result.collect { |r| r } # force it to load
+            end
+            Utilities.object_class(@options[:receiver]).send(@options[:proxy], @result)
+          elsif is_activerecord_reflection?
+            lazy_cache.klass = @result.proxy_reflection.klass if @result.respond_to?(:proxy_reflection)
+            if @options.count_only?
+              lazy_cache.count = @result.count
+            else
+              lazy_cache.ids = @result.collect { |r| r[:id] }
+              lazy_cache.count = @result.size
+            end
+            lazy_cache
+          elsif is_activerecord? || is_empty?
             lazy_cache.ids = @result.collect { |r| r[:id] }
             lazy_cache.count = @result.size
+            lazy_cache.klass = @result.first.class
+            lazy_cache
+          else
+            @result
           end
-          lazy_cache
-        elsif is_activerecord? || is_empty?
-          lazy_cache.ids = @result.collect { |r| r[:id] }
-          lazy_cache.count = @result.size
-          lazy_cache.klass = @result.first.class
-          lazy_cache
-        else
-          @result
-        end
       end
 
       # Apply any options like pagination or ordering and return the result, which
@@ -78,16 +89,32 @@ module AridCache
       def to_result
         if @options.count_only?
           get_count
-        elsif @options.raw? || (!is_cached_result? && !is_enumerable?)
+        elsif is_cached_result? && @options.raw?
           @result
-        else
-          if is_cached_result?
-            fetch_activerecords(filter_results(@result.ids))
-          elsif order_in_database?
-            fetch_activerecords(filter_results(@result))
+        elsif @options.proxy?
+          results = 
+            if @cached.nil? || !@options.raw?
+              @result
+            else
+              @cached
+            end
+          filtered = filter_results(results)
+          if @cached.nil? && !@options.raw?
+            proxy_result = Utilities.object_class(@options[:receiver]).send(@options[:proxy], filtered)
+            if filtered.is_a?(WillPaginate::Collection) && proxy_result.is_a?(Enumerable)
+              filtered.replace(proxy_result)
+            else
+              proxy_result
+            end
           else
-            filter_results(@result)
+            filtered
           end
+        elsif is_cached_result?
+          fetch_activerecords(filter_results(@result.ids))
+        elsif order_in_database?
+          fetch_activerecords(filter_results(@result))
+        else
+          filter_results(@result)
         end
       end
 

data/spec/arid_cache/cache_proxy/options_spec.rb

@@ -76,5 +76,11 @@ describe AridCache::CacheProxy::Options do
     it "should use find_all_by_id as the finder" do
       new_options.opts_for_paginate[:finder].should == :find_all_by_id
     end
+  end 
+  
+  describe "proxies" do
+    it "should use proxy" do
+      new_options(:proxy => :serializing_proxy).proxy?.should be_true
+    end
   end
 end

data/spec/arid_cache/cache_proxy/result_processor_spec.rb

@@ -179,8 +179,8 @@ describe AridCache::CacheProxy::ResultProcessor do
       it "should order hashes by symbol key" do
         new_result(@hashes, :order => :high).to_result.collect { |h| h[:high] }.should == @high
       end
-    end 
-    
+    end
+
     describe "paginating arrays" do
       before :each do
         @value = (1..10).to_a
@@ -191,27 +191,168 @@ describe AridCache::CacheProxy::ResultProcessor do
         @result.should be_a(WillPaginate::Collection)
         @result.total_entries.should == @value.size
         @result.current_page.should == 1
-      end                          
-      
+      end
+
       it "should handle per_page option" do
         @result = new_result(@value, :page => 3, :per_page => 3).to_result
         @result.should be_a(WillPaginate::Collection)
         @result.total_entries.should == @value.size
         @result.current_page.should == 3
-        @result.per_page.should == 3        
+        @result.per_page.should == 3
       end
     end
-    
-    it "should order limit and then paginate all at once" do     
+
+    it "should order limit and then paginate all at once" do
        # It will reverse it, offset 2, limit 15, then paginate
        @options = {
-         :limit => 15, 
-         :offset => 2, 
+         :limit => 15,
+         :offset => 2,
          :order => Proc.new { |a, b| b <=> a },
-         :page => 2, 
+         :page => 2,
          :per_page => 5
        }
        @result = new_result((1..20).to_a, @options).to_result.should == [13, 12, 11, 10, 9]
     end
   end
+
+  describe "proxies" do
+    before :each do
+      class User
+        instance_caches do
+          companies(:proxy => :abc)
+        end
+
+        def self.abc(records)
+          return records if records.empty?
+          records.first.is_a?(ActiveRecord::Base) ? records.collect(&:attributes) : records.collect { |r| Company.find_by_id(r['id']) }
+        end
+      end
+
+      @user = User.make
+      @company = Company.make
+      @user.companies << @company
+      @user.cached_companies(:clear => true)
+    end
+
+    it "the proxy called on itself should return the original value" do
+      User.abc(User.abc([@company])).should == [@company]
+    end
+
+    it "should serialize" do
+      @user.cached_companies.should == [@company]
+    end
+
+    it "should un-serialize" do
+      @user.cached_companies # seed the cache
+      @user.cached_companies.should == [@company]
+    end
+
+    it "should return json with :raw => true" do
+      # Seed the cache; it should use the serialized result in the return value.
+      value = @user.cached_companies(:raw => true)
+
+      # Comparing the hashes directly doesn't work because the updated_at Time are
+      # not considered equal...don't know why, cause the to_s looks the same.
+      # debugger
+      value.should be_a(Array)
+      value.first.should be_a(Hash)
+      value.first.each_pair do |k, v|
+        v.to_s.should == @company.attributes[k].to_s
+      end
+
+      # Cache is seeded, it should use the cached result
+      User.expects(:abc).never
+      value = @user.cached_companies(:raw => true)
+      value.should be_a(Array)
+      value.first.should be_a(Hash)
+      value.first.each_pair do |k, v|
+        v.to_s.should == @company.attributes[k].to_s
+      end
+    end
+
+    describe "with options" do
+      before :each do
+        @c2 = Company.make
+        @c3 = Company.make
+        @user.companies << @c2
+        @user.companies << @c3
+      end
+
+      it "should apply limit and offset" do
+        @companies = @user.cached_companies
+        @user.cached_companies(:limit => 2, :offset => 1).should == @companies[1,2]
+      end
+
+      it "should apply limit and offset with :raw => true" do
+        @companies = @user.cached_companies
+        @user.cached_companies(:limit => 2, :offset => 1, :raw => true).should == User.abc(@companies[1,2])
+      end
+
+      it "should apply pagination" do
+        @companies = @user.cached_companies
+        value = @user.cached_companies(:page => 2, :per_page => 2)
+        value.should be_a(WillPaginate::Collection)
+        value.first.should be_a(Company)
+        value.first.should == @companies[-1]
+        value.total_entries.should == @companies.size
+        value.current_page.should == 2
+        value.size.should == 1
+      end
+
+      it "should get the count for free" do
+        lambda { @user.cached_companies_count }.should query(1)
+        lambda { @user.cached_companies_count }.should query(0)
+      end
+
+      it "should paginate with :raw => true" do
+        @companies = User.abc(@user.cached_companies)
+        value = @user.cached_companies(:page => 2, :per_page => 2, :raw => true)
+        value.should be_a(WillPaginate::Collection)
+        value.first.should be_a(Hash)
+        value.first.should == @companies[-1]
+        value.total_entries.should == @companies.size
+        value.current_page.should == 2
+        value.size.should == 1
+      end
+
+      it "should order by" do
+        @companies = @user.cached_companies
+        @user.cached_companies(:order => 'id').should == @companies
+        @user.cached_companies(:order => Proc.new { |a, b| b['id'] <=> a['id'] }).should == @companies.reverse
+      end
+
+      it "should order by with :raw => true" do
+        @companies = @user.cached_companies(:raw => true)
+        @companies.first.should be_a(Hash)
+        @user.cached_companies(:order => 'id', :raw => true).should == @companies
+        @user.cached_companies(:order => Proc.new { |a, b| b['id'] <=> a['id'] }, :raw => true).should == @companies.reverse
+      end
+
+      it "should apply all options at once" do
+        @companies = @user.cached_companies
+        value = @user.cached_companies(
+          :order => Proc.new { |a, b| b['id'] <=> a['id'] },
+          :limit => 2, :offset => 1,
+          :page => 1, :per_page => 2)
+        value.should be_a(WillPaginate::Collection)
+        value.current_page.should == 1
+        value.total_entries.should == 2
+        value.to_a.should == [@companies[1], @companies[0]]
+      end
+
+      it "should apply all options with :raw => true" do
+        @companies = @user.cached_companies(:raw => true)
+        value = @user.cached_companies(
+          :order => Proc.new { |a, b| b['id'] <=> a['id'] },
+          :limit => 2, :offset => 1,
+          :page => 1, :per_page => 2,
+          :raw => true)
+        value.should be_a(WillPaginate::Collection)
+        value.current_page.should == 1
+        value.total_entries.should == 2
+        value.first.should be_a(Hash)
+        value.to_a.should == [@companies[1], @companies[0]]
+      end
+    end
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: arid_cache
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: 
   segments: 
   - 1
   - 3
-  - 0
-  version: 1.3.0
+  - 1
+  version: 1.3.1
 platform: ruby
 authors: 
 - Karl Varga
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-05 00:00:00 -07:00
+date: 2011-04-06 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency