arid_cache 0.1.0 → 0.1.1

data/README.rdoc

@@ -1,10 +1,50 @@
 == ARID Cache
 
-ARID Cache is a DRY ActiveRecord ID cache.
+ARID Cache makes caching easy and effective.  ARID cache supports caching on all your model named scopes, class methods and instance methods right out of the box.  ARID cache prevents caching logic from cluttering your models and clarifies your logic by making explicit calls to cached result sets.
 
-== Example
+ARID Cache is designed for handling large, expensive ActiveRecord collections but is equally useful for caching anything else as well.
 
-Given the following model:
+=== Counts for free
+
+ARID Cache gives you counts for free.  When a large collection is stored in the cache
+ARID Cache stores the count as well so the next time you want request the count it
+just takes a single read from the cache.  This is also supported for your non-ActiveRecord
+collections if the collection <tt>responds_to?(:count)</tt>.
+
+Given that we have a cache like <tt>album.cached_tracks</tt> we can get the count by calling <tt>album.cached_tracks_count</tt>.
+  
+=== Auto-expiring cache keys
+  
+Caches on model instances automatically incorporate the ActiveRecord <tt>cache_key</tt> which includes the <tt>updated_at</tt> timestamp of that instance, making them auto-expire when the instance is updated.
+
+Caches on your model classes (like on the results of named scopes) will not expire however.
+
+ARID cache provides methods to help you expire your caches.
+  
+  AridCache.clear_all_caches  => expires all ARID Cache caches
+  Model.clear_all_caches      => expires class and instance-level caches for this model
+  Model.clear_instance_caches => expires instance-level caches for this model
+  Model.clear_class_caches    => expires class-level caches for this model
+  
+These methods are also available on model instances.
+
+ARID Cache keys are based on the method you call to create the cache.  For example:
+  Album.cached_featured_albums  => cache key is arid-cache-album-featured_albums
+  album.cached_top_tracks       => cache key like arid-cache-albums/2-20090930200-top_tracks
+
+=== Support for pagination and options to <tt>find</tt>
+
+ARID cache performs pagination and applies <tt>:limit</tt> and <tt>:offset</tt> to the IDs in memory and only selects the page/sub-set from the database, directly from the target table.
+
+You can pass options like <tt>:include</tt> (or any other valid <tt>find</tt> options) to augment the results of your cached query.
+
+=== Efficiency
+
+ARID Cache 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.
+
+== Examples
+
+==== Given the following model:
 
   class User < ActiveRecord::Base
     include AridCache
@@ -13,12 +53,11 @@ Given the following model:
     named_scope :active, :conditions => [ 'updated_at <= ', 5.minutes.ago ]
   end
 
-ARID Cache provides these methods:
+==== ARID Cache provides these methods:
  
   User.cached_active         # caches the user IDs and the count
   User.cached_active_count   # gets the count for free
 
-  user = User.first
   user.cached_pets           # caches the pets IDs and the count
   user.cached_pets_count     # gets the count for free
    
@@ -28,9 +67,9 @@ selects where the IDs are the cached IDs.
 
 It also gives you paging using WillPaginate.  The IDs from the cache are paginated and
 only that page is selected from the database - again directly from the table, without
-any complex joins or anything.
+any complex joins.
 
-Some examples of pagination:
+==== Some examples of pagination:
 
   User.cached_active.paginate(:page => 1, :per_page => 30)
   User.cached_active.paginate(:page => 1)
@@ -40,21 +79,32 @@ You can also include options for find, such as <tt>:join</tt>, <tt>:include</tt>
 
   User.cached_active.paginate(:page => 1, :include => :preferences)
   User.cached_active.paginate(:page => 1, :order => 'created_at DESC') # don't change the order, just enforce it
+
+You can limit the results returned using <tt>:limit</tt> and <tt>:offset</tt>:
+
+  user.cached_pets(:limit => 2, :include => :toys)
+  user.cached_pets(:limit => 2, :offset => 3, :include => :toys)
   
-You can configure your cached blocks in your models:
-  
-  class User < ActiveRecord::Base
-    include AridCache
-    has_many    :pets
-    has_one     :preferences
-    named_scope :active, :conditions => [ 'updated_at <= ', 5.minutes.ago ]
-    
-    self.cached_active_users(:order => 'created_at DESC', :include => :preferences) do
-      self.active
-    end
+==== You can dynamically create caches
+
+  User.cached_most_active_users do
+    self.active.find(:order => 'activity DESC', :limit => 10)
   end
-  
 
+Dynamic caches that make use of other cached collections:
+
+  @tracks  = @genre.cached_highlight_tracks(:order => 'release_date DESC', :include => [:album, :artist]) do
+    cached_tracks(:order => 'release_date DESC', :limit => 10, :include => [:album, :artist])
+  end
+  @artists = @genre.cached_highlight_artists do
+    cached_artists(:limit => 10)
+  end
+  @albums  = @genre.cached_highlight_albums(:order => 'release_date DESC', :include => :artist) do
+    cached_albums(:order => 'release_date DESC', :limit => 3, :include => :artist)
+  end
+    
+More docs to come...
+  
 == Note on Patches/Pull Requests
 
 * Fork the project.

data/Rakefile

@@ -6,7 +6,11 @@ begin
   Jeweler::Tasks.new do |gem|
     gem.name = "arid_cache"
     gem.summary = %Q{Automates efficient caching of your ActiveRecord collections, gives you counts for free and supports pagination.}
-    gem.description = %Q{}
+    gem.description = <<-END.gsub(/^\s+/, '')
+      ARID Cache makes caching easy and effective.  ARID cache supports caching on all your model named scopes, class methods and instance methods right out of the box.  ARID cache prevents caching logic from cluttering your models and clarifies your logic by making explicit calls to cached result sets.
+      
+      ARID Cache is designed for handling large, expensive ActiveRecord collections but is equally useful for caching anything else as well.
+    END
     gem.email = "kjvarga@gmail.com"
     gem.homepage = "http://github.com/kjvarga/arid_cache"
     gem.authors = ["Karl Varga"]

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/arid_cache.gemspec

@@ -5,12 +5,14 @@
 
 Gem::Specification.new do |s|
   s.name = %q{arid_cache}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Karl Varga"]
-  s.date = %q{2009-12-21}
-  s.description = %q{}
+  s.date = %q{2009-12-25}
+  s.description = %q{ARID Cache makes caching easy and effective.  ARID cache supports caching on all your model named scopes, class methods and instance methods right out of the box.  ARID cache prevents caching logic from cluttering your models and clarifies your logic by making explicit calls to cached result sets.
+ARID Cache is designed for handling large, expensive ActiveRecord collections but is equally useful for caching anything else as well.
+}
   s.email = %q{kjvarga@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE",
@@ -23,13 +25,13 @@ Gem::Specification.new do |s|
      "Rakefile",
      "VERSION",
      "arid_cache.gemspec",
+     "init.rb",
      "lib/arid_cache.rb",
      "lib/arid_cache/active_record.rb",
      "lib/arid_cache/cache_proxy.rb",
+     "lib/arid_cache/helpers.rb",
      "lib/arid_cache/store.rb",
      "rails/init.rb",
-     "rails/install.rb",
-     "rails/uninstall.rb",
      "spec/arid_cache_spec.rb",
      "spec/spec.opts",
      "spec/spec_helper.rb",

data/init.rb

@@ -0,0 +1,6 @@
+begin
+  require File.join(File.dirname(__FILE__), 'lib', 'arid_cache') # From here
+rescue LoadError
+  require 'arid_cache' # From gem
+end
+AridCache.init_rails

data/lib/arid_cache/active_record.rb

@@ -1,44 +1,67 @@
 module AridCache
-  module ActiveRecord
+  module ActiveRecord      
+    def self.included(base)
+      base.extend         MirrorMethods
+      base.send :include, MirrorMethods
+      base.class_eval do
+        alias_method_chain :method_missing, :arid_cache 
+      end
+      class << base
+        alias_method_chain :method_missing, :arid_cache 
+      end
+    end
+    
     module MirrorMethods
+      def clear_all_caches
+        AridCache.cache.clear_class_caches(self)
+        AridCache.cache.clear_instance_caches(self)
+      end
+
+      def clear_class_caches
+        AridCache.cache.clear_class_caches(self)
+      end
+
+      def clear_instance_caches
+        AridCache.cache.clear_instance_caches(self)
+      end
+                  
+      def get_singleton
+        class << self; self; end
+      end
       
       # Return a cache key for the given key e.g.
       #   User.arid_cache_key('companies')       => 'user-companies'
-      #   User.first.arid_cache_key('companies') => 'users/1-companies'
-      def arid_cache_key(key, suffix=nil)
-        arid_cache_key = (self.is_a?(Class) ? self.name.downcase : self.cache_key) + '-' + key.to_s
-        suffix.nil? ? arid_cache_key : arid_cache_key + suffix
-        ('arid-cache-' + arid_cache_key).to_sym
+      #   User.first.arid_cache_key('companies') => 'users/20090120091123-companies'
+      def arid_cache_key(key)
+        key = (self.is_a?(Class) ? self.name.downcase : self.cache_key) + '-' + key.to_s
+        'arid-cache-' + key
       end
 
-      def clear_cache
-        AridCache.cache.clear(self)
-      end
-          
-      # Return the cache store from the class
-      def cache_store
-        (self.is_a?(Class) ? self : self.class).send(:class_variable_get, :@@cache_store)
-      end    
+      def respond_to?(method, include_private = false) #:nodoc:
+        if (method.to_s =~ /^class_cache_.*|cache_.*|cached_.*(_count)?$/).nil?
+          super(method, include_private)
+        elsif method.to_s =~ /^cached_(.*)_count$/
+          AridCache.store.has?(self, "#{$1}_count") || AridCache.store.has?(self, $1) || super("#{$1}_count", include_private) || super($1, include_private)
+        elsif method.to_s =~ /^cached_(.*)$/
+          AridCache.store.has?(self, $1) || super($1, include_private)
+        else
+          super(method, include_private)
+        end
+      end
+            
+      protected
 
       # Intercept methods beginning with <tt>cached_</tt>
-      def method_missing_with_arid_cache(method, *args, &block)
-        if method.to_s =~ /^cached_(.*)$/
-          args = args.empty? ? {} : args.first
-          cache_store.query($1, args, self, &block)
+      def method_missing_with_arid_cache(method, *args, &block) #:nodoc:
+        opts = args.empty? ? {} : args.first
+        if method.to_s =~ /^cache_(.*)$/
+          AridCache.define(self, $1, opts, &block)
+        elsif method.to_s =~ /^cached_(.*)$/
+          AridCache.lookup(self, $1, opts, &block)
         else
           method_missing_without_arid_cache(method, *args)
         end
-      end 
-      alias_method :method_missing_without_arid_cache, :method_missing
-      alias_method :method_missing, :method_missing_with_arid_cache
-    end
-          
-    def self.included(base)
-      base.extend         MirrorMethods
-      base.send :include, MirrorMethods
-      base.class_eval do
-        @@cache_store = AridCache::Store.new
       end
     end
   end
-end
+end

data/lib/arid_cache/cache_proxy.rb

@@ -1,96 +1,164 @@
-# AridCache::Cache is a singleton instance
 module AridCache
   class CacheProxy
-    Struct.new('Result', :opts, :ids, :klass, :count) do
+    attr_accessor :object, :key, :opts, :blueprint, :cached, :cache_key, :block, :records
+    
+    # AridCache::CacheProxy::Result
+    #
+    # This struct is stored in the cache and stores information we need
+    # to re-query for results.
+    Result = Struct.new(:ids, :klass, :count) do
       
       def has_count?
         !count.nil?
       end
-      
+        
       def has_ids?
         !ids.nil?
       end
+            
+      def klass=(value)
+        self['klass'] = value.is_a?(Class) ? value.name : value
+      end
+      
+      def klass
+        self['klass'].constantize unless self['klass'].nil?
+      end
     end
+
+    def self.clear_all_caches
+      Rails.cache.delete_matched(%r[arid-cache-.*])
+    end 
     
-    # Clear the cache of all arid cache entries.
-    #
-    # If *object* is passed, only clear cached entries for that object's
-    # class and instances e.g.
-    #   User.clear_cache deletes 'arid-cache-users/1-companies' as well 
-    #   as 'arid-cache-user-companies'
-    def clear(object=nil)
-      key = 'arid-cache-'
-      key += (object.is_a?(Class) ? object : object.class).name.downcase unless object.nil?
-      Rails.cache.delete_matched(%r[#{key}.*])
-    end
-    
-    def self.instance
-      @@singleton_instance ||= self.new
-    end
+    def self.clear_class_caches(object)
+      key = (object.is_a?(Class) ? object : object.class).name.downcase + '-'
+      Rails.cache.delete_matched(%r[arid-cache-#{key}.*])
+    end 
         
-    def has?(object, key)
+    def self.clear_instance_caches(object)
+      key = (object.is_a?(Class) ? object : object.class).name.pluralize.downcase
+      Rails.cache.delete_matched(%r[arid-cache-#{key}.*])
+    end    
+    
+    def self.has?(object, key)
       Rails.cache.exist?(object.arid_cache_key(key))
     end
-    
-    def fetch_count(blueprint)
-      cached = Rails.cache.read(blueprint.cache_key)
-      if cached.nil?
-        execute_count(blueprint)
-      elsif cached.is_a?(Struct::Result)
-        cached.has_count? ? cached.count : execute_count(blueprint)
+
+    def self.fetch_count(object, key, opts, &block)
+      CacheProxy.new(object, key, opts, &block).fetch_count
+    end
+          
+    def self.fetch(object, key, opts, &block)
+      CacheProxy.new(object, key, opts, &block).fetch
+    end
+
+    def initialize(object, key, opts, &block)
+      self.object = object
+      self.key = key
+      self.opts = opts || {}
+      self.blueprint = AridCache.store.find(object, key)
+      self.cache_key = object.arid_cache_key(key)
+      self.cached = Rails.cache.read(cache_key)
+      self.block = block
+      self.records = nil
+    end
+            
+    def fetch_count
+      if cached.nil? || opts[:force]
+        execute_count
+      elsif cached.is_a?(AridCache::CacheProxy::Result)
+        cached.has_count? ? cached.count : execute_count
+      elsif cached.is_a?(Fixnum)
+        cached
+      elsif cached.respond_to?(:count)
+        cached.count
       else
-        cached # some base type, return it
+        cached # what else can we do? return it
       end
     end
-    
-    def fetch(blueprint, opts)
-      cached = Rails.cache.read(blueprint.cache_key)
-      if cached.nil?
-        execute_find(blueprint, opts)
-      elsif cached.is_a?(Struct::Result)
+          
+    def fetch
+      if cached.nil? || opts[:force]
+        execute_find
+      elsif cached.is_a?(AridCache::CacheProxy::Result)
         if cached.has_ids? # paginate and fetch here
+          klass = find_class_of_results
           if opts.include?(:page)
-            blueprint.klass.paginate(cached.ids, opts_for_paginate(opts, cached))
+            klass.paginate(cached.ids, opts_for_paginate)
           else
-            blueprint.klass.find(cached.ids, opts_for_find(opts, cached))
+            klass.find(cached.ids, opts_for_find)
           end
         else
-          execute_find(blueprint, opts)
+          execute_find
         end
       else
         cached # some base type, return it
       end
     end
-
+      
     private
 
-      def execute_find(blueprint, opts)
-        records = blueprint.proc.call
-
-        if !records.is_a?(Enumerable)
-          return records # some base type, return it
-        end
-                
-        # Update Rails cache and return the records
-        cached = Struct::Result.new(blueprint.opts)
-        cached.ids = records.collect(&:id)
-        cached.count = records.size
-        if records.respond_to?(:proxy_reflection) # association proxy
-          cached.klass = records.proxy_reflection.klass
-        elsif records.is_a?(Enumerable)
-          cached.klass = records.empty? ? blueprint.klass : records.first.class
-          RAILS_DEFAULT_LOGGER.info("** AridCache: inferring class of collection for cache #{blueprint.cache_key} to be #{cached.klass}")
+      def get_records
+        block = block || blueprint.proc
+        self.records = block.nil? ? object.instance_eval(key) : object.instance_eval(&block)
+      end
+      
+      def execute_find
+        get_records        
+        cached = AridCache::CacheProxy::Result.new
+        
+        if !records.is_a?(Enumerable) || (!records.empty? && !records.first.is_a?(::ActiveRecord::Base))
+          cached = records # some base type, cache it as itself
+        else
+          cached.ids = records.collect(&:id)
+          cached.count = records.size
+          if records.respond_to?(:proxy_reflection) # association proxy
+            cached.klass = records.proxy_reflection.klass
+          elsif !records.empty?
+            cached.klass = records.first.class
+          else
+            cached.klass = object_base_class
+          end
         end
+        Rails.cache.write(cache_key, cached)
         
-        Rails.cache.write(blueprint.cache_key, cached)
-        opts.include?(:page) ? records.paginate(opts_for_paginate(opts, cached)) : records      
+        self.cached = cached
+        return_records(records)
+      end
+
+      # Convert records to an array before calling paginate.  If we don't do this
+      # and the result is a named scope, paginate will trigger an additional query
+      # to load the page rather than just using the records we have already fetched.
+      #
+      # If we are not paginating and the options include :limit (and optionally :offset)
+      # apply the limit and offset to the records before returning them.
+      #
+      # Otherwise we have an issue where all the records are returned the first time
+      # the collection is loaded, but on subsequent calls the options_for_find are
+      # included and you get different results.  Note that with options like :order
+      # this cannot be helped.  We don't want to modify the query that generates the
+      # collection because the idea is to allow getting different perspectives of the
+      # cached collection without relying on modifying the collection as a whole.
+      #
+      # If you do want a specialized, modified, or subset of the collection it's best
+      # to define it in a block and have a new cache for it:
+      #
+      # model.my_special_collection { the_collection(:order => 'new order') }      
+      def return_records(records)
+        if opts.include?(:page)
+          records = records.respond_to?(:to_a) ? records.to_a : records
+          records.respond_to?(:paginate) ? records.paginate(opts_for_paginate) : records
+        elsif opts.include?(:limit)
+          records = records.respond_to?(:to_a) ? records.to_a : records
+          offset = opts[:offset] || 0 
+          records[offset, opts[:limit]]
+        else
+          records
+        end      
       end
       
-      def execute_count(blueprint)
-        records = blueprint.proc.call
-        
-        # Update Rails cache and return the count
-        cached = Struct::Result.new(blueprint.opts)
+      def execute_count
+        get_records
+        cached = AridCache::CacheProxy::Result.new
 
         # Just get the count if we can.
         #
@@ -103,42 +171,39 @@ module AridCache
         # and passes the respond_to? on to it.
         if records.respond_to?(:proxy_reflection) || records.respond_to?(:proxy_options)
           cached.count = records.count # just get the count
-          cached.klass = blueprint.klass
-        elsif records.is_a?(Enumerable)
+          cached.klass = object_base_class
+        elsif records.is_a?(Enumerable) && (records.empty? || records.first.is_a?(::ActiveRecord::Base))
           cached.ids = records.collect(&:id) # get everything now that we have it
           cached.count = records.size
-          cached.klass = records.empty? ? blueprint.klass : records.first.class
-          Rails.logger.info("** AridCache: inferring class of collection for cache #{blueprint.cache_key} to be #{cached.klass}")
+          cached.klass = records.empty? ? object_base_class : records.first.class
         else
           cached = records # some base type, cache it as itself
         end
         
-        Rails.cache.write(blueprint.cache_key, cached)
-        cached.count
-      end
-      
-      def paginate(records, opts, proc=nil) 
-        if !proc.nil?
-          ids = opts.include?(:page) ? records.paginate(opts) : records
-          records = proc.call(ids)
-          ids.is_a?(WillPaginate::Collection) ? ids.replace(records) : records
-        else
-          opts.include?(:page) ? records.paginate(opts) : records
-        end
+        Rails.cache.write(cache_key, cached)
+        self.cached = cached
+        cached.respond_to?(:count) ? cached.count : cached
       end
                   
-      def opts_for_paginate(opts, cached)
-        opts = cached.opts.merge(opts.symbolize_keys)
-        opts[:total_entries] = cached.count
-        opts
+      def opts_for_paginate
+        paginate_opts = blueprint.nil? ? opts.symbolize_keys : blueprint.opts.merge(opts.symbolize_keys)
+        paginate_opts[:total_entries] = cached.count
+        paginate_opts
       end
     
-      def opts_for_find(opts, cached)
-        opts = cached.opts.merge(opts.symbolize_keys)
-        opts.values_at([:include, :joins, :conditions, :order, :group, :having]).compact
+      VALID_FIND_OPTIONS = [ :conditions, :include, :joins, :limit, :offset, :order, :select, :readonly, :group, :having, :from, :lock ]
+      
+      def opts_for_find
+        find_opts = blueprint.nil? ? opts.symbolize_keys : blueprint.opts.merge(opts.symbolize_keys) 
+        find_opts.delete_if { |k,v| !VALID_FIND_OPTIONS.include?(k) }
       end
-    
-      def initialize
+      
+      def object_base_class
+        object.is_a?(Class) ? object : object.class
+      end
+      
+      def find_class_of_results
+        opts[:class] || (blueprint && blueprint.opts[:class]) || cached.klass || object_base_class
       end
   end
 end

data/lib/arid_cache/helpers.rb

@@ -0,0 +1,86 @@
+module AridCache
+  module Helpers
+
+    # Lookup something from the cache.
+    #
+    # If no block is provided, create one dynamically.  If a block is
+    # provided, it is only used the first time it is encountered.
+    # This allows you to dynamically define your caches while still
+    # returning the results of your query.
+    #
+    # @return a WillPaginate::Collection if the options include :page,
+    #  a Fixnum count if the request is for a count or the results of
+    #  the ActiveRecord query otherwise.
+    def lookup(object, key, opts, &block)
+      if !block.nil?
+        define(object, key, opts, &block)
+      elsif key =~ /(.*)_count$/
+        if AridCache.store.has?(object, $1)
+          method_for_cached(object, $1, :fetch_count, key)
+        elsif object.respond_to?(key)
+          define(object, key, opts, :fetch_count)
+        elsif object.respond_to?($1)
+          define(object, $1, opts, :fetch_count, key)
+        else
+          raise ArgumentError.new("#{object} doesn't respond to #{key} or #{$1}!  Cannot dynamically create query to get the count, please call with a block.")
+        end 
+      elsif object.respond_to?(key)
+        define(object, key, opts, &block)
+      else
+        raise ArgumentError.new("#{object} doesn't respond to #{key}!  Cannot dynamically create query, please call with a block.")
+      end
+      object.send("cached_#{key}", opts)
+    end
+
+    # Store the options and optional block for a call to the cache.
+    #
+    # If no block is provided, create one dynamically.
+    #
+    # @return an AridCache::Store::Blueprint.
+    def define(object, key, opts, fetch_method=:fetch, method_name=nil, &block)
+      if block.nil? && !object.respond_to?(key)
+        raise ArgumentError.new("#{object} doesn't respond to #{key}!  Cannot dynamically create a block for your cache item.")
+      end
+      
+      # FIXME: Pass default options to store.add
+      # Pass nil in for now until we get the cache_ calls working.
+      # This means that the first time you define a dynamic cache
+      # (by passing in a block), the options you used are not
+      # stored in the blueprint and applied to each subsequent call.
+      #
+      # Otherwise we have a situation where a :limit passed in to the
+      # first call persists when no options are passed in on subsequent calls,
+      # but if a different :limit is passed in that limit is applied.
+      #
+      # I think in this scenario one would expect no limit to be applied
+      # if no options are passed in.
+      #
+      # When the cache_ methods are supported, those options should be
+      # remembered and applied to the collection however.
+      blueprint = AridCache.store.add(object, key, block, nil)
+      method_for_cached(object, key, fetch_method, method_name)
+      blueprint
+    end
+
+    private
+
+    def method_for_cached(object, key, fetch_method=:fetch, method_name=nil)
+      method_name = "cached_" + (method_name || key)
+      if object.is_a?(Class)
+        (class << object; self; end).instance_eval do
+          define_method(method_name) do |*args, &block|
+            opts = args.empty? ? {} : args.first
+            AridCache.cache.send(fetch_method, self, key, opts, &block)
+          end
+        end
+      else
+        object.class_eval do
+          define_method(method_name) do |*args, &block|
+            opts = args.empty? ? {} : args.first
+            AridCache.cache.send(fetch_method, self, key, opts, &block)
+          end
+        end
+      end
+    end
+  end  
+end

data/lib/arid_cache/store.rb

@@ -1,58 +1,84 @@
 module AridCache
   class Store < Hash
-    Struct.new('Item', :cache_key, :proc, :klass, :opts)
+    extend ActiveSupport::Memoizable
     
-    def query(key, opts, object, &block)
-      return store(object, key, Proc.new, opts) if block_given? # store a proc
+    # AridCache::Store::Blueprint
+    #
+    # Stores options and blocks that are used to generate results for finds
+    # and counts.
+    Blueprint = Struct.new(:key, :klass, :proc, :opts)  do
 
-      if has?(object, key)
-        AridCache.cache.fetch(find(object, key), opts)
-      elsif key =~ /(.*)_count$/
-        if has?(object, $1)
-          AridCache.cache.fetch_count(find(object, $1))
-        elsif object.respond_to?(key)
-          AridCache.cache.fetch_count(find_or_create(object, key))
-        elsif object.respond_to?($1)
-          AridCache.cache.fetch_count(find_or_create(object, $1))
-        else
-          raise ArgumentError.new("#{object} doesn't respond to #{key} or #{$1}!  Cannot dynamically create query to get the count.")
-        end 
-      else         
-        if object.respond_to?(key)
-          AridCache.cache.fetch(find_or_create(object, key), opts)
+      def initialize(key, klass, proc=nil, opts={})
+        self.key = key
+        self.klass = klass
+        self.proc = proc
+        self.opts = opts
+      end
+            
+      def klass=(value) # store the base class of *value*
+        self['klass'] = value.is_a?(Class) ? value.name : value.class.name
+      end
+      
+      def klass
+        self['klass'].constantize unless self['klass'].nil?
+      end 
+      
+      def opts=(value)
+        self['opts'] = value.symbolize_keys! unless !value.respond_to?(:symbolize_keys)
+      end    
+      
+      def opts
+        self['opts'] || {}
+      end
+      
+      def proc(object=nil)
+        if self['proc'].nil? && !object.nil?
+          self['proc'] = key
         else
-          raise ArgumentError.new("#{object} doesn't respond to #{key}!  Cannot dynamically create query.")
+          self['proc']
         end
-      end
+      end 
     end
     
-    # Store a proc
-    def store(object, key, proc, opts)
-      cache_key = object.arid_cache_key(key)
-      self[cache_key] = Struct::Item.new(cache_key, proc, (object.is_a?(Class) ? object : object.class), opts.symbolize_keys!)
+    def has?(object, key)
+      self.include?(object_store_key(object, key))
     end
     
+    # Empty the proc store
+    def delete!
+      delete_if { true }
+    end 
+
+    def self.instance
+      @@singleton_instance ||= self.new
+    end
+
     def find(object, key)
-      self[object.arid_cache_key(key)]
+      self[object_store_key(object, key)]
+    end
+    
+    def add(object, key, proc, opts)
+      store_key = object_store_key(object, key)
+      self[store_key] = AridCache::Store::Blueprint.new(key, object, proc, opts)
     end
     
-    # Find or dynamically create a proc
     def find_or_create(object, key)
-      cache_key = object.arid_cache_key(key)
-      if include?(cache_key)
-        self[cache_key]
+      store_key = object_store_key(object, key)
+      if self.include?(store_key)
+        self[store_key]
       else
-        self[cache_key] = Struct::Item.new(cache_key, Proc.new { object.send(key) }, (object.is_a?(Class) ? object : object.class))
+        self[store_key] = AridCache::Store::Blueprint.new(key, object)
       end
     end
     
-    def has?(object, key)
-      self.include?(object.arid_cache_key(key))
+    protected
+    
+    def initialize
     end
     
-    # Empty the proc store
-    def delete!
-      delete_if { true }
-    end 
+    def object_store_key(object, key)
+      (object.is_a?(Class) ? object.name.downcase : object.class.name.pluralize.downcase) + '-' + key.to_s
+    end
+    memoize :object_store_key
   end 
 end

data/lib/arid_cache.rb

@@ -1,15 +1,47 @@
+dir = File.dirname(__FILE__)
+$LOAD_PATH.unshift dir unless $LOAD_PATH.include?(dir)
+
+require 'arid_cache/helpers'
 require 'arid_cache/store'
 require 'arid_cache/active_record'
 require 'arid_cache/cache_proxy'
 
 module AridCache
+  extend AridCache::Helpers
   class Error < StandardError; end
 
   def self.cache
-    AridCache::CacheProxy.instance
+    AridCache::CacheProxy
   end
 
+  def self.clear_all_caches
+    AridCache::CacheProxy.clear_all_caches
+  end 
+  
+  def self.clear_class_caches(object)
+    AridCache::CacheProxy.clear_class_caches(object)
+  end 
+      
+  def self.clear_instance_caches(object)
+    AridCache::CacheProxy.clear_instance_caches(object)
+  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 ARID Cache for Rails.
+  #
+  # This method is called by `init.rb`,
+  # which is run by Rails on startup.
+  def self.init_rails
+    ::ActiveRecord::Base.send(:include, AridCache::ActiveRecord)
+  end
 end

data/rails/init.rb

@@ -1 +1 @@
-require 'arid_cache'
+Kernel.load File.join(File.dirname(__FILE__), '..', 'init.rb')

data/test/arid_cache_test.rb

@@ -3,37 +3,44 @@ require File.join(File.dirname(__FILE__), 'test_helper')
 class AridCacheTest < ActiveSupport::TestCase
   def setup
     Rails.cache.clear
+    AridCache.store.delete!
     get_user
   end
-    
+
+  test "initializes needed objects" do
+    assert_instance_of AridCache::Store, AridCache.store
+    assert_same AridCache::CacheProxy, AridCache.cache
+  end
+      
   test "should respond to methods" do
-    assert_respond_to(User, :cache_store)
-    assert_respond_to(User.first, :cache_store)
-    assert_instance_of AridCache::Store, User.cache_store
-    assert_same User.cache_store, User.first.cache_store
+    assert User.respond_to?(:clear_cache)
+    assert User.first.respond_to?(:clear_cache)    
+    assert_instance_of AridCache::Store, AridCache.store
   end
     
-  test "should not clobber method_missing" do
-    assert_respond_to User.first, :name                                                                  
-  end 
-  
-  test "should allow access to valid methods" do
+  test "should not clobber model methods" do
+    assert_respond_to User.first, :name
+    assert_respond_to Company.first, :name
+    assert_nothing_raised { User.first.name }
+    assert_nothing_raised { Company.first.name }
+    
+    # Shouldn't mess with your model's method_missing
     assert_nothing_raised { User.first.is_high? }
-    assert User.first.is_high?
-  end 
+    assert User.first.is_high?  
+  end
     
   test "should allow me to cache on the model" do
     assert_nothing_raised do
       define_model_cache(User)
     end
-    assert_instance_of(Proc, User.cache_store[User.arid_cache_key('companies')].proc)
+    #assert_instance_of(Proc, AridCache.store[User.arid_cache_key('companies')].proc)
   end
   
   test "should allow me to cache on the instance" do
     assert_nothing_raised do
       define_instance_cache(@user)
     end
-    assert_instance_of(Proc, @user.cache_store[@user.arid_cache_key('companies')].proc)
+    #assert_instance_of(Proc, AridCache.store[AridCache.store.store_key@user.arid_cache_key('companies')].proc)
   end
     
   test "should raise an error on invalid dynamic caches" do
@@ -44,7 +51,7 @@ class AridCacheTest < ActiveSupport::TestCase
   
   test "should create dynamic caches given valid arguments" do
     assert_nothing_raised { @user.cached_companies }
-    assert_instance_of(Proc, @user.cache_store[@user.arid_cache_key('companies')].proc)
+    #assert_instance_of(Proc, AridCache.store[@user.arid_cache_key('companies')].proc)
   end
   
   test "counts queries correctly" do
@@ -58,9 +65,9 @@ class AridCacheTest < ActiveSupport::TestCase
   end
   
   test "paginates results" do
-    results = @user.cached_companies(:page => 1)
+    results = @user.cached_companies(:page => 1, :per_page => 3)
     assert_kind_of WillPaginate::Collection, results
-    assert_equal 2, results.size
+    assert_equal 3, results.size
     assert_equal @user.companies.count, results.total_entries
     assert_equal 1, results.current_page
   end
@@ -75,15 +82,16 @@ class AridCacheTest < ActiveSupport::TestCase
   test "works for different pages" do
     results = @user.cached_companies(:page => 2, :per_page => 3)
     assert_kind_of WillPaginate::Collection, results
-    assert_equal (@user.companies.count-3)%3, results.size
-    assert_equal @user.companies.count, results.total_entries    
+    assert results.size <= 3
+    assert_equal @user.companies.count, results.total_entries  
+    assert_equal 2, results.current_page  
   end
-
+  
   test "ignores random parameters" do
     result = @user.cached_companies(:invalid => :params, 'random' => 'values', :user_id => 3)
     assert_equal @user.companies, result
   end
-
+  
   test "passes on options to find" do
     actual = @user.cached_companies(:order => 'users.id DESC')
     expected = @user.companies
@@ -99,31 +107,101 @@ class AridCacheTest < ActiveSupport::TestCase
   end
         
   test "gets the count only if it's requested first" do
+    count = @user.companies.count
+    assert_queries(1) do
+      assert_equal count, @user.cached_companies_count
+      assert_equal count, @user.cached_companies_count
+    end
+    assert_queries(1) do
+      assert_equal count, @user.cached_companies.size
+      assert_equal count, @user.cached_companies_count
+    end
+  end
+  
+  test "calling cache_ defines methods on the object" do
+    assert !User.method_defined?(:cached_favorite_companies)
+    User.cache_favorite_companies(:order => 'name DESC') do
+      User.companies
+    end
+    assert User.respond_to?(:cached_favorite_companies)
+    assert_nothing_raised do
+      User.method(:cached_favorite_companies)
+    end    
+  end
+
+  test "applies limit and offset" do
+    @user.cached_limit_companies do
+      companies
+    end
+    assert_equal 2, @user.cached_limit_companies(:limit => 2).size
+    assert_equal 3, @user.cached_limit_companies(:limit => 3).size
+    assert_equal @user.companies.all(:limit => 2, :offset => 1), @user.cached_limit_companies(:limit => 2, :offset => 1)
+    assert_equal @user.companies.size, @user.cached_limit_companies.size    
+    User.cached_successful_limit_companies do
+      User.successful
+    end
+    raise User.cached_successful_limit_companies.inspect
+    assert_equal 2, User.cached_successful_limit_companies(:limit => 2).size
+    assert_equal 3, User.cached_successful_limit_companies(:limit => 3).size
+    assert_equal User.successful.all(:limit => 2, :offset => 1), User.cached_successful_limit_companies(:limit => 2, :offset => 1)
+    assert_equal User.successful.size, User.cached_successful_limit_companies.size  
+  end
+  
+  test "pagination should not result in an extra query" do
+    assert_queries(1) do
+      @user.cached_big_companies(:page => 1)
+    end
     assert_queries(1) do
-      assert_equal 5, @user.cached_companies_count
-      assert_equal 5, @user.cached_companies_count
+      User.cached_companies(:page => 1)
     end
+  end
+  
+  test "should support a 'force' option" do
+    # ActiveRecord caches the result of the proc, so we need to
+    # use different instances of the user to test the force option.
+    uncached_user = User.first
+    companies = @user.companies
+    size = companies.size
     assert_queries(1) do
-      assert_equal 5, @user.cached_companies.size
-      assert_equal 5, @user.cached_companies_count
-    end
-  end
-     
-  # test "should empty the Rails cache" do
-  #   @user.cached_companies
-  #   User.cached_companies
-  #   assert Rails.cache.exist?(@user.arid_cache_key('companies'))
-  #   assert Rails.cache.exist?(User.arid_cache_key('companies'))
-  #   User.clear_cache
-  #   assert Rails.cache.exist?(@user.arid_cache_key('companies'))
-  #   assert Rails.cache.exist?(User.arid_cache_key('companies'))   
-  # end
+      assert_equal companies, @user.cached_companies
+      assert_equal size, @user.cached_companies_count
+      assert_equal size, uncached_user.cached_companies_count
+    end
+    assert_queries(2) do
+      assert_equal companies, uncached_user.cached_companies(:force => true)
+      assert_equal size, uncached_user.cached_companies_count(:force => true)
+    end
+  end
+  
+  test "should handle various different model instances" do
+    one = User.first
+    two = User.first :offset => 1
+    assert_not_same one, two
+    assert_equal one.companies, one.cached_companies
+    assert_equal two.companies, two.cached_companies
+  end
+
+  test "should handle arrays of non-active record instances" do
+    assert_equal @user.pet_names, @user.cached_pet_names
+    assert_equal @user.pet_names, @user.cached_pet_names
+    assert_equal @user.pet_names.count, @user.cached_pet_names_count
+  end
+             
+  test "should empty the Rails cache" do
+    define_model_cache(User)
+    @user.cached_companies
+    User.cached_companies
+    assert Rails.cache.exist?(@user.arid_cache_key('companies'))
+    assert Rails.cache.exist?(User.arid_cache_key('companies'))
+    User.clear_cache
+    assert Rails.cache.exist?(@user.arid_cache_key('companies'))
+    assert Rails.cache.exist?(User.arid_cache_key('companies'))   
+  end
       
   protected
 
     def get_user
       @user = User.first
-      @user.cache_store.delete!
       @user.clear_cache
       define_instance_cache(@user)
       @user
@@ -141,13 +219,13 @@ class AridCacheTest < ActiveSupport::TestCase
     end
   
     def define_instance_cache(user)
-      user.cached_companies(:per_page => 2) do
+      user.cache_companies(:per_page => 2) do
         user.companies
       end    
     end 
 
     def define_model_cache(model)
-      model.cached_companies(:per_page => 2) do
+      model.cache_companies(:per_page => 2) do
         model.companies
       end    
     end 

data/test/db/schema.rb

@@ -8,5 +8,6 @@ ActiveRecord::Schema.define do
     t.column "name",  :text
     t.column "owner_id", :integer
     t.column "country_id", :integer
+    t.column "employees", :integer    
   end
 end

data/test/fixtures/companies.yml

@@ -1,5 +1,6 @@
-<% for digit in 1..5 %>
+<% for digit in 1..15 %>
 acme_<%= digit %>:
   name: Acme <%= digit %>
-  owner_id: 1
+  owner_id: <%= rand(10) %>
+  employees: <%= rand(200) %>
 <% end %>

data/test/fixtures/users.yml

@@ -1,3 +1,5 @@
-bob:
-  name: Bob
-  email: bob@ibm.com
+<% for digit in 1..10 %>
+user_<%= digit %>:
+  name: Bob <%= digit %>
+  email: bob<%= digit %>@ibm.com
+<% end %>

data/test/models/user.rb

@@ -1,9 +1,17 @@
 require 'arid_cache'
 
 class User < ActiveRecord::Base
-  include AridCache
   has_many :companies, :foreign_key => :owner_id
   named_scope :companies, :joins => :companies
+  named_scope :successful, :joins => :companies, :conditions => 'companies.employees > 50'
+  
+  def big_companies
+    companies.find :all, :conditions => [ 'employees > 20' ]
+  end
+
+  def pet_names
+    ['Fuzzy', 'Peachy']
+  end
   
   def method_missing(method, *args)
     if method == :is_high?

data/test/test_helper.rb

@@ -7,7 +7,11 @@ require 'active_support'
 require 'active_support/test_case'
 require 'test/unit' # required by ActiveSupport::TestCase
 require 'will_paginate'
+require 'ruby-debug'
+
+# Activate ARID Cache
 require 'arid_cache'
+AridCache.init_rails
 
 # Setup logging
 log = File.expand_path(File.join(File.dirname(__FILE__), 'log', 'test.log'))

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: arid_cache
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Karl Varga
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-21 00:00:00 +08:00
+date: 2009-12-25 00:00:00 +08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -42,7 +42,10 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
     version: 
-description: ""
+description: |
+  ARID Cache makes caching easy and effective.  ARID cache supports caching on all your model named scopes, class methods and instance methods right out of the box.  ARID cache prevents caching logic from cluttering your models and clarifies your logic by making explicit calls to cached result sets.
+  ARID Cache is designed for handling large, expensive ActiveRecord collections but is equally useful for caching anything else as well.
+
 email: kjvarga@gmail.com
 executables: []
 
@@ -58,13 +61,13 @@ files:
 - Rakefile
 - VERSION
 - arid_cache.gemspec
+- init.rb
 - lib/arid_cache.rb
 - lib/arid_cache/active_record.rb
 - lib/arid_cache/cache_proxy.rb
+- lib/arid_cache/helpers.rb
 - lib/arid_cache/store.rb
 - rails/init.rb
-- rails/install.rb
-- rails/uninstall.rb
 - spec/arid_cache_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb

data/rails/install.rb

@@ -1 +0,0 @@
-# Install hook code here

data/rails/uninstall.rb

@@ -1 +0,0 @@
-# Uninstall hook code here