cached_record 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 93cc1d0bfdf782350a6fff60b88abc1b8d5a8562
+  data.tar.gz: 1b6b13ba8e18d9c417a015c5715a48c88d493531
+SHA512:
+  metadata.gz: 44b292a27fed4e2bf01eff14ea8ca9fd39c6241a03db518fa25d778cbc2ce4312cb3f80756e85996ab9c86f907de8b188f5f3c97a7da5dba11a577475081e75c
+  data.tar.gz: ed9dc9141708f4a5e7ba71dceb98403bd94f583b9dead3b01a05bf0e8a30f865b5269a38bcb5a89fbe836cc9cb8d4545d50618d70880ef7bdc3ca062e6e729c2

data/.gitignore

@@ -0,0 +1,8 @@
+.DS_Store
+.bundle
+.rvmrc
+Gemfile.lock
+doc
+log/*.log
+pkg
+test/coverage

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 1.9.3
+services:
+  - memcached
+  - redis-server
+before_script:
+  - 'printf "test:\n  adapter: mysql2\n  database: cached_record_test\n  username: travis\n  encoding: utf8" > config/database.yml'
+  - 'mysql -e "create database cached_record_test;"'
+  - 'mysql cached_record_test < db/cached_record.sql'

data/CHANGELOG.rdoc

@@ -0,0 +1,5 @@
+= CachedRecord CHANGELOG
+
+== Version 0.1.0 (February 18, 2014)
+
+* Initial release

data/Gemfile

@@ -0,0 +1,13 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "cached_record", :path => "."
+end
+
+group :test do
+  gem "simplecov", :require => false
+  gem "minitest"
+  gem "mocha"
+end

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2014 Paul Engel
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,391 @@
+== CachedRecord {<img src="https://secure.travis-ci.org/archan937/cached_record.png"/>}[http://travis-ci.org/archan937/cached_record] {<img src="https://codeclimate.com/github/archan937/cached_record.png"/>}[https://codeclimate.com/github/archan937/cached_record]
+
+Cache (and optionally memoize) ActiveRecord or DataMapper records in Redis or Memcached.
+
+=== Installation
+
+==== Using Bundler
+
+Add CachedRecord in <tt>Gemfile</tt> as a gem dependency:
+
+  gem "cached_record"
+
+Run the following in your console to install with Bundler:
+
+  $ bundle install
+
+=== Setting up development and test databases
+
+Make sure you have the correct database config in +database.yml+ and run:
+
+  $ rake db:install
+
+=== Usage
+
+==== Set up CachedRecord
+
+At startup, you need to invoke <tt>CachedRecord.setup</tt>. This method does the following:
+
+* it preps <tt>ActiveRecord::Base</tt> and/or <tt>DataMapper::Resource</tt> (only when defined)
+* it registers the available cache stores (Redis and/or Memcached)
+
+In a Rails application, you can add a Ruby source file (e.g. <tt>cached_record.rb</tt>) within <tt>config/initializers</tt> for instance.
+
+You can specify the available cache stores by passing either a Symbol (<tt>:redis</tt> and/or <tt>:memcached</tt> with default localhost settings) or a key / value pair (with custom server settings):
+
+When using Redis at localhost:
+
+  CachedRecord.setup :redis
+
+When using Redis at localhost and Memcached at another server:
+
+  CachedRecord.setup :redis, :memcached => {:host => "123.45.67.8", :port => 90}
+
+==== Specify cache structure and strategy
+
+A record will not automatically be cached in a cache store. You have to make a choice whether to only serialize objects within the cache store or whether you want also memoize objects (which is much more performant but at the cost of extra memory usage).
+
+Also, you can specify which attributes, associations and/or instance variables need to be cached.
+
+===== Cache strategy
+
+As already mentioned, you will have to choose whether you only want to serialize objects within the cache store or whether you also want to memoize them.
+
+====== Serializing objects
+
+To only serialize objects within the cache store, use the class method <tt>as_cache</tt>:
+
+  class Article < ActiveRecord::Base
+    as_cache :only => [:title]
+  end
+
+When using <tt>DataMapper</tt>:
+
+  class Article
+    include DataMapper::Resource
+    property :id, Serial, :key => true
+    property :title, String
+    as_cache :only => [:title]
+  end
+
+Please note that the <tt>id</tt> of a record will always be cached and that in previous examples both the <tt>id</tt> and <tt>title</tt> attributes will be cached.
+
+When trying this out in the console (please note when the query hits occur):
+
+  [1] pry(main)> ActiveRecord::Base.logger = Logger.new STDOUT; nil
+  => nil
+  [2] pry(main)> a = Article.first
+  D, [2013-12-12T22:59:52.223555 #23583] DEBUG -- :   Article Load (0.3ms)  SELECT `articles`.* FROM `articles` ORDER BY `articles`.`id` ASC LIMIT 1
+  => #<Article id: 1, title: "Behold! It's CachedRecord!", content: "Cache ORM instances to avoid database queries", author_id: 1, foo_id: 2, published_at: "2013-08-01 12:00:00", created_at: "2013-08-01 10:00:00", updated_at: "2013-08-01 11:00:00">
+  [3] pry(main)> a.as_cache_json
+  => {:id=>1, :title=>"Behold! It's CachedRecord!"}
+  [4] pry(main)> a.to_cache_json
+  => "{\"id\":1,\"title\":\"Behold! It's CachedRecord!\"}"
+  [5] pry(main)> Article.cached(1)
+  D, [2013-12-12T22:59:59.656254 #23583] DEBUG -- :   Article Load (0.3ms)  SELECT `articles`.* FROM `articles` WHERE `articles`.`id` = 1 LIMIT 1
+  => #<Article id: 1, title: "Behold! It's CachedRecord!", content: nil, author_id: nil, foo_id: nil, published_at: nil, created_at: nil, updated_at: nil>
+  [6] pry(main)> Article.cached(1).object_id == Article.cached(1).object_id
+  => false
+  [7] pry(main)> Article.cached(1).title
+  => "Behold! It's CachedRecord!"
+  [8] pry(main)> Redis.new.get "article.1"
+  => "{\"id\":1,\"title\":\"Behold! It's CachedRecord!\"}"
+  [9] pry(main)> Article.first.title
+  D, [2013-12-12T23:00:04.159257 #23583] DEBUG -- :   Article Load (0.3ms)  SELECT `articles`.* FROM `articles` ORDER BY `articles`.`id` ASC LIMIT 1
+  => "Behold! It's CachedRecord!"
+
+I will only continue with <tt>ActiveRecord::Base</tt> instances within examples as using <tt>DataMapper</tt> is quite similar.
+
+====== Serializing and memoizing objects
+
+For better performance at the cost of extra memory usage, use the class method <tt>as_memoized_cache</tt>:
+
+  class Article < ActiveRecord::Base
+    as_memoized_cache :only => [:title]
+  end
+
+When trying this out in the console:
+
+  [1] pry(main)> ActiveRecord::Base.logger = Logger.new STDOUT; nil
+  => nil
+  [2] pry(main)> a = Article.first
+  D, [2013-12-12T23:01:29.387239 #23763] DEBUG -- :   Article Load (0.3ms)  SELECT `articles`.* FROM `articles` ORDER BY `articles`.`id` ASC LIMIT 1
+  => #<Article id: 1, title: "Behold! It's CachedRecord!", content: "Cache ORM instances to avoid database queries", author_id: 1, foo_id: 2, published_at: "2013-08-01 12:00:00", created_at: "2013-08-01 10:00:00", updated_at: "2013-08-01 11:00:00">
+  [3] pry(main)> a.as_cache_json
+  => {:id=>1, :title=>"Behold! It's CachedRecord!"}
+  [4] pry(main)> a.to_cache_json
+  => "{\"id\":1,\"title\":\"Behold! It's CachedRecord!\"}"
+  [5] pry(main)> Article.cached(1)
+  D, [2013-12-12T23:01:36.061953 #23763] DEBUG -- :   Article Load (0.3ms)  SELECT `articles`.* FROM `articles` WHERE `articles`.`id` = 1 LIMIT 1
+  => #<Article id: 1, title: "Behold! It's CachedRecord!", content: nil, author_id: nil, foo_id: nil, published_at: nil, created_at: nil, updated_at: nil>
+  [6] pry(main)> Article.cached(1).object_id == Article.cached(1).object_id
+  => true
+  [7] pry(main)> Article.cached(1).title
+  => "Behold! It's CachedRecord!"
+  [8] pry(main)> Redis.new.get "article.1"
+  => "{\"id\":1,\"title\":\"Behold! It's CachedRecord!\"}@1386885696"
+  [9] pry(main)> Article.first.title
+  D, [2013-12-12T23:01:40.556263 #23763] DEBUG -- :   Article Load (0.4ms)  SELECT `articles`.* FROM `articles` ORDER BY `articles`.`id` ASC LIMIT 1
+  => "Behold! It's CachedRecord!"
+  [10] pry(main)> CachedRecord::Cache.send :cache
+  => {Dalli::Client=>{},
+   Redis=>
+    {"article.1"=>
+      {:instance=>
+        #<Article id: 1, title: "Behold! It's CachedRecord!", content: nil, author_id: nil, foo_id: nil, published_at: nil, created_at: nil, updated_at: nil>,
+       :epoch_time=>1386885696}}}
+
+===== Cache store
+
+When having specified more than one cache store with <tt>CachedRecord.setup</tt>, you will have to pass which cache store you want to use for a specific record class.
+
+Either pass <tt>:memcached</tt> or <tt>:redis</tt> as follows:
+
+  class Article < ActiveRecord::Base
+    as_memoized_cache :memcached, :only => [:title]
+  end
+
+When having specified only one cache store, you can leave it out:
+
+  CachedRecord.setup :redis
+
+  class Article < ActiveRecord::Base
+    as_memoized_cache :only => [:title]
+  end
+
+This serializes Article records within the Redis server.
+
+===== Attributes
+
+You have control over which attributes have to be serialized. Pass the <tt>:only</tt> option. When you don't pass the option, all attributes will be included.
+
+  class Article < ActiveRecord::Base
+    as_cache
+  end
+
+  [1] pry(main)> Article.first.as_cache_json
+  => {:id=>1,
+   :title=>"Behold! It's CachedRecord!",
+   :content=>"Cache ORM instances to avoid database queries",
+   :published_at=>2013-08-01 12:00:00 +0200,
+   :created_at=>2013-08-01 10:00:00 +0200,
+   :updated_at=>2013-08-01 11:00:00 +0200}
+
+===== Associations
+
+You can include associations by passing the <tt>:include</tt> option. When using the setup of <tt>script/console</tt>:
+
+  [1] pry(main)> ActiveRecord::Base.logger = Logger.new STDOUT; nil
+  => nil
+  [2] pry(main)> Article.cached(1).as_cache_json
+  D, [2013-12-12T23:54:54.729034 #25722] DEBUG -- :   Article Load (0.4ms)  SELECT `articles`.* FROM `articles` WHERE `articles`.`id` = 1 LIMIT 1
+  D, [2013-12-12T23:54:54.746719 #25722] DEBUG -- :   User Load (0.3ms)  SELECT `users`.* FROM `users` WHERE `users`.`id` = 1 ORDER BY `users`.`id` ASC LIMIT 1
+  D, [2013-12-12T23:54:54.787599 #25722] DEBUG -- :   Comment Load (0.4ms)  SELECT `comments`.* FROM `comments` WHERE `comments`.`article_id` = 1
+  D, [2013-12-12T23:54:54.803960 #25722] DEBUG -- :   Tag Load (0.4ms)  SELECT `tags`.* FROM `tags` INNER JOIN `articles_tags` ON `tags`.`id` = `articles_tags`.`tag_id` WHERE `articles_tags`.`article_id` = 1
+  D, [2013-12-12T23:54:54.811653 #25722] DEBUG -- :   User Load (0.3ms)  SELECT `users`.* FROM `users` WHERE `users`.`id` = 1 LIMIT 1
+  D, [2013-12-12T23:54:54.814919 #25722] DEBUG -- :   Article Load (0.4ms)  SELECT `articles`.* FROM `articles` WHERE `articles`.`foo_id` = 1 ORDER BY `articles`.`id` ASC LIMIT 1
+  D, [2013-12-12T23:54:54.817261 #25722] DEBUG -- :   Comment Load (0.3ms)  SELECT `comments`.* FROM `comments` WHERE `comments`.`id` = 1 LIMIT 1
+  D, [2013-12-12T23:54:54.818860 #25722] DEBUG -- :   User Load (0.2ms)  SELECT `users`.* FROM `users` WHERE `users`.`id` = 2 ORDER BY `users`.`id` ASC LIMIT 1
+  D, [2013-12-12T23:54:54.820553 #25722] DEBUG -- :   User Load (0.2ms)  SELECT `users`.* FROM `users` WHERE `users`.`id` = 2 LIMIT 1
+  D, [2013-12-12T23:54:54.821601 #25722] DEBUG -- :   Article Load (0.2ms)  SELECT `articles`.* FROM `articles` WHERE `articles`.`foo_id` = 2 ORDER BY `articles`.`id` ASC LIMIT 1
+  D, [2013-12-12T23:54:54.823996 #25722] DEBUG -- :   Comment Load (0.4ms)  SELECT `comments`.* FROM `comments` WHERE `comments`.`id` = 2 LIMIT 1
+  D, [2013-12-12T23:54:54.825475 #25722] DEBUG -- :   User Load (0.3ms)  SELECT `users`.* FROM `users` WHERE `users`.`id` = 1 ORDER BY `users`.`id` ASC LIMIT 1
+  D, [2013-12-12T23:54:54.828590 #25722] DEBUG -- :   Tag Load (0.2ms)  SELECT `tags`.* FROM `tags` WHERE `tags`.`id` = 1 LIMIT 1
+  D, [2013-12-12T23:54:54.830137 #25722] DEBUG -- :   Tag Load (0.2ms)  SELECT `tags`.* FROM `tags` WHERE `tags`.`id` = 2 LIMIT 1
+  => {:id=>1,
+   :title=>"Behold! It's CachedRecord!",
+   :author_id=>1,
+   :_comment_ids=>[1, 2],
+   :_tag_ids=>[1, 2]}
+  [3] pry(main)> Article.cached(1).as_cache_json
+  => {:id=>1,
+   :title=>"Behold! It's CachedRecord!",
+   :author_id=>1,
+   :_comment_ids=>[1, 2],
+   :_tag_ids=>[1, 2]}
+  [4] pry(main)> Article.cached(1).author
+  => #<User id: 1, name: "Paul Engel", description: nil, active: nil, created_at: nil, updated_at: nil>
+  [5] pry(main)> a = Article.cached(1)
+  => #<Article id: 1, title: "Behold! It's CachedRecord!", content: nil, author_id: 1, foo_id: nil, published_at: nil, created_at: nil, updated_at: nil>
+  [6] pry(main)> a.author.object_id == a.comments[1].poster.object_id
+  => true
+
+===== Instance variables
+
+Finally, you can cache instance variables. Pass the <tt>:memoize</tt> option. This can be a Symbol or a Hash.
+
+When passing a Symbol, CachedRecord expects that a method with that name is defined and that it memoizes an instance variable with the same name (prefixed with a <tt>@</tt>):
+
+  class Article < ActiveRecord::Base
+    as_cache :memcached, :only => [], :memoize => [:random_array]
+    def random_array
+      @random_array ||= [rand(10)]
+    end
+  end
+
+  [1] pry(main)> Article.cached(1).random_array
+  => [2]
+  [2] pry(main)> Article.cached(1).random_array
+  => [2]
+  [3] pry(main)> Article.first.random_array
+  => [4]
+  [4] pry(main)> Article.first.random_array
+  => [0]
+  [5] pry(main)> Article.cached(1).random_array
+  => [2]
+  [6] pry(main)> Article.cached(1).random_array
+  => [2]
+  [7] pry(main)> Dalli::Client.new.get "article.1"
+  => "{\"id\":1,\"@random_array\":[2]}"
+
+You should pass a Hash when the name of the method differs from the name of the corresponding instance variable:
+
+  class Article < ActiveRecord::Base
+    as_cache :memcached, :only => [], :memoize => {:random_array => :@rarray}
+    def random_array
+      @rarray ||= [rand(10)]
+    end
+  end
+
+  [1] pry(main)> Article.cached(1).random_array
+  => [5]
+  [2] pry(main)> Article.cached(1).random_array
+  => [5]
+  [3] pry(main)> Article.first.random_array
+  => [9]
+  [4] pry(main)> Article.first.random_array
+  => [7]
+  [5] pry(main)> Article.cached(1).random_array
+  => [5]
+  [6] pry(main)> Article.cached(1).random_array
+  => [5]
+  [7] pry(main)> Dalli::Client.new.get "article.1"
+  => "{\"id\":1,\"@rarray\":[5]}"
+
+===== Include root
+
+Like in Rails, you can pass <tt>:include_root</tt> when parsing a record to JSON. It wraps the resulting hash with an extra key (the class name underscored).
+
+You can also do this with <tt>CachedRecord</tt>:
+
+  class Article < ActiveRecord::Base
+    as_cache :only => [:title], :include_root => true
+  end
+
+When trying this out in the console:
+
+  [1] pry(main)> Article.first.as_cache_json
+  => {:article=>{:id=>1, :title=>"Behold! It's CachedRecord!"}}
+
+Namespaces are ignored at default:
+
+  module Blog
+    class Article < ActiveRecord::Base
+      as_cache :only => [:title], :include_root => true
+    end
+  end
+
+  [1] pry(main)> Blog::Article.first.as_cache_json
+  => {:article=>{:id=>1, :title=>"Behold! It's CachedRecord!"}}
+
+You can override this behaviour by overriding the `cache_root` class method:
+
+  module Blog
+    class Article < ActiveRecord::Base
+      as_cache :only => [:title], :include_root => true
+      def self.cache_root
+        :"#{name.underscore.gsub("/", ".")}"
+      end
+    end
+  end
+
+  [1] pry(main)> Blog::Article.first.as_cache_json
+  => {:"blog.article"=>{:id=>1, :title=>"Behold! It's CachedRecord!"}}
+
+===== Expiration
+
+You can specify the TTL (Time To Live) of a record by passing the <tt>:expire</tt> option:
+
+  class Article < ActiveRecord::Base
+    as_memoized_cache :redis, :only => [:title], :expire => 5.seconds
+  end
+
+  [1] pry(main)> puts Article.cached(1).object_id; sleep 4; puts Article.cached(1).object_id; sleep 2; puts Article.cached(1).object_id
+  70311156481000
+  70311156481000
+  70311131970100
+  => nil
+
+===== Retaining
+
+You can retain memoized instances for a specific period of time. This reduces cache store hits and thus is more performant.
+
+  class Article < ActiveRecord::Base
+    as_memoized_cache :redis, :only => [:title], :retain => 5.seconds
+  end
+
+In this case, memoized <tt>Article</tt> instances are retained for at least 5 seconds.
+
+== Using the console
+
+As you probably already noticed, the <tt>CachedRecord</tt> repo is provided with a <tt>script/console</tt> command which you can use for development / testing purposes. Please note that you have to run a Redis server locally.
+
+Run the following command in your console:
+
+  $ script/console
+  Loading CachedRecord development environment (0.1.0)
+  [1] pry(main)> a = Article.cached(1)
+  => #<Article id: 1, title: "Behold! It's CachedRecord!", content: nil, author_id: 1, foo_id: nil, published_at: nil, created_at: nil, updated_at: nil>
+  [2] pry(main)> a.object_id == Article.cached(1).object_id
+  => true
+
+== Benchmarking
+
+The <tt>CachedRecord</tt> repo is provided with several benchmarks. You can run them using <tt>rake benchmark</tt>.
+
+  ruby-2.0.0 paulengel:cached_record (master) $ rake benchmark
+  Benchmarking uncached instances (5000 times)
+  -> [++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++] 100.0% in 27.92s
+  Benchmarking cached instances (5000 times)
+  -> [++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++] 100.0% in 25.66s
+  Benchmarking memoized instances (5000 times)
+  -> [++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++] 100.0% in 1.52s
+  Benchmarking retained instances (5000 times)
+  -> [++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++] 100.0% in 0.41s
+  Benchmarking memoized instances (150000 times)
+  -> [++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++] 100.0% in 39.40s
+  Benchmarking retained instances (150000 times)
+  -> [++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++] 100.0% in 7.75s
+  Done.
+
+As expected, <b>retaining instances is the fastest cache strategy</b> at the cost of extra memory usage and having stale instances (in this case for 10 seconds).
+
+Be sure to have a Redis server running locally when running the Rake task.
+
+== Testing
+
+Run the following command for testing:
+
+  $ rake
+
+You can also run a single test file:
+
+  $ ruby test/unit/test_cached_record.rb
+
+Please note that you have to run both a Redis server and a Memcached server locally.
+
+=== TODO
+
+* Improve cache expiration (expiration period, memoized instances, references)
+
+=== License
+
+Copyright (c) 2014 Paul Engel, released under the MIT license
+
+http://gettopup.com – http://github.com/archan937 – http://twitter.com/archan937 – {pm_engel@icloud.com}[mailto:pm_engel@icloud.com]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,90 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+task :default => :test
+
+Rake::TestTask.new do |test|
+  test.pattern = "test/**/test_*.rb"
+end
+
+task :benchmark do
+  require_relative "benchmark/setup"
+
+  def benchmark(description, count, interval)
+    Redis.new.flushdb
+    puts "Benchmarking #{description} (#{count} times)"
+    puts "-> [#{"." * 100}] 0.0% in 0.0s"
+    t = Time.now
+    count.times do |i|
+      if i % interval == (interval - 1)
+        print "\e[A\e[K"
+        percentage = (i / count.to_f) * 100
+        puts "-> [#{("+" * percentage.ceil).ljust(100, ".")}] #{"%.1f" % percentage}% in #{"%.2f" % (Time.now - t)}s"
+      end
+      yield
+    end
+  end
+
+  count = 5000
+  benchmark "uncached instances", count, 10 do
+    article = Cached::Article.find 1
+    article.author.foo
+    article.comments[0].poster.foo
+    article.comments[1].poster.foo
+  end
+  benchmark "cached instances", count, 10 do
+    article = Cached::Article.cached 1
+    article.author.foo
+    article.comments[0].poster.foo
+    article.comments[1].poster.foo
+  end
+  benchmark "memoized instances", count, 50 do
+    article = Memoized::Article.cached 1
+    article.author.foo
+    article.comments[0].poster.foo
+    article.comments[1].poster.foo
+  end
+  benchmark "retained instances", count, 50 do
+    article = Retained::Article.cached 1
+    article.author.foo
+    article.comments[0].poster.foo
+    article.comments[1].poster.foo
+  end
+
+  count = 150000
+  benchmark "memoized instances", count, 50  do Memoized::Article.cached 1 end
+  benchmark "retained instances", count, 100 do Retained::Article.cached 1 end
+
+  puts "Done."
+end
+
+namespace :db do
+  task :install do
+    require "bundler"
+    Bundler.require
+    require "yaml"
+    require "active_record"
+
+    %w(development test).each do |environment|
+      puts "Installing #{environment} database..."
+      dbconfig = YAML.load_file(File.expand_path("../config/database.yml", __FILE__))[environment]
+      host, port, user, password, database = dbconfig.values_at *%w(host port user password database)
+      options = {:charset => "utf8", :collation => "utf8_unicode_ci"}
+
+      ActiveRecord::Base.establish_connection dbconfig.merge("database" => nil)
+      ActiveRecord::Base.connection.create_database dbconfig["database"], options
+
+      `#{
+        [
+          "mysql",
+         ("-h #{host}" unless host.blank?), ("-P #{port}" unless port.blank?),
+          "-u #{user || "root"}", ("-p#{password}" unless password.blank?),
+          "#{database} < db/cached_record.sql"
+        ].compact.join(" ")
+      }`
+    end
+
+    puts "Done."
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/benchmark/setup.rb

