arid_cache 1.3.1 → 1.3.2

data/Gemfile

@@ -1,8 +1,8 @@
 # A sample Gemfile
 source "http://rubygems.org"
 
-gem 'activerecord', '=2.3.8'
-gem 'activesupport', '=2.3.8'
+gem 'activerecord', '=2.3.11'
+gem 'activesupport', '=2.3.11'
 gem 'sqlite3-ruby', '=1.3.1'
 
 gem 'will_paginate', '=2.3.15'

data/README.rdoc

@@ -8,10 +8,11 @@ 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.
+* v1.3.2: <tt>AridCache.raw_with_options</tt> configuration for better <tt>:raw</tt> handling on cached ActiveRecord collections
+* v1.3.1: Proxy support 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...almost Rails agnostic!
+* v1.0.5: Support <tt>:raw</tt> and <tt>:clear</tt> options.
 
 == Install
 
@@ -38,17 +39,17 @@ Then
 == Features
 
 * Include the AridCache module in any Class
-* Rails 2 & 3 compatible with automatic ActiveRecord::Base integration
-* Supports auto-expiring cache keys
-* Supports limits, ordering & pagination of cached Enumerables and ActiveRecord collections
+* <b>Rails 2 & 3 compatible</b> with automatic ActiveRecord::Base integration
+* Supports <b>auto-expiring cache keys</b>
+* 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
-* 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
+* <b>Counts for free</b> - if you have already cached the result, you get the count for free
+* <b>Smart counts</b> - 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 <b>eager-loading</b> 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 <b>clear caches</b> individually, at the instance-level, class-level and globally
+* <b>Preserves ordering</b> of your cached ActiveRecord collections
+* <b>Optimized</b> to make as few cache and database accesses as absolutely neccessary
+* Define your own <b>cache proxy</b> to serialize your objects as they go to and from the cache
 
 == Introduction
 
@@ -241,10 +242,6 @@ Or via the cache configuration,
     featured_albums
   end
 
-If you would like to be able to pass more options to your cache store (like <tt>:unless_exists</tt>, etc), just add them to the <tt>AridCache::CacheProxy::OPTIONS_FOR_CACHE</tt> class constant, for example
-
-  AridCache::CacheProxy::OPTIONS_FOR_CACHE.push(:raw, :unless_exist)
-
 == Extras
 
 === Cached Counts
@@ -333,15 +330,23 @@ For example, we could call:
 
 To return page two of the active users, with the <tt>preferences</tt> association eager-loaded for all the users.
 
-=== Accessing the cached IDs directly
+=== The <tt>:raw</tt> option & Accessing the cached IDs directly
+
+When you cache a collection of ActiveRecords, the records IDs are stored in the cache in a <tt>AridCache::CacheProxy::CachedResult</tt> which is a <tt>Struct</tt> with methods to return the <tt>ids</tt>, <tt>count</tt> and <tt>klass</tt> of the cached records.
+
+Sometimes you may want to access what is in the cache without instantiating any records.  <tt>:raw => true</tt> is what you use for that.
+
+The current (and deprecated) behaviour of <tt>:raw => true</tt> is to return the +CachedResult+ object and ignore all other options - if the cached result is an ActiveRecord collection.  Passing <tt>:raw => true</tt> when you have cached an Enumerable or some other base type does not share this behaviour.  For these types <tt>:raw => true</tt> returns whatever is in the cache, after applying all options.  This means that we can apply limits, ordering and pagination to our cached results and return the same type of data as is stored in the cache.
 
-Sometimes you may want to access the cached list of record IDs without instantiating all the records.  This can be useful, for example, to determine if a particular track belongs to a user's favorite tracks.  If we have cached the list of favorite tracks, we just need to determine whether the track's ID appears in the cached list of IDs.
+v1.3.2 introduces a new configuration option which makes the behaviour on cached ActiveRecord collections the same as for other cached types.  Set
 
-The cached result is a <tt>AridCache::CacheProxy::Result</tt> and can be accessed by passing the <b><tt>:raw => true</tt></b> option in your cached call.  The <tt>AridCache::CacheProxy::Result</tt> is a type of <tt>Struct</tt> with methods to return the <tt>ids</tt>, <tt>count</tt> and <tt>klass</tt> of the cached records.
+  AridCache.raw_with_options = true
 
