active_model_serializers 0.10.0.rc5 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 79d558ff503a5d3d80c7e28d07fbad6858c87416
-  data.tar.gz: e1345a0b533ac95996f62e873366907377f8e175
+  metadata.gz: eb97c8740c2530c085ee9186ea27ddd220367fc3
+  data.tar.gz: 0a768d3ab122abe2c3e7f5b6c00a8dada6872433
 SHA512:
-  metadata.gz: ded6c2f6e8a7bbe81543a4939ae02c255908697a3894556bc81b5c46cb21b81cf771370fc60a902d393391b0b3addd9a5018cf142a04ecf3752c2aa1dcab2292
-  data.tar.gz: 285de3be1603f3ad013da4813ff3a95528e99bf3b2b4f511e780cefb6babd8d9555b113a3eaca762400e64e941d2fc699de02a73745ff56d7365b9dc6c41957a
+  metadata.gz: 5589022dd6fa160c0a03981cedf46433fb1eb19e4bac5f3489908671e9e0969c48bb7a86cf03d12cf8ce825b2efe3ed6ad1b6594019635470319c899e7964617
+  data.tar.gz: 989cf413780f12d47a553a7aae5cba33de1625bbc022366b7e4533810b87b151302ed6000116c03234bf2b2048a913048624728a54be87cead848076924cf6ce

data/.gitignore

@@ -23,3 +23,13 @@ tmp
 .ruby-gemset
 vendor/bundle
 tags
+
+# silly macs
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+Icon?
+ehthumbs.db
+Thumbs.db

data/.travis.yml

@@ -3,7 +3,6 @@ language: ruby
 sudo: false
 
 rvm:
-  - 2.0.0
   - 2.1
   - 2.2.3
   - 2.3.0
@@ -26,25 +25,18 @@ env:
   global:
     - "JRUBY_OPTS='--dev -J-Xmx1024M --debug'"
   matrix:
-    - "RAILS_VERSION=4.0"
     - "RAILS_VERSION=4.1"
     - "RAILS_VERSION=4.2"
     - "RAILS_VERSION=master"
 
 matrix:
   exclude:
-  - rvm: 2.0.0
-    env: RAILS_VERSION=master
   - rvm: 2.1
     env: RAILS_VERSION=master
   - rvm: jruby-9.0.4.0
     env: RAILS_VERSION=master
-  - rvm: jruby-9.0.4.0
-    env: RAILS_VERSION=4.0
   - rvm: jruby-head
     env: RAILS_VERSION=master
-  - rvm: jruby-head
-    env: RAILS_VERSION=4.0
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 ## 0.10.x
 
+### [master (unreleased)](https://github.com/rails-api/active_model_serializers/compare/v0.10.0...master)
+
+### v0.10.0 (2016-05-17)
+
+Breaking changes:
+- [#1662](https://github.com/rails-api/active_model_serializers/pull/1662) Drop support for Rails 4.0 and Ruby 2.0.0. (@remear)
+
+Features:
+- [#1677](https://github.com/rails-api/active_model_serializers/pull/1677) Add `assert_schema`, `assert_request_schema`, `assert_request_response_schema`. (@bf4)
+- [#1697](https://github.com/rails-api/active_model_serializers/pull/1697) Include actual exception message with custom exceptions;
+  `Test::Schema` exceptions are now `Minitest::Assertion`s. (@bf4)
+- [#1699](https://github.com/rails-api/active_model_serializers/pull/1699) String/Lambda support for conditional attributes/associations (@mtsmfm)
+- [#1687](https://github.com/rails-api/active_model_serializers/pull/1687) Only calculate `_cache_digest` (in `cache_key`) when `skip_digest` is false. (@bf4)
+- [#1647](https://github.com/rails-api/active_model_serializers/pull/1647) Restrict usage of `serializable_hash` options
+  to the ActiveModel::Serialization and ActiveModel::Serializers::JSON interface. (@bf4)
+
+Fixes:
+- [#1700](https://github.com/rails-api/active_model_serializers/pull/1700) Support pagination link for Kaminari when no data is returned. (@iamnader)
+- [#1726](https://github.com/rails-api/active_model_serializers/pull/1726) Adds polymorphic option to association definition which includes association type/nesting in serializer (@cgmckeever)
+
+Misc:
+- [#1673](https://github.com/rails-api/active_model_serializers/pull/1673) Adds "How to" guide on using AMS with POROs (@DrSayre)
+
 ### [v0.10.0.rc5 (2016-04-04)](https://github.com/rails-api/active_model_serializers/compare/v0.10.0.rc4...v0.10.0.rc5)
 
 Breaking changes:

data/CONTRIBUTING.md

@@ -7,7 +7,7 @@ Before opening an issue, try the following:
 See if your issue can be resolved by information in the documentation.
 
 - [0.10 (master) Documentation](https://github.com/rails-api/active_model_serializers/tree/master/docs)
-  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/v0.10.0.rc5)
+  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/v0.10.0)
   - [Guides](docs)
 - [0.9 (0-9-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-9-stable)
 - [0.8 (0-8-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-8-stable)
@@ -74,10 +74,15 @@ Run a single test
 `$ rake test TEST=path/to/test.rb TESTOPTS="--name=test_something"`
 
 Run tests against different Rails versions by setting the RAILS_VERSION variable
-and bundling gems.
+and bundling gems.  (save this script somewhere executable and run from top of AMS repository)
 
 ```bash
-for version in 4.0 4.1 4.2 master; do
+#!/usr/bin/env bash
+
+rcommand='puts YAML.load_file("./.travis.yml")["env"]["matrix"].join(" ").gsub("RAILS_VERSION=", "")'
+versions=$(ruby -ryaml -e "$rcommand")
+
+for version in ${versions[@]}; do
   export RAILS_VERSION="$version"
   rm -f Gemfile.lock
   bundle check || bundle --local || bundle
@@ -88,7 +93,12 @@ for version in 4.0 4.1 4.2 master; do
   else
     # red in ANSI
     echo -e "\033[31m **** Tests failed against Rails ${RAILS_VERSION} **** \033[0m"
-  fi
+    read -p '[Enter] any key to continue, [q] to quit...' prompt
+    if [ "$prompt" = 'q' ]; then
+      unset RAILS_VERSION
+      exit 1
+    fi
+fi
   unset RAILS_VERSION
 done
 ```

data/Gemfile

@@ -44,11 +44,10 @@ end
 group :test do
   gem 'sqlite3',                          platform: (@windows_platforms + [:ruby])
   gem 'activerecord-jdbcsqlite3-adapter', platform: :jruby
-
   gem 'codeclimate-test-reporter', require: false
 end
 
 group :development, :test do
-  gem 'rubocop', '~> 0.36', require: false
+  gem 'rubocop', '~> 0.39.0', require: false
   gem 'yard', require: false
 end

data/README.md

@@ -28,7 +28,7 @@
 ## Documentation
 
 - [0.10 (master) Documentation](https://github.com/rails-api/active_model_serializers/tree/master)
-  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/v0.10.0.rc5)
+  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/v0.10.0)
   - [Guides](docs)
 - [0.9 (0-9-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-9-stable)
   - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/0-9-stable)
@@ -137,7 +137,7 @@ The model can be serialized as:
 
 ```ruby
 options = {}
-serialization = SerializableResource.new(resource, options)
+serialization = ActiveModelSerializers::SerializableResource.new(resource, options)
 serialization.to_json
 serialization.as_json
 ```
@@ -146,7 +146,7 @@ SerializableResource delegates to the adapter, which it builds as:
 
 ```ruby
 adapter_options = {}
-adapter = Adapter.create(serializer, adapter_options)
+adapter = ActiveModelSerializers::Adapter.create(serializer, adapter_options)
 adapter.to_json
 adapter.as_json
 adapter.serializable_hash

data/active_model_serializers.gemspec

@@ -60,7 +60,7 @@ Gem::Specification.new do |spec|
 
   spec.post_install_message = <<-EOF
 NOTE: The default key case for the JsonApi adapter has changed to dashed.
-See https://github.com/rails-api/active_model_serializers/blob/master/docs/general/key_transform.md
+See https://github.com/rails-api/active_model_serializers/blob/master/docs/general/key_transforms.md
 for more information on configuring this behavior.
 EOF
 end

data/appveyor.yml

@@ -3,23 +3,19 @@ version: '{build}'
 skip_tags: true
 
 environment:
+  JRUBY_OPTS: "--dev -J-Xmx1024M --debug"
   matrix:
-    - ruby_version: "200"
-    - ruby_version: "200-x64"
-    - ruby_version: "21"
-    - ruby_version: "21-x64"
-    - ruby_version: "jruby-9.0.4.0"
+    - ruby_version: "Ruby21"
+    - ruby_version: "Ruby21-x64"
+    - ruby_version: "jruby-9.0.0.0"
 
 cache:
   - vendor/bundle
 
 install:
-  - SET PATH=C:\Ruby%ruby_version%\bin;%PATH%
-  - ruby --version
-  - gem --version
+  - SET PATH=C:\%ruby_version%\bin;%PATH%
   - gem install bundler
-  - bundler --version
-  - bundle platform
+  - bundle env
   - bundle install --path=vendor/bundle --retry=3 --jobs=3
 
 test_script:

data/docs/ARCHITECTURE.md

@@ -44,7 +44,7 @@ ActiveModelSerializers.
 
 If the collection serializer (ArraySerializer) cannot
 identify a serializer for a resource in its collection, it raises [`NoSerializerError`](https://github.com/rails-api/active_model_serializers/issues/1191#issuecomment-142327128)
-which is rescued in `AcitveModel::Serializer::Reflection#build_association` which sets
+which is rescued in `ActiveModel::Serializer::Reflection#build_association` which sets
 the association value directly:
 
 ```ruby

data/docs/README.md

@@ -27,6 +27,7 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 - [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md)
 - [Testing ActiveModelSerializers](howto/test.md)
 - [Passing Arbitrary Options](howto/passing_arbitrary_options.md)
+- [How to serialize a Plain-Old Ruby Object (PORO)](howto/serialize_poro.md)
 
 ## Integrations
 

data/docs/general/deserialization.md

@@ -35,30 +35,30 @@ Given a JSON API document,
 
 ```
 document = {
-  data: {
-    id: 1,
-    type: 'post',
-    attributes: {
-      title: 'Title 1',
-      date: '2015-12-20'
+  'data' => {
+    'id' => 1,
+    'type' => 'post',
+    'attributes' => {
+      'title' => 'Title 1',
+      'date' => '2015-12-20'
     },
-    associations: {
-      author: {
-        data: {
-          type: 'user',
-          id: 2
+    'associations' => {
+      'author' => {
+        'data' => {
+          'type' => 'user',
+          'id' => '2'
         }
       },
-      second_author: {
-        data: nil
+      'second_author' => {
+        'data' => nil
       },
-      comments: {
-        data: [{
-          type: 'comment',
-          id: 3
+      'comments' => {
+        'data' => [{
+          'type' => 'comment',
+          'id' => '3'
         },{
-          type: 'comment',
-          id: 4
+          'type' => 'comment',
+          'id' => '4'
         }]
       }
     }

data/docs/general/serializers.md

@@ -38,6 +38,27 @@ Serialization of the resource `title`
 
 ### Associations
 
+The interface for associations is, generically:
+
+> `association_type(association_name, options, &block)`
+
+Where:
+
+- `association_type` may be `has_one`, `has_many`, `belongs_to`.
+- `association_name` is a method name the serializer calls.
+- optional: `options` may be:
+  - `key:` The name used for the serialized association.
+  - `serializer:`
+  - `if:`
+  - `unless:`
+  - `virtual_value:`
+  - `polymorphic:` defines if polymorphic relation type should be nested in serialized association.
+- optional: `&block` is a context that returns the association's attributes.
+  - prevents `association_name` method from being called.
+  - return value of block is used as the association value.
+  - yields the `serializer` to the block.
+  - `include_data false` prevents the `data` key from being rendered in the JSON API relationship.
+
 #### ::has_one
 
 e.g.
@@ -58,6 +79,18 @@ def cached_blog
 end
 ```
 
+```ruby
+has_one :blog, if: :show_blog?
+# you can also use a string or lambda
+# has_one :blog, if: 'scope.admin?'
+# has_one :blog, if: -> (serializer) { serializer.scope.admin? }
+# has_one :blog, if: -> { scope.admin? }
+
+def show_blog?
+  scope.admin?
+end
+```
+
 #### ::has_many
 
 e.g.

data/docs/howto/serialize_poro.md

@@ -0,0 +1,32 @@
+[Back to Guides](../README.md)
+
+# How to serialize a Plain-Old Ruby Object (PORO)
+
+When you are first getting started with ActiveModelSerializers, it may seem only `ActiveRecord::Base` objects can be serializable, but pretty much any object can be serializable with ActiveModelSerializers.  Here is an example of a PORO that is serializable:
+```ruby
+# my_model.rb
+class MyModel
+  alias :read_attribute_for_serialization :send
+  attr_accessor :id, :name, :level
+  
+  def initialize(attributes)
+    @id = attributes[:id]
+    @name = attributes[:name]
+    @level = attributes[:level]
+  end
+
+  def self.model_name
+    @_model_name ||= ActiveModel::Name.new(self)
+  end
+end
+```
+
+Fortunately, ActiveModelSerializers provides a [`ActiveModelSerializers::Model`](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/model.rb) which you can use in production code that will make your PORO a lot cleaner.  The above code now becomes:
+```ruby
+# my_model.rb
+class MyModel < ActiveModelSerializers::Model
+  attr_accessor :id, :name, :level
+end
+```
+
+The default serializer would be `MyModelSerializer`.

data/lib/active_model/serializer.rb

@@ -18,6 +18,8 @@ require 'active_model/serializer/type'
 # reified when subclassed to decorate a resource.
 module ActiveModel
   class Serializer
+    # @see #serializable_hash for more details on these valid keys.
+    SERIALIZABLE_HASH_VALID_KEYS = [:only, :except, :methods, :include, :root].freeze
     extend ActiveSupport::Autoload
     autoload :Adapter
     autoload :Null

data/lib/active_model/serializer/caching.rb

@@ -1,5 +1,6 @@
 module ActiveModel
   class Serializer
+    UndefinedCacheKey = Class.new(StandardError)
     module Caching
       extend ActiveSupport::Concern
 
@@ -17,8 +18,9 @@ module ActiveModel
           #    force
           #    race_condition_ttl
           #  Passed to ::_cache as
-          #    serializer._cache.fetch(cache_key, @klass._cache_options)
-          serializer.class_attribute :_cache_digest # @api private : Generated
+          #    serializer.cache_store.fetch(cache_key, @klass._cache_options)
+          #  Passed as second argument to serializer.cache_store.fetch(cache_key, self.class._cache_options)
+          serializer.class_attribute :_cache_digest_file_path # @api private : Derived at inheritance
         end
       end
 
@@ -41,7 +43,12 @@ module ActiveModel
         def inherited(base)
           super
           caller_line = caller[1]
-          base._cache_digest = digest_caller_file(caller_line)
+          base._cache_digest_file_path = caller_line
+        end
+
+        def _cache_digest
+          return @_cache_digest if defined?(@_cache_digest)
+          @_cache_digest = digest_caller_file(_cache_digest_file_path)
         end
 
         # Hashes contents of file for +_cache_digest+
@@ -62,6 +69,14 @@ module ActiveModel
           _cache_options && _cache_options[:skip_digest]
         end
 
+        def cached_attributes
+          _cache_only ? _cache_only : _attributes - _cache_except
+        end
+
+        def non_cached_attributes
+          _attributes - cached_attributes
+        end
+
         # @api private
         # Used by FragmentCache on the CachedSerializer
         #  to call attribute methods on the fragmented cached serializer.
@@ -145,6 +160,173 @@ module ActiveModel
           perform_caching? && cache_store &&
             (_cache_only && !_cache_except || !_cache_only && _cache_except)
         end
+
+        # Read cache from cache_store
+        # @return [Hash]
+        def cache_read_multi(collection_serializer, adapter_instance, include_tree)
+          return {} if ActiveModelSerializers.config.cache_store.blank?
+
+          keys = object_cache_keys(collection_serializer, adapter_instance, include_tree)
+
+          return {} if keys.blank?
+
+          ActiveModelSerializers.config.cache_store.read_multi(*keys)
+        end
+
+        # Find all cache_key for the collection_serializer
+        # @param serializers [ActiveModel::Serializer::CollectionSerializer]
+        # @param adapter_instance [ActiveModelSerializers::Adapter::Base]
+        # @param include_tree [ActiveModel::Serializer::IncludeTree]
+        # @return [Array] all cache_key of collection_serializer
+        def object_cache_keys(collection_serializer, adapter_instance, include_tree)
+          cache_keys = []
+
+          collection_serializer.each do |serializer|
+            cache_keys << object_cache_key(serializer, adapter_instance)
+
+            serializer.associations(include_tree).each do |association|
+              if association.serializer.respond_to?(:each)
+                association.serializer.each do |sub_serializer|
+                  cache_keys << object_cache_key(sub_serializer, adapter_instance)
+                end
+              else
+                cache_keys << object_cache_key(association.serializer, adapter_instance)
+              end
+            end
+          end
+
+          cache_keys.compact.uniq
+        end
+
+        # @return [String, nil] the cache_key of the serializer or nil
+        def object_cache_key(serializer, adapter_instance)
+          return unless serializer.present? && serializer.object.present?
+
+          serializer.class.cache_enabled? ? serializer.cache_key(adapter_instance) : nil
+        end
+      end
+
+      # Get attributes from @cached_attributes
+      # @return [Hash] cached attributes
+      # def cached_attributes(fields, adapter_instance)
+      def cached_fields(fields, adapter_instance)
+        cache_check(adapter_instance) do
+          attributes(fields)
+        end
+      end
+
+      def cache_check(adapter_instance)
+        if self.class.cache_enabled?
+          self.class.cache_store.fetch(cache_key(adapter_instance), self.class._cache_options) do
+            yield
+          end
+        elsif self.class.fragment_cache_enabled?
+          fetch_fragment_cache(adapter_instance)
+        else
+          yield
+        end
+      end
+
+      # 1. Create a CachedSerializer and NonCachedSerializer from the serializer class
+      # 2. Serialize the above two with the given adapter
+      # 3. Pass their serializations to the adapter +::fragment_cache+
+      #
+      # It will split the serializer into two, one that will be cached and one that will not
+      #
+      # Given a resource name
+      # 1. Dynamically creates a CachedSerializer and NonCachedSerializer
+      #   for a given class 'name'
+      # 2. Call
+      #       CachedSerializer.cache(serializer._cache_options)
+      #       CachedSerializer.fragmented(serializer)
+      #       NonCachedSerializer.cache(serializer._cache_options)
+      # 3. Build a hash keyed to the +cached+ and +non_cached+ serializers
+      # 4. Call +cached_attributes+ on the serializer class and the above hash
+      # 5. Return the hash
+      #
+      # @example
+      #   When +name+ is <tt>User::Admin</tt>
+      #   creates the Serializer classes (if they don't exist).
+      #     CachedUser_AdminSerializer
+      #     NonCachedUser_AdminSerializer
+      #
+      # Given a hash of its cached and non-cached serializers
+      # 1. Determine cached attributes from serializer class options
+      # 2. Add cached attributes to cached Serializer
+      # 3. Add non-cached attributes to non-cached Serializer
+      def fetch_fragment_cache(adapter_instance)
+        serializer_class_name = self.class.name.gsub('::'.freeze, '_'.freeze)
+        self.class._cache_options ||= {}
+        self.class._cache_options[:key] = self.class._cache_key if self.class._cache_key
+
+        cached_serializer = _get_or_create_fragment_cached_serializer(serializer_class_name)
+        cached_hash = ActiveModelSerializers::SerializableResource.new(
+          object,
+          serializer: cached_serializer,
+          adapter: adapter_instance.class
+        ).serializable_hash
+
+        non_cached_serializer = _get_or_create_fragment_non_cached_serializer(serializer_class_name)
+        non_cached_hash = ActiveModelSerializers::SerializableResource.new(
+          object,
+          serializer: non_cached_serializer,
+          adapter: adapter_instance.class
+        ).serializable_hash
+
+        # Merge both results
+        adapter_instance.fragment_cache(cached_hash, non_cached_hash)
+      end
+
+      def _get_or_create_fragment_cached_serializer(serializer_class_name)
+        cached_serializer = _get_or_create_fragment_serializer "Cached#{serializer_class_name}"
+        cached_serializer.cache(self.class._cache_options)
+        cached_serializer.type(self.class._type)
+        cached_serializer.fragmented(self)
+        self.class.cached_attributes.each do |attribute|
+          options = self.class._attributes_keys[attribute] || {}
+          cached_serializer.attribute(attribute, options)
+        end
+        cached_serializer
+      end
+
+      def _get_or_create_fragment_non_cached_serializer(serializer_class_name)
+        non_cached_serializer = _get_or_create_fragment_serializer "NonCached#{serializer_class_name}"
+        non_cached_serializer.type(self.class._type)
+        non_cached_serializer.fragmented(self)
+        self.class.non_cached_attributes.each do |attribute|
+          options = self.class._attributes_keys[attribute] || {}
+          non_cached_serializer.attribute(attribute, options)
+        end
+        non_cached_serializer
+      end
+
+      def _get_or_create_fragment_serializer(name)
+        return Object.const_get(name) if Object.const_defined?(name)
+        Object.const_set(name, Class.new(ActiveModel::Serializer))
+      end
+
+      def cache_key(adapter_instance)
+        return @cache_key if defined?(@cache_key)
+
+        parts = []
+        parts << object_cache_key
+        parts << adapter_instance.cached_name
+        parts << self.class._cache_digest unless self.class._skip_digest?
+        @cache_key = parts.join('/')
+      end
+
+      # Use object's cache_key if available, else derive a key from the object
+      # Pass the `key` option to the `cache` declaration or override this method to customize the cache key
+      def object_cache_key
+        if object.respond_to?(:cache_key)
+          object.cache_key
+        elsif (serializer_cache_key = (self.class._cache_key || self.class._cache_options[:key]))
+          object_time_safe = object.updated_at
+          object_time_safe = object_time_safe.strftime('%Y%m%d%H%M%S%9N') if object_time_safe.respond_to?(:strftime)
+          "#{serializer_cache_key}/#{object.id}-#{object_time_safe}"
+        else
+          fail UndefinedCacheKey, "#{object.class} must define #cache_key, or the 'key:' option must be passed into '#{self.class}.cache'"
+        end
       end
     end
   end