@@ -0,0 +1,77 @@
+require "bundler"
+Bundler.require :default, :development
+
+require "active_record"
+
+dbconfig = YAML.load_file(File.expand_path("../../config/database.yml", __FILE__))["development"]
+ActiveRecord::Base.establish_connection dbconfig
+ActiveRecord::Base.time_zone_aware_attributes = true
+ActiveRecord::Base.default_timezone = :local
+
+CachedRecord.setup :redis
+
+module Cached
+  class Article < ActiveRecord::Base
+    self.table_name = "articles"
+    belongs_to :author, :class_name => "Cached::User", :foreign_key => "author_id"
+    has_many :comments, :class_name => "Cached::Comment", :foreign_key => "article_id"
+    as_cache :only => [:title], :include => [:author, :comments]
+  end
+
+  class User < ActiveRecord::Base
+    self.table_name = "users"
+    has_one :foo, :class_name => "Cached::Article", :foreign_key => "foo_id"
+    as_cache :only => [:name], :include => [:foo]
+  end
+
+  class Comment < ActiveRecord::Base
+    self.table_name = "comments"
+    belongs_to :article, :class_name => "Cached::Article", :foreign_key => "article_id"
+    belongs_to :poster, :class_name => "Cached::User", :foreign_key => "poster_id"
+    as_cache :only => [:content], :include => [:poster]
+  end
+end
+
+module Memoized
+  class Article < ActiveRecord::Base
+    self.table_name = "articles"
+    belongs_to :author, :class_name => "Memoized::User", :foreign_key => "author_id"
+    has_many :comments, :class_name => "Memoized::Comment", :foreign_key => "article_id"
+    as_memoized_cache :only => [:title], :include => [:author, :comments]
+  end
+
+  class User < ActiveRecord::Base
+    self.table_name = "users"
+    has_one :foo, :class_name => "Memoized::Article", :foreign_key => "foo_id"
+    as_memoized_cache :only => [:name], :include => [:foo]
+  end
+
+  class Comment < ActiveRecord::Base
+    self.table_name = "comments"
+    belongs_to :article, :class_name => "Memoized::Article", :foreign_key => "article_id"
+    belongs_to :poster, :class_name => "Memoized::User", :foreign_key => "poster_id"
+    as_memoized_cache :only => [:content], :include => [:poster]
+  end
+end
+
+module Retained
+  class Article < ActiveRecord::Base
+    self.table_name = "articles"
+    belongs_to :author, :class_name => "Retained::User", :foreign_key => "author_id"
+    has_many :comments, :class_name => "Retained::Comment", :foreign_key => "article_id"
+    as_memoized_cache :only => [:title], :include => [:author, :comments], :retain => 10.seconds
+  end
+
+  class User < ActiveRecord::Base
+    self.table_name = "users"
+    has_one :foo, :class_name => "Retained::Article", :foreign_key => "foo_id"
+    as_memoized_cache :only => [:name], :include => [:foo], :retain => 10.seconds
+  end
+
+  class Comment < ActiveRecord::Base
+    self.table_name = "comments"
+    belongs_to :article, :class_name => "Retained::Article", :foreign_key => "article_id"
+    belongs_to :poster, :class_name => "Retained::User", :foreign_key => "poster_id"
+    as_memoized_cache :only => [:content], :include => [:poster], :retain => 10.seconds
+  end
+end

data/cached_record.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path("../lib/cached_record/version", __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Paul Engel"]
+  gem.email         = ["pm_engel@icloud.com"]
+  gem.summary       = %q{Cache (and optionally memoize) ActiveRecord or DataMapper records in Redis or Memcached}
+  gem.description   = %q{Cache (and optionally memoize) ActiveRecord or DataMapper records in Redis or Memcached}
+  gem.homepage      = "https://github.com/archan937/cached_record"
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "cached_record"
+  gem.require_paths = ["lib"]
+  gem.version       = CachedRecord::VERSION
+
+  gem.add_dependency "dalli"
+  gem.add_dependency "redis"
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "pry"
+  gem.add_development_dependency "mysql2"
+  gem.add_development_dependency "activerecord"
+  gem.add_development_dependency "dm-mysql-adapter"
+  gem.add_development_dependency "data_mapper"
+end