granola-cache 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 02a1ad1117691d8f9e4839c15debccf1239fcee9
+  data.tar.gz: 4ff5f68499ed602dc741d59cc178e95c5d117aab
+SHA512:
+  metadata.gz: 74bac219d9f6d8350c95065e14eb0fb3b84003b9367d9d98003bf6ea290b75ff71130b2548e20430c8a952e95245a60925ce19a76873f530001122465b57261e
+  data.tar.gz: a1ae267d04594de510fb1c950815f8c7cebb65e5df6cb8976e3ddc6e93d76c11a794df31506c5b56944946d9ef000dcafc0945f7cab34117d000ed614d6789ff

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2016 Nicolas Sanguinetti <hi@nicolassanguinetti.info>
+
+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,109 @@
+# Granola::Cache [![Build Status](https://img.shields.io/travis/foca/granola-cache.svg)](https://travis-ci.org/foca/granola-cache) [![RubyGem](https://img.shields.io/gem/v/granola-cache.svg)](https://rubygems.org/gems/granola-cache)
+
+Provide caching options for the result of your [Granola][] serializers.
+
+[Granola]: https://github.com/foca/granola
+
+## Example
+
+``` ruby
+class PersonSerializer < Granola::Serializer
+  cache key: "person", expire_in: 3600
+
+  def data
+    {
+      id: object.id,
+      name: object.name,
+    }
+  end
+
+  def cache_key
+    "%s:%s" % [object.id, object.updated_at.to_i]
+  end
+end
+
+serializer = PersonSerializer.new(person)
+serializer.to_json # Generates JSON and stores it in the cache.
+serializer.to_json # Retreives from cache without rendering.
+
+person.update(...) # Do something that would change the `cache_key` (e.g. update
+                   # the object's `updated_at`.)
+
+serializer.to_json # Generates JSON again, storing the new version in the cache.
+```
+
+**NOTE**: Changing the cache key will invalidate previous versions of the cached
+object, but will _not_ delete them from the cache store.
+
+## Install
+
+    gem install granola-cache
+
+## Cache Stores
+
+By default, Granola::Cache stores cached output from serializers in an in-memory
+Hash. This is not meant for production use. You should provide an alternative
+store for your application.
+
+Alternative stores should implement a single method:
+
+``` ruby
+fetch(key, options = {}, &block)
+```
+
+Where:
+
+* `key`: The cache key to fetch from cache.
+* `options`: Any options the cache store can take (for example, `:expire_in`
+  if your store supports Time-based expiration.)
+
+If the key isn't found in the store, the block is invoked, and the result from
+this block is both returned _and_ stored in the cache for further use.
+
+There's an example [Redis Store](./examples/redis_store.rb) included in this
+repository, should you wish to inspect it.
+
+### Rails
+
+This is compatible with `ActiveSupport::Cache::Store`, so if you're in a Rails
+application, you can just do this in `config/initializers/granola.rb`:
+
+``` ruby
+Granola::Cache.store = Rails.cache
+```
+
+## Cache Options
+
+Pass caching options to a serializer by calling the `cache` singleton method.
+
+Granola::Cache only recognizes these options: `:key` and `:store`. Any other
+option passed will be ignored by Granola, but forwarded to the [cache
+store](#cache-stores).
+
+### `:key`
+
+This is meant to be a prefix applied to cache keys. In the example above, any
+particular serializer will be stored in the cache with the following key:
+
+``` ruby
+"#{key}/#{object.id}:#{object.updated_at.to_i}"
+```
+
+### `:store`
+
+This allows overriding the caching store for a specific serializer.
+
+``` ruby
+class WeeklyReportSerializer < Granola::Serializer
+  cache store: DifferentStore.new
+end
+```
+
+See [Cache Stores](#cache-stores) for more on configuring the global store.
+
+## License
+
+This project is shared under the MIT license. See the attached [LICENSE][] file
+for details.
+
+[LICENSE]: ./LICENSE

data/examples/redis_store.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "redic"
+
+module Granola
+  module Cache
+    # Redis-based cache store, relying on Redic for transport.
+    #
+    # Example:
+    #
+    #   Granola::Cache.store = Granola::Cache::RedisStore.new($redic)
+    class RedisStore
+      # Public: Initialize the store.
+      #
+      # redis - A Redic instance (defaults to `Redic.new`).
+      def initialize(redis = Redic.new)
+        @redis = redis
+      end
+
+      # Public: Fetch/Store a value from the cache.
+      #
+      # key     - String key under which to store the value.
+      # options - Options Hash (defaults to: `{}`):
+      #           :expire_in - Integer TTL in seconds for keys to expire.
+      #
+      # Yields if the key isn't found, and the result of the block is stored in
+      #   the cache.
+      #
+      # Returns a String.
+      def fetch(key, options = {})
+        value = @redis.call("GET", key)
+        return value unless value.nil?
+
+        value = yield
+
+        expiration = ["EX", options[:expire_in]] if options[:expire_in]
+        @redis.call("SET", key, value, *expiration)
+
+        value
+      end
+    end
+  end
+end

data/lib/granola/cache.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "granola"
+
+# Adds caching capabilities to Granola serializers. Use the `cache` directive on
+# the serializers for this:
+#
+# Example:
+#
+#   class PersonSerializer < Granola::Serializer
+#     cache key: "person", expires_in: 3600
+#
+#     def data
+#       {}
+#     end
+#
+#     def cache_key
+#       [object.id, object.updated_at.to_i].join(":")
+#     end
+#   end
+#
+#   serializer = PersonSerializer.new(person)
+#   serializer.to_json #=> generates JSON and stores in Granola::Cache.store
+#   serializer.to_json #=> retreives the JSON from the cache.
+#
+#   # do something with person so that `person.updated_at` changes
+#
+#   serializer.to_json #=> generates JSON and puts the new version in the store
+#
+# Cache Options
+# =============
+#
+# Granola::Cache only recognizes two options: `:key` and `:store`. Any other
+# option passed will be ignored by Granola, but forwarded to the cache store
+# (see below.)
+#
+# `:key`
+# ------
+#
+# This is meant to be a prefix applied to cache keys. In the example above, any
+# particular serializer will be stored in the cache with the following key:
+#
+#   "#{key}/#{object.id}:#{object.updated_at.to_i}"
+#
+# `:store`
+# --------
+#
+# This allows overriding the caching store for a specific serializer.
+#
+#   class WeeklyReportSerializer < Granola::Serializer
+#     cache store: DifferentStore.new
+#   end
+#
+# See Cache Stores below for more on configuring the global store.
+#
+# Cache Stores
+# ============
+#
+# By default, Granola::Cache stores cached output from serializers in an
+# in-memory Hash. This is not meant for production use. You should provide an
+# alternative store for your application.
+#
+# Alternative stores should implement a single method:
+#
+#   fetch(key, options = {}, &block)
+#
+# Where:
+#
+#   key     - The cache key to fetch from cache.
+#   options - Any options the cache store can take (for example, `:expires_in`
+#             if your store supports Time-based expiration.)
+#
+# If the key isn't found in the store, the block is invoked, and the result from
+# this block is both returned _and_ stored in the cache for further use.
+#
+# This is compatible with `ActiveSupport::Cache::Store`, so if you're in a Rails
+# application, you can just do this in `config/initializers/granola.rb`:
+#
+#   Granola::Cache.store = Rails.cache
+module Granola::Cache
+  class << self
+    # Public: Get/Set the Cache store. By default this is an instance of
+    # Granola::Cache::MemoryStore. See that class for the expected interface.
+    attr_accessor :store
+  end
+
+  # MemoryStore just stores things in a Hash in memory. WARNING: MemoryStore is
+  # *not* thread safe. It's not meant for production use. You should provide a
+  # proper implementation that stores the rendered output somewhere (like redis,
+  # memcached, etc)
+  class MemoryStore
+    def initialize # :nodoc:
+      @store = {}
+    end
+
+    # Public: Fetch an object from the cache, or, if none is found, yield and
+    # store the result of executing the block.
+    #
+    # key     - A String with the cache key.
+    # options - A Hash of options. MemoryStore does not support any options, and
+    #           just ignores this argument.
+    #
+    # Yields and stores the result of evaluating the block on a cache miss.
+    # Returns the value stored in the cache.
+    def fetch(key, options = {})
+      @store.fetch(key) { @store[key] = yield }
+    end
+  end
+
+  # Extensions to Granola::Serializer to support configuring caching on a
+  # serializer-by-serializer basis.
+  module CacheableSerializer
+    # Public: Make this serializer cacheable. Any unrecognized options will be
+    # forwarded to the cache store.
+    #
+    # options - Hash of options (default: {}):
+    #           :key - The prefix to use for keys when storing keys in the
+    #                  cache.
+    #
+    # Returns nothing.
+    def cache(options = {})
+      cache_options[:should_cache] = true
+      cache_options.update(options)
+    end
+
+    # Internal: Access the current cache options for this serializer.
+    def cache_options
+      @cache_options ||= {}
+    end
+
+    # Public: Disable caching for the duration of the block.
+    def without_caching
+      should_cache = cache_options[:should_cache]
+      cache_options[:should_cache] = false
+      yield
+    ensure
+      cache_options[:should_cache] = should_cache
+    end
+  end
+
+  # Extensions to Granola::Renderer to perform the actual storing in or
+  # retreiving from the cache.
+  module CacheableRenderer
+    def render(serializer, *) # :nodoc:
+      options = case serializer
+                when Granola::List
+                  serializer.item_serializer.cache_options
+                else
+                  serializer.class.cache_options
+                end
+
+      options = options.dup
+
+      store = options.delete(:store) { Granola::Cache.store }
+      if options.delete(:should_cache)
+        key = [options.delete(:key), serializer.cache_key].compact.join("/")
+        store.fetch(key, options) { super }
+      else
+        super
+      end
+    end
+  end
+end
+
+Granola::Serializer.extend(Granola::Cache::CacheableSerializer)
+Granola::Renderer.prepend(Granola::Cache::CacheableRenderer)
+Granola::Cache.store = Granola::Cache::MemoryStore.new

data/lib/granola/cache/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Granola
+  module Cache
+    VERSION = "0.1.0"
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: granola-cache
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nicolas Sanguinetti
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-11-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: granola
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.13'
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.13'
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: cutest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: redic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+description: |
+  Granola::Cache provides an interface to wrap your serialization in a cache
+  so that you don't needlessly generate the same bit of JSON over and over
+  again.
+email:
+- contacto@nicolassanguinetti.info
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- examples/redis_store.rb
+- lib/granola/cache.rb
+- lib/granola/cache/version.rb
+homepage: http://github.com/foca/granola
+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: Cache the output of your Granola serializers.
+test_files: []