active_model_serializers 0.10.0.rc3 → 0.10.0.rc4

data/lib/active_model/serializer/attribute.rb

@@ -0,0 +1,25 @@
+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/attributes.rb

@@ -0,0 +1,82 @@
+module ActiveModel
+  class Serializer
+    module Attributes
+      extend ActiveSupport::Concern
+
+      included do
+        with_options instance_writer: false, instance_reader: false do |serializer|
+          serializer.class_attribute :_attributes_data # @api private
+          self._attributes_data ||= {}
+        end
+
+        extend ActiveSupport::Autoload
+        autoload :Attribute
+
+        # Return the +attributes+ of +object+ as presented
+        # by the serializer.
+        def attributes(requested_attrs = nil, reload = false)
+          @attributes = nil if reload
+          @attributes ||= self.class._attributes_data.each_with_object({}) do |(key, attr), hash|
+            next if attr.excluded?(self)
+            next unless requested_attrs.nil? || requested_attrs.include?(key)
+            hash[key] = attr.value(self)
+          end
+        end
+      end
+
+      module ClassMethods
+        def inherited(base)
+          super
+          base._attributes_data = _attributes_data.dup
+        end
+
+        # @example
+        #   class AdminAuthorSerializer < ActiveModel::Serializer
+        #     attributes :id, :name, :recent_edits
+        def attributes(*attrs)
+          attrs = attrs.first if attrs.first.class == Array
+
+          attrs.each do |attr|
+            attribute(attr)
+          end
+        end
+
+        # @example
+        #   class AdminAuthorSerializer < ActiveModel::Serializer
+        #     attributes :id, :recent_edits
+        #     attribute :name, key: :title
+        #
+        #     attribute :full_name do
+        #       "#{object.first_name} #{object.last_name}"
+        #     end
+        #
+        #     def recent_edits
+        #       object.edits.last(5)
+        #     end
+        def attribute(attr, options = {}, &block)
+          key = options.fetch(:key, attr)
+          _attributes_data[key] = Attribute.new(attr, options, block)
+        end
+
+        # @api private
+        # keys of attributes
+        # @see Serializer::attribute
+        def _attributes
+          _attributes_data.keys
+        end
+
+        # @api private
+        # maps attribute value to explict key name
+        # @see Serializer::attribute
+        # @see Adapter::FragmentCache#fragment_serializer
+        def _attributes_keys
+          _attributes_data
+            .each_with_object({}) do |(key, attr), hash|
+              next if key == attr.name
+              hash[attr.name] = { key: key }
+            end
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/caching.rb

@@ -0,0 +1,100 @@
+module ActiveModel
+  class Serializer
+    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 object
+          serializer.class_attribute :_fragmented    # @api private : @see ::fragmented
+          serializer.class_attribute :_cache_key     # @api private : when present, is first item in cache_key
+          serializer.class_attribute :_cache_only    # @api private : when fragment caching, whitelists cached_attributes. Cannot combine with except
+          serializer.class_attribute :_cache_except  # @api private : when fragment caching, blacklists cached_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.fetch(cache_key, @klass._cache_options)
+          serializer.class_attribute :_cache_digest # @api private : Generated
+        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)
+          super
+          caller_line = caller[1]
+          base._cache_digest = digest_caller_file(caller_line)
+        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)
+          Digest::MD5.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
+
+        # @api private
+        # Used by FragmentCache on the CachedSerializer
+        #  to call attribute methods on the fragmented cached serializer.
+        def fragmented(serializer)
+          self._fragmented = serializer
+        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
+        #
+        # @params options [Hash] with valid keys:
+        #   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 = ActiveModelSerializers.config.cache_store if ActiveModelSerializers.config.perform_caching
+          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
+      end
+    end
+  end
+end

data/lib/active_model/serializer/collection_serializer.rb

@@ -0,0 +1,47 @@
+module ActiveModel
+  class Serializer
+    class CollectionSerializer
+      NoSerializerError = Class.new(StandardError)
+      include Enumerable
+      delegate :each, to: :@serializers
+
+      attr_reader :object, :root
+
+      def initialize(resources, options = {})
+        @root = options[:root]
+        @object = resources
+        @serializers = resources.map do |resource|
+          serializer_context_class = options.fetch(:serializer_context_class, ActiveModel::Serializer)
+          serializer_class = options.fetch(:serializer) { serializer_context_class.serializer_for(resource) }
+
+          if serializer_class.nil?
+            fail NoSerializerError, "No serializer found for resource: #{resource.inspect}"
+          else
+            serializer_class.new(resource, options.except(:serializer))
+          end
+        end
+      end
+
+      def json_key
+        root || derived_root
+      end
+
+      def paginated?
+        object.respond_to?(:current_page) &&
+          object.respond_to?(:total_pages) &&
+          object.respond_to?(:size)
+      end
+
+      protected
+
+      attr_reader :serializers
+
+      private
+
+      def derived_root
+        key = serializers.first.try(:json_key) || object.try(:name).try(:underscore)
+        key.try(:pluralize)
+      end
+    end
+  end
+end

data/lib/active_model/serializer/configuration.rb

@@ -4,10 +4,24 @@ module ActiveModel
       include ActiveSupport::Configurable
       extend ActiveSupport::Concern
 
+      # Configuration options may also be set in
+      # Serializers and Adapters
       included do |base|
-        base.config.array_serializer = ActiveModel::Serializer::ArraySerializer
-        base.config.adapter = :flatten_json
-        base.config.jsonapi_resource_type = :plural
+        config = base.config
+        config.collection_serializer = ActiveModel::Serializer::CollectionSerializer
+        config.serializer_lookup_enabled = true
+
+        def config.array_serializer=(collection_serializer)
+          self.collection_serializer = collection_serializer
+        end
+
+        def config.array_serializer
+          collection_serializer
+        end
+
+        config.adapter = :attributes
+        config.jsonapi_resource_type = :plural
+        config.schema_path = 'test/support/schemas'
       end
     end
   end

data/lib/active_model/serializer/field.rb

@@ -0,0 +1,56 @@
+module ActiveModel
+  class Serializer
+    # Holds all the meta-data about a field (i.e. attribute or association) as it was
+    # specified in the ActiveModel::Serializer class.
+    # Notice that the field block is evaluated in the context of the serializer.
+    Field = Struct.new(:name, :options, :block) do
+      # Compute the actual value of a field for a given serializer instance.
+      # @param [Serializer] The serializer instance for which the value is computed.
+      # @return [Object] value
+      #
+      # @api private
+      #
+      def value(serializer)
+        if block
+          serializer.instance_eval(&block)
+        else
+          serializer.read_attribute_for_serialization(name)
+        end
+      end
+
+      # Decide whether the field should be serialized by the given serializer instance.
+      # @param [Serializer] The serializer instance
+      # @return [Bool]
+      #
+      # @api private
+      #
+      def excluded?(serializer)
+        case condition_type
+        when :if
+          !serializer.public_send(condition)
+        when :unless
+          serializer.public_send(condition)
+        else
+          false
+        end
+      end
+
+      private
+
+      def condition_type
+        @condition_type ||=
+          if options.key?(:if)
+            :if
+          elsif options.key?(:unless)
+            :unless
+          else
+            :none
+          end
+      end
+
+      def condition
+        options[condition_type]
+      end
+    end
+  end
+end

data/lib/active_model/serializer/fieldset.rb

@@ -1,36 +1,27 @@
 module ActiveModel
   class Serializer
     class Fieldset
-      def initialize(fields, root = nil)
-        @root       = root
-        @raw_fields = fields
+      def initialize(fields)
+        @raw_fields = fields || {}
       end
 
       def fields
         @fields ||= parsed_fields
       end
 
-      def fields_for(serializer)
-        key = serializer.json_key
-        fields[key.to_sym] || fields[key.pluralize.to_sym]
+      def fields_for(type)
+        fields[type.singularize.to_sym] || fields[type.pluralize.to_sym]
       end
 
-      private
+      protected
 
-      ActiveModelSerializers.silence_warnings do
-        attr_reader :raw_fields, :root
-      end
+      attr_reader :raw_fields
+
+      private
 
       def parsed_fields
         if raw_fields.is_a?(Hash)
-          raw_fields.inject({}) { |h, (k, v)| h[k.to_sym] = v.map(&:to_sym); h }
-        elsif raw_fields.is_a?(Array)
-          if root.nil?
-            raise ArgumentError, 'The root argument must be specified if the fields argument is an array.'
-          end
-          hash = {}
-          hash[root.to_sym] = raw_fields.map(&:to_sym)
-          hash
+          raw_fields.each_with_object({}) { |(k, v), h| h[k.to_sym] = v.map(&:to_sym) }
         else
           {}
         end

data/lib/active_model/serializer/include_tree.rb

@@ -0,0 +1,111 @@
+module ActiveModel
+  class Serializer
+    # TODO: description of this class, and overview of how it's used
+    class IncludeTree
+      module Parsing
+        module_function
+
+        # Translates a comma separated list of dot separated paths (JSON API format) into a Hash.
+        #
+        # @example
+        #   `'posts.author, posts.comments.upvotes, posts.comments.author'`
+        #
+        #   would become
+        #
+        #   `{ posts: { author: {}, comments: { author: {}, upvotes: {} } } }`.
+        #
+        # @param [String] included
+        # @return [Hash] a Hash representing the same tree structure
+        def include_string_to_hash(included)
+          # TODO: Needs comment walking through the process of what all this is doing.
+          included.delete(' ').split(',').reduce({}) do |hash, path|
+            include_tree = path.split('.').reverse_each.reduce({}) { |a, e| { e.to_sym => a } }
+            hash.deep_merge!(include_tree)
+          end
+        end
+
+        # Translates the arguments passed to the include option into a Hash. The format can be either
+        # a String (see #include_string_to_hash), an Array of Symbols and Hashes, or a mix of both.
+        #
+        # @example
+        #  `posts: [:author, comments: [:author, :upvotes]]`
+        #
+        #  would become
+        #
+        #   `{ posts: { author: {}, comments: { author: {}, upvotes: {} } } }`.
+        #
+        # @example
+        #  `[:author, :comments => [:author]]`
+        #
+        #   would become
+        #
+        #   `{:author => {}, :comments => { author: {} } }`
+        #
+        # @param [Symbol, Hash, Array, String] included
+        # @return [Hash] a Hash representing the same tree structure
+        def include_args_to_hash(included)
+          case included
+          when Symbol
+            { included => {} }
+          when Hash
+            included.each_with_object({}) do |(key, value), hash|
+              hash[key] = include_args_to_hash(value)
+            end
+          when Array
+            included.reduce({}) { |a, e| a.deep_merge!(include_args_to_hash(e)) }
+          when String
+            include_string_to_hash(included)
+          else
+            {}
+          end
+        end
+      end
+
+      # Builds an IncludeTree from a comma separated list of dot separated paths (JSON API format).
+      # @example `'posts.author, posts.comments.upvotes, posts.comments.author'`
+      #
+      # @param [String] included
+      # @return [IncludeTree]
+      #
+      def self.from_string(included)
+        new(Parsing.include_string_to_hash(included))
+      end
+
+      # Translates the arguments passed to the include option into an IncludeTree.
+      # The format can be either a String (see #from_string), an Array of Symbols and Hashes, or a mix of both.
+      # @example `posts: [:author, comments: [:author, :upvotes]]`
+      #
+      # @param [Symbol, Hash, Array, String] included
+      # @return [IncludeTree]
+      #
+      def self.from_include_args(included)
+        return included if included.is_a?(IncludeTree)
+
+        new(Parsing.include_args_to_hash(included))
+      end
+
+      # @param [Hash] hash
+      def initialize(hash = {})
+        @hash = hash
+      end
+
+      def key?(key)
+        @hash.key?(key) || @hash.key?(:*) || @hash.key?(:**)
+      end
+
+      def [](key)
+        # TODO(beauby): Adopt a lazy caching strategy for generating subtrees.
+        case
+        when @hash.key?(key)
+          self.class.new(@hash[key])
+        when @hash.key?(:*)
+          self.class.new(@hash[:*])
+        when @hash.key?(:**)
+          self.class.new(:** => {})
+        else
+          nil
+        end
+      end
+    end
+  end
+end