cacheable 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dcf3283fac4f544317c0b3db775ef6a55686b12f
+  data.tar.gz: 9d214b09f7c242a7879343034b5a9edeedc85bee
+SHA512:
+  metadata.gz: b0065e91bae9e147ac4c134ecc7b862d576b3e4968fdf13f4360ee81a4c804608b3e0f3148164a764b2cd8d6ab0bc323ef93c412a9410ba3f6ecb015d881dbc0
+  data.tar.gz: a671db83562e5655161a7e92efc41f99ca7f597d0987e869dc64f6a3500e4c89582d4f545c648b77a4d1915b143432fec6db7a8c07b1a9bc1da0835174218099

data/README.md

@@ -0,0 +1,218 @@
+# Cacheable
+
+By [Splitwise](https://www.splitwise.com)
+
+Cacheable is a gem which intends to adds method caching in an [aspect-oriented programming (AOP)](https://en.wikipedia.org/wiki/Aspect-oriented_programming) fashion in Ruby. Its core goals are:
+
+* ease of use (method annotation)
+* flexibility (simple adaptablability for any cache backend)
+* portability (plain Ruby for use with any framework)
+
+While Rails is not a requirement, Cacheable was built inside a mature Rails app and later extracted. This first release will seemlyless work in Rails and only includes an adapter for an in-memory cache backed by a simple Hash. This may be enough for you needs but it is more likely that additional cache adapters will need to be written.
+
+See more about [Cache Adapters](cache-adapters.md).
+
+## Getting Started
+
+Add it to your Gemfile:
+
+```ruby
+gem 'cacheable'
+```
+
+Set your cache adapter
+
+```ruby
+# If you're in a Rails app place the following in config/initializers/cacheable.rb
+Cacheable.cache_adapter = Rails.cache
+
+# Otherwise you can specify the name of the adapter anywhere before you use it
+Cacheable.cache_adapter = :memory
+```
+
+### Simple Implementation Example
+
+Cacheable is designed to work seemlessly with your already existings codebase. Consider the following contrived class:
+
+```ruby
+class SimpleExample
+  def expensive_calculation
+    puts 'beginning expensive method'
+    …
+    return 'my_result'
+  end
+end
+```
+
+To cache this method and it's result, simply add the following:
+
+```ruby
+require 'cacheable' # this may not be necessary depending on your autoloading system
+
+class SimpleExample
+  include Cacheable
+
+  cacheable :expensive_calculation
+
+  def expensive_calculation
+    puts 'beginning expensive method'
+    …
+    return 'my_result'
+  end
+end
+```
+
+**Thats it!** There's some complex Ruby magic going on under the hood but to the end user you can simply call `expensive_calculation` and the result will be retreived from the cache, if available, or generated and placed into the cache. To confirm it is working, fire up an IRB console try the following:
+
+```irb
+> s = SimpleExample.new
+> s.expensive_calculation
+beginning expensive method
+ => "my_result"
+> s.expensive_calculation
+ => "my_result"
+
+# Notice that the `puts` was not output the 2nd time the method was invoked.
+```
+
+### Additional Methods
+
+Cacheable also adds two useful methods to your class.
+
+#### Skip the Cache via `#{method}_without_cache`
+
+The cache can intentionally be skipped by appending `_without_cache` to the method name. This invocation with neither check the cache nor populate it as if you called the original method and never used Cacheable.
+
+```irb
+> s = SimpleExample.new
+> s.expensive_calculation_without_cache
+beginning expensive method
+ => "my_result"
+> s.expensive_calculation_without_cache
+beginning expensive method
+ => "my_result"
+ ```
+
+#### Remove the Value via `clear_#{method}_cache`
+
+The cache can be cleared at any time by calling `clear_#{your_method_name}_cache`.
+
+```irb
+> s = SimpleExample.new
+> s.expensive_calculation
+beginning expensive method
+ => "my_result"
+> s.expensive_calculation
+ => "my_result"
+
+> s.clear_expensive_calculation_cache
+ => true
+> s.expensive_calculation
+beginning expensive method
+ => "my_result"
+```
+
+## Additional Configuration
+
+### Cache Invalidation
+
+#### Default
+
+One of the hardest things to do correctly is cache invalidation. Cacheable handles this in a variety of ways. By default Cacheable will construct key a key in the format `[cache_key || class_name, method_name]`.
+
+If the object responds to `cache_key` its return value will be the first element in the array. `ActiveRecord` provides [`cache_key`](https://api.rubyonrails.org/classes/ActiveRecord/Integration.html#method-i-cache_key) but it can be added to any Ruby object or overwritten. If the object does not respond to it, the name of the class will be used instead. The second element will be the name of the method as a symbol.
+
+It is up to the cache adapter what to do with this array. For example, Rails will turn `[SomeClass, :some_method]` into `"SomeClass/some_method"`. For more information see the documentation on [Cache Adapters](cache-adapters.md)
+
+#### Set Your Own
+
+If (re)defining `cache_key` does not provide enough flexibility you can pass a proc to the `key_format:` option of `cacheable`.
+
+```ruby
+class CustomKeyExample
+  include Cacheable
+
+  cacheable :my_method, key_format: -> (target, method_name, method_args) do
+    args = method_args.collect { |argument| "#{argument.class}::#{argument}" }.join
+    "#{method_name} called on #{target} with #{args}"
+  end
+
+  def my_method(arg1)
+    …
+  end
+end
+```
+
+* `target` is the object the method is being called on (`#<CustomKeyExample:0x0…0>`)
+* `method_name` is the name of the method being cached (`:my_method`)
+* `method_args` is an array of arguments being passed to the method (`[arg1]`)
+
+So if we called `CustomKeyExample.new.my_method(123)` we would get the cache key
+
+`"my_method called on #<CustomKeyExample:0x0…0> with Integer::123"`.
+
+### Conditional Cacheing
+
+You can control if a method should be cached by supplying a proc to the `unless:` option which will get the same arguments as `key_format:`. Alternatively this method can be defined on the class and a symbol of the name of the method can be passed. **Note**: When using a symbol, the first argument will not be passed but will be available in the method as `self`. The following example will not cache the value if the first argument to the method is `false`.
+
+
+```ruby
+class ConditionalCachingExample
+  include Cacheable
+
+  cacheable :maybe_cache, unless: :should_not_cache?
+
+  def maybe_cache(cache)
+    …
+  end
+
+  def should_not_cache?(_method_name, method_args)
+    method_args.first == false
+  end
+end
+```
+
+### Cache Options
+
+If your cache backend supports options you can pass them as the `cache_options:` option. This will be passed though untouched to the cache's `fetch` method.
+
+```ruby
+cacheable :with_options, cache_options: {expires_in: 3_600}
+```
+
+### Flexible Options
+
+You can use the same options with multiple cache methods or limit them only to specific methods:
+
+```
+cacheable :these, :methods, :share, :options, key_format: key_proc, unless: unless_proc
+cacheable :this_method_has_its_own_options, unless: unless_proc2
+```
+
+### Class Method Cacheing
+
+You can cache class methods just as easily as a Ruby class is just an instance of `Class`. You simply need to `include Cacheable` within the `class << self` block. Methods can be defined in this block or outside using the `def self.` syntax.
+
+```ruby
+class StaticMethodExample
+  class << self
+    include Cacheable
+
+    cacheable :class_method, :self_class_method
+
+    def class_method
+      puts 'class_method called'
+    end
+  end
+
+  def self.self_class_method
+    puts 'self_class_method called'
+  end
+end
+```
+
+### Contributors (alphabetical by last name)
+
+* [Jess Hottenstein](https://github.com/jhottenstein)
+* [Ryan Laughlin](https://github.com/rofreg)
+* [Aaron Rosenberg](https://github.com/agrberg)

data/cache-adapters.md

@@ -0,0 +1,28 @@
+# Cache Adapters
+
+A cache adapter is an object that Cacheable can use as an interface to your system's cache. Cacheable will work out of the box using the object returned by `Rails.cache` as a cache adapter.
+
+The other adapter provided with the library is the [Memory Adapter](lib/cacheable/cache_adapters/memory_adapter.rb). Is a simple memoizing cache used in testing. It is little more than an object that conforms to the protocol and is backed by a Ruby Hash. When writting a new cache adapter it can be used as a template.
+
+### Protocol
+
+There are only two methods the cache adapter protocol requires.
+
+#### `fetch(key, cache_options) { block }`
+
+`fetch` takes a key and options for the cache implementation. If the key is found in the cache the associated value will be returned. If it is not found, the block will be run and the result of the block will be returned and placed in the cache.
+
+**Note**: Unless manually defined by [setting your own key format proc](README.md#set-your-own), `key` will be an *Array*. It is the cache adapter's responsibility to turn this into whatever value your cache backend requires for keys.
+
+#### `delete(key)`
+
+`delete` takes a key and removes it's associated value in the cache. While not currently dependend on by Cacheable, it appears the standard is to return `true` if the value was present and removed and `false` if not present to begin with.
+
+#### Additional useful methods
+
+These are additional methods that are very useful to have on a cache adapter but are not depended on by Cacheable. They can be found in the Memory Adapter but they are only used to aid in testing.
+
+* **`read(key)`** read the value for the given key out of the cache or `nil` if the key is not present
+* **`write(key, value)`** write a value to the cache under the key
+* **`exist?(key)`** `true` if the key exists in the cache, `false` otherwise
+* **`clear`** reset the entire cache

data/lib/cacheable.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+#--
+# Copyright (c) 2017-2018 Splitwise Inc.
+#
+# 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.
+#++
+
+require 'cacheable/cache_adapter'
+require 'cacheable/cache_adapters'
+require 'cacheable/method_generator'
+require 'cacheable/version'
+
+module Cacheable
+  extend CacheAdapter
+
+  def self.included(base)
+    base.extend(Cacheable::MethodGenerator)
+
+    interceptor_name = base.send(:method_interceptor_module_name)
+    remove_const(interceptor_name) if const_defined?(interceptor_name)
+
+    base.prepend const_set(interceptor_name, Module.new)
+  end
+end

data/lib/cacheable/cache_adapter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Cacheable
+  module CacheAdapter
+    CACHE_ADAPTER_METHODS = %i[fetch delete].freeze
+    DEFAULT_ADAPTER = :memory
+
+    def self.extended(base)
+      base.instance_variable_set(:@_cache_adapter, nil)
+      base.cache_adapter = DEFAULT_ADAPTER
+    end
+
+    def cache_adapter
+      @_cache_adapter
+    end
+
+    def cache_adapter=(name_or_adapter)
+      @_cache_adapter = interprete_adapter(name_or_adapter)
+    end
+
+    private
+
+    def interprete_adapter(name_or_adapter)
+      return name_or_adapter if cache_adapter?(name_or_adapter)
+
+      unless [Symbol, String].include?(name_or_adapter.class)
+        raise ArgumentError, 'Must pass the name of a known adapter or an instance'
+      end
+
+      Cacheable::CacheAdapters.lookup(name_or_adapter).new
+    end
+
+    def cache_adapter?(adapter_instance)
+      CACHE_ADAPTER_METHODS.all? { |method| adapter_instance.respond_to?(method) }
+    end
+  end
+end

data/lib/cacheable/cache_adapters.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'cacheable/cache_adapters/memory_adapter'
+
+module Cacheable
+  module CacheAdapters
+    ADAPTER = 'Adapter'
+
+    class << self
+      def lookup(adapter_name)
+        const_get(class_name_for(adapter_name.to_s) + ADAPTER)
+      end
+
+      private
+
+      def class_name_for(string)
+        string.split('_').map { |name_part| "#{name_part[0].upcase}#{name_part[1..-1].downcase}" }.join
+      end
+    end
+  end
+end

data/lib/cacheable/cache_adapters/memory_adapter.rb

@@ -0,0 +1,42 @@
+module Cacheable
+  module CacheAdapters
+    class MemoryAdapter
+      def initialize
+        clear
+      end
+
+      def read(key)
+        cache[key]
+      end
+
+      def write(key, value)
+        cache[key] = value
+      end
+
+      def exist?(key)
+        cache.key?(key)
+      end
+
+      def fetch(key, _options = {})
+        return read(key) if exist?(key)
+
+        write(key, Proc.new.call)
+      end
+
+      def delete(key)
+        return false unless exist?(key)
+
+        cache.delete key
+        true
+      end
+
+      def clear
+        @cache = {}
+      end
+
+      private
+
+      attr_reader :cache
+    end
+  end
+end

data/lib/cacheable/method_generator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+require 'english'
+
+module Cacheable
+  module MethodGenerator
+    def cacheable(*original_method_names, **opts)
+      original_method_names.each do |original_method_name|
+        create_cacheable_methods(original_method_name, opts)
+      end
+    end
+
+    private
+
+    def method_interceptor_module_name
+      class_name = name || to_s.gsub(/[^a-zA-Z_0-9]/, '')
+      "#{class_name}Cacher"
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def create_cacheable_methods(original_method_name, opts = {})
+      method_names = create_method_names(original_method_name)
+      key_format_proc = opts[:key_format] || default_key_format
+
+      const_get(method_interceptor_module_name).class_eval do
+        define_method(method_names[:key_format_method_name]) do |*args|
+          key_format_proc.call(self, original_method_name, args)
+        end
+
+        define_method(method_names[:clear_cache_method_name]) do |*args|
+          Cacheable.cache_adapter.delete(__send__(method_names[:key_format_method_name], *args))
+        end
+
+        define_method(method_names[:without_cache_method_name]) do |*args|
+          original_method = method(original_method_name).super_method
+          original_method.call(*args)
+        end
+
+        define_method(method_names[:with_cache_method_name]) do |*args|
+          Cacheable.cache_adapter.fetch(__send__(method_names[:key_format_method_name], *args), opts[:cache_options]) do
+            __send__(method_names[:without_cache_method_name], *args)
+          end
+        end
+
+        define_method(original_method_name) do |*args|
+          unless_proc = opts[:unless].is_a?(Symbol) ? opts[:unless].to_proc : opts[:unless]
+
+          if unless_proc&.call(self, original_method_name, args)
+            __send__(method_names[:without_cache_method_name], *args)
+          else
+            __send__(method_names[:with_cache_method_name], *args)
+          end
+        end
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    def default_key_format
+      proc do |target, method_name, _method_args|
+        # By default, we omit the _method_args from the cache key because there is no acceptable default behavior
+        class_name = (target.is_a?(Module) ? target.name : target.class.name)
+        cache_key = target.respond_to?(:cache_key) ? target.cache_key : class_name
+        [cache_key, method_name].compact
+      end
+    end
+
+    def create_method_names(original_method_name)
+      method_name_without_punctuation = original_method_name.to_s.sub(/([?!=])$/, '')
+      punctuation = $LAST_PAREN_MATCH
+
+      {
+        with_cache_method_name: "#{method_name_without_punctuation}_with_cache#{punctuation}",
+        without_cache_method_name: "#{method_name_without_punctuation}_without_cache#{punctuation}",
+        key_format_method_name: "#{method_name_without_punctuation}_key_format#{punctuation}",
+        clear_cache_method_name: "clear_#{method_name_without_punctuation}_cache#{punctuation}"
+      }
+    end
+  end
+end

data/lib/cacheable/version.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Cacheable
+  module VERSION
+    MAJOR = 1
+    MINOR = 0
+    TINY = 2
+    PRE = nil
+
+    STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.').freeze
+
+    def self.to_s
+      STRING
+    end
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: cacheable
+version: !ruby/object:Gem::Version
+  version: 1.0.2
+platform: ruby
+authors:
+- Jess Hottenstein
+- Ryan Laughlin
+- Aaron Rosenberg
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-07-31 00:00:00.000000000 Z
+dependencies: []
+description: Add caching simply without modifying your existing code. Inlcudes configurable
+  options for simple cache invalidation. See README on github for more information.
+email: support@splitwise.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- cache-adapters.md
+- lib/cacheable.rb
+- lib/cacheable/cache_adapter.rb
+- lib/cacheable/cache_adapters.rb
+- lib/cacheable/cache_adapters/memory_adapter.rb
+- lib/cacheable/method_generator.rb
+- lib/cacheable/version.rb
+homepage: https://github.com/splitwise/cacheable
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.13
+signing_key: 
+specification_version: 4
+summary: Add caching to any Ruby method in a aspect orientated programming approach.
+test_files: []
+has_rdoc: