mongoid-cached-json 1.0

data/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2011 Art.sy, Aaron Windsor, Daniel Doubrovkine
+
+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,138 @@
+Mongoid::CachedJson [![Build Status](https://secure.travis-ci.org/dblock/mongoid-cached-json.png)](http://travis-ci.org/dblock/mongoid-cached-json)
+===================
+
+Typical *as_json* definitions may involve lots of database point queries and method calls. When returning collections of objects, a single call may yield hundreds of database queries that can take seconds. This library mitigates the problem by implementing a module called *CachedJson*.
+
+CachedJson enables returning multiple JSON formats from a single class and provides some rules for returning embedded or referenced data. It then uses a scheme where fragments of JSON are cached for a particular (class, id) pair containing only the data that doesn't involve references/embedded documents. To get the full JSON for an instance, CachedJson will combine fragments of JSON from the instance with fragments representing the JSON for its references. In the best case, when all of these fragments are cached, this falls through to a few cache lookups followed by a couple Ruby hash merges to create the JSON.
+
+Using Mongoid::CachedJson we were able to cut our JSON API average response time by about a factor of 10.
+
+Resources
+---------
+
+* [Need Help?](http://groups.google.com/group/mongoid-cached-json)
+* [Source Code](http://github.com/dblock/mongoid-cached-json)
+* [Travis CI](https://secure.travis-ci.org/dblock/mongoid-cached-json)
+
+Quickstart
+----------
+
+Add `mongoid-cached-json` to your Gemfile.
+
+    gem "mongoid-cached-json"
+
+Include `Mongoid::CachedJson` in your models.
+
+``` ruby
+class Gadget
+  include Mongoid::CachedJson
+
+  field :name
+  field :extras
+
+  belongs_to :widget
+
+  json_fields \
+    :name => { },
+    :extras => { :properties => :public }
+
+end
+
+class Widget
+  include Mongoid::CachedJson
+
+  field :name
+  has_many :gadgets
+
+  json_fields \
+    :name => { },
+    :gadgets => { :type => :reference, :properties => :public }
+
+end
+```
+
+Invoke `as_json`.
+
+``` ruby
+# the `:short` version of the JSON, `gadgets` not included
+Widget.first.as_json
+
+# equivalent to the above
+Widget.first.as_json({ :properties => :short })
+
+# `:public` version of the JSON, `gadgets` returned with `:short` JSON, no `:extras`
+Widget.first.as_json({ :properties => :public })
+
+# `:all` version of the JSON, `gadgets` returned with `:all` JSON, including `:extras`
+Widget.first.as_json({ :properties => :all })
+```
+
+Configuration
+-------------
+
+By default `Mongoid::CachedJson` will use an instance of `ActiveSupport::Cache::MemoryStore` in a non-Rails and `Rails.cache` in a Rails environment. You can configure it to use any other cache store.
+
+``` ruby
+Mongoid::CachedJson.configure do |config|
+  config.cache = ActiveSupport::Cache::FileStore.new
+end
+```
+
+Definining Fields
+-----------------
+
+Mongoid::CachedJson supports the following options.
+
+* `:hide_as_child_json_when` is an optional function that hides the child JSON from `as_json` parent objects, eg. `cached_json :hide_as_child_json_when => lambda { |instance| ! instance.is_secret? }`
+
+Mongoid::CachedJson field definitions support the following options.
+
+* `:definition` can be a symbol or an anonymous function, eg. `:description => { :definition => :name }` or `:description => { :definition => lambda { |instance| instance.name } }`
+* `:type` can be `:reference`, required for referenced objects
+* `:properties` can be one of `:short`, `:public`, `:all`, in this order
+
+Transformations
+---------------
+
+You can define global transformations on all JSON values with `Mongoid::CachedJson.config.transform`. Each transformation must return a value. In the following example we extend the JSON definition with an application-specific `:trusted` field and encode any content that is not trusted.
+
+``` ruby
+class Widget
+  include Mongoid::CachedJson
+
+  field :name
+  field :description
+
+  json_fields \
+    :name => { :trusted => true },
+    :description => { }
+end
+```
+
+``` ruby
+  Mongoid::CachedJson.config.transform do |field, definition, value|
+    (!! definition[:trusted]) ? value : CGI.escapeHTML(value)
+  end
+```
+
+Mixing with Standard as_json
+----------------------------
+
+Taking part in the Mongoid::CachedJson `json_fields` scheme is optional: you can still write *as_json* methods where it makes sense.
+
+Turning Caching Off
+-------------------
+
+You can set `Mongoid::CachedJson.config.disable_caching = true`. It may be a good idea to set it to `ENV['DISABLE_JSON_CACHING']`, in case this turns out not to be The Solution To All Of Your Performance Problems (TM).
+
+Contributing
+------------
+
+Fork the project. Make your feature addition or bug fix with tests. Send a pull request. Bonus points for topical branches.
+
+Copyright and License
+---------------------
+
+MIT License, see [LICENSE](LICENSE.md) for details.
+
+(c) 2012 [Art.sy Inc.](http://artsy.github.com) and [Contributors](HISTORY.md)

data/lib/mongoid-cached-json.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+require 'mongoid'
+require 'active_support/concern'
+require 'mongoid-cached-json/version'
+require 'mongoid-cached-json/config'
+require 'mongoid-cached-json/cached_json'
+

data/lib/mongoid-cached-json/cached_json.rb

@@ -0,0 +1,151 @@
+# encoding: utf-8
+module Mongoid
+  module CachedJson
+    extend ActiveSupport::Concern
+  
+    included do
+      class_attribute :all_json_properties
+      class_attribute :cached_json_field_defs
+      class_attribute :cached_json_reference_defs
+      class_attribute :hide_as_child_json_when
+    end
+  
+    module ClassMethods
+    
+      # Define JSON fields for a class.
+      #
+      # @param [ hash ] defs JSON field definition.
+      #
+      # @since 1.0.0
+      def json_fields(defs)
+        self.hide_as_child_json_when = defs.delete(:hide_as_child_json_when) || lambda { |a| false }
+        self.all_json_properties = [:short, :public, :all]
+        cached_json_defs = Hash[defs.map { |k,v| [k, { :type => :callable, :properties => :short, :definition => k }.merge(v)] }]
+        self.cached_json_field_defs = {}
+        self.cached_json_reference_defs = {}
+        self.all_json_properties.each_with_index do |property, i|
+          self.cached_json_field_defs[property] = Hash[cached_json_defs.find_all do |field, definition|
+            self.all_json_properties.find_index(definition[:properties]) <= i and definition[:type] == :callable
+          end]
+          self.cached_json_reference_defs[property] = Hash[cached_json_defs.find_all do |field, definition|
+            self.all_json_properties.find_index(definition[:properties]) <= i and definition[:type] == :reference
+          end]
+          # If the field is a reference and is just specified as a symbol, reflect on it to get metadata
+          self.cached_json_reference_defs[property].to_a.each do |field, definition|
+            if definition[:definition].is_a?(Symbol)
+              self.cached_json_reference_defs[property][field][:metadata] = self.reflect_on_association(definition[:definition])
+            end
+          end
+        end
+        before_save :expire_cached_json
+      end
+  
+      # Given an object definition in the form of either an object or a class, id pair,
+      # grab the as_json representation from the cache if possible, otherwise create
+      # the as_json representation by loading the object from the database. For any
+      # references in the object's JSON representation, we have to recursively materialize
+      # the JSON by calling resolve_json_reference on each of them (which may, in turn,
+      # call materialize_json)
+      def materialize_json(options, object_def)
+        return nil if !object_def[:object] and !object_def[:id]
+        is_top_level_json = options[:is_top_level_json] || false
+        if object_def[:object]
+          object_reference = object_def[:object]
+          clazz, id = object_def[:object].class, object_def[:object].id
+        else
+          object_reference = nil
+          clazz, id = object_def[:clazz], object_def[:id]
+        end
+        json = Mongoid::CachedJson.config.cache.fetch(self.cached_json_key(options, clazz, id), { :force => !! Mongoid::CachedJson.config.disable_caching }) do
+          object_reference = clazz.where({ :_id => id }).first if !object_reference
+          if !object_reference or (!is_top_level_json and options[:properties] != :all and clazz.hide_as_child_json_when.call(object_reference))
+            nil
+          else
+            Hash[clazz.cached_json_field_defs[options[:properties]].map do |field, definition|
+              json_value = (definition[:definition].is_a?(Symbol) ? object_reference.send(definition[:definition]) : definition[:definition].call(object_reference))
+              Mongoid::CachedJson.config.transform.each do |t|
+                json_value = t.call(field, definition, json_value)
+              end
+              [field, json_value]
+            end]
+          end
+        end
+        reference_defs = clazz.cached_json_reference_defs[options[:properties]]
+        if !reference_defs.empty?
+          object_reference = clazz.where({ :_id => id }).first if !object_reference
+          if object_reference and (is_top_level_json or options[:properties] == :all or !clazz.hide_as_child_json_when.call(object_reference))
+            json = json.merge(Hash[reference_defs.map do |field, definition|
+              json_properties_type = (options[:properties] == :all) ? :all : :short
+              [field, clazz.resolve_json_reference(options.merge({ :properties => json_properties_type, :is_top_level_json => false}), object_reference, field, definition)]
+            end])
+          end
+        end
+        json
+      end
+  
+      # Cache key.
+      def cached_json_key(options, cached_class, cached_id)
+        "as_json/#{cached_class}/#{cached_id}/#{options[:properties]}/#{!!options[:is_top_level_json]}"
+      end
+  
+      # If the reference is a symbol, we may be lucky and be able to figure out the as_json
+      # representation by the (class, id) pair definition of the reference. That is, we may
+      # be able to load the as_json representation from the cache without even getting the
+      # model from the database and materializing it through Mongoid. We'll try to do this first.
+      def resolve_json_reference(options, object, field, reference_def)
+        reference_json = nil
+        if reference_def[:metadata]
+          clazz = reference_def[:metadata].class_name.constantize
+          key = reference_def[:metadata].key.to_sym
+          if reference_def[:metadata].relation == Mongoid::Relations::Referenced::ManyToMany
+            reference_json = object.send(key).map do |id|
+              materialize_json(options, { :clazz => clazz, :id => id })
+            end.compact
+          elsif reference_def[:metadata].relation == Mongoid::Relations::Referenced::In
+            reference_json = materialize_json(options, { :clazz => clazz, :id => object.send(key) })
+          end
+        end
+        # If we get to this point and reference_json is still nil, there's no chance we can
+        # load the JSON from cache so we go ahead and call as_json on the object.
+        if !reference_json
+          reference = reference_def[:definition].is_a?(Symbol) ? object.send(reference_def[:definition]) : reference_def[:definition].call(object)
+          reference_json = reference.as_json(options) if reference
+        end
+        reference_json
+      end
+  
+    end
+  
+    def as_json(options = { :properties => :short })
+      raise ArgumentError.new("Missing options[:properties]") if (options.nil? || options[:properties].nil?)
+      raise ArgumentError.new("Unknown properties option: #{options[:properties]}") if !self.all_json_properties.member?(options[:properties])
+      self.class.materialize_json({ :is_top_level_json => true }.merge(options), { :object => self })
+    end
+  
+    # Expire all JSON entries for this class.
+    def expire_cached_json
+      self.all_json_properties.each do |properties|
+        [true, false].each do |is_top_level_json|
+          Mongoid::CachedJson.config.cache.delete(self.class.cached_json_key({:properties => properties, :is_top_level_json => is_top_level_json}, self.class, self.id))
+        end
+      end
+    end
+  
+    class << self
+    
+      # Set the configuration options. Best used by passing a block.
+      #
+      # @example Set up configuration options.
+      #   Mongoid::CachedJson.configure do |config|
+      #     config.cache = Rails.cache
+      #   end
+      #
+      # @return [ Config ] The configuration obejct.
+      def configure
+        block_given? ? yield(Mongoid::CachedJson::Config) : Mongoid::CachedJson::Config
+      end
+      alias :config :configure
+    end
+      
+  end
+end

data/lib/mongoid-cached-json/config.rb

@@ -0,0 +1,94 @@
+# encoding: utf-8
+module Mongoid
+  module CachedJson #:nodoc
+    module Config
+      extend self
+      include ActiveSupport::Callbacks
+  
+      attr_accessor :settings, :defaults
+      @settings = {}
+      @defaults = {}
+  
+      # Define a configuration option with a default.
+      #
+      # @example Define the option.
+      #   Config.option(:cache, :default => nil)
+      #
+      # @param [ Symbol ] name The name of the configuration option.
+      # @param [ Hash ] options Extras for the option.
+      #
+      # @option options [ Object ] :default The default value.
+      def option(name, options = {})
+        defaults[name] = settings[name] = options[:default]
+  
+        class_eval <<-RUBY
+          def #{name}
+            settings[#{name.inspect}]
+          end
+  
+          def #{name}=(value)
+            settings[#{name.inspect}] = value
+          end
+  
+          def #{name}?
+            #{name}
+          end
+        RUBY
+      end
+      
+      option :disable_caching, { :default => false }
+      
+      # Returns the default cache store, which is either a Rails logger of stdout logger
+      #
+      # @example Get the default cache store
+      #   config.default_cache
+      #
+      # @return [ Cache ] The default Cache instance.
+      def default_cache
+        defined?(Rails) && Rails.respond_to?(:cache) ? Rails.cache : ::ActiveSupport::Cache::MemoryStore.new
+      end
+  
+      # Returns the cache, or defaults to Rails cache or ActiveSupport::Cache::MemoryStore logger.
+      #
+      # @example Get the cache.
+      #   config.cache
+      #
+      # @return [ Cache ] The configured cache or a default cache instance.
+      def cache
+        settings[:cache] = default_cache unless settings.has_key?(:cache)
+        settings[:cache]
+      end
+  
+      # Sets the cache to use.
+      #
+      # @example Set the cache.
+      #   config.cache = Rails.cache
+      #
+      # @return [ Cache ] The newly set cache.
+      def cache=(cache)
+        settings[:cache] = cache
+      end
+  
+      # Reset the configuration options to the defaults.
+      #
+      # @example Reset the configuration options.
+      #   config.reset!
+      def reset!
+        settings.replace(defaults)
+      end
+      
+      # Define a transformation on JSON data.
+      #
+      # @example Convert every string in materialized JSON to upper-case.
+      #   config.transform do |field, value|
+      #      value.upcase
+      #   end
+      def transform(& block)
+        settings[:transform] = [] unless settings.has_key?(:transform)
+        settings[:transform] << block if block_given?
+        settings[:transform]
+      end
+  
+    end
+  end
+end

data/lib/mongoid-cached-json/version.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+module Mongoid
+  module CachedJson
+    VERSION = '1.0'
+  end
+end
+

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: mongoid-cached-json
+version: !ruby/object:Gem::Version
+  version: '1.0'
+  prerelease: 
+platform: ruby
+authors:
+- Aaron Windsor
+- Daniel Doubrovkine
+- Frank Macreery
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-20 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &70215312132660 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70215312132660
+- !ruby/object:Gem::Dependency
+  name: mongoid
+  requirement: &70215312131960 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70215312131960
+- !ruby/object:Gem::Dependency
+  name: bson_ext
+  requirement: &70215312120160 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70215312120160
+- !ruby/object:Gem::Dependency
+  name: hpricot
+  requirement: &70215312118740 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70215312118740
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70215312117220 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: *70215312117220
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: &70215312116260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: *70215312116260
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: &70215312115520 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: *70215312115520
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &70215312114460 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: *70215312114460
+description: Cached-json is a DSL for describing JSON representations of Mongoid models.
+email: dblock@dblock.org
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.md
+- README.md
+files:
+- lib/mongoid-cached-json.rb
+- lib/mongoid-cached-json/cached_json.rb
+- lib/mongoid-cached-json/config.rb
+- lib/mongoid-cached-json/version.rb
+- LICENSE.md
+- README.md
+homepage: http://github.com/dblock/mongoid-cached-json
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 2087512391400708959
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Effective model-level JSON caching for the Mongoid ODM.
+test_files: []