agi_active_model_serializers 0.10.7

data/docs/rfcs/0000-namespace.md

@@ -0,0 +1,106 @@
+- Start Date: (2015-10-29)
+- RFC PR: https://github.com/rails-api/active_model_serializers/pull/1310
+- ActiveModelSerializers Issue: https://github.com/rails-api/active_model_serializers/issues/1298
+
+# Summary
+
+Provide a consistent API for the user of the AMS.
+
+# Motivation
+
+The actual public API is defined under `ActiveModelSerializers`,
+`ActiveModel::Serializer` and `ActiveModel`.
+
+At the `ActiveModel::Serializer` we have:
+
+- `ActiveModel::Serializer.config`
+- `ActiveModel::Serializer`
+
+At the `ActiveModelSerializers` we have:
+
+- `ActiveModelSerializers::Model`
+- `ActiveModelSerializers.logger`
+
+At `ActiveModel` we have:
+
+- `ActiveModel::SerializableResource`
+
+The idea here is to provide a single namespace `ActiveModelSerializers` to the user.
+Following the same idea we have on other gems like
+[Devise](https://github.com/plataformatec/devise/blob/e9c82472ffe7c43a448945f77e034a0e47dde0bb/lib/devise.rb),
+[Refile](https://github.com/refile/refile/blob/6b24c293d044862dafbf1bfa4606672a64903aa2/lib/refile.rb) and
+[Active Job](https://github.com/rails/rails/blob/30bacc26f8f258b39e12f63fe52389a968d9c1ea/activejob/lib/active_job.rb)
+for example.
+
+This way we are clarifing the boundaries of
+[ActiveModelSerializers and Rails](https://github.com/rails-api/active_model_serializers/blob/master/CHANGELOG.md#prehistory)
+and make clear that the `ActiveModel::Serializer` class is no longer the primary
+behavior of the ActiveModelSerializers.
+
+# Detailed design
+
+## New classes and modules organization
+
+Since this will be a big change we can do this on baby steps, read small pull requests. A
+possible approach is:
+
+- All new code will be in `lib/active_model_serializers/` using
+  the module namespace `ActiveModelSerializers`.
+- Move all content under `ActiveModel::Serializer` to be under
+  `ActiveModelSerializers`, the adapter is on this steps;
+- Move all content under `ActiveModel` to be under `ActiveModelSerializers`,
+  the `SerializableResource` is on this step;
+- Change all public API that doesn't make sense, keeping in mind only to keep
+  this in the same namespace
+- Update the README;
+- Update the docs;
+
+The following table represents the current and the desired classes and modules
+at the first moment.
+
+| Current                                                | Desired                                          | Notes              |
+|--------------------------------------------------------|--------------------------------------------------|--------------------|
+| `ActiveModelSerializers` and `ActiveModel::Serializer` | `ActiveModelSerializers`                         | The main namespace |
+| `ActiveModelSerializers.logger`                        | `ActiveModelSerializers.logger`                  ||
+| `ActiveModelSerializers::Model`                        | `ActiveModelSerializers::Model`                  ||
+| `ActiveModel::SerializableResource`                    | `ActiveModelSerializers::SerializableResource`   ||
+| `ActiveModel::Serializer`                              | `ActiveModelSerializers::Serializer`             | The name can be discussed in a future pull request. For example, we can rename this to `Resource` [following this idea](https://github.com/rails-api/active_model_serializers/pull/1301/files#r42963185) more info about naming in the next section|
+| `ActiveModel::Serializer.config`                       | `ActiveModelSerializers.config`                ||
+
+## Renaming of class and modules
+
+When moving some content to the new namespace we can find some names that does
+not make much sense like `ActiveModel::Serializer::Adapter::JsonApi`.
+Discussion of renaming existing classes / modules and JsonApi objects will
+happen in separate pull requests, and issues, and in the google doc
+https://docs.google.com/document/d/1rcrJr0sVcazY2Opd_6Kmv1iIwuHbI84s1P_NzFn-05c/edit?usp=sharing
+
+Some of names already have a definition.
+
+- Adapters get their own namespace under ActiveModelSerializers. E.g
+  `ActiveModelSerializers::Adapter`
+- Serializers get their own namespace under ActiveModelSerializers. E.g
+  `ActiveModelSerializers::Serializer`
+
+## Keeping compatibility
+
+All moved classes or modules be aliased to their old name and location with
+deprecation warnings, such as
+[was done for CollectionSerializer](https://github.com/rails-api/active_model_serializers/pull/1251).
+
+# Drawbacks
+
+This will be a breaking change, so all users serializers will be broken after a
+major bump.
+All pull requests will need to rebase since the architeture will change a lot.
+
+# Alternatives
+
+We can keep the way it is, and keep in mind to not add another namespace as a
+public API.
+
+# Unresolved questions
+
+What is the better class name to be used to the class that will be inherited at
+the creation of a serializer. This can be discussed in other RFC or directly via
+pull request.

data/docs/rfcs/template.md

@@ -0,0 +1,15 @@
+- Start Date: (YYYY-MM-DD)
+- RFC PR: https://github.com/rails-api/active_model_serializers/pull/dddd
+- ActiveModelSerializers Issue: https://github.com/rails-api/active_model_serializers/issues/dddd
+
+# Summary
+
+# Motivation
+
+# Detailed design
+
+# Drawbacks
+
+# Alternatives
+
+# Unresolved questions

data/lib/action_controller/serialization.rb

@@ -0,0 +1,66 @@
+require 'active_support/core_ext/class/attribute'
+require 'active_model_serializers/serialization_context'
+
+module ActionController
+  module Serialization
+    extend ActiveSupport::Concern
+
+    include ActionController::Renderers
+
+    module ClassMethods
+      def serialization_scope(scope)
+        self._serialization_scope = scope
+      end
+    end
+
+    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
+      return unless _serialization_scope && respond_to?(_serialization_scope, true)
+
+      send(_serialization_scope)
+    end
+
+    def get_serializer(resource, options = {})
+      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 }
+      # For compatibility with the JSON renderer: `json.to_json(options) if json.is_a?(String)`.
+      # Otherwise, since `serializable_resource` is not a string, the renderer would call
+      # `to_json` on a String and given odd results, such as `"".to_json #=> '""'`
+      serializable_resource.adapter.is_a?(String) ? serializable_resource.adapter : serializable_resource
+    end
+
+    # Deprecated
+    def use_adapter?
+      true
+    end
+
+    [:_render_option_json, :_render_with_renderer_json].each do |renderer_method|
+      define_method renderer_method do |resource, options|
+        options.fetch(:serialization_context) do
+          options[:serialization_context] = ActiveModelSerializers::SerializationContext.new(request, options)
+        end
+        serializable_resource = get_serializer(resource, options)
+        super(serializable_resource, options)
+      end
+    end
+  end
+end

data/lib/active_model/serializable_resource.rb

@@ -0,0 +1,11 @@
+require 'set'
+
+module ActiveModel
+  class SerializableResource
+    class << self
+      extend ActiveModelSerializers::Deprecate
+
+      delegate_and_deprecate :new, ActiveModelSerializers::SerializableResource
+    end
+  end
+end

data/lib/active_model/serializer.rb

@@ -0,0 +1,231 @@
+require 'thread_safe'
+require 'jsonapi/include_directive'
+require 'active_model/serializer/collection_serializer'
+require 'active_model/serializer/array_serializer'
+require 'active_model/serializer/error_serializer'
+require 'active_model/serializer/errors_serializer'
+require 'active_model/serializer/concerns/associations'
+require 'active_model/serializer/concerns/attributes'
+require 'active_model/serializer/concerns/caching'
+require 'active_model/serializer/concerns/configuration'
+require 'active_model/serializer/concerns/links'
+require 'active_model/serializer/concerns/meta'
+require 'active_model/serializer/concerns/type'
+require 'active_model/serializer/fieldset'
+require 'active_model/serializer/lint'
+
+# ActiveModel::Serializer is an abstract class that is
+# 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
+    include Configuration
+    include Associations
+    include Attributes
+    include Caching
+    include Links
+    include Meta
+    include Type
+
+    # @param resource [ActiveRecord::Base, ActiveModelSerializers::Model]
+    # @return [ActiveModel::Serializer]
+    #   Preferentially returns
+    #   1. resource.serializer
+    #   2. ArraySerializer when resource is a collection
+    #   3. options[:serializer]
+    #   4. lookup serializer when resource is a Class
+    def self.serializer_for(resource, options = {})
+      if resource.respond_to?(:serializer_class)
+        resource.serializer_class
+      elsif resource.respond_to?(:to_ary)
+        config.collection_serializer
+      else
+        options.fetch(:serializer) { get_serializer_for(resource.class, options[:namespace]) }
+      end
+    end
+
+    # @see ActiveModelSerializers::Adapter.lookup
+    # Deprecated
+    def self.adapter
+      ActiveModelSerializers::Adapter.lookup(config.adapter)
+    end
+    class << self
+      extend ActiveModelSerializers::Deprecate
+      deprecate :adapter, 'ActiveModelSerializers::Adapter.configured_adapter'
+    end
+
+    # @api private
+    def self.serializer_lookup_chain_for(klass, namespace = nil)
+      lookups = ActiveModelSerializers.config.serializer_lookup_chain
+      Array[*lookups].flat_map do |lookup|
+        lookup.call(klass, self, namespace)
+      end.compact
+    end
+
+    # Used to cache serializer name => serializer class
+    # when looked up by Serializer.get_serializer_for.
+    def self.serializers_cache
+      @serializers_cache ||= ThreadSafe::Cache.new
+    end
+
+    # @api private
+    # Find a serializer from a class and caches the lookup.
+    # Preferentially returns:
+    #   1. class name appended with "Serializer"
+    #   2. try again with superclass, if present
+    #   3. nil
+    def self.get_serializer_for(klass, namespace = nil)
+      return nil unless config.serializer_lookup_enabled
+
+      cache_key = ActiveSupport::Cache.expand_cache_key(klass, namespace)
+      serializers_cache.fetch_or_store(cache_key) do
+        # NOTE(beauby): When we drop 1.9.3 support we can lazify the map for perfs.
+        lookup_chain = serializer_lookup_chain_for(klass, namespace)
+        serializer_class = lookup_chain.map(&:safe_constantize).find { |x| x && x < ActiveModel::Serializer }
+
+        if serializer_class
+          serializer_class
+        elsif klass.superclass
+          get_serializer_for(klass.superclass)
+        end
+      end
+    end
+
+    # @api private
+    def self.include_directive_from_options(options)
+      if options[:include_directive]
+        options[:include_directive]
+      elsif options[:include]
+        JSONAPI::IncludeDirective.new(options[:include], allow_wildcard: true)
+      else
+        ActiveModelSerializers.default_include_directive
+      end
+    end
+
+    # @api private
+    def self.serialization_adapter_instance
+      @serialization_adapter_instance ||= ActiveModelSerializers::Adapter::Attributes
+    end
+
+    attr_accessor :object, :root, :scope
+
+    # `scope_name` is set as :current_user by default in the controller.
+    # If the instance does not have a method named `scope_name`, it
+    # defines the method so that it calls the +scope+.
+    def initialize(object, options = {})
+      self.object = object
+      self.instance_options = options
+      self.root = instance_options[:root]
+      self.scope = instance_options[:scope]
+
+      return if !(scope_name = instance_options[:scope_name]) || respond_to?(scope_name)
+
+      define_singleton_method scope_name, -> { scope }
+    end
+
+    def success?
+      true
+    end
+
+    # @return [Hash] containing the attributes and first level
+    # associations, similar to how ActiveModel::Serializers::JSON is used
+    # in ActiveRecord::Base.
+    #
+    # TODO: Include <tt>ActiveModel::Serializers::JSON</tt>.
+    # So that the below is true:
+    #   @param options [nil, Hash] The same valid options passed to `serializable_hash`
+    #      (:only, :except, :methods, and :include).
+    #
+    #     See
+    #     https://github.com/rails/rails/blob/v5.0.0.beta2/activemodel/lib/active_model/serializers/json.rb#L17-L101
+    #     https://github.com/rails/rails/blob/v5.0.0.beta2/activemodel/lib/active_model/serialization.rb#L85-L123
+    #     https://github.com/rails/rails/blob/v5.0.0.beta2/activerecord/lib/active_record/serialization.rb#L11-L17
+    #     https://github.com/rails/rails/blob/v5.0.0.beta2/activesupport/lib/active_support/core_ext/object/json.rb#L147-L162
+    #
+    #   @example
+    #     # The :only and :except options can be used to limit the attributes included, and work
+    #     # similar to the attributes method.
+    #     serializer.as_json(only: [:id, :name])
+    #     serializer.as_json(except: [:id, :created_at, :age])
+    #
+    #     # To include the result of some method calls on the model use :methods:
+    #     serializer.as_json(methods: :permalink)
+    #
+    #     # To include associations use :include:
+    #     serializer.as_json(include: :posts)
+    #     # Second level and higher order associations work as well:
+    #     serializer.as_json(include: { posts: { include: { comments: { only: :body } }, only: :title } })
+    def serializable_hash(adapter_options = nil, options = {}, adapter_instance = self.class.serialization_adapter_instance)
+      adapter_options ||= {}
+      options[:include_directive] ||= ActiveModel::Serializer.include_directive_from_options(adapter_options)
+      cached_attributes = adapter_options[:cached_attributes] ||= {}
+      resource = fetch_attributes(options[:fields], cached_attributes, adapter_instance)
+      relationships = resource_relationships(adapter_options, options, adapter_instance)
+      resource.merge(relationships)
+    end
+    alias to_hash serializable_hash
+    alias to_h serializable_hash
+
+    # @see #serializable_hash
+    # TODO: When moving attributes adapter logic here, @see #serializable_hash
+    # So that the below is true:
+    #   @param options [nil, Hash] The same valid options passed to `as_json`
+    #      (:root, :only, :except, :methods, and :include).
+    #   The default for `root` is nil.
+    #   The default value for include_root is false. You can change it to true if the given
+    #   JSON string includes a single root node.
+    def as_json(adapter_opts = nil)
+      serializable_hash(adapter_opts)
+    end
+
+    # Used by adapter as resource root.
+    def json_key
+      root || _type || object.class.model_name.to_s.underscore
+    end
+
+    def read_attribute_for_serialization(attr)
+      if respond_to?(attr)
+        send(attr)
+      else
+        object.read_attribute_for_serialization(attr)
+      end
+    end
+
+    # @api private
+    def resource_relationships(adapter_options, options, adapter_instance)
+      relationships = {}
+      include_directive = options.fetch(:include_directive)
+      associations(include_directive).each do |association|
+        adapter_opts = adapter_options.merge(include_directive: include_directive[association.key])
+        relationships[association.key] ||= relationship_value_for(association, adapter_opts, adapter_instance)
+      end
+
+      relationships
+    end
+
+    # @api private
+    def relationship_value_for(association, adapter_options, adapter_instance)
+      return association.options[:virtual_value] if association.options[:virtual_value]
+      association_serializer = association.serializer
+      association_object = association_serializer && association_serializer.object
+      return unless association_object
+
+      relationship_value = association_serializer.serializable_hash(adapter_options, {}, adapter_instance)
+
+      if association.options[:polymorphic] && relationship_value
+        polymorphic_type = association_object.class.name.underscore
+        relationship_value = { type: polymorphic_type, polymorphic_type.to_sym => relationship_value }
+      end
+
+      relationship_value
+    end
+
+    protected
+
+    attr_accessor :instance_options
+  end
+end

data/lib/active_model/serializer/adapter.rb

@@ -0,0 +1,24 @@
+require 'active_model_serializers/adapter'
+require 'active_model_serializers/deprecate'
+
+module ActiveModel
+  class Serializer
+    # @deprecated Use ActiveModelSerializers::Adapter instead
+    module Adapter
+      class << self
+        extend ActiveModelSerializers::Deprecate
+
+        DEPRECATED_METHODS = [:create, :adapter_class, :adapter_map, :adapters, :register, :lookup].freeze
+        DEPRECATED_METHODS.each do |method|
+          delegate_and_deprecate method, ActiveModelSerializers::Adapter
+        end
+      end
+    end
+  end
+end
+
+require 'active_model/serializer/adapter/base'
+require 'active_model/serializer/adapter/null'
+require 'active_model/serializer/adapter/attributes'
+require 'active_model/serializer/adapter/json'
+require 'active_model/serializer/adapter/json_api'