any_cache 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b5cb4e91050841afb6fb75ae7cdf793a209291e28521a07467c3172ca6327b7
-  data.tar.gz: 127050e1c3e23797c9ea49c418818ecb54dc34c2c882cf3a20ea095bfe5a852b
+  metadata.gz: fb955a7841f5f154dd3a18dcc911333edcf3f9ccc7564c84a8165022cb64e201
+  data.tar.gz: 85ff1e78b433f11a8b870c49fd012b984491873923be153abf6117c57b757a49
 SHA512:
-  metadata.gz: dac1643ccf2b3ade6a75c5c7f55c37b69bd41ac8b057c43cb581a58bd2eb3f82e0e5d66562a66f8545a4ec1289f004f5bb3bc589861f6b9c980b297dc41bc58c
-  data.tar.gz: 83ec5094b541f79268691ea95e8daeaa01a6d296fbe7e1728289cf7e96ba03536787a3af137350a88194f7264067ffb2a6457611a22bccdf3ef26731e7a46c44
+  metadata.gz: aaf92352c50ff3a15610214136f4c8b586786548ee384ec46c377b8f055318060417b0cf14ce9c4522e551b3891a2fe35546570f7ba7bef050faee921b4acbbe
+  data.tar.gz: 14c37f9ab0c5319408e6366c4bcafacf3eb0f220b621fb7c68325ceac0bed3173953003e1ba052888788e875e98390d21e95588b9d82cddcef361a9b630e51ff

data/.travis.yml

@@ -82,3 +82,15 @@ matrix:
   - rvm: ruby-head
     gemfile: gemfiles/redis_store.gemfile
     env: TEST_REDIS_CACHE=true
+  - rvm: 2.3.7
+    gemfile: gemfiles/active_support_with_dalli.gemfile
+    env: TEST_AS_MEM_CACHE_STORE_CACHE=true
+  - rvm: 2.4.4
+    gemfile: gemfiles/active_support_with_dalli.gemfile
+    env: TEST_AS_MEM_CACHE_STORE_CACHE=true
+  - rvm: 2.5.1
+    gemfile: gemfiles/active_support_with_dalli.gemfile
+    env: TEST_AS_MEM_CACHE_STORE_CACHE=true
+  - rvm: ruby-head
+    gemfile: gemfiles/active_support_with_dalli.gemfile
+    env: TEST_AS_MEM_CACHE_STORE_CACHE=true

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] - 2018-09-03
+- fetching operation `AnyCache#fetch(key, force:, expires_in:, &block)`
+  - fetches data from the cache using the given key;
+  - if a block has been passed and data with the given key does not exist -
+    that block will be called and the return value will be written to the cache;
+- existence operation `AnyCache#exist?(key)` - determine if an entry exists or not;
+- support for `ActiveSupport::Cache::MemCacheStore`;
+- configuration layer `AnyCache.configure`: an ability to choose and configure a necessary cache client
+  without any explicit client object instantiation (client object will be instantiated implicitly);
+
 ## [0.1.0] - 2018-08-26
 - Release :)

data/README.md

@@ -1,16 +1,17 @@
 # AnyCache · [![Gem Version](https://badge.fury.io/rb/any_cache.svg)](https://badge.fury.io/rb/any_cache) [![Build Status](https://travis-ci.org/0exp/any_cache.svg?branch=master)](https://travis-ci.org/0exp/any_cache) [![Coverage Status](https://coveralls.io/repos/github/0exp/any_cache/badge.svg)](https://coveralls.io/github/0exp/any_cache)
 
 AnyCache - a simplest cache wrapper that provides a minimalistic generic interface for all well-known cache storages and includes a minimal set of necessary operations:
-`read`, `write`, `delete`, `expire`, `persist`, `clear`, `increment`, `decrement`.
+`fetch`, `read`, `write`, `delete`, `expire`, `persist`, `exist?`, `clear`, `increment`, `decrement`.
 
 Supported clients:
 
 - `Redis` ([gem redis](https://github.com/redis/redis-rb)) ([redis storage](https://redis.io/))
 - `Redis::Store` ([gem redis-store](https://github.com/redis-store/redis-store)) ([redis storage](https://redis.io/))
 - `Dalli::Client` ([gem dalli](https://github.com/petergoldstein/dalli)) ([memcached storage](https://memcached.org/))
+- `ActiveSupport::Cache::RedisCacheStore` ([gem activesupport](https://github.com/rails/rails/blob/master/activesupport/lib/active_support/cache/redis_cache_store.rb)) ([redis cache storage](https://api.rubyonrails.org/classes/ActiveSupport/Cache/RedisCacheStore.html))
+- `ActiveSupport::Cache::MemCacheStore` ([gem activesupport](https://github.com/rails/rails/blob/master/activesupport/lib/active_support/cache/mem_cache_store.rb)) ([memcache storage](https://api.rubyonrails.org/classes/ActiveSupport/Cache/MemCacheStore.html))
 - `ActiveSupport::Cache::FileStore` ([gem activesupport](https://github.com/rails/rails/blob/master/activesupport/lib/active_support/cache/file_store.rb)) ([file storage](https://api.rubyonrails.org/classes/ActiveSupport/Cache/FileStore.html))
 - `ActiveSupport::Cache::MemoryStore` ([gem activesupport](https://github.com/rails/rails/blob/master/activesupport/lib/active_support/cache/memory_store.rb)) ([in memory storage](https://api.rubyonrails.org/classes/ActiveSupport/Cache/MemoryStore.html))
-- `ActiveSupport::Cache::RedisCacheStore` ([gem activesupport](https://github.com/rails/rails/blob/master/activesupport/lib/active_support/cache/redis_cache_store.rb)) ([redis cache storage](https://api.rubyonrails.org/classes/ActiveSupport/Cache/RedisCacheStore.html))
 
 ---
 
@@ -35,7 +36,19 @@ require 'any_cache'
 ## Usage / Table of Contents
 
 - [Creation](#creation)
-- **Operations**
+    - [Manual creation](#manual-creation)
+    - [Config-based creation](#config-based-creation)
+        - [AnyCache with Redis](#anycache-with-redis)
+        - [AnyCache with Redis::Store](#anycache-with-redisstore)
+        - [AnyCache with Dalli::Client](#anycache-with-dalliclient)
+        - [AnyCache with ActiveSupport::Cache::RedisCacheStore](#anycache-with-activesupportcacherediscachestore)
+        - [AnyCache with ActiveSupport::Cache::MemCacheStore](#anycache-with-activesupportcachememcachestore)
+        - [AnyCache with ActiveSupport::Cache::FileStore](#anycache-with-activesupportcachefilestore)
+        - [AnyCache with ActiveSupport::Cache::MemoryStore](#anycache-with-activesupportcachememorystore)
+    - [Many cache storages](#many-cache-storages)
+    - [Custom cache clients](#custom-cache-clients)
+- [Operations](#operations)
+    - [Fetch](#fetch)
     - [Read](#read)
     - [Write](#write)
     - [Delete](#delete)
@@ -43,6 +56,7 @@ require 'any_cache'
     - [Decrement](#decrement)
     - [Expire](#expire)
     - [Persist](#persist)
+    - [Existence](#existence)
     - [Clear](#clear)
 
 ---
@@ -51,16 +65,25 @@ require 'any_cache'
 
 To instantiate AnyCache instance you have to provide a client.
 Client - an independent driver that works with a corresponding cache storage (external dependency).
+
 Supported clients:
 
 - `Redis`
 - `Redis::Store`
 - `Dalli::Client`
 - `ActiveSupport::Cache::RedisCacheStore`
+- `ActiveSupport::Cache::MemCacheStore`
 - `ActiveSupport::Cache::FileStore`
 - `ActiveSupport::Cache::MemoryStore`
 
-`AnyCache` instantiation:
+`AnyCache` can be instantiated by two ways:
+
+- with explicit client object instantiated manually ([read](#manual-creation));
+- via configuration ([read](#config-based-creation));
+
+#### Manual creation
+
+Custom instantiation with explicit client objects:
 
 ```ruby
 # 1) create client object
@@ -71,6 +94,8 @@ client = Redis::Store.new(...)
 client = Dalli::Client.new(...)
 # -- or --
 client = ActiveSupport::Cache::RedisCacheStore.new(...)
+# --- or ---
+client = ActiveSupport::Cache::MemCacheStore.new(...)
 # -- or --
 client = ActiveSupport::Cache::FileStore.new(...)
 # -- or --
@@ -80,22 +105,237 @@ client = ActiveSupport::Cache::MemoryStore.new(...)
 any_cache = AnyCache.build(client) # => <AnyCache:0x00007f990527f268 ...>
 ```
 
+#### Config-based creation
+
+You can configure `AnyCache` globally or create subclasses and configure each of them. After that
+storage instantiation works via `.build` method without explicit attributes.
+
+- `AnyCache.configure` is used for configuration;
+- `config.driver` is used for determine which client should be used;
+- `config.__driver_name__.options` stores client-related options;
+
+Supported drivers:
+
+- `:redis` - [Redis](#anycache-with-redis);
+- `:redis_tore` - [Redis::Client](#anycache-with-redisstore);
+- `:dalli` - [Dalli::Client](#anycache-with-dalliclient);
+- `:as_redis_cache_store` - [ActiveSupport::Cache::RedisCacheStore](#anycache-with-activesupportcacherediscachestore);
+- `:as_mem_cache_store` - [ActiveSupport::Cache::MemCacheStore](#anycache-with-activesupportcachememcachestore);
+- `:as_file_store` - [ActiveSupport::Cache::FileStore](#anycache-with-activesupportcachefilestore);
+- `:as_memory_store` - [ActiveSupport::Cache::MemoryStore](#anycache-with-activesupportcachememorystore);
+
+##### `AnyCache` with `Redis`:
+
+```ruby
+require 'redis'
+require 'any_cache'
+
+AnyCache.configure do |conf|
+  conf.driver = :redis
+  conf.redis.options = { ... } # Redis-related options
+end
+
+AnyCache.build
+```
+
+##### `AnyCache` with `Redis::Store`:
+
+```ruby
+require 'redis-store'
+require 'any_cache'
+
+AnyCache.configure do |conf|
+  conf.driver = :redis_store
+  conf.redis_store.options = { ... } # Redis::Store-related options
+end
+
+AnyCache.build
+```
+
+##### `AnyCache` with `Dalli::Client`:
+
+```ruby
+require 'dalli'
+require 'any_cache'
+
+AnyCache.configure do |conf|
+  conf.driver = :dalli
+  conf.dalli.servers = ... # string or array of strings
+  conf.dalli.options = { ... } # Dalli::Client-related options
+end
+
+AnyCache.build
+```
+
+##### `AnyCache` with `ActiveSupport::Cache::RedisCacheStore`:
+
+```ruby
+require 'active_support'
+require 'any_cache'
+
+AnyCache.configure do |conf|
+  conf.driver = :as_redis_cache_store
+  conf.as_redis_cache_store.options = { ... } # ActiveSupport::Cache::RedisCacheStore-related options
+end
+
+AnyCache.build
+```
+
+##### `AnyCache` with `ActiveSupport::Cache::MemCacheStore`:
+
+```ruby
+require 'active_support'
+require 'any_cache'
+
+AnyCache.configure do |conf|
+  conf.driver = :as_mem_cache_store
+  conf.as_memory_store.servers = ... # string or array of strings
+  conf.as_memory_store.options = { ... } # ActiveSupport::Cache::MemCacheStore-related options
+end
+
+AnyCache.build
+```
+
+##### `AnyCache` with `ActiveSupport::Cache::FileStore`:
+
+```ruby
+require 'active_support'
+require 'any_cache'
+
+AnyCache.configure do |conf|
+  conf.driver = :as_file_store
+  conf.as_file_store.cache_path = '/path/to/cache'
+  conf.as_file_store.options = { ... } # ActiveSupport::Cache::FileStore-related options
+end
+
+AnyCache.build
+```
+
+##### `AnyCache` with `ActiveSupport::Cache::MemoryStore`:
+
+```ruby
+require 'activesupport'
+require 'any_cache'
+
+AnyCache.configure do |conf|
+  conf.driver = :as_memory_store
+  conf.as_memory_store.options = { ... } # ActiveSupport::Cache::MemoryStore-related options
+end
+
+AnyCache.build
+```
+
+#### Many cache storages
+
+You can inherit `AnyCache` class and create and configure as many cache storages as you want:
+
+```ruby
+class RedisCache < AnyCache
+  configure do |conf|
+    conf.driver = :redis
+  end
+end
+
+class DalliCache < AnyCache
+  configure do |conf|
+    conf.driver = :dalli
+  end
+end
+
+redis_cache = RedisCache.build
+dalli_cache = DalliCache.build
+```
+
+#### Custom cache clients
+
 If you want to use your own cache client implementation, you should provide an object that responds to:
 
+- `#fetch(*key, [**options])` ([doc](#fetch))
 - `#read(key, [**options])` ([doc](#read))
 - `#write(key, value, [**options])` ([doc](#write))
 - `#delete(key, [**options])` ([doc](#delete))
 - `#increment(key, amount, [**options])` ([doc](#increment))
-- `#decrmeent(key, amount, [**options])` ([doc](#decrement))
+- `#decrement(key, amount, [**options])` ([doc](#decrement))
 - `#expire(key, [**options])` ([doc](#expire))
 - `#persist(key, [**options])` ([doc](#persist))
+- `#exist?(key, [**options])` ([doc](#existence))
 - `#clear([**options])` ([doc](#clear))
 
+```ruby
+class MyCacheClient
+  # ...
+
+  def read(key, **)
+    # ...
+  end
+
+  def write(key, value, **)
+    # ...
+  end
+
+  # ...
+end
+
+AnyCache.build(MyCacheClient.new)
+```
+
+## Operations
+
+`AnyCache` provides a following operation set:
+
+- [fetch](#fetch)
+- [read](#read)
+- [write](#write)
+- [delete](#delete)
+- [increment](#increment)
+- [decrement](#decrement)
+- [expire](#expire)
+- [persist](#persist)
+- [clear](#clear)
+- [exist?](#existence)
+
+---
+
+### Fetch
+
+- `AnyCache#fetch(key, [force:], [expires_in:], [&block])`
+    - works in `ActiveSupport::Cache::Store#fetch`-manner;
+    - fetches data from the cache, using the given key;
+    - if there is data in the cache with the given key, then that data is returned;
+    - if there is no such data in the cache (a cache miss), then nil will be returned:
+        - if a block has been passed, that block will be passed the key and executed in the event of a cache miss;
+        - the return value of the block will be written to the cache under the given cache key, and that return value will be returned;
+
+```ruby
+# --- entry exists ---
+any_cache.fetch("data") # => "some_data"
+any_cache.fetch("data") { "new_data" } # => "some_data"
+
+# --- entry does not exist ---
+any_cache.fetch("data") # => nil
+any_cache.fetch("data") { "new_data" } # => "new_data"
+any_cache.fetch("data") # => "new_data"
+
+# --- new entry with expiration time ---
+any_cache.fetch("data") # => nil
+any_cache.fetch("data", expires_in: 8) { "new_data" } # => "new_data"
+any_cache.fetch("data") # => "new_data"
+# ...sleep 8 seconds...
+any_cache.fetch("data") # => nil
+
+# --- force update/rewrite ---
+any_cache.fetch("data") # => "some_data"
+any_cache.fetch("data", expires_in: 8, force: true) { "new_data" } # => "new_data"
+any_cache.fetch("data") # => "new_data"
+# ...sleep 8 seconds...
+any_cache.fetch("data") # => nil
+```
+
 ---
 
 ### Read
 
-- `AnyCache#read(key)` - get entry value from cache storage
+- `AnyCache#read(key)` - get an entry value from the cache storage
 
 ```ruby
 # --- entry exists ---
@@ -109,7 +349,7 @@ any_cache.read("data") # => nil
 
 ### Write
 
-- `AnyCache#write(key, value, [expires_in:])` - write new entry to cache storage
+- `AnyCache#write(key, value, [expires_in:])` - write a new entry to the cache storage
 
 ```ruby
 # --- permanent entry ---
@@ -123,7 +363,7 @@ any_cache.write("data", 123, expires_in: 60)
 
 ### Delete
 
-- `AnyCache#delete(key)` - remove entry from cache storage
+- `AnyCache#delete(key)` - remove entry from the cache storage
 
 ```ruby
 any_cache.delete("data")
@@ -133,8 +373,8 @@ any_cache.delete("data")
 
 ### Increment
 
-- `AnyCache#increment(key, amount = 1, [expires_in:])` - increment entry's value by passed amount
-  and set new expiration time if needed
+- `AnyCache#increment(key, amount = 1, [expires_in:])` - increment entry's value by the given amount
+  and set the new expiration time if needed
 
 ```ruby
 # --- increment existing entry ---
@@ -157,8 +397,8 @@ any_cache.increment("another_data", 5, expires_in: 5) # => 5
 
 ### Decrement
 
-- `AnyCache#decrement(key, amount = 1, [expires_in:])` - decrement entry's value by passed amount
-  and set new expiration time if needed
+- `AnyCache#decrement(key, amount = 1, [expires_in:])` - decrement entry's value by the given amount
+  and set the new expiration time if needed
 
 ```ruby
 # --- decrement existing entry ---
@@ -207,6 +447,20 @@ any_cache.persist("data")
 
 ---
 
+### Existence
+
+- `AnyCache#exist?(key)` - determine if an entry exists
+
+```ruby
+# --- entry exists ---
+any_cache.exist?("data") # => true
+
+# --- entry does not exist ---
+any_cache.exist?("another-data") # => false
+```
+
+---
+
 ### Clear
 
 - `AnyCache#clear()` - clear cache database
@@ -239,16 +493,11 @@ bin/rspec --test-dalli # run specs with Dalli::Client
 bin/rspec --test-as-file-store # run specs with ActiveSupport::Cache::FileStore
 bin/rspec --test-as-memory-store # run specs with ActiveSupport::Cache::MemoryStore
 bin/rspec --test-as-redis-cache-store # run specs with ActiveSupport::Cache::RedisCacheStore
+bin/rspec --test-as-mem-cache-store # run specs with ActiveSupport::Cache::MemCacheStore
 ```
 
 ---
 
-## Roadmap
-
-- configuration layer with ability to instantiate cache clients implicitly
-
----
-
 ## Contributing
 
 - Fork it (https://github.com/0exp/any_cache/fork)

data/Rakefile

@@ -2,6 +2,16 @@
 
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'rubocop'
+require 'rubocop-rspec'
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new(:rubocop) do |t|
+  config_path = File.expand_path(File.join('.rubocop.yml'), __dir__)
+
+  t.options = ['--config', config_path]
+  t.requires << 'rubocop-rspec'
+end
 
 RSpec::Core::RakeTask.new(:rspec)
 

data/any_cache.gemspec

@@ -28,12 +28,12 @@ Gem::Specification.new do |spec|
   end
 
   spec.add_dependency 'concurrent-ruby', '~> 1.0'
+  spec.add_dependency 'qonfig',          '~> 0.6'
 
   spec.add_development_dependency 'coveralls',        '~> 0.8'
   spec.add_development_dependency 'simplecov',        '~> 0.16'
-  spec.add_development_dependency 'armitage-rubocop', '~> 0.6'
+  spec.add_development_dependency 'armitage-rubocop', '~> 0.7'
   spec.add_development_dependency 'rspec',            '~> 3.8'
-  spec.add_development_dependency 'qonfig',           '~> 0.6'
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'

data/bin/rspec

@@ -8,18 +8,16 @@ module AnyCacheSpecRunner
   extend self
 
   def expand_gemfile_path(gemfile_name)
-    File.expand_path(
-      File.join('..', '..', 'gemfiles', gemfile_name),
-      Pathname.new(__FILE__).realpath
-    )
+    File.expand_path(File.join('..', 'gemfiles', gemfile_name), __dir__)
   end
 
   GEMFILES = {
     redis:                     expand_gemfile_path('redis.gemfile'),
     redis_store:               expand_gemfile_path('redis_store.gemfile'),
     dalli:                     expand_gemfile_path('dalli.gemfile'),
+    active_support:            expand_gemfile_path('active_support.gemfile'),
     active_support_with_redis: expand_gemfile_path('active_support_with_redis.gemfile'),
-    active_support:            expand_gemfile_path('active_support.gemfile')
+    active_support_with_dalli: expand_gemfile_path('active_support_with_dalli.gemfile')
   }.freeze
 
   # rubocop:disable Metrics/MethodLength, Metrics/BlockLength
@@ -57,6 +55,11 @@ module AnyCacheSpecRunner
         'Run specs with ActiveSupport::Cache::MemoryStore cache storage'
       ) { run_as_memory_store_cache_specs! }
 
+      opts.on(
+        '--test-as-mem-cache-store',
+        'Run specs with ActiveSupport::Cache::MemCacheStore cache storage'
+      ) { run_as_mem_cache_store_cache_specs! }
+
       opts.on(
         '-h', '--help',
         'Show this message'
@@ -109,6 +112,13 @@ module AnyCacheSpecRunner
     run_tests!
   end
 
+  def run_as_mem_cache_store_cache_specs!
+    ENV['TEST_AS_MEM_CACHE_STORE_CACHE'] = 'true'
+    ENV['BUNDLE_GEMFILE'] = GEMFILES[:active_support_with_dalli]
+
+    run_tests!
+  end
+
   def run_tests!
     require 'rubygems'
     require 'bundler/setup'

data/gemfiles/active_support_with_dalli.gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'dalli',         '~> 2.7'
+gem 'activesupport', '~> 5.2'
+
+gemspec path: '..'

data/lib/any_cache/adapters/active_support_file_store.rb

@@ -18,8 +18,7 @@ module AnyCache::Adapters
       # @api private
       # @since 0.1.0
       def supported_driver?(driver)
-        defined?(::ActiveSupport::Cache::FileStore) &&
-        driver.is_a?(::ActiveSupport::Cache::FileStore)
+        AnyCache::Drivers::ActiveSupportFileStore.supported_source?(driver)
       end
     end
   end