mongoid-cached-json 1.0 → 1.1

data/README.md

@@ -3,7 +3,7 @@ Mongoid::CachedJson [![Build Status](https://secure.travis-ci.org/dblock/mongoid
 
 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.
+CachedJson enables returning multiple JSON formats and versions 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.
 
@@ -78,8 +78,16 @@ Mongoid::CachedJson.configure do |config|
 end
 ```
 
-Definining Fields
------------------
+The default JSON version returned from `as_json` is `:unspecified`. If you wish to redefine this, set `Mongoid::CachedJson.config.default_version`.
+
+``` ruby
+Mongoid::CachedJson.configure do |config|
+  config.default_version = :v2
+end
+```
+
+Defining Fields
+---------------
 
 Mongoid::CachedJson supports the following options.
 
@@ -90,6 +98,42 @@ 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
+* `:version` can be a single version for this field to appear in
+* `:versions` can be an array of versions for this field to appear in
+
+Versioning
+----------
+
+You can set an optional `version` or `versions` attribute on JSON fields. Consider the following definition where the first version defined `:name`, then split it into `:first`, `:middle` and `:last` in version `:v2` and introduced a date of birth in `:v3`.
+
+``` ruby
+class Person
+  include Mongoid::Document
+  include Mongoid::CachedJson
+
+  field :first
+  field :last
+
+  def name
+    [ first, middle, last ].compact.join(" ")
+  end
+
+  json_fields \
+    :first => { :versions => [ :v2, :v3 ] },
+    :last => { :versions => [ :v2, :v3 ] },
+    :middle => { :versions => [ :v2, :v3 ] },
+    :born => { :versions => :v3 },
+    :name => { :definition => :name }
+
+end
+```
+
+``` ruby
+person = Person.create({ :first => "John", :middle => "F.", :last => "Kennedy", :born => "May 29, 1917" })
+person.as_json # { :name => "John F. Kennedy" }
+person.as_json({ :version => :v2 }) # { :first => "John", :middle => "F.", :last => "Kennedy", :name => "John F. Kennedy" }
+person.as_json({ :version => :v3 }) # { :first => "John", :middle => "F.", :last => "Kennedy", :name => "John F. Kennedy", :born => "May 29, 1917" }
+```
 
 Transformations
 ---------------
@@ -98,6 +142,7 @@ You can define global transformations on all JSON values with `Mongoid::CachedJs
 
 ``` ruby
 class Widget
+  include Mongoid::Document
   include Mongoid::CachedJson
 
   field :name
@@ -128,11 +173,11 @@ You can set `Mongoid::CachedJson.config.disable_caching = true`. It may be a goo
 Contributing
 ------------
 
-Fork the project. Make your feature addition or bug fix with tests. Send a pull request. Bonus points for topical branches.
+Fork the project. Make your feature addition or bug fix with tests. Send a pull request. Bonus points for topic branches.
 
 Copyright and License
 ---------------------
 
-MIT License, see [LICENSE](LICENSE.md) for details.
+MIT License, see [LICENSE](https://github.com/dblock/mongoid-cached-json/blob/master/LICENSE.md) for details.
 
-(c) 2012 [Art.sy Inc.](http://artsy.github.com) and [Contributors](HISTORY.md)
+(c) 2012 [Art.sy Inc.](http://artsy.github.com) and [Contributors](https://github.com/dblock/mongoid-cached-json/blob/master/HISTORY.md)

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

@@ -5,6 +5,7 @@ module Mongoid
   
     included do
       class_attribute :all_json_properties
+      class_attribute :all_json_versions
       class_attribute :cached_json_field_defs
       class_attribute :cached_json_reference_defs
       class_attribute :hide_as_child_json_when
@@ -16,13 +17,17 @@ module Mongoid
       #
       # @param [ hash ] defs JSON field definition.
       #
-      # @since 1.0.0
+      # @since 1.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 = {}
+        # Collect all versions for clearing cache
+        self.all_json_versions = cached_json_defs.map do |field, definition|
+          [ :unspecified, definition[:version], Array(definition[:versions]) ]
+        end.flatten.compact.uniq
         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
@@ -62,6 +67,9 @@ module Mongoid
             nil
           else
             Hash[clazz.cached_json_field_defs[options[:properties]].map do |field, definition|
+              # version match
+              versions = ([definition[:version] ] | Array(definition[:versions])).compact
+              next unless versions.empty? or versions.include?(options[:version])
               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)
@@ -85,9 +93,9 @@ module Mongoid
   
       # Cache key.
       def cached_json_key(options, cached_class, cached_id)
-        "as_json/#{cached_class}/#{cached_id}/#{options[:properties]}/#{!!options[:is_top_level_json]}"
+        "as_json/#{options[:version]}/#{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
@@ -116,17 +124,24 @@ module Mongoid
   
     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 })
+    def as_json(options = {})
+      if options[:properties] and ! self.all_json_properties.member?(options[:properties])
+        raise ArgumentError.new("Unknown properties option: #{options[:properties]}")
+      end
+      self.class.materialize_json({ 
+        :properties => :short, :is_top_level_json => true, :version => Mongoid::CachedJson.config.default_version 
+      }.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))
+          self.all_json_versions.each do |version|
+            Mongoid::CachedJson.config.cache.delete(self.class.cached_json_key({
+              :properties => properties, :is_top_level_json => is_top_level_json, :version => version
+            }, self.class, self.id))
+          end
         end
       end
     end
@@ -148,4 +163,4 @@ module Mongoid
     end
       
   end
-end
+end

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

@@ -1,11 +1,16 @@
 # encoding: utf-8
-module Mongoid
-  module CachedJson #:nodoc
+module Mongoid 
+  module CachedJson 
     module Config
       extend self
       include ActiveSupport::Callbacks
   
-      attr_accessor :settings, :defaults
+      # Current configuration settings.
+      attr_accessor :settings
+      
+      # Default configuration settings.
+      attr_accessor :defaults
+      
       @settings = {}
       @defaults = {}
   
@@ -36,8 +41,30 @@ module Mongoid
         RUBY
       end
       
+      # Disable caching.
       option :disable_caching, { :default => false }
       
+      # Returns the default JSON version
+      #
+      # @example Get the default JSON version
+      #   config.default_version
+      #
+      # @return [ Version ] The default JSON version.
+      def default_version
+        settings[:default_version] = :unspecified unless settings.has_key?(:default_version)
+        settings[:default_version]
+      end
+
+      # Sets the default JSON version.
+      #
+      # @example Set the default version.
+      #   config.default_version = :v2
+      #
+      # @return [ Version ] The newly set default version.
+      def default_version=(default_version)
+        settings[:default_version] = default_version
+      end
+      
       # Returns the default cache store, which is either a Rails logger of stdout logger
       #
       # @example Get the default cache store

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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongoid-cached-json
 version: !ruby/object:Gem::Version
-  version: '1.0'
+  version: '1.1'
   prerelease: 
 platform: ruby
 authors:
@@ -11,11 +11,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-20 00:00:00.000000000Z
+date: 2012-03-13 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70215312132660 !ruby/object:Gem::Requirement
+  requirement: &82900940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -23,10 +23,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70215312132660
+  version_requirements: *82900940
 - !ruby/object:Gem::Dependency
   name: mongoid
-  requirement: &70215312131960 !ruby/object:Gem::Requirement
+  requirement: &82886650 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -34,10 +34,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70215312131960
+  version_requirements: *82886650
 - !ruby/object:Gem::Dependency
   name: bson_ext
-  requirement: &70215312120160 !ruby/object:Gem::Requirement
+  requirement: &82886190 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -45,10 +45,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70215312120160
+  version_requirements: *82886190
 - !ruby/object:Gem::Dependency
   name: hpricot
-  requirement: &70215312118740 !ruby/object:Gem::Requirement
+  requirement: &82885630 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -56,10 +56,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70215312118740
+  version_requirements: *82885630
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70215312117220 !ruby/object:Gem::Requirement
+  requirement: &82885050 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -67,10 +67,10 @@ dependencies:
         version: '2.5'
   type: :development
   prerelease: false
-  version_requirements: *70215312117220
+  version_requirements: *82885050
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70215312116260 !ruby/object:Gem::Requirement
+  requirement: &82884260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -78,10 +78,10 @@ dependencies:
         version: '1.0'
   type: :development
   prerelease: false
-  version_requirements: *70215312116260
+  version_requirements: *82884260
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70215312115520 !ruby/object:Gem::Requirement
+  requirement: &82883690 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -89,10 +89,10 @@ dependencies:
         version: '1.6'
   type: :development
   prerelease: false
-  version_requirements: *70215312115520
+  version_requirements: *82883690
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &70215312114460 !ruby/object:Gem::Requirement
+  requirement: &82883090 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -100,7 +100,7 @@ dependencies:
         version: '0.6'
   type: :development
   prerelease: false
-  version_requirements: *70215312114460
+  version_requirements: *82883090
 description: Cached-json is a DSL for describing JSON representations of Mongoid models.
 email: dblock@dblock.org
 executables: []
@@ -130,7 +130,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2087512391400708959
+      hash: -206724813
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: