active_model_serializers 0.10.0 → 0.10.6

data/docs/howto/upgrade_from_0_8_to_0_10.md

@@ -0,0 +1,265 @@
+[Back to Guides](../README.md)
+
+# How to migrate from `0.8` to `0.10` safely
+
+## Disclaimer
+### Proceed at your own risk
+This document attempts to outline steps to upgrade your app based on the collective experience of
+developers who have done this already. It may not cover all edge cases and situations that may cause issues,
+so please proceed with a certain level of caution.
+
+## Overview
+This document outlines the steps needed to migrate from `0.8` to `0.10`. The method described
+below has been created via the collective knowledge of contributions of those who have done
+the migration successfully. The method has been tested specifically for migrating from `0.8.3`
+to `0.10.2`.
+
+The high level approach is to upgrade to `0.10` and change all serializers to use
+a backwards-compatible `ActiveModel::V08::Serializer`or `ActiveModel::V08::CollectionSerializer`
+and a `ActiveModelSerializers::Adapter::V08Adapter`. After a few more manual changes, you should have the same
+functionality as you had with `AMS 0.8`. Then, you can continue to develop in your app by creating
+new serializers that don't use these backwards compatible versions and slowly migrate
+existing serializers to the `0.10` versions as needed.
+
+### `0.10` breaking changes
+- Passing a serializer to `render json:` is no longer supported
+
+```ruby
+render json: CustomerSerializer.new(customer) # rendered in 0.8, errors in 0.10
+```
+
+- Passing a nil resource to serializer now fails
+
+```ruby
+CustomerSerializer.new(nil) # returned nil in 0.8, throws error in 0.10
+```
+
+- Attribute methods are no longer defined on the serializer, and must be explicitly
+  accessed through `object`
+
+```ruby
+class MySerializer
+  attributes :foo, :bar
+
+  def foo
+    bar + 1 # bar does not work, needs to be object.bar in 0.10
+  end
+end
+```
+
+ - `root` option to collection serializer behaves differently
+
+```ruby
+# in 0.8
+ActiveModel::ArraySerializer.new(resources, root: "resources")
+# resulted in { "resources": <serialized_resources> }, does not work in 0.10
+```
+
+- No default serializer when serializer doesn't exist
+- `@options` changed to `instance_options`
+- Nested relationships are no longer walked by default. Use the `:include` option at **controller `render`** level to specify what relationships to walk. E.g. `render json: @post, include: {comments: :author}` if you want the `author` relationship walked, otherwise the json would only include the post with comments. See: https://github.com/rails-api/active_model_serializers/pull/1127
+- To emulate `0.8`'s walking of arbitrarily deep relationships use: `include: '**'`. E.g. `render json: @post, include: '**'`
+
+## Steps to migrate
+
+### 1. Upgrade the `active_model_serializer` gem in you `Gemfile`
+Change to `gem 'active_model_serializers', '~> 0.10'` and run `bundle install`
+
+### 2. Add `ActiveModel::V08::Serializer`
+
+```ruby
+module ActiveModel
+  module V08
+    class Serializer < ActiveModel::Serializer
+      include Rails.application.routes.url_helpers
+
+      # AMS 0.8 would delegate method calls from within the serializer to the
+      # object.
+      def method_missing(*args)
+        method = args.first
+        read_attribute_for_serialization(method)
+      end
+
+      alias_method :options, :instance_options
+
+      # Since attributes could be read from the `object` via `method_missing`,
+      # the `try` method did not behave as before. This patches `try` with the
+      # original implementation plus the addition of
+      # ` || object.respond_to?(a.first, true)` to check if the object responded to
+      # the given method.
+      def try(*a, &b)
+        if a.empty? || respond_to?(a.first, true) || object.respond_to?(a.first, true)
+          try!(*a, &b)
+        end
+      end
+
+      # AMS 0.8 would return nil if the serializer was initialized with a nil
+      # resource.
+      def serializable_hash(adapter_options = nil,
+                            options = {},
+                            adapter_instance =
+                              self.class.serialization_adapter_instance)
+        object.nil? ? nil : super
+      end
+    end
+  end
+end
+
+```
+Add this class to your app however you see fit. This is the class that your existing serializers
+that inherit from `ActiveModel::Serializer` should inherit from.
+
+### 3. Add `ActiveModel::V08::CollectionSerializer`
+```ruby
+module ActiveModel
+  module V08
+    class CollectionSerializer < ActiveModel::Serializer::CollectionSerializer
+      # In AMS 0.8, passing an ArraySerializer instance with a `root` option
+      # properly nested the serialized resources within the given root.
+      # Ex.
+      #
+      # class MyController < ActionController::Base
+      #   def index
+      #     render json: ActiveModel::Serializer::ArraySerializer
+      #       .new(resources, root: "resources")
+      #   end
+      # end
+      #
+      # Produced
+      #
+      # {
+      #   "resources": [
+      #     <serialized_resource>,
+      #     ...
+      #   ]
+      # }
+      def as_json(options = {})
+        if root
+          {
+            root => super
+          }
+        else
+          super
+        end
+      end
+
+      # AMS 0.8 used `DefaultSerializer` if it couldn't find a serializer for
+      # the given resource. When not using an adapter, this is not true in
+      # `0.10`
+      def serializer_from_resource(resource, serializer_context_class, options)
+        serializer_class =
+          options.fetch(:serializer) { serializer_context_class.serializer_for(resource) }
+
+        if serializer_class.nil? # rubocop:disable Style/GuardClause
+          DefaultSerializer.new(resource, options)
+        else
+          serializer_class.new(resource, options.except(:serializer))
+        end
+      end
+
+      class DefaultSerializer
+        attr_reader :object, :options
+
+        def initialize(object, options={})
+          @object, @options = object, options
+        end
+
+        def serializable_hash
+          @object.as_json(@options)
+        end
+      end
+    end
+  end
+end
+```
+Add this class to your app however you see fit. This is the class that existing uses of
+`ActiveModel::ArraySerializer` should be changed to use.
+
+### 4. Add `ActiveModelSerializers::Adapter::V08Adapter`
+```ruby
+module ActiveModelSerializers
+  module Adapter
+    class V08Adapter < ActiveModelSerializers::Adapter::Base
+      def serializable_hash(options = nil)
+        options ||= {}
+
+        if serializer.respond_to?(:each)
+          if serializer.root
+            delegate_to_json_adapter(options)
+          else
+            serializable_hash_for_collection(options)
+          end
+        else
+          serializable_hash_for_single_resource(options)
+        end
+      end
+
+      def serializable_hash_for_collection(options)
+        serializer.map do |s|
+          V08Adapter.new(s, instance_options)
+            .serializable_hash(options)
+        end
+      end
+
+      def serializable_hash_for_single_resource(options)
+        if serializer.object.is_a?(ActiveModel::Serializer)
+          # It is recommended that you add some logging here to indicate
+          # places that should get converted to eventually allow for this
+          # adapter to get removed.
+          @serializer = serializer.object
+        end
+
+        if serializer.root
+          delegate_to_json_adapter(options)
+        else
+          options = serialization_options(options)
+          serializer.serializable_hash(instance_options, options, self)
+        end
+      end
+
+      def delegate_to_json_adapter(options)
+        ActiveModelSerializers::Adapter::Json
+          .new(serializer, instance_options)
+          .serializable_hash(options)
+      end
+    end
+  end
+end
+```
+Add this class to your app however you see fit.
+
+Add
+```ruby
+ActiveModelSerializers.config.adapter =
+  ActiveModelSerializers::Adapter::V08Adapter
+```
+to `config/active_model_serializer.rb` to configure AMS to use this
+class as the default adapter.
+
+### 5. Change inheritors of `ActiveModel::Serializer` to inherit from `ActiveModel::V08::Serializer`
+Simple find/replace
+
+### 6. Remove `private` keyword from serializers
+Simple find/replace. This is required to allow the `ActiveModel::V08::Serializer`
+to have proper access to the methods defined in the serializer.
+
+You may be able to change the `private` to `protected`, but this is hasn't been tested yet.
+
+### 7. Remove references to `ActiveRecord::Base#active_model_serializer`
+This method is no longer supported in `0.10`.
+
+`0.10` does a good job of discovering serializers for `ActiveRecord` objects.
+
+### 8. Rename `ActiveModel::ArraySerializer` to `ActiveModel::V08::CollectionSerializer`
+Find/replace uses of `ActiveModel::ArraySerializer` with `ActiveModel::V08::CollectionSerializer`.
+
+Also, be sure to change the `each_serializer` keyword to `serializer` when calling making the replacement.
+
+### 9. Replace uses of `@options` to `instance_options` in serializers
+Simple find/replace
+
+## Conclusion
+After you've done the steps above, you should test your app to ensure that everything is still working properly.
+
+If you run into issues, please contribute back to this document so others can benefit from your knowledge.
+

data/docs/integrations/ember-and-json-api.md

@@ -17,25 +17,75 @@ To solve this, in Ember, both the adapter and the serializer will need some modi
 
 ### Server-Side Changes
 
-there are multiple mimetypes for json that should all be parsed similarly, so
-in `config/initializers/mime_types.rb`:
+First, set the adapter type in an initializer file:
+
+```ruby
+# config/initializers/active_model_serializers.rb
+ActiveModelSerializers.config.adapter = :json_api
+```
+
+or:
+
+```ruby
+# config/initializers/active_model_serializers.rb
+ActiveModelSerializers.config.adapter = ActiveModelSerializers::Adapter::JsonApi
+```
+
+You will also want to set the `key_transform` to `:unaltered` since you will adjust the attributes in your Ember serializer to use underscores instead of dashes later. You could also use `:underscore`, but `:unaltered` is better for performance.
+
+```ruby
+# config/initializers/active_model_serializers.rb
+ActiveModelSerializers.config.key_transform = :unaltered
+```
+
+In order to properly handle JSON API responses, we need to register a JSON API renderer, like so:
+
+```ruby
+# config/initializers/active_model_serializers.rb
+ActiveSupport.on_load(:action_controller) do
+  require 'active_model_serializers/register_jsonapi_renderer'
+end
+```
+Rails also requires your controller to tell it that you accept and generate JSONAPI data.  To do that, you use `respond_to` in your controller handlers to tell rails you are consuming and returning jsonapi format data. Without this, Rails will refuse to parse the request body into params.  You can add `ActionController::MimeResponds` to your application controller to enable this:
+
+```ruby
+class ApplicationController < ActionController::API
+  include ActionController::MimeResponds
+end
+```
+Then, in your controller you can tell rails you're accepting and rendering the jsonapi format:
 ```ruby
-api_mime_types = %W(
-  application/vnd.api+json
-  text/x-json
-  application/json
-)
-
-Mime::Type.unregister :json
-Mime::Type.register 'application/json', :json, api_mime_types
+ # POST /post
+  def create
+    @post = Post.new(post_params)
+    respond_to do |format|
+      if @post.save
+        format.jsonapi { render jsonapi: @post, status: :created, location: @post }
+      else
+        format.jsonapi { render jsonapi: @post.errors, status: :unprocessable_entity }
+      end
+    end
+  end
+  
+    # Only allow a trusted parameter "white list" through.
+    def post_params
+      ActiveModelSerializers::Deserialization.jsonapi_parse!(params, only: [:title, :body] )
+    end
+end
 ```
 
+#### Note: 
+In Rails 5, the "unsafe" method ( `jsonapi_parse!` vs the safe `jsonapi_parse`) throws an `InvalidDocument` exception when the payload does not meet basic criteria for JSON API deserialization.
+
+
 ### Adapter Changes
 
 ```javascript
 // app/adapters/application.js
+import Ember from 'ember';
 import DS from 'ember-data';
 import ENV from "../config/environment";
+const { underscore, pluralize } = Ember.String;
 
 export default  DS.JSONAPIAdapter.extend({
   namespace: 'api',
@@ -46,22 +96,10 @@ export default  DS.JSONAPIAdapter.extend({
 
   // allows the multiword paths in urls to be underscored
   pathForType: function(type) {
-    let underscored = Ember.String.underscore(type);
-    return Ember.String.pluralize(underscored);
+    let underscored = underscore(type);
+    return pluralize(underscored);
   },
 
-  // allows queries to be sent along with a findRecord
-  // hopefully Ember / EmberData will soon have this built in
-  // ember-data issue tracked here:
-  // https://github.com/emberjs/data/issues/3596
-  urlForFindRecord(id, modelName, snapshot) {
-    let url = this._super(...arguments);
-    let query = Ember.get(snapshot, 'adapterOptions.query');
-    if(query) {
-      url += '?' + Ember.$.param(query);
-    }
-    return url;
-  }
 });
 ```
 
@@ -85,22 +123,19 @@ export default DS.JSONAPISerializer.extend({
 
 ```
 
-## Including Nested Resources
 
-Previously, `store.find` and `store.findRecord` did not allow specification of any query params.
-The ActiveModelSerializers default for the `include` parameter is to be `nil` meaning that if any associations are defined in your serializer, only the `id` and `type` will be in the `relationships` structure of the JSON API response.
-For more on `include` usage, see: [The JSON API include examples](./../general/adapters.md#JSON-API)
+## Including Nested Resources
 
-With the above modifications, you can execute code as below in order to include nested resources while doing a find query.
+Ember Data can request related records by using `include`.  Below are some examples of how to make Ember Data request the inclusion of related records. For more on `include` usage, see: [The JSON API include examples](./../general/adapters.md#JSON-API)
 
 ```javascript
-store.findRecord('post', postId, { adapterOptions: { query: { include: 'comments' } } });
+store.findRecord('post', postId, { include: 'comments' } );
 ```
-will generate the path `/posts/{postId}?include='comments'`
+which will generate the path /posts/{postId}?include='comments'
 
 So then in your controller, you'll want to be sure to have something like:
 ```ruby
-render json: @post, include: params[:include]
+render jsonapi: @post, include: params[:include]
 ```
 
 If you want to use `include` on a collection, you'd write something like this:

data/docs/jsonapi/schema.md

@@ -28,7 +28,7 @@ Example supported requests
 - Relationships
   - GET /articles/1/relationships/comments
   - GET /articles/1/relationships/author
-- Optional: [Inclusion of related resources](http://jsonapi.org/format/#fetching-includes) `ActiveModel::Serializer::IncludeTree`
+- Optional: [Inclusion of related resources](http://jsonapi.org/format/#fetching-includes) `JSONAPI::IncludeDirective`
   - GET /articles/1?`include`=comments
   - GET /articles/1?`include`=comments.author
   - GET /articles/1?`include`=author,comments.author

data/lib/action_controller/serialization.rb

@@ -16,19 +16,29 @@ module ActionController
     included do
       class_attribute :_serialization_scope
       self._serialization_scope = :current_user
+
+      attr_writer :namespace_for_serializer
+    end
+
+    def namespace_for_serializer
+      @namespace_for_serializer ||= self.class.parent unless self.class.parent == Object
     end
 
     def serialization_scope
-      send(_serialization_scope) if _serialization_scope &&
-        respond_to?(_serialization_scope, true)
+      return unless _serialization_scope && respond_to?(_serialization_scope, true)
+
+      send(_serialization_scope)
     end
 
     def get_serializer(resource, options = {})
-      if !use_adapter?
+      unless use_adapter?
         warn 'ActionController::Serialization#use_adapter? has been removed. '\
           "Please pass 'adapter: false' or see ActiveSupport::SerializableResource.new"
         options[:adapter] = false
       end
+
+      options.fetch(:namespace) { options[:namespace] = namespace_for_serializer }
+
       serializable_resource = ActiveModelSerializers::SerializableResource.new(resource, options)
       serializable_resource.serialization_scope ||= options.fetch(:scope) { serialization_scope }
       serializable_resource.serialization_scope_name = options.fetch(:scope_name) { _serialization_scope }

data/lib/active_model/serializer/adapter/base.rb

@@ -7,9 +7,11 @@ module ActiveModel
           deprecate :inherited, 'ActiveModelSerializers::Adapter::Base.'
         end
 
+        # :nocov:
         def initialize(serializer, options = {})
           super(ActiveModelSerializers::Adapter::Base.new(serializer, options))
         end
+        # :nocov:
       end
     end
   end

data/lib/active_model/serializer/array_serializer.rb

@@ -1,9 +1,12 @@
 require 'active_model/serializer/collection_serializer'
-class ActiveModel::Serializer
-  class ArraySerializer < CollectionSerializer
-    class << self
-      extend ActiveModelSerializers::Deprecate
-      deprecate :new, 'ActiveModel::Serializer::CollectionSerializer.'
+
+module ActiveModel
+  class Serializer
+    class ArraySerializer < CollectionSerializer
+      class << self
+        extend ActiveModelSerializers::Deprecate
+        deprecate :new, 'ActiveModel::Serializer::CollectionSerializer.'
+      end
     end
   end
 end

data/lib/active_model/serializer/association.rb

@@ -1,19 +1,71 @@
+require 'active_model/serializer/lazy_association'
+
 module ActiveModel
   class Serializer
-    # This class hold all information about serializer's association.
+    # This class holds all information about serializer's association.
     #
-    # @attr [Symbol] name
-    # @attr [ActiveModel::Serializer] serializer
-    # @attr [Hash{Symbol => Object}] options
-    #
-    # @example
-    #  Association.new(:comments, CommentSummarySerializer)
-    #
-    Association = Struct.new(:name, :serializer, :options, :links, :meta) do
+    # @api private
+    Association = Struct.new(:reflection, :association_options) do
+      attr_reader :lazy_association
+      delegate :object, :include_data?, :virtual_value, :collection?, to: :lazy_association
+
+      def initialize(*)
+        super
+        @lazy_association = LazyAssociation.new(reflection, association_options)
+      end
+
+      # @return [Symbol]
+      delegate :name, to: :reflection
+
       # @return [Symbol]
       def key
-        options.fetch(:key, name)
+        reflection_options.fetch(:key, name)
+      end
+
+      # @return [True,False]
+      def key?
+        reflection_options.key?(:key)
+      end
+
+      # @return [Hash]
+      def links
+        reflection_options.fetch(:links) || {}
+      end
+
+      # @return [Hash, nil]
+      # This gets mutated, so cannot use the cached reflection_options
+      def meta
+        reflection.options[:meta]
+      end
+
+      def belongs_to?
+        reflection.foreign_key_on == :self
+      end
+
+      def polymorphic?
+        true == reflection_options[:polymorphic]
+      end
+
+      # @api private
+      def serializable_hash(adapter_options, adapter_instance)
+        association_serializer = lazy_association.serializer
+        return virtual_value if virtual_value
+        association_object = association_serializer && association_serializer.object
+        return unless association_object
+
+        serialization = association_serializer.serializable_hash(adapter_options, {}, adapter_instance)
+
+        if polymorphic? && serialization
+          polymorphic_type = association_object.class.name.underscore
+          serialization = { type: polymorphic_type, polymorphic_type.to_sym => serialization }
+        end
+
+        serialization
       end
+
+      private
+
+      delegate :reflection_options, to: :lazy_association
     end
   end
 end

data/lib/active_model/serializer/belongs_to_reflection.rb

@@ -1,9 +1,10 @@
 module ActiveModel
   class Serializer
     # @api private
-    class BelongsToReflection < SingularReflection
-      def macro
-        :belongs_to
+    class BelongsToReflection < Reflection
+      # @api private
+      def foreign_key_on
+        :self
       end
     end
   end

data/lib/active_model/serializer/collection_serializer.rb

@@ -1,7 +1,6 @@
 module ActiveModel
   class Serializer
     class CollectionSerializer
-      NoSerializerError = Class.new(StandardError)
       include Enumerable
       delegate :each, to: :@serializers
 
@@ -11,22 +10,23 @@ module ActiveModel
         @object                  = resources
         @options                 = options
         @root                    = options[:root]
-        serializer_context_class = options.fetch(:serializer_context_class, ActiveModel::Serializer)
-        @serializers = resources.map do |resource|
-          serializer_class = options.fetch(:serializer) { serializer_context_class.serializer_for(resource) }
-
-          if serializer_class.nil? # rubocop:disable Style/GuardClause
-            fail NoSerializerError, "No serializer found for resource: #{resource.inspect}"
-          else
-            serializer_class.new(resource, options.except(:serializer))
-          end
-        end
+        @serializers             = serializers_from_resources
       end
 
       def success?
         true
       end
 
+      # @api private
+      def serializable_hash(adapter_options, options, adapter_instance)
+        include_directive = ActiveModel::Serializer.include_directive_from_options(adapter_options)
+        adapter_options[:cached_attributes] ||= ActiveModel::Serializer.cache_read_multi(self, adapter_instance, include_directive)
+        adapter_opts = adapter_options.merge(include_directive: include_directive)
+        serializers.map do |serializer|
+          serializer.serializable_hash(adapter_opts, options, adapter_instance)
+        end
+      end
+
       # TODO: unify naming of root, json_key, and _type.  Right now, a serializer's
       # json_key comes from the root option or the object's model name, by default.
       # But, if a dev defines a custom `json_key` method with an explicit value,
@@ -51,7 +51,8 @@ module ActiveModel
       # rubocop:enable Metrics/CyclomaticComplexity
 
       def paginated?
-        object.respond_to?(:current_page) &&
+        ActiveModelSerializers.config.jsonapi_pagination_links_enabled &&
+          object.respond_to?(:current_page) &&
           object.respond_to?(:total_pages) &&
           object.respond_to?(:size)
       end
@@ -59,6 +60,28 @@ module ActiveModel
       protected
 
       attr_reader :serializers, :options
+
+      private
+
+      def serializers_from_resources
+        serializer_context_class = options.fetch(:serializer_context_class, ActiveModel::Serializer)
+        object.map do |resource|
+          serializer_from_resource(resource, serializer_context_class, options)
+        end
+      end
+
+      def serializer_from_resource(resource, serializer_context_class, options)
+        serializer_class = options.fetch(:serializer) do
+          serializer_context_class.serializer_for(resource, namespace: options[:namespace])
+        end
+
+        if serializer_class.nil?
+          ActiveModelSerializers.logger.debug "No serializer found for resource: #{resource.inspect}"
+          throw :no_serializer
+        else
+          serializer_class.new(resource, options.except(:serializer))
+        end
+      end
     end
   end
 end