-Note that passing the <tt>:raw</tt> option to your cache store is not supported, because the AridCache option shares the same name.  If you really want to get the marshalled result from your cache you will have to use <tt>cache.read</tt>, manually passing in the AridCache key and <tt>:raw</tt> option.
+to enable the new behaviour.  With this option set, rather than return a <tt>CachedResult</tt> <tt>:raw => true<tt> will return the list of IDs itself, <b>after applying all options</b>.  So you can limit, order (with a Proc) and paginate the IDs before they are returned.  Keep in mind the <tt>:order</tt> Proc is applied <b>to the cached/raw data</tt>.
 
-Usage example:
+Note that passing the <tt>:raw</tt> option to your cache store is not supported, because the AridCache option shares the same name.  If you really want to get the marshalled result from your cache you can do a cache read manually.
+
+The current (deprecated) behaviour:
 
   user = User.first
   user.cached_favorite_tracks  => returns [#<Track:1>, #<Track:2>]
@@ -353,7 +358,7 @@ Usage example:
       }
   user.cached_favorite_tracks(:raw => true).ids => returns [1, 2]
 
-The cache will be primed if it is empty, so you can be sure that it will always return a <tt>AridCache::CacheProxy::Result</tt>.
+The cache will be primed if it is empty, so you can be sure that it will always return a <tt>AridCache::CacheProxy::CachedResult</tt>.
 
 In some circumstances - like when you are querying on a named scope - if you have only requested a count, only the count is computed, which means the ids array is <tt>nil</tt>.  When you call your cached method passing in <tt>:raw => true</tt> AridCache detects that the ids array has not yet been set, so in this case it will perform a query to seed the ids array before returning the result.  This can be seen in the following example:
 
@@ -375,6 +380,18 @@ 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
     }
 
+With <tt>AridCache.raw_with_options = true</tt>:
+
+    user = User.first
+    user.cached_favorite_tracks
+    >> [#<Track:1>, #<Track:2>]
+    user.cached_favorite_tracks(:raw => true)
+    >> [1, 2]
+    user.cached_favorite_tracks(:order => Proc.new { |a, b| b <=> a }, :raw => true)
+    >> [2, 1]
+    user.cached_favorite_tracks(:offset => 1, :raw => true)
+    >> [2]
+
 == 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.
@@ -444,22 +461,22 @@ In practice you probably want to define your proxy method on <tt>ActiveRecord::B
 == Compatibility
 
 Tested on Ruby 1.8.6, 1.8.7, REE 1.8.7 and 1.9.1.
-Tested in Rails 2.3.11, Rails 3.0.0, Rails 3.0.5
+Tested in Rails 2.3.8, 2.3.11, Rails 3.0.0, Rails 3.0.5
 
 For Ruby < 1.8.7 you probably want to include the following to extend the Array class with a <tt>count</tt> method.  Otherwise your <tt>cached_<key>_count</tt> calls probably won't work:
 
   Array.class_eval { alias count size }
 
-== Resources & Metrics
+== Resources
 
-
-* {RDoc}[http://rdoc.info/projects/kjvarga/arid_cache]
-* {GetCaliper Metrics}[http://getcaliper.com/caliper/project?repo=git%3A%2F%2Fgithub.com%2Fkjvarga%2Farid_cache.git]
+* {RDoc}[http://rdoc.info/github/kjvarga/arid_cache/master/frames]
 
 == 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.  If you need polymorphism consider using a proxy.
+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 and do the record-loading yourself.
+3. Rails ActiveRecord (or SQL) has a quirk where if you pass an +offset+ without a +limit+ the +offset+ is ignored.  AridCache fixes this unexpected behaviour by including a +limit+ on its queries.
+4. When you use the <tt>:order</tt> option with a cached ActiveRecord collection we have to go to the database to order.  So we also do pagination and limiting there because we want to retrieve as few records as possible.  So we use WillPaginate's ActiveRecord::Base#paginate method.  Unfortunately if you pass <tt>:limit</tt> or <tt>:offset</tt> in addition to your pagination options, the limit and offset are ignored.  This is not the behaviour when interacting with other cached types.  In that case we apply the order, then the limits and finally the pagination, which is what you would expect.
 
 == Contributors
 
@@ -471,7 +488,6 @@ Contributions are welcome!  Please,
 * Commit (don't mess with the Rakefile, version, or history).
 * Send me a pull request.
 
-
 ==== Thank-you to these contributors to AridCache:
 
 * {Sutto}[http://github.com/Sutto]

data/VERSION

@@ -1 +1 @@
-1.3.1
+1.3.2

data/arid_cache.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{arid_cache}
-  s.version = "1.3.1"
+  s.version = "1.3.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Karl Varga"]
-  s.date = %q{2011-04-06}
+  s.date = %q{2011-04-07}
   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/cache_proxy/options.rb

@@ -6,14 +6,14 @@ module AridCache
       def initialize(opts={})
         self.merge!(opts)
       end
-      
+
       # Filter options for paginate.  Get the :per_page value from the receiver if it's not set.
       # Set total_entries to +records.size+ if +records+ is supplied
       def opts_for_paginate(records=nil)
         paginate_opts = reject { |k,v| !OPTIONS_FOR_PAGINATE.include?(k) }
         paginate_opts[:finder] = :find_all_by_id unless paginate_opts.include?(:finder)
         if self[:result_klass].respond_to?(:per_page) && !paginate_opts.include?(:per_page)
-          paginate_opts[:per_page] = self[:result_klass].per_page 
+          paginate_opts[:per_page] = self[:result_klass].per_page
         end
         paginate_opts[:total_entries] = records.size unless records.nil?
         paginate_opts
@@ -43,35 +43,39 @@ module AridCache
       # Returns options that affect the cache proxy result
       def opts_for_cache_proxy
         reject { |k,v| !OPTIONS_FOR_CACHE_PROXY.include?(k) }
-      end  
-      
+      end
+
       def force?
         !!self[:force]
-      end 
-      
+      end
+
       def paginate?
         include?(:page)
       end
-      
+
       def raw?
         !!self[:raw]
       end
-      
+
       def count_only?
         !!self[:count_only]
       end
-    
+
       def order_by_proc?
         include?(:order) && self[:order].is_a?(Proc)
       end
-      
+
       def order_by_key?
         include?(:order) && (self[:order].is_a?(Symbol) || self[:order].is_a?(String))
-      end  
-      
+      end
+
       def proxy?
         include?(:proxy)
       end
+
+      def deprecated_raw?
+        !!(raw? && !AridCache.raw_with_options)
+      end
     end
   end
-end
+end

data/lib/arid_cache/cache_proxy/result_processor.rb

@@ -36,7 +36,7 @@ module AridCache
       # Order in the database if an order clause has been specified and we
       # have a list of ActiveRecords or a CachedResult.
       def order_in_database?
-        is_cached_result? || (@options.order_by_key? && is_activerecord?)
+        (is_cached_result? && !@options.raw?) || (@options.order_by_key? && is_activerecord?)
       end
 
       # Return true if the result is an enumerable and the first item is
@@ -89,10 +89,9 @@ module AridCache
       def to_result
         if @options.count_only?
           get_count
-        elsif is_cached_result? && @options.raw?
-          @result
+
         elsif @options.proxy?
-          results = 
+          results =
             if @cached.nil? || !@options.raw?
               @result
             else
@@ -109,6 +108,21 @@ module AridCache
           else
             filtered
           end
+
+        elsif @options.raw?
+
+          result =
+            if @cached.is_a?(AridCache::CacheProxy::CachedResult)
+              @cached
+            else
+              @result
+            end
+          if @options.deprecated_raw?
+            result
+          else
+            filter_results(result.is_a?(AridCache::CacheProxy::CachedResult) ? result.ids : result)
+          end
+
         elsif is_cached_result?
           fetch_activerecords(filter_results(@result.ids))
         elsif order_in_database?

data/lib/arid_cache.rb

@@ -12,33 +12,43 @@ module AridCache
   extend AridCache::Helpers
   Error = Class.new(StandardError) #:nodoc:
 
+  # Set to true to make the :raw option return ids after applying options to them.
+  # The deprecated behaviour is to return a CachedResult and ignore all options.
+  def self.raw_with_options=(value)
+    @raw_with_options = value
+  end
+
+  def self.raw_with_options
+    !!@raw_with_options
+  end
+
   def self.cache
     AridCache::CacheProxy
   end
 
   def self.clear_caches
     AridCache::CacheProxy.clear_caches
-  end 
-  
+  end
+
   def self.clear_class_caches(object)
     AridCache::CacheProxy.clear_class_caches(object)
-  end 
-      
+  end
+
   def self.clear_instance_caches(object)
     AridCache::CacheProxy.clear_instance_caches(object)
-  end  
-    
+  end
+
   def self.store
     AridCache::Store.instance
   end
-  
+
   # The old method of including this module, if you don't want to
   # extend active record.  Just add 'include AridCache' to your
   # model class.
   def self.included(base)
     base.send(:include, AridCache::ActiveRecord)
   end
-  
+
   # Initializes AridCache for Rails.
   #
   # This method is called by `init.rb`,

data/spec/arid_cache/arid_cache_spec.rb

@@ -20,7 +20,7 @@ describe AridCache do
         results[1].name.should == @company2.name
       end
     end
-  
+
     it "order should match the order option" do
       3.times do |t|
         results = Company.cached_ordered_by_name(:order => 'name DESC')
@@ -29,11 +29,17 @@ describe AridCache do
         results[1].name.should == @company1.name
       end
     end
-    
+
     it "with order option should go to the database to order" do
       lambda {
         Company.cached_ordered_by_name(:order => 'name DESC')
       }.should query(2)
     end
   end
+
+  it "should set the special raw flag" do
+    AridCache.raw_with_options.should be_false
+    AridCache.raw_with_options = true
+    AridCache.raw_with_options.should be_true
+  end
 end

data/spec/arid_cache/cache_proxy/options_spec.rb

@@ -76,11 +76,23 @@ 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 
-  
+  end
+
   describe "proxies" do
     it "should use proxy" do
       new_options(:proxy => :serializing_proxy).proxy?.should be_true
     end
   end
+
+  describe "deprecated raw" do
+    it "should be deprecated" do
+      AridCache.expects(:raw_with_options).returns(false)
+      new_options(:raw => true).deprecated_raw?.should be_true
+    end
+
+    it "should not be deprecated" do
+      AridCache.expects(:raw_with_options).returns(true)
+      new_options(:raw => true).deprecated_raw?.should be_false
+    end
+  end
 end

data/spec/arid_cache/cache_proxy/result_processor_spec.rb

@@ -355,4 +355,47 @@ describe AridCache::CacheProxy::ResultProcessor do
       end
     end
   end
+
+  describe "raw with options handling" do
+    before :each do
+      AridCache.raw_with_options = true
+      @user = User.make
+      @company1 = Company.make
+      @company2 = Company.make
+      @user.companies << @company1
+      @user.companies << @company2
+      class User
+        instance_caches do
+          raw_companies(:raw => true) { companies }
+        end
+      end
+      @user.cached_raw_companies(:clear => true)
+    end
+
+    it "should return ids" do
+      @user.cached_raw_companies.should == [@company1.id, @company2.id]
+    end
+
+    it "should apply order" do
+      @user.cached_raw_companies(:order => Proc.new { |a,b| b <=> a }).should == [@company2.id, @company1.id]
+    end
+
+    it "should not order in database" do
+       new_result(AridCache::CacheProxy::CachedResult.new).order_in_database?.should be_true
+       new_result(AridCache::CacheProxy::CachedResult.new, { :raw => true }).order_in_database?.should be_false
+    end
+
+    it "should apply offset and limit" do
+      @user.cached_raw_companies(:limit => 1).should == [@company1.id]
+      @user.cached_raw_companies(:offset => 1).should == [@company2.id]
+    end
+
+    it "should apply pagination" do
+      value = @user.cached_raw_companies(:page => 2, :per_page => 1)
+      value.should be_a(WillPaginate::Collection)
+      value.total_entries.should == 2
+      value.current_page.should == 2
+      value.should == [@company2.id]
+    end
+  end
 end

metadata

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