cachable 0.5.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 70e62e1e63223309b99070e0b8d17707a93e2a1e
+  data.tar.gz: a43bad698ed24dfe8a86b26d5ba4120cdd8f93ea
+SHA512:
+  metadata.gz: 299c3e2bd420d884196ed55883a9e2d6b4c745df9fdf90d4bfca1c24ad14b728920ae2c427f49f861087fc9bee421d3579eda032d0ca082b1840a0c7d34c07b7
+  data.tar.gz: 789bf412bf8b7d4a4a0cddd74fc235febebd29045b05f033a846c854aa5e465f5a30760ea53eada73d6ec116e3193fbb612cf2f25e66e534a8d52b1b3d4652eb

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2017 Kai Marshland
+
+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.md

@@ -0,0 +1,190 @@
+# Cachable
+Caching is often a bother. This gem allows you to simply wrap your code in a block and have it be cached with redis.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'cachable'
+```
+
+You must also add redis to your app. On heroku, you can add [Heroku Redis](https://elements.heroku.com/addons/heroku-redis).
+
+## Usage
+At its hearty, this gem is the `unless_cached` method. 
+Although no options are required, it accepts the following:
+ - key. If present, will be added to the base key to generate the full key. Defaults to the name of the caller.
+ - json. If true, will serialize and deserialize the result as json
+ - expiration Time for which to cache the result. Defaults to 1 day
+ - json_options. Options that get passed into json serialization and deserialization
+ - skip_cache. If true, will not populate the cache -- this can be used if you populate the cache elsewhere, but still want to check if there's something there. 
+
+### Examples
+In your model:
+
+```ruby
+include Cachable
+
+def your_method
+  unless_cached do 
+    # ... output of this will be cached under the key model_name_id_updated_at_your_method 
+  end
+end
+```
+
+Of course, `unless_cached` accepts a variety of options:
+```ruby
+# opts[:key]. If present, will be added to the base key to generate the full key. Defaults to the name of the caller.
+unless_cached(key: 'some_key') do
+  # will be stored under the key model_name_id_some_key
+end
+
+
+# opts[:json]. If true, will serialize and deserialize the result as json
+unless_cached(json: true) do
+  {
+    json: 'object'
+  }
+end
+
+# opts[:expiration]. Time for which to cache the result. Defaults to 1 day
+unless_cached(expiration: 30.minutes) do
+  # result will expire in half an hour
+end
+
+
+# opts[:json_options]. Options that get passed into json serialization and deserialization
+unless_cached(json: true, json_options: {allow_nan: true}) do
+  {
+    value: Float::NAN
+  }
+end
+```
+
+## Other features
+
+### Configuring the redis connection
+It defaults to checking the `REDIS_URL` and the `HEROKU_REDIS_URL` environment variables to make a connection to redis. 
+However, you may wish to change the way you connect to redis. Create an initializer in `config/initializers/cachable.rb`. 
+```ruby
+Cachable::configure do |config|
+  
+  # set a lambda to get a redis connection
+  config.redis_connection = -> {
+    Redis.new
+  }
+  
+  # set the redis instance directly
+  config.redis_instance = Redis.new
+  
+  # or set the redis url
+  config.redis_url = 'YOUR REDIS URL'
+  
+end
+```
+
+### Deleting from the cache
+Sometimes you want to delete something from the cache. 
+This can be done using the `delete_from_cache` method, which takes in one or more keys. 
+These keys are either the 
+```ruby
+delete_from_cache(:key1, :key2)
+```
+
+A special use case is after the changes have been committed. 
+For this, you can use the special `purge_cache` callback. 
+You must define the `tracked_cache_keys` method for this to work properly. 
+The following example will clear the cache for `cached_a` and `cached_b`, but not `cached_c`.
+```ruby
+# in your model
+after_commit :purge_cache
+
+def tracked_cache_keys
+  [:cached_a, :cached_b]
+end
+
+def cached_a
+  unless_cached do 
+    # ...
+  end
+end
+
+def cached_b
+  unless_cached do 
+    # ...
+  end
+end
+
+def cached_c
+  unless_cached do 
+    # ...
+  end
+end
+```
+
+If you want to use the `delete_from_cache` method directly in an `after_commit` callback, you must specify that in the options.
+```ruby
+delete_from_cache(:key1, :key2, after_commit: true)
+```
+
+### Batch requests to the cache
+Oftentimes, you want the output of a given method on an ActiveRecordCollection. 
+You could loop through each record in the collection, but if you expect the method to be cached, 
+it's much more efficient this gem's method, and avoid the memory overhead and extra database calls. 
+
+Imagine you have a model that looks as follows: 
+```ruby
+class Book < ActiveRecord::Base
+  include Cachable
+  
+  def summary
+    unless_cached do
+      'Some summary'
+    end
+  end
+end
+```
+To get the summaries of all fantasy books, you could run `Book.where(genre: 'fantasy').unless_cached(:summary)`.
+
+Note that this will remove any ordering on the collection unless you set the slurp option to true or include `EachInOrder` in your model (this gem has not yet been released -- create an issue if you need me to release it). A full list of options is as follows:
+ - slurp. If true will not pull the records in in batches, which increases memory overhead but preserves order.
+ - force_cache. If true will add its own cache, regardless of what the underlying function does. 
+ - cache_batches. If true will add another layer of caching outside each individual model. This caches a the result of up to 50 records at a time, which can drastically speed up the cache but will also increase the cache size. 
+ - skip_result. If true will not return the result, but it will still prepopulate the cache, which can avoid memory overhead.
+ - clear_previous_batch. If true, and was also true previous times, it will remove the cached batches for the previous batch. This can be very useful when you are frequently adding more records and want to keep the redis memory usage down. Note that this was designed to have minimal overhead, and so was based on the total number of records, which may cause a small number of stale keys to stay in memory.  
+ - You can also pass in all normal unless_cached options, such as expiration, json, and json_options.  
+
+
+### Adding an additional redis key
+Sometimes your cache depends on more than just the model. 
+For example, imagine you have a model book that `belongs_to` an author. 
+When the author is updated, you want the cache to become invalidated.
+In your book model, you might have something like this:
+```ruby
+def added_redis_key
+  self.author.updated_at.to_i
+end
+
+def self.added_redis_key
+  first = all.first
+  return '' if first.blank?
+
+  first.author.updated_at.to_i
+end
+
+```
+
+### Using the cache outside of a specific instance
+Sometimes you need to cache something in a static (class) method. It accepts the following options:
+- json. If true, will serialize and deserialize the result as json
+- expiration Time for which to cache the result. Defaults to 1 day
+- json_options. Options that get passed into json serialization and deserialization
+- skip_cache. If true, will not populate the cache -- this can be used if you populate the cache elsewhere, but still want to check if there's something there. 
+```ruby
+self.class.unless_cached_base("#{self.class.to_s.downcase}_key", json: true, expiration: 1.day) do
+ # this output will be cached under the key your_model_name_key
+end
+```
+
+## License
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Cachable'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/lib/cachable.rb

@@ -0,0 +1,165 @@
+require 'cachable/configuration'
+
+module Cachable
+
+  extend ActiveSupport::Concern
+
+  included do
+
+    after_commit :purge_cache #try to purge the cache after anything changes
+
+    #Generates the basic redis key from id, updated_at, and whatever else we want
+    def base_redis_key(opts={})
+      added = ''
+      added = "_#{self.added_redis_key}" if self.respond_to? :added_redis_key
+
+      on_previous_changes = opts[:after_commit] && self.previous_changes['updated_at']
+      updated_at = on_previous_changes ? self.previous_changes['updated_at'].first : self.updated_at
+
+      "#{self.class.to_s.downcase}_#{self.id}_#{updated_at.to_i}#{added}"
+    end
+
+    #Clears the given keys from redis
+    def delete_from_cache(*keys, **opts)
+      base_key = self.base_redis_key opts
+      keys.each do |key|
+        Cachable::redis.del "#{base_key}_#{key}"
+      end
+    end
+
+    # Purges the cache for this record, if the client has defined the purge_cache method
+    def purge_cache
+      return unless self.respond_to? :tracked_cache_keys
+
+      self.delete_from_cache(*self.tracked_cache_keys, after_commit: true)
+    end
+
+    # If the is present in the cache, returns that; otherwise generates and caches the result
+    # opts[:key]. If present, will be added to the base key to generate the full key. Defaults to the name of the caller.
+    # opts[:json]. If true, will serialize and deserialize the result as json
+    # opts[:expiration]. Time for which to cache the result. Defaults to 1 day
+    # opts[:json_options]. Options that get passed into json serialization and deserialization
+    def unless_cached(opts={})
+      partial_key = opts[:key].present? ? opts[:key] : caller.first.match(/`[^']*/).to_s[1..-1]
+      key = "#{self.base_redis_key}_#{partial_key}"
+
+      self.class.unless_cached_base(key, opts) do
+        yield
+      end
+    end
+
+    # Calls unless cached on all records passed
+    # action
+    # opts[:slurp]. If true will not pull the records in in batches, which increases memory overhead but preserves order.
+    # opts[:force_cache]. If true will add its own cache, regardless of what the underlying function does
+    # opts[:cache_batches]. If true will add another layer of caching outside
+    # opts[:skip_result]. If true will not generate (useful for prepopulating the cache with lower overhead)
+    # opts[clear_previous_batch] If true, and was also true previous times, it will remove the cached batches for the previous batch. This can be very useful when you are frequently adding more records and want to keep the redis memory usage down.
+    # Can also pass in all normal unless_cached options
+    def self.unless_cached(action, opts={})
+      result = []
+
+      iterator = all.find_in_batches
+      iterator = all.each_in_order_in_batches if self.respond_to? :each_in_order_in_batches
+      iterator = all.each if opts[:slurp]
+
+      partial_key = opts[:key].present? ? opts[:key] : action
+      added_key = ''
+      added_key = "_#{self.added_redis_key}" if self.respond_to? :added_redis_key
+
+      batch_key_list = []
+      record_count = 0
+
+      opts[:skip_cache] = !opts[:force_cache]
+
+      iterator.each do |batch|
+        factors = batch.pluck(:id, :updated_at)
+        record_count += factors.length if opts[:clear_previous_batch]
+
+        if opts[:cache_batches]
+          batch_key = "#{self.to_s.downcase}_#{factors.flatten.join(',')}#{added_key}_#{partial_key}"
+          batch_key_list << batch_key if opts[:clear_previous_batch]
+
+          existing_result = Cachable::redis.get batch_key
+          if existing_result.present?
+            result.concat JSON(existing_result)
+            next
+          end
+        end
+
+        batch_result = factors.map do |id, updated_at|
+          key = "#{self.to_s.downcase}_#{id}_#{updated_at.to_i}#{added_key}_#{partial_key}"
+
+          self.unless_cached_base(key, opts) do
+            record = self.unscope(:order, :where, :offset).find id
+
+            block_given? ? (yield record) : record.send(action) if record.present?
+          end
+        end
+
+        result.concat batch_result unless opts[:skip_result]
+
+        if opts[:cache_batches]
+          Cachable::redis.set batch_key, JSON(batch_result)
+          expiration = opts[:expiration]
+          expiration = 15.minutes unless expiration.present?
+          Cachable::redis.expire batch_key, expiration unless expiration === false
+        end
+      end
+
+      if opts[:clear_previous_batch]
+
+        # store the keys for the current batch list
+        expiration = opts[:expiration]
+        expiration = 15.minutes unless expiration.present?
+
+        gen_key -> n {
+          "#{self.to_s.downcase}_keys_#{n}_#{added_key}_#{partial_key}"
+        }
+        batch_key = gen_key[record_count]
+
+        Cachable::redis.set(batch_key, JSON(batch_key_list))
+        Cachable::redis.expire(batch_key, expiration)
+
+        # delete the keys from the previous batch list
+        Cachable::redis.del(gen_key[record_count - 1])
+        Cachable::redis.del(gen_key[record_count + 1])
+      end
+
+      result
+    end
+
+    # Core implementation of unless cached.
+    # As well as options from above:
+    # opts[:skip_cache]. If true, will not populate the cache
+    def self.unless_cached_base(key, opts={})
+      opts[:json] = true if opts[:json].nil?
+
+      cached = Cachable::redis.get(key)
+      if cached.present?
+        cached = JSON.parse(cached, opts[:json_options]) if opts[:json]
+
+        return cached
+      end
+
+      result = yield
+
+      unless opts[:skip_cache]
+        if opts[:json]
+          Cachable::redis.set(key, JSON.generate(result, opts[:json_options]))
+        else
+          Cachable::redis.set(key, result)
+        end
+
+        expiration = opts[:expiration]
+        expiration = 1.day unless expiration.present?
+        Cachable::redis.expire(key, expiration) unless expiration === false
+      end
+
+      result
+
+    end
+
+  end
+
+end

data/lib/cachable/configuration.rb

@@ -0,0 +1,31 @@
+
+module Cachable
+  class Configuration
+    attr_accessor :redis_connection, :redis_instance, :redis_url
+
+    def redis
+      return @redis_connection.call if @redis_connection.present?
+      return @redis_instance if @redis_instance.present?
+
+
+      @redis_url = ENV['REDIS_URL'] || ENV['HEROKU_REDIS_URL']
+      raise 'No redis url provided' if @redis_url.blank?
+
+      uri = URI.parse(@redis_url)
+      @redis_instance = Redis.new(:host => uri.host, :port => uri.port, :password => uri.password)
+    end
+  end
+
+  def self.configuration
+    @config ||= Configuration.new
+  end
+
+  def self.configure
+    yield self.configuration
+  end
+
+  def self.redis
+    self.configuration.redis
+  end
+
+end

data/lib/cachable/version.rb

@@ -0,0 +1,3 @@
+module Cachable
+  VERSION = '0.5.3'
+end

data/lib/tasks/cachable_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :cachable do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: cachable
+version: !ruby/object:Gem::Version
+  version: 0.5.3
+platform: ruby
+authors:
+- Kai Marshland
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-03-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Easily add caching to models
+email:
+- kaimarshland@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/cachable.rb
+- lib/cachable/configuration.rb
+- lib/cachable/version.rb
+- lib/tasks/cachable_tasks.rake
+homepage: https://github.com/KMarshland/cachable
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Easily add caching to models
+test_files: []