cacheable 1.0.3 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc1692072ddcd1c2c657224d22f14b9705a36fc341753afa37ffa49d0f0baa0e
-  data.tar.gz: 27dbec107256dd9e0468635cf6121ee10c139a8424cb07d9af7ddb2abd6cc77d
+  metadata.gz: ba379f0770988ff42a99397f056206bbbb9b60a59b51a5fee51d687263adb96e
+  data.tar.gz: ef68f492cf221457515452df0324ff87d634914ac67e286a4e698c096e5a2a3e
 SHA512:
-  metadata.gz: e7b0757cd1a849bc0be1801d166676bb0856646494261251d6d9ddf5a3171f6b3e920039b53cf11afa5553f6778dc2aa31182d8d2752eb765aed841b0cc30c68
-  data.tar.gz: a9225a74404e0b0a4b1a2cb646bb6ff5e2b6fe88a002ad0060312bc688b5124f5f08f729abb811414e18dd45874d00a67037cf28c70f49570616d8437565b1c0
+  metadata.gz: 79e94e9ec720e03d2be5370ac8554c2c1635589b5cfffec5a56f27fe228944e659da1e5aa52b94836559fc06301a6f1e41d0df418c7305db925a175754ce73d8
+  data.tar.gz: e56db78b1855a5cb4bcba7b1f408d4c4cff9cbef03f05641596e721c0b332bfc7878769632ef2eda6e6d2476505bdaf38b477fa32abc6513170b88806d21209b

data/README.md

@@ -2,13 +2,13 @@
 
 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:
+Cacheable is a gem which adds method caching in Ruby following an [aspect-oriented programming (AOP)](https://en.wikipedia.org/wiki/Aspect-oriented_programming) paradigm. Its core goals are:
 
 * ease of use (method annotation)
-* flexibility (simple adaptablability for any cache backend)
+* flexibility (simple adaptability 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.
+While using Ruby on Rails is not a requirement, Cacheable was built inside a mature Rails app and later extracted. The current release is designed for drop-in support in Rails, and includes an adapter for an in-memory cache backed by a simple hash. This may be enough for your needs, but it's more likely that additional cache adapters will need to be written for other projects.
 
 See more about [Cache Adapters](cache-adapters.md).
 
@@ -32,47 +32,58 @@ Cacheable.cache_adapter = :memory
 
 ### Simple Implementation Example
 
-Cacheable is designed to work seemlessly with your already existings codebase. Consider the following contrived class:
+Cacheable is designed to work seamlessly with your already existing codebase. Consider the following example where we fetch the star count for Cacheable from GitHub's API. Feel free to copy/paste it into your IRB console or use the code in `examples/simple_example.rb`.
 
 ```ruby
-class SimpleExample
-  def expensive_calculation
-    puts 'beginning expensive method'
-    …
-    return 'my_result'
+require 'json'
+require 'net/http'
+
+class GitHubApiAdapter
+  def star_count
+    puts 'Fetching data from GitHub'
+    url = 'https://api.github.com/repos/splitwise/cacheable'
+
+    JSON.parse(Net::HTTP.get(URI.parse(url)))['stargazers_count']
   end
 end
 ```
 
-To cache this method and it's result, simply add the following:
+To cache this method and its result, simply add the following:
 
 ```ruby
+# From examples/simple_example.rb
+
 require 'cacheable' # this may not be necessary depending on your autoloading system
+require 'json'
+require 'net/http'
 
-class SimpleExample
+class GitHubApiAdapter
   include Cacheable
 
-  cacheable :expensive_calculation
+  cacheable :star_count
+
+  def star_count
+    puts 'Fetching data from GitHub'
+    url = 'https://api.github.com/repos/splitwise/cacheable'
 
-  def expensive_calculation
-    puts 'beginning expensive method'
-    …
-    return 'my_result'
+
+    JSON.parse(Net::HTTP.get(URI.parse(url)))['stargazers_count']
   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:
+**That's it!** There's some complex Ruby magic going on under the hood but to the end user you can simply call `star_count` and the result will be retrieved from the cache, if available, or fetched from the network 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.
+> a = GitHubApiAdapter.new
+> a.star_count
+Fetching data from GitHub
+ => 19
+> a.star_count
+ => 19
+
+# Notice that "Fetching data from GitHub" was not output the 2nd time the method was invoked.
+# The network call and result parsing would also not be performed again.
 ```
 
 ### Additional Methods
@@ -81,44 +92,46 @@ 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.
+The cache can intentionally be skipped by appending `_without_cache` to the method name. This invocation will neither check the cache nor populate it.  It is 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"
- ```
+> a = GitHubApiAdapter.new
+> a.star_count
+Fetching data from GitHub
+ => 19
+> a.star_count_without_cache
+Fetching data from GitHub
+ => 19
+> a.star_count
+ => 19
+```
 
 #### Remove the Value via `clear_#{method}_cache`
 
-The cache can be cleared at any time by calling `clear_#{your_method_name}_cache`.
+The cached value 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
+> a = GitHubApiAdapter.new
+> a.star_count
+Fetching data from GitHub
+ => 19
+> a.star_count
+ => 19
+
+> a.clear_star_count_cache
  => true
-> s.expensive_calculation
-beginning expensive method
- => "my_result"
+> a.star_count
+Fetching data from GitHub
+ => 19
 ```
 
 ## Additional Configuration
 
-### Cache Invalidation
+### Cache Keys
 
 #### 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]`.
+By default, Cacheable will construct key a key in the format `[cache_key || class_name, method_name]` without using method arguments.
 
 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.
 
@@ -126,55 +139,109 @@ It is up to the cache adapter what to do with this array. For example, Rails wil
 
 #### 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`.
+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
+# From examples/custom_key_example.rb
+
+require 'cacheable'
+require 'json'
+require 'net/http'
+
+class GitHubApiAdapter
   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}"
+  cacheable :star_count, key_format: ->(target, method_name, method_args) do
+    [target.class, method_name, method_args.first, Time.now.strftime('%Y-%m-%d')].join('/')
   end
 
-  def my_method(arg1)
-    …
+  def star_count(repo)
+    puts "Fetching data from GitHub for #{repo}"
+    url = "https://api.github.com/repos/splitwise/#{repo}"
+
+    JSON.parse(Net::HTTP.get(URI.parse(url)))['stargazers_count']
   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]`)
+* `target` is the object the method is being called on (`#<GitHubApiAdapter:0x0…0>`)
+* `method_name` is the name of the method being cached (`:star_count`)
+* `method_args` is an array of arguments being passed to the method (`[params]`)
 
-So if we called `CustomKeyExample.new.my_method(123)` we would get the cache key
+Including the method argument(s) allows you to cache different calls to the same method. Without the arguments in the cache key, a call to `star_count('cacheable')` would populate the cache and `star_count('tokenautocomplete')` would return the number of stars for Cacheable instead of what you want.
 
-`"my_method called on #<CustomKeyExample:0x0…0> with Integer::123"`.
+In addition, we're including the current date in the cache key so calling this method tomorrow will return an updated value.
 
-### Conditional Cacheing
+```irb
+> a = GitHubApiAdapter.new
+> a.star_count('cacheable')
+Fetching data from GitHub for cacheable
+ => 19
+> a.star_count('cacheable')
+ => 19
+> a.star_count('tokenautocomplete')
+Fetching data from GitHub for tokenautocomplete
+ => 1164
+> a.star_count('tokenautocomplete')
+ => 1164
+
+ # In this example the follow cache keys are generated:
+ # GitHubApiAdapter/star_count/cacheable/2018-09-21
+ # GitHubApiAdapter/star_count/tokenautocomplete/2018-09-21
+```
 
-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`.
+### Conditional Caching
 
+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:`. This logic can be defined in a method on the class and the name of the method as a symbol can be passed as well. **Note**: When using a symbol, the first argument, `target`, will not be passed but will be available as `self`.
 
 ```ruby
-class ConditionalCachingExample
+# From examples/conditional_example.rb
+
+require 'cacheable'
+require 'json'
+require 'net/http'
+
+class GitHubApiAdapter
   include Cacheable
 
-  cacheable :maybe_cache, unless: :should_not_cache?
+  cacheable :star_count, unless: :growing_fast?, key_format: ->(target, method_name, method_args) do
+    [target.class, method_name, method_args.first].join('/')
+  end
+
+  def star_count(repo)
+    puts "Fetching data from GitHub for #{repo}"
+    url = "https://api.github.com/repos/splitwise/#{repo}"
 
-  def maybe_cache(cache)
-    …
+    JSON.parse(Net::HTTP.get(URI.parse(url)))['stargazers_count']
   end
 
-  def should_not_cache?(_method_name, method_args)
-    method_args.first == false
+  def growing_fast?(_method_name, method_args)
+    method_args.first == 'cacheable'
   end
 end
 ```
 
+Cacheable is new so we don't want to cache the number of stars it has as we expect it to change quickly.
+
+```irb
+> a = GitHubApiAdapter.new
+> a.star_count('tokenautocomplete')
+Fetching data from GitHub for tokenautocomplete
+ => 1164
+a.star_count('tokenautocomplete')
+ => 1164
+
+> a.star_count('cacheable')
+Fetching data from GitHub for cacheable
+ => 19
+> a.star_count('cacheable')
+Fetching data from GitHub for cacheable
+ => 19
+```
+
 ### 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.
+If your cache backend supports options, you can pass them as the `cache_options:` option. This will be passed through untouched to the cache's `fetch` method.
 
 ```ruby
 cacheable :with_options, cache_options: {expires_in: 3_600}
@@ -189,28 +256,64 @@ cacheable :these, :methods, :share, :options, key_format: key_proc, unless: unle
 cacheable :this_method_has_its_own_options, unless: unless_proc2
 ```
 
-### Class Method Cacheing
+### Class Method Caching
 
-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.
+You can cache static (class) methods as well by including Cacheable in your class' [eigenclass](https://en.wikipedia.org/wiki/Metaclass#In_Ruby). This is because all Ruby classes are instances of the `Class` class. Understanding how Ruby's class structure works is powerful and useful, however, further explanation is beyond the scope of this README and not necessary to proceed.
+
+Simply put `include Cacheable` and the `cacheable` directive within a `class << self` block as in the example below. The methods you want to cache can be defined in this block or outside using the `def self.#{method_name}` syntax.
 
 ```ruby
-class StaticMethodExample
+# From examples/class_method_example.rb
+
+require 'cacheable'
+require 'json'
+require 'net/http'
+
+class GitHubApiAdapter
   class << self
     include Cacheable
 
-    cacheable :class_method, :self_class_method
+    cacheable :star_count_for_cacheable, :star_count_for_tokenautocomplete
+
+    def star_count_for_cacheable
+      star_count('cacheable')
+    end
+
+    private
 
-    def class_method
-      puts 'class_method called'
+    def star_count(repo)
+      puts "Fetching data from GitHub for #{repo}"
+      url = "https://api.github.com/repos/splitwise/#{repo}"
+
+      JSON.parse(Net::HTTP.get(URI.parse(url)))['stargazers_count']
     end
   end
 
-  def self.self_class_method
-    puts 'self_class_method called'
+  def self.star_count_for_tokenautocomplete
+    star_count('tokenautocomplete')
   end
 end
 ```
 
+```irb
+> GitHubApiAdapter.star_count_for_cacheable
+Fetching data from GitHub for cacheable
+ => 19
+> GitHubApiAdapter.star_count_for_cacheable
+ => 19
+
+> GitHubApiAdapter.star_count_for_tokenautocomplete
+Fetching data from GitHub for tokenautocomplete
+ => 1164
+> GitHubApiAdapter.star_count_for_tokenautocomplete
+ => 1164
+```
+
+### Other Notes / Frequently Asked Questions
+
+- Q: How does Cacheable handle cache invalidation?
+- A: Cacheable takes Rails' cue and sidesteps the difficult problem of cache invalidation in favor of [key-based expiration](https://signalvnoise.com/posts/3113-how-key-based-cache-expiration-works). As DHH mentions in the blog post, `ActiveRecord`'s `cache_key` uses the `updated_at` timestamp so the cache is recalculated as the object changes. This results in new cache values being calculated, and your cache implementation can be configured to expire least recently used (LRU) values. In other applications, care must be taken to include a mechanism of key-based expiration in the `cache_key` method or [`key_format` proc](#set-your-own) or you risk serving stale data. Alternatively the generated [cache clearing](#remove-the-value-via-clear_method_cache) method can be used to explicitly invalidate the cache.
+
 ### Contributors (alphabetical by last name)
 
 * [Jess Hottenstein](https://github.com/jhottenstein)

data/cache-adapters.md

@@ -2,7 +2,7 @@
 
 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.
+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 writing a new cache adapter it can be used as a template.
 
 ### Protocol
 
@@ -16,7 +16,7 @@ There are only two methods the cache adapter protocol requires.
 
 #### `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.
+`delete` takes a key and removes it's associated value in the cache. While not currently depended 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
 

data/lib/cacheable/cache_adapter.rb

@@ -15,12 +15,12 @@ module Cacheable
     end
 
     def cache_adapter=(name_or_adapter)
-      @_cache_adapter = interprete_adapter(name_or_adapter)
+      @_cache_adapter = interpret_adapter(name_or_adapter)
     end
 
     private
 
-    def interprete_adapter(name_or_adapter)
+    def interpret_adapter(name_or_adapter)
       return name_or_adapter if cache_adapter?(name_or_adapter)
 
       unless [Symbol, String].include?(name_or_adapter.class)

data/lib/cacheable/method_generator.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require 'English'
 
 module Cacheable
@@ -12,7 +13,7 @@ module Cacheable
     private
 
     def method_interceptor_module_name
-      class_name = name || to_s.gsub(/[^a-zA-Z_0-9]/, '')
+      class_name = name&.gsub(/:/, '') || to_s.gsub(/[^a-zA-Z_0-9]/, '')
       "#{class_name}Cacher"
     end
 

data/lib/cacheable/version.rb

@@ -4,7 +4,7 @@ module Cacheable
   module VERSION
     MAJOR = 1
     MINOR = 0
-    TINY = 3
+    TINY = 4
     PRE = nil
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.').freeze

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cacheable
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.4
 platform: ruby
 authors:
 - Jess Hottenstein
@@ -12,7 +12,7 @@ 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
+description: Add caching simply without modifying your existing code. Includes configurable
   options for simple cache invalidation. See README on github for more information.
 email: support@splitwise.com
 executables: []
@@ -39,7 +39,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.0.0
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -47,7 +47,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 2.7.8
 signing_key: 
 specification_version: 4
 summary: Add caching to any Ruby method in a aspect orientated programming approach.