active_model_serializers 0.9.0 → 0.10.12

data/lib/active_model/serializer/adapter.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+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'

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveModel
+  class Serializer
+    module Adapter
+      class Attributes < DelegateClass(ActiveModelSerializers::Adapter::Attributes)
+        def initialize(serializer, options = {})
+          super(ActiveModelSerializers::Adapter::Attributes.new(serializer, options))
+        end
+        class << self
+          extend ActiveModelSerializers::Deprecate
+          deprecate :new, 'ActiveModelSerializers::Adapter::Json.'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActiveModel
+  class Serializer
+    module Adapter
+      class Base < DelegateClass(ActiveModelSerializers::Adapter::Base)
+        class << self
+          extend ActiveModelSerializers::Deprecate
+          deprecate :inherited, 'ActiveModelSerializers::Adapter::Base.'
+        end
+
+        # :nocov:
+        def initialize(serializer, options = {})
+          super(ActiveModelSerializers::Adapter::Base.new(serializer, options))
+        end
+        # :nocov:
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveModel
+  class Serializer
+    module Adapter
+      class Json < DelegateClass(ActiveModelSerializers::Adapter::Json)
+        def initialize(serializer, options = {})
+          super(ActiveModelSerializers::Adapter::Json.new(serializer, options))
+        end
+        class << self
+          extend ActiveModelSerializers::Deprecate
+          deprecate :new, 'ActiveModelSerializers::Adapter::Json.new'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveModel
+  class Serializer
+    module Adapter
+      class JsonApi < DelegateClass(ActiveModelSerializers::Adapter::JsonApi)
+        def initialize(serializer, options = {})
+          super(ActiveModelSerializers::Adapter::JsonApi.new(serializer, options))
+        end
+        class << self
+          extend ActiveModelSerializers::Deprecate
+          deprecate :new, 'ActiveModelSerializers::Adapter::JsonApi.new'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveModel
+  class Serializer
+    module Adapter
+      class Null < DelegateClass(ActiveModelSerializers::Adapter::Null)
+        def initialize(serializer, options = {})
+          super(ActiveModelSerializers::Adapter::Null.new(serializer, options))
+        end
+        class << self
+          extend ActiveModelSerializers::Deprecate
+          deprecate :new, 'ActiveModelSerializers::Adapter::Null.new'
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/array_serializer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'active_model/serializer/collection_serializer'
+
+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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'active_model/serializer/lazy_association'
+
+module ActiveModel
+  class Serializer
+    # This class holds all information about serializer's association.
+    #
+    # @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
+        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/attribute.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'active_model/serializer/field'
+
+module ActiveModel
+  class Serializer
+    # Holds all the meta-data about an attribute as it was specified in the
+    # ActiveModel::Serializer class.
+    #
+    # @example
+    #   class PostSerializer < ActiveModel::Serializer
+    #     attribute :content
+    #     attribute :name, key: :title
+    #     attribute :email, key: :author_email, if: :user_logged_in?
+    #     attribute :preview do
+    #       truncate(object.content)
+    #     end
+    #
+    #     def user_logged_in?
+    #       current_user.logged_in?
+    #     end
+    #   end
+    #
+    class Attribute < Field
+    end
+  end
+end

data/lib/active_model/serializer/belongs_to_reflection.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActiveModel
+  class Serializer
+    # @api private
+    class BelongsToReflection < Reflection
+      # @api private
+      def foreign_key_on
+        :self
+      end
+    end
+  end
+end

data/lib/active_model/serializer/collection_serializer.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module ActiveModel
+  class Serializer
+    class CollectionSerializer
+      include Enumerable
+      delegate :each, to: :@serializers
+
+      attr_reader :object, :root
+
+      def initialize(resources, options = {})
+        @object                  = resources
+        @options                 = options
+        @root                    = options[:root]
+        @serializers             = serializers_from_resources
+      end
+
+      def success?
+        true
+      end
+
+      # @api private
+      def serializable_hash(adapter_options, options, adapter_instance)
+        options[:include_directive] ||= ActiveModel::Serializer.include_directive_from_options(adapter_options)
+        options[:cached_attributes] ||= ActiveModel::Serializer.cache_read_multi(self, adapter_instance, options[:include_directive])
+        serializers.map do |serializer|
+          serializer.serializable_hash(adapter_options, 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,
+      # we have no simple way to know that it is safe to call that instance method.
+      # (which is really a class property at this point, anyhow).
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # Disabling cop since it's good to highlight the complexity of this method by
+      # including all the logic right here.
+      def json_key
+        return root if root
+        # 1. get from options[:serializer] for empty resource collection
+        key = object.empty? &&
+          (explicit_serializer_class = options[:serializer]) &&
+          explicit_serializer_class._type
+        # 2. get from first serializer instance in collection
+        key ||= (serializer = serializers.first) && serializer.json_key
+        # 3. get from collection name, if a named collection
+        key ||= object.respond_to?(:name) ? object.name && object.name.underscore : nil
+        # 4. key may be nil for empty collection and no serializer option
+        key &&= key.pluralize
+        # 5. fail if the key cannot be determined
+        key || fail(ArgumentError, 'Cannot infer root key from collection type. Please specify the root or each_serializer option, or render a JSON String')
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+
+      def paginated?
+        ActiveModelSerializers.config.jsonapi_pagination_links_enabled &&
+          object.respond_to?(:current_page) &&
+          object.respond_to?(:total_pages) &&
+          object.respond_to?(:size)
+      end
+
+      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

data/lib/active_model/serializer/concerns/caching.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module ActiveModel
+  class Serializer
+    UndefinedCacheKey = Class.new(StandardError)
+    module Caching
+      extend ActiveSupport::Concern
+
+      included do
+        with_options instance_writer: false, instance_reader: false do |serializer|
+          serializer.class_attribute :_cache         # @api private : the cache store
+          serializer.class_attribute :_cache_key     # @api private : when present, is first item in cache_key.  Ignored if the serializable object defines #cache_key.
+          serializer.class_attribute :_cache_only    # @api private : when fragment caching, whitelists fetch_attributes. Cannot combine with except
+          serializer.class_attribute :_cache_except  # @api private : when fragment caching, blacklists fetch_attributes. Cannot combine with only
+          serializer.class_attribute :_cache_options # @api private : used by CachedSerializer, passed to _cache.fetch
+          #  _cache_options include:
+          #    expires_in
+          #    compress
+          #    force
+          #    race_condition_ttl
+          #  Passed to ::_cache as
+          #    serializer.cache_store.fetch(cache_key, @klass._cache_options)
+          #  Passed as second argument to serializer.cache_store.fetch(cache_key, serializer_class._cache_options)
+          serializer.class_attribute :_cache_digest_file_path # @api private : Derived at inheritance
+        end
+      end
+
+      # Matches
+      #  "c:/git/emberjs/ember-crm-backend/app/serializers/lead_serializer.rb:1:in `<top (required)>'"
+      #  AND
+      #  "/c/git/emberjs/ember-crm-backend/app/serializers/lead_serializer.rb:1:in `<top (required)>'"
+      #  AS
+      #  c/git/emberjs/ember-crm-backend/app/serializers/lead_serializer.rb
+      CALLER_FILE = /
+        \A       # start of string
+        .+       # file path (one or more characters)
+        (?=      # stop previous match when
+          :\d+     # a colon is followed by one or more digits
+          :in      # followed by a colon followed by in
+        )
+      /x
+
+      module ClassMethods
+        def inherited(base)
+          caller_line = caller[1]
+          base._cache_digest_file_path = caller_line
+          super
+        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+
+        def digest_caller_file(caller_line)
+          serializer_file_path = caller_line[CALLER_FILE]
+          serializer_file_contents = IO.read(serializer_file_path)
+          algorithm = ActiveModelSerializers.config.use_sha1_digests ? Digest::SHA1 : Digest::MD5
+          algorithm.hexdigest(serializer_file_contents)
+        rescue TypeError, Errno::ENOENT
+          warn <<-EOF.strip_heredoc
+            Cannot digest non-existent file: '#{caller_line}'.
+            Please set `::_cache_digest` of the serializer
+            if you'd like to cache it.
+            EOF
+          ''.freeze
+        end
+
+        def _skip_digest?
+          _cache_options && _cache_options[:skip_digest]
+        end
+
+        # @api private
+        # maps attribute value to explicit key name
+        # @see Serializer::attribute
+        # @see Serializer::fragmented_attributes
+        def _attributes_keys
+          _attributes_data
+            .each_with_object({}) do |(key, attr), hash|
+            next if key == attr.name
+            hash[attr.name] = { key: key }
+          end
+        end
+
+        def fragmented_attributes
+          cached = _cache_only ? _cache_only : _attributes - _cache_except
+          cached = cached.map! { |field| _attributes_keys.fetch(field, field) }
+          non_cached = _attributes - cached
+          non_cached = non_cached.map! { |field| _attributes_keys.fetch(field, field) }
+          {
+            cached: cached,
+            non_cached: non_cached
+          }
+        end
+
+        # Enables a serializer to be automatically cached
+        #
+        # Sets +::_cache+ object to <tt>ActionController::Base.cache_store</tt>
+        #   when Rails.configuration.action_controller.perform_caching
+        #
+        # @param options [Hash] with valid keys:
+        #   cache_store    : @see ::_cache
+        #   key            : @see ::_cache_key
+        #   only           : @see ::_cache_only
+        #   except         : @see ::_cache_except
+        #   skip_digest    : does not include digest in cache_key
+        #   all else       : @see ::_cache_options
+        #
+        # @example
+        #   class PostSerializer < ActiveModel::Serializer
+        #     cache key: 'post', expires_in: 3.hours
+        #     attributes :title, :body
+        #
+        #     has_many :comments
+        #   end
+        #
+        # @todo require less code comments. See
+        # https://github.com/rails-api/active_model_serializers/pull/1249#issuecomment-146567837
+        def cache(options = {})
+          self._cache =
+            options.delete(:cache_store) ||
+            ActiveModelSerializers.config.cache_store ||
+            ActiveSupport::Cache.lookup_store(:null_store)
+          self._cache_key = options.delete(:key)
+          self._cache_only = options.delete(:only)
+          self._cache_except = options.delete(:except)
+          self._cache_options = options.empty? ? nil : options
+        end
+
+        # Value is from ActiveModelSerializers.config.perform_caching. Is used to
+        # globally enable or disable all serializer caching, just like
+        # Rails.configuration.action_controller.perform_caching, which is its
+        # default value in a Rails application.
+        # @return [true, false]
+        # Memoizes value of config first time it is called with a non-nil value.
+        # rubocop:disable Style/ClassVars
+        def perform_caching
+          return @@perform_caching if defined?(@@perform_caching) && !@@perform_caching.nil?
+          @@perform_caching = ActiveModelSerializers.config.perform_caching
+        end
+        alias perform_caching? perform_caching
+        # rubocop:enable Style/ClassVars
+
+        # The canonical method for getting the cache store for the serializer.
+        #
+        # @return [nil] when _cache is not set (i.e. when `cache` has not been called)
+        # @return [._cache] when _cache is not the NullStore
+        # @return [ActiveModelSerializers.config.cache_store] when _cache is the NullStore.
+        #   This is so we can use `cache` being called to mean the serializer should be cached
+        #   even if ActiveModelSerializers.config.cache_store has not yet been set.
+        #   That means that when _cache is the NullStore and ActiveModelSerializers.config.cache_store
+        #   is configured, `cache_store` becomes `ActiveModelSerializers.config.cache_store`.
+        # @return [nil] when _cache is the NullStore and ActiveModelSerializers.config.cache_store is nil.
+        def cache_store
+          return nil if _cache.nil?
+          return _cache if _cache.class != ActiveSupport::Cache::NullStore
+          if ActiveModelSerializers.config.cache_store
+            self._cache = ActiveModelSerializers.config.cache_store
+          else
+            nil
+          end
+        end
+
+        def cache_enabled?
+          perform_caching? && cache_store && !_cache_only && !_cache_except
+        end
+
+        def fragment_cache_enabled?
+          perform_caching? && cache_store &&
+            (_cache_only && !_cache_except || !_cache_only && _cache_except)
+        end
+
+        # Read cache from cache_store
+        # @return [Hash]
+        # Used in CollectionSerializer to set :cached_attributes
+        def cache_read_multi(collection_serializer, adapter_instance, include_directive)
+          return {} if ActiveModelSerializers.config.cache_store.blank?
+
+          keys = object_cache_keys(collection_serializer, adapter_instance, include_directive)
+
+          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_directive [JSONAPI::IncludeDirective]
+        # @return [Array] all cache_key of collection_serializer
+        def object_cache_keys(collection_serializer, adapter_instance, include_directive)
+          cache_keys = []
+
+          collection_serializer.each do |serializer|
+            cache_keys << object_cache_key(serializer, adapter_instance)
+
+            serializer.associations(include_directive).each do |association|
+              # TODO(BF): Process relationship without evaluating lazy_association
+              association_serializer = association.lazy_association.serializer
+              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.class.fragment_cache_enabled?) ? serializer.cache_key(adapter_instance) : nil
+        end
+      end
+
+      ### INSTANCE METHODS
+      def fetch_attributes(fields, cached_attributes, adapter_instance)
+        key = cache_key(adapter_instance)
+        cached_attributes.fetch(key) do
+          fetch(adapter_instance, serializer_class._cache_options, key) do
+            attributes(fields, true)
+          end
+        end
+      end
+
+      def fetch(adapter_instance, cache_options = serializer_class._cache_options, key = nil)
+        if serializer_class.cache_store
+          key ||= cache_key(adapter_instance)
+          serializer_class.cache_store.fetch(key, cache_options) do
+            yield
+          end
+        else
+          yield
+        end
+      end
+
+      # 1. Determine cached fields from serializer class options
+      # 2. Get non_cached_fields and fetch cache_fields
+      # 3. Merge the two hashes using adapter_instance#fragment_cache
+      def fetch_attributes_fragment(adapter_instance, cached_attributes = {})
+        serializer_class._cache_options ||= {}
+        serializer_class._cache_options[:key] = serializer_class._cache_key if serializer_class._cache_key
+        fields = serializer_class.fragmented_attributes
+
+        non_cached_fields = fields[:non_cached].dup
+        non_cached_hash = attributes(non_cached_fields, true)
+        include_directive = JSONAPI::IncludeDirective.new(non_cached_fields - non_cached_hash.keys)
+        non_cached_hash.merge! associations_hash({}, { include_directive: include_directive }, adapter_instance)
+
+        cached_fields = fields[:cached].dup
+        key = cache_key(adapter_instance)
+        cached_hash =
+          cached_attributes.fetch(key) do
+            fetch(adapter_instance, serializer_class._cache_options, key) do
+              hash = attributes(cached_fields, true)
+              include_directive = JSONAPI::IncludeDirective.new(cached_fields - hash.keys)
+              hash.merge! associations_hash({}, { include_directive: include_directive }, adapter_instance)
+            end
+          end
+        # Merge both results
+        adapter_instance.fragment_cache(cached_hash, non_cached_hash)
+      end
+
+      def cache_key(adapter_instance)
+        return @cache_key if defined?(@cache_key)
+
+        parts = []
+        parts << object_cache_key
+        parts << adapter_instance.cache_key
+        parts << serializer_class._cache_digest unless serializer_class._skip_digest?
+        @cache_key = expand_cache_key(parts)
+      end
+
+      def expand_cache_key(parts)
+        ActiveSupport::Cache.expand_cache_key(parts)
+      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_with_version)
+          object.cache_key_with_version
+        elsif object.respond_to?(:cache_key)
+          object.cache_key
+        elsif (serializer_cache_key = (serializer_class._cache_key || serializer_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 '#{serializer_class}.cache'"
+        end
+      end
+
+      def serializer_class
+        @serializer_class ||= self.class
+      end
+    end
+  end
+end