active_model_serializers 0.10.0 → 0.10.11

data/lib/active_model_serializers/adapter/json_api.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # {http://jsonapi.org/format/ JSON API specification}
 # rubocop:disable Style/AsciiComments
 # TODO: implement!
@@ -22,25 +24,38 @@ module ActiveModelSerializers
   module Adapter
     class JsonApi < Base
       extend ActiveSupport::Autoload
-      autoload :Jsonapi
-      autoload :ResourceIdentifier
-      autoload :Relationship
-      autoload :Link
-      autoload :PaginationLinks
-      autoload :Meta
-      autoload :Error
-      autoload :Deserialization
-
-      def initialize(serializer, options = {})
-        super
-        @include_tree = ActiveModel::Serializer::IncludeTree.from_include_args(options[:include])
-        @fieldset = options[:fieldset] || ActiveModel::Serializer::Fieldset.new(options.delete(:fields))
+      eager_autoload do
+        autoload :Jsonapi
+        autoload :ResourceIdentifier
+        autoload :Link
+        autoload :PaginationLinks
+        autoload :Meta
+        autoload :Error
+        autoload :Deserialization
+        autoload :Relationship
       end
 
       def self.default_key_transform
         :dash
       end
 
+      def self.fragment_cache(cached_hash, non_cached_hash, root = true)
+        core_cached       = cached_hash.first
+        core_non_cached   = non_cached_hash.first
+        no_root_cache     = cached_hash.delete_if { |key, _value| key == core_cached[0] }
+        no_root_non_cache = non_cached_hash.delete_if { |key, _value| key == core_non_cached[0] }
+        cached_resource   = (core_cached[1]) ? core_cached[1].deep_merge(core_non_cached[1]) : core_non_cached[1]
+        hash = root ? { root => cached_resource } : cached_resource
+
+        hash.deep_merge no_root_non_cache.deep_merge no_root_cache
+      end
+
+      def initialize(serializer, options = {})
+        super
+        @include_directive = JSONAPI::IncludeDirective.new(options[:include], allow_wildcard: true)
+        @fieldset = options[:fieldset] || ActiveModel::Serializer::Fieldset.new(options.delete(:fields))
+      end
+
       # {http://jsonapi.org/format/#crud Requests are transactional, i.e. success or failure}
       # {http://jsonapi.org/format/#document-top-level data and errors MUST NOT coexist in the same document.}
       def serializable_hash(*)
@@ -52,6 +67,11 @@ module ActiveModelSerializers
         self.class.transform_key_casing!(document, instance_options)
       end
 
+      def fragment_cache(cached_hash, non_cached_hash)
+        root = !instance_options.include?(:include)
+        self.class.fragment_cache(cached_hash, non_cached_hash, root)
+      end
+
       # {http://jsonapi.org/format/#document-top-level Primary data}
       # definition:
       #   ☐ toplevel_data (required)
@@ -174,18 +194,6 @@ module ActiveModelSerializers
         hash
       end
 
-      def fragment_cache(cached_hash, non_cached_hash)
-        root = false if instance_options.include?(:include)
-        core_cached       = cached_hash.first
-        core_non_cached   = non_cached_hash.first
-        no_root_cache     = cached_hash.delete_if { |key, _value| key == core_cached[0] }
-        no_root_non_cache = non_cached_hash.delete_if { |key, _value| key == core_non_cached[0] }
-        cached_resource   = (core_cached[1]) ? core_cached[1].deep_merge(core_non_cached[1]) : core_non_cached[1]
-        hash = root ? { root => cached_resource } : cached_resource
-
-        hash.deep_merge no_root_non_cache.deep_merge no_root_cache
-      end
-
       protected
 
       attr_reader :fieldset
@@ -231,17 +239,17 @@ module ActiveModelSerializers
         @primary = []
         @included = []
         @resource_identifiers = Set.new
-        serializers.each { |serializer| process_resource(serializer, true) }
-        serializers.each { |serializer| process_relationships(serializer, @include_tree) }
+        serializers.each { |serializer| process_resource(serializer, true, @include_directive) }
+        serializers.each { |serializer| process_relationships(serializer, @include_directive) }
 
         [@primary, @included]
       end
 
-      def process_resource(serializer, primary)
+      def process_resource(serializer, primary, include_slice = {})
         resource_identifier = ResourceIdentifier.new(serializer, instance_options).as_json
         return false unless @resource_identifiers.add?(resource_identifier)
 
-        resource_object = resource_object_for(serializer)
+        resource_object = resource_object_for(serializer, include_slice)
         if primary
           @primary << resource_object
         else
@@ -251,21 +259,22 @@ module ActiveModelSerializers
         true
       end
 
-      def process_relationships(serializer, include_tree)
-        serializer.associations(include_tree).each do |association|
-          process_relationship(association.serializer, include_tree[association.key])
+      def process_relationships(serializer, include_slice)
+        serializer.associations(include_slice).each do |association|
+          # TODO(BF): Process relationship without evaluating lazy_association
+          process_relationship(association.lazy_association.serializer, include_slice[association.key])
         end
       end
 
-      def process_relationship(serializer, include_tree)
+      def process_relationship(serializer, include_slice)
         if serializer.respond_to?(:each)
-          serializer.each { |s| process_relationship(s, include_tree) }
+          serializer.each { |s| process_relationship(s, include_slice) }
           return
         end
         return unless serializer && serializer.object
-        return unless process_resource(serializer, false)
+        return unless process_resource(serializer, false, include_slice)
 
-        process_relationships(serializer, include_tree)
+        process_relationships(serializer, include_slice)
       end
 
       # {http://jsonapi.org/format/#document-resource-object-attributes Document Resource Object Attributes}
@@ -289,21 +298,9 @@ module ActiveModelSerializers
       end
 
       # {http://jsonapi.org/format/#document-resource-objects Document Resource Objects}
-      def resource_object_for(serializer)
-        resource_object = cache_check(serializer) do
-          resource_object = ResourceIdentifier.new(serializer, instance_options).as_json
-
-          requested_fields = fieldset && fieldset.fields_for(resource_object[:type])
-          attributes = attributes_for(serializer, requested_fields)
-          resource_object[:attributes] = attributes if attributes.any?
-          resource_object
-        end
+      def resource_object_for(serializer, include_slice = {})
+        resource_object = data_for(serializer, include_slice)
 
-        requested_associations = fieldset.fields_for(resource_object[:type]) || '*'
-        relationships = relationships_for(serializer, requested_associations)
-        resource_object[:relationships] = relationships if relationships.any?
-
-        links = links_for(serializer)
         # toplevel_links
         # definition:
         #   allOf
@@ -317,7 +314,10 @@ module ActiveModelSerializers
         # prs:
         #   https://github.com/rails-api/active_model_serializers/pull/1247
         #   https://github.com/rails-api/active_model_serializers/pull/1018
-        resource_object[:links] = links if links.any?
+        if (links = links_for(serializer)).any?
+          resource_object ||= {}
+          resource_object[:links] = links
+        end
 
         # toplevel_meta
         #   alias meta
@@ -327,12 +327,33 @@ module ActiveModelSerializers
         #   {
         #     :'git-ref' => 'abc123'
         #   }
-        meta = meta_for(serializer)
-        resource_object[:meta] = meta unless meta.blank?
+        if (meta = meta_for(serializer)).present?
+          resource_object ||= {}
+          resource_object[:meta] = meta
+        end
 
         resource_object
       end
 
+      def data_for(serializer, include_slice)
+        data = serializer.fetch(self) do
+          resource_object = ResourceIdentifier.new(serializer, instance_options).as_json
+          break nil if resource_object.nil?
+
+          requested_fields = fieldset && fieldset.fields_for(resource_object[:type])
+          attributes = attributes_for(serializer, requested_fields)
+          resource_object[:attributes] = attributes if attributes.any?
+          resource_object
+        end
+        data.tap do |resource_object|
+          next if resource_object.nil?
+          # NOTE(BF): the attributes are cached above, separately from the relationships, below.
+          requested_associations = fieldset.fields_for(resource_object[:type]) || '*'
+          relationships = relationships_for(serializer, requested_associations, include_slice)
+          resource_object[:relationships] = relationships if relationships.any?
+        end
+      end
+
       # {http://jsonapi.org/format/#document-resource-object-relationships Document Resource Object Relationship}
       # relationships
       # definition:
@@ -428,17 +449,13 @@ module ActiveModelSerializers
       #     id: 'required-id',
       #     meta: meta
       #   }.reject! {|_,v| v.nil? }
-      def relationships_for(serializer, requested_associations)
-        include_tree = ActiveModel::Serializer::IncludeTree.from_include_args(requested_associations)
-        serializer.associations(include_tree).each_with_object({}) do |association, hash|
-          hash[association.key] = Relationship.new(
-            serializer,
-            association.serializer,
-            instance_options,
-            options: association.options,
-            links: association.links,
-            meta: association.meta
-          ).as_json
+      def relationships_for(serializer, requested_associations, include_slice)
+        include_directive = JSONAPI::IncludeDirective.new(
+          requested_associations,
+          allow_wildcard: true
+        )
+        serializer.associations(include_directive, include_slice).each_with_object({}) do |association, hash|
+          hash[association.key] = Relationship.new(serializer, instance_options, association).as_json
         end
       end
 
@@ -467,7 +484,9 @@ module ActiveModelSerializers
       #   }.reject! {|_,v| v.nil? }
       def links_for(serializer)
         serializer._links.each_with_object({}) do |(name, value), hash|
-          hash[name] = Link.new(serializer, value).as_json
+          next if value.excluded?(serializer)
+          result = Link.new(serializer, value.block).as_json
+          hash[name] = result if result
         end
       end
 

data/lib/active_model_serializers/adapter/null.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveModelSerializers
   module Adapter
     class Null < Base

data/lib/active_model_serializers/adapter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveModelSerializers
   module Adapter
     UnknownAdapterError = Class.new(ArgumentError)
@@ -5,11 +7,13 @@ module ActiveModelSerializers
     private_constant :ADAPTER_MAP if defined?(private_constant)
 
     class << self # All methods are class functions
+      # :nocov:
       def new(*args)
         fail ArgumentError, 'Adapters inherit from Adapter::Base.' \
           "Adapter.new called with args: '#{args.inspect}', from" \
           "'caller[0]'."
       end
+      # :nocov:
 
       def configured_adapter
         lookup(ActiveModelSerializers.config.adapter)
@@ -33,7 +37,7 @@ module ActiveModelSerializers
 
       # @return [Array<Symbol>] list of adapter names
       def adapters
-        adapter_map.keys.sort
+        adapter_map.keys.sort!
       end
 
       # Adds an adapter 'klass' with 'name' to the 'adapter_map'
@@ -51,6 +55,10 @@ module ActiveModelSerializers
         self
       end
 
+      def registered_name(adapter_class)
+        ADAPTER_MAP.key adapter_class
+      end
+
       # @param  adapter [String, Symbol, Class] name to fetch adapter by
       # @return [ActiveModelSerializers::Adapter] subclass of Adapter
       # @raise  [UnknownAdapterError]

data/lib/active_model_serializers/callbacks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Adapted from
 # https://github.com/rails/rails/blob/7f18ea14c8/activejob/lib/active_job/callbacks.rb
 require 'active_support/callbacks'

data/lib/active_model_serializers/deprecate.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 ##
 # Provides a single method +deprecate+ to be used to declare when
 # something is going away.
@@ -36,8 +38,7 @@ module ActiveModelSerializers
           target = is_a?(Module) ? "#{self}." : "#{self.class}#"
           msg = ["NOTE: #{target}#{name} is deprecated",
                  replacement == :none ? ' with no replacement' : "; use #{replacement} instead",
-                 "\n#{target}#{name} called from #{ActiveModelSerializers.location_of_caller.join(":")}"
-                ]
+                 "\n#{target}#{name} called from #{ActiveModelSerializers.location_of_caller.join(':')}"]
           warn "#{msg.join}."
           send old, *args, &block
         end

data/lib/active_model_serializers/deserialization.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveModelSerializers
   module Deserialization
     module_function
@@ -6,8 +8,10 @@ module ActiveModelSerializers
       Adapter::JsonApi::Deserialization.parse(*args)
     end
 
+    # :nocov:
     def jsonapi_parse!(*args)
       Adapter::JsonApi::Deserialization.parse!(*args)
     end
+    # :nocov:
   end
 end

data/lib/active_model_serializers/json_pointer.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveModelSerializers
   module JsonPointer
     module_function

data/lib/active_model_serializers/logging.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 ##
 # ActiveModelSerializers::Logging
 #

data/lib/active_model_serializers/lookup_chain.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module ActiveModelSerializers
+  module LookupChain
+    # Standard appending of Serializer to the resource name.
+    #
+    # Example:
+    #   Author => AuthorSerializer
+    BY_RESOURCE = lambda do |resource_class, _serializer_class, _namespace|
+      serializer_from(resource_class)
+    end
+
+    # Uses the namespace of the resource to find the serializer
+    #
+    # Example:
+    #  British::Author => British::AuthorSerializer
+    BY_RESOURCE_NAMESPACE = lambda do |resource_class, _serializer_class, _namespace|
+      resource_namespace = namespace_for(resource_class)
+      serializer_name = serializer_from(resource_class)
+
+      "#{resource_namespace}::#{serializer_name}"
+    end
+
+    # Uses the controller namespace of the resource to find the serializer
+    #
+    # Example:
+    #  Api::V3::AuthorsController => Api::V3::AuthorSerializer
+    BY_NAMESPACE = lambda do |resource_class, _serializer_class, namespace|
+      resource_name = resource_class_name(resource_class)
+      namespace ? "#{namespace}::#{resource_name}Serializer" : nil
+    end
+
+    # Allows for serializers to be defined in parent serializers
+    # - useful if a relationship only needs a different set of attributes
+    #   than if it were rendered independently.
+    #
+    # Example:
+    #   class BlogSerializer < ActiveModel::Serializer
+    #     class AuthorSerialier < ActiveModel::Serializer
+    #     ...
+    #     end
+    #
+    #     belongs_to :author
+    #     ...
+    #   end
+    #
+    #  The belongs_to relationship would be rendered with
+    #    BlogSerializer::AuthorSerialier
+    BY_PARENT_SERIALIZER = lambda do |resource_class, serializer_class, _namespace|
+      return if serializer_class == ActiveModel::Serializer
+
+      serializer_name = serializer_from(resource_class)
+      "#{serializer_class}::#{serializer_name}"
+    end
+
+    DEFAULT = [
+      BY_PARENT_SERIALIZER,
+      BY_NAMESPACE,
+      BY_RESOURCE_NAMESPACE,
+      BY_RESOURCE
+    ].freeze
+
+    module_function
+
+    def namespace_for(klass)
+      klass.name.deconstantize
+    end
+
+    def resource_class_name(klass)
+      klass.name.demodulize
+    end
+
+    def serializer_from_resource_name(name)
+      "#{name}Serializer"
+    end
+
+    def serializer_from(klass)
+      name = resource_class_name(klass)
+      serializer_from_resource_name(name)
+    end
+  end
+end

data/lib/active_model_serializers/model/caching.rb

@@ -0,0 +1,25 @@
+module ActiveModelSerializers
+  class Model
+    module Caching
+      extend ActiveSupport::Concern
+
+      included do
+        attr_writer :updated_at
+        attributes :id
+      end
+
+      # Defaults to the downcased model name and updated_at
+      def cache_key
+        ActiveSupport::Cache.expand_cache_key([
+          self.class.model_name.name.downcase,
+          "#{id}-#{updated_at.strftime('%Y%m%d%H%M%S%9N')}"
+        ].compact)
+      end
+
+      # Defaults to the time the serializer file was modified.
+      def updated_at
+        defined?(@updated_at) ? @updated_at : File.mtime(__FILE__)
+      end
+    end
+  end
+end

data/lib/active_model_serializers/model.rb

@@ -1,49 +1,132 @@
-# ActiveModelSerializers::Model is a convenient
-# serializable class to inherit from when making
-# serializable non-activerecord objects.
+# frozen_string_literal: true
+
+# ActiveModelSerializers::Model is a convenient superclass for making your models
+# from Plain-Old Ruby Objects (PORO). It also serves as a reference implementation
+# that satisfies ActiveModel::Serializer::Lint::Tests.
+require 'active_support/core_ext/hash'
 module ActiveModelSerializers
   class Model
-    include ActiveModel::Model
     include ActiveModel::Serializers::JSON
+    include ActiveModel::Model
 
-    attr_reader :attributes, :errors
+    # Declare names of attributes to be included in +attributes+ hash.
+    # Is only available as a class-method since the ActiveModel::Serialization mixin in Rails
+    # uses an +attribute_names+ local variable, which may conflict if we were to add instance methods here.
+    #
+    # @overload attribute_names
+    #   @return [Array<Symbol>]
+    class_attribute :attribute_names, instance_writer: false, instance_reader: false
+    # Initialize +attribute_names+ for all subclasses.  The array is usually
+    # mutated in the +attributes+ method, but can be set directly, as well.
+    self.attribute_names = []
 
-    def initialize(attributes = {})
-      @attributes = attributes
-      @errors = ActiveModel::Errors.new(self)
-      super
+    # Easily declare instance attributes with setters and getters for each.
+    #
+    # To initialize an instance, all attributes must have setters.
+    # However, the hash returned by +attributes+ instance method will ALWAYS
+    # be the value of the initial attributes, regardless of what accessors are defined.
+    # The only way to change the change the attributes after initialization is
+    # to mutate the +attributes+ directly.
+    # Accessor methods do NOT mutate the attributes.  (This is a bug).
+    #
+    # @note For now, the Model only supports the notion of 'attributes'.
+    #   In the tests, there is a special Model that also supports 'associations'. This is
+    #   important so that we can add accessors for values that should not appear in the
+    #   attributes hash when modeling associations. It is not yet clear if it
+    #   makes sense for a PORO to have associations outside of the tests.
+    #
+    # @overload attributes(names)
+    #   @param names [Array<String, Symbol>]
+    #   @param name [String, Symbol]
+    def self.attributes(*names)
+      self.attribute_names |= names.map(&:to_sym)
+      # Silence redefinition of methods warnings
+      ActiveModelSerializers.silence_warnings do
+        attr_accessor(*names)
+      end
     end
 
-    # Defaults to the downcased model name.
-    def id
-      attributes.fetch(:id) { self.class.name.downcase }
+    # Opt-in to breaking change
+    def self.derive_attributes_from_names_and_fix_accessors
+      unless included_modules.include?(DeriveAttributesFromNamesAndFixAccessors)
+        prepend(DeriveAttributesFromNamesAndFixAccessors)
+      end
     end
 
-    # Defaults to the downcased model name and updated_at
-    def cache_key
-      attributes.fetch(:cache_key) { "#{self.class.name.downcase}/#{id}-#{updated_at.strftime("%Y%m%d%H%M%S%9N")}" }
+    module DeriveAttributesFromNamesAndFixAccessors
+      def self.included(base)
+        # NOTE that +id+ will always be in +attributes+.
+        base.attributes :id
+      end
+
+      # Override the +attributes+ method so that the hash is derived from +attribute_names+.
+      #
+      # The fields in +attribute_names+ determines the returned hash.
+      # +attributes+ are returned frozen to prevent any expectations that mutation affects
+      # the actual values in the model.
+      def attributes
+        self.class.attribute_names.each_with_object({}) do |attribute_name, result|
+          result[attribute_name] = public_send(attribute_name).freeze
+        end.with_indifferent_access.freeze
+      end
     end
 
-    # Defaults to the time the serializer file was modified.
-    def updated_at
-      attributes.fetch(:updated_at) { File.mtime(__FILE__) }
+    # Support for validation and other ActiveModel::Errors
+    # @return [ActiveModel::Errors]
+    attr_reader :errors
+
+    # (see #updated_at)
+    attr_writer :updated_at
+
+    # The only way to change the attributes of an instance is to directly mutate the attributes.
+    # @example
+    #
+    #   model.attributes[:foo] = :bar
+    # @return [Hash]
+    attr_reader :attributes
+
+    # @param attributes [Hash]
+    def initialize(attributes = {})
+      attributes ||= {} # protect against nil
+      @attributes = attributes.symbolize_keys.with_indifferent_access
+      @errors = ActiveModel::Errors.new(self)
+      super
     end
 
-    def read_attribute_for_serialization(key)
-      if key == :id || key == 'id'
-        attributes.fetch(key) { id }
-      else
-        attributes[key]
+    # Defaults to the downcased model name.
+    # This probably isn't a good default, since it's not a unique instance identifier,
+    # but that's what is currently implemented \_('-')_/.
+    #
+    # @note Though +id+ is defined, it will only show up
+    #   in +attributes+ when it is passed in to the initializer or added to +attributes+,
+    #   such as <tt>attributes[:id] = 5</tt>.
+    # @return [String, Numeric, Symbol]
+    def id
+      attributes.fetch(:id) do
+        defined?(@id) ? @id : self.class.model_name.name && self.class.model_name.name.downcase
       end
     end
 
-    # The following methods are needed to be minimally implemented for ActiveModel::Errors
-    def self.human_attribute_name(attr, _options = {})
-      attr
+    # When not set, defaults to the time the file was modified.
+    #
+    # @note Though +updated_at+ and +updated_at=+ are defined, it will only show up
+    #   in +attributes+ when it is passed in to the initializer or added to +attributes+,
+    #   such as <tt>attributes[:updated_at] = Time.current</tt>.
+    # @return [String, Numeric, Time]
+    def updated_at
+      attributes.fetch(:updated_at) do
+        defined?(@updated_at) ? @updated_at : File.mtime(__FILE__)
+      end
     end
 
-    def self.lookup_ancestors
-      [self]
+    # To customize model behavior, this method must be redefined. However,
+    # there are other ways of setting the +cache_key+ a serializer uses.
+    # @return [String]
+    def cache_key
+      ActiveSupport::Cache.expand_cache_key([
+        self.class.model_name.name.downcase,
+        "#{id}-#{updated_at.strftime('%Y%m%d%H%M%S%9N')}"
+      ].compact)
     end
   end
 end

data/lib/active_model_serializers/railtie.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rails/railtie'
 require 'action_controller'
 require 'action_controller/railtie'
@@ -5,6 +7,8 @@ require 'action_controller/serialization'
 
 module ActiveModelSerializers
   class Railtie < Rails::Railtie
+    config.eager_load_namespaces << ActiveModelSerializers
+
     config.to_prepare do
       ActiveModel::Serializer.serializers_cache.clear
     end
@@ -23,7 +27,7 @@ module ActiveModelSerializers
     # This hook is run after the action_controller railtie has set the configuration
     # based on the *environment* configuration and before any config/initializers are run
     # and also before eager_loading (if enabled).
-    initializer 'active_model_serializers.set_configs', :after => 'action_controller.set_configs' do
+    initializer 'active_model_serializers.set_configs', after: 'action_controller.set_configs' do
       ActiveModelSerializers.logger = Rails.configuration.action_controller.logger
       ActiveModelSerializers.config.perform_caching = Rails.configuration.action_controller.perform_caching
       # We want this hook to run after the config has been set, even if ActionController has already loaded.
@@ -32,11 +36,13 @@ module ActiveModelSerializers
       end
     end
 
+    # :nocov:
     generators do |app|
       Rails::Generators.configure!(app.config.generators)
       Rails::Generators.hidden_namespaces.uniq!
       require 'generators/rails/resource_override'
     end
+    # :nocov:
 
     if Rails.env.test?
       ActionController::TestCase.send(:include, ActiveModelSerializers::Test::Schema)