active_model_serializers 0.10.0 → 0.10.9

data/docs/ARCHITECTURE.md

@@ -1,126 +0,0 @@
-[Back to Guides](README.md)
-
-This document focuses on architecture the 0.10.x version of ActiveModelSerializers. If you are interested in the architecture of the 0.8 or 0.9 versions,
-please refer to the [0.8 README](https://github.com/rails-api/active_model_serializers/blob/0-8-stable/README.md) or
-[0.9 README](https://github.com/rails-api/active_model_serializers/blob/0-9-stable/README.md).
-
-The original design is also available [here](https://github.com/rails-api/active_model_serializers/blob/d72b66d4c5355b0ff0a75a04895fcc4ea5b0c65e/README.textile).
-
-# ARCHITECTURE
-
-An **`ActiveModel::Serializer`** wraps a [serializable resource](https://github.com/rails/rails/blob/4-2-stable/activemodel/lib/active_model/serialization.rb)
-and exposes an `attributes` method, among a few others.
-It allows you to specify which attributes and associations should be represented in the serializatation of the resource.
-It requires an adapter to transform its attributes into a JSON document; it cannot be serialized itself.
-It may be useful to think of it as a
-[presenter](http://blog.steveklabnik.com/posts/2011-09-09-better-ruby-presenters).
-
-The **`ActiveModel::ArraySerializer`** represent a collection of resources as serializers
-and, if there is no serializer, primitives.
-
-The **`ActiveModel::Adapter`** describes the structure of the JSON document generated from a
-serializer. For example, the `Attributes` example represents each serializer as its
-unmodified attributes.  The `JsonApi` adapter represents the serializer as a [JSON
-API](http://jsonapi.org/) document.
-
-The **`ActiveModelSerializers::SerializableResource`** acts to coordinate the serializer(s) and adapter
-to an object that responds to `to_json`, and `as_json`.  It is used in the controller to
-encapsulate the serialization resource when rendered. However, it can also be used on its own
-to serialize a resource outside of a controller, as well.
-
-## Primitive handling
-
-Definitions: A primitive is usually a String or Array. There is no serializer
-defined for them; they will be serialized when the resource is converted to JSON (`as_json` or
-`to_json`).  (The below also applies for any object with no serializer.)
-
-ActiveModelSerializers doesn't handle primitives passed to `render json:` at all.
-
-However, when a primitive value is an attribute or in a collection,
-it is not modified.
-
-Internally, if no serializer can be found in the controller, the resource is not decorated by
-ActiveModelSerializers.
-
-If the collection serializer (ArraySerializer) cannot
-identify a serializer for a resource in its collection, it raises [`NoSerializerError`](https://github.com/rails-api/active_model_serializers/issues/1191#issuecomment-142327128)
-which is rescued in `ActiveModel::Serializer::Reflection#build_association` which sets
-the association value directly:
-
-```ruby
-reflection_options[:virtual_value] = association_value.try(:as_json) || association_value
-```
-
-(which is called by the adapter as `serializer.associations(*)`.)
-
-## How options are parsed
-
-High-level overview:
-
-- For a collection
-  - `:serializer` specifies the collection serializer and
-  - `:each_serializer` specifies the serializer for each resource in the collection.
-- For a single resource, the `:serializer` option is the resource serializer.
-- Options are partitioned in serializer options and adapter options.  Keys for adapter options are specified by
-    [`ADAPTER_OPTION_KEYS`](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/serializable_resource.rb#L5).
-    The remaining options are serializer options.
-
-Details:
-
-1. **ActionController::Serialization**
-  1. `serializable_resource = ActiveModelSerializers::SerializableResource.new(resource, options)`
-    1. `options` are partitioned into `adapter_opts` and everything else (`serializer_opts`).
-      The `adapter_opts`  keys are defined in `ActiveModelSerializers::SerializableResource::ADAPTER_OPTION_KEYS`.
-1. **ActiveModelSerializers::SerializableResource**
-  1. `if serializable_resource.serializer?` (there is a serializer for the resource, and an adapter is used.)
-    - Where `serializer?` is `use_adapter? && !!(serializer)`
-      - Where `use_adapter?`: 'True when no explicit adapter given, or explicit value is truthy (non-nil);
-        False when explicit adapter is falsy (nil or false)'
-      - Where `serializer`:
-        1. from explicit `:serializer` option, else
-        2. implicitly from resource `ActiveModel::Serializer.serializer_for(resource)`
-  1. A side-effect of checking `serializer` is:
-     - The `:serializer` option is removed from the serializer_opts hash
-     - If the `:each_serializer` option is present, it is removed from the serializer_opts hash and set as the `:serializer` option
-  1. The serializer and adapter are created as
-    1. `serializer_instance = serializer.new(resource, serializer_opts)`
-    2. `adapter_instance = ActiveModel::Serializer::Adapter.create(serializer_instance, adapter_opts)`
-1. **ActiveModel::Serializer::ArraySerializer#new**
-  1. If the `serializer_instance` was a `ArraySerializer` and the `:serializer` serializer_opts
-    is present, then [that serializer is passed into each resource](https://github.com/rails-api/active_model_serializers/blob/a54d237e2828fe6bab1ea5dfe6360d4ecc8214cd/lib/active_model/serializer/array_serializer.rb#L14-L16).
-1. **ActiveModel::Serializer#attributes** is used by the adapter to get the attributes for
-  resource as defined by the serializer.
-
-## What does a 'serializable resource' look like?
-
-- An `ActiveRecord::Base` object.
-- Any Ruby object that passes the
-  [Lint](http://www.rubydoc.info/github/rails-api/active_model_serializers/ActiveModel/Serializer/Lint/Tests)
-  [code](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer/lint.rb).
-
-ActiveModelSerializers provides a
-[`ActiveModelSerializers::Model`](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/model.rb),
-which is a simple serializable PORO (Plain-Old Ruby Object).
-
-ActiveModelSerializers::Model may be used either as a template, or in production code.
-
-```ruby
-class MyModel < ActiveModelSerializers::Model
-  attr_accessor :id, :name, :level
-end
-```
-
-The default serializer for `MyModel` would be `MyModelSerializer` whether MyModel is an
-ActiveRecord::Base object or not.
-
-Outside of the controller the rules are **exactly** the same as for records. For example:
-
-```ruby
-render json: MyModel.new(level: 'awesome'), adapter: :json
-```
-
-would be serialized the same as
-
-```ruby
-ActiveModelSerializers::SerializableResource.new(MyModel.new(level: 'awesome'), adapter: :json).as_json
-```

data/lib/active_model/serializer/associations.rb

@@ -1,100 +0,0 @@
-module ActiveModel
-  class Serializer
-    # Defines an association in the object should be rendered.
-    #
-    # The serializer object should implement the association name
-    # as a method which should return an array when invoked. If a method
-    # with the association name does not exist, the association name is
-    # dispatched to the serialized object.
-    #
-    module Associations
-      extend ActiveSupport::Concern
-
-      DEFAULT_INCLUDE_TREE = ActiveModel::Serializer::IncludeTree.from_string('*')
-
-      included do
-        with_options instance_writer: false, instance_reader: true do |serializer|
-          serializer.class_attribute :_reflections
-          self._reflections ||= []
-        end
-
-        extend ActiveSupport::Autoload
-        autoload :Association
-        autoload :Reflection
-        autoload :SingularReflection
-        autoload :CollectionReflection
-        autoload :BelongsToReflection
-        autoload :HasOneReflection
-        autoload :HasManyReflection
-      end
-
-      module ClassMethods
-        def inherited(base)
-          super
-          base._reflections = _reflections.dup
-        end
-
-        # @param [Symbol] name of the association
-        # @param [Hash<Symbol => any>] options for the reflection
-        # @return [void]
-        #
-        # @example
-        #  has_many :comments, serializer: CommentSummarySerializer
-        #
-        def has_many(name, options = {}, &block)
-          associate(HasManyReflection.new(name, options, block))
-        end
-
-        # @param [Symbol] name of the association
-        # @param [Hash<Symbol => any>] options for the reflection
-        # @return [void]
-        #
-        # @example
-        #  belongs_to :author, serializer: AuthorSerializer
-        #
-        def belongs_to(name, options = {}, &block)
-          associate(BelongsToReflection.new(name, options, block))
-        end
-
-        # @param [Symbol] name of the association
-        # @param [Hash<Symbol => any>] options for the reflection
-        # @return [void]
-        #
-        # @example
-        #  has_one :author, serializer: AuthorSerializer
-        #
-        def has_one(name, options = {}, &block)
-          associate(HasOneReflection.new(name, options, block))
-        end
-
-        private
-
-        # Add reflection and define {name} accessor.
-        # @param [ActiveModel::Serializer::Reflection] reflection
-        # @return [void]
-        #
-        # @api private
-        #
-        def associate(reflection)
-          self._reflections << reflection
-        end
-      end
-
-      # @param [IncludeTree] include_tree (defaults to all associations when not provided)
-      # @return [Enumerator<Association>]
-      #
-      def associations(include_tree = DEFAULT_INCLUDE_TREE)
-        return unless object
-
-        Enumerator.new do |y|
-          self.class._reflections.each do |reflection|
-            next if reflection.excluded?(self)
-            key = reflection.options.fetch(:key, reflection.name)
-            next unless include_tree.key?(key)
-            y.yield reflection.build_association(self, instance_options)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/active_model/serializer/attributes.rb

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

@@ -1,7 +0,0 @@
-module ActiveModel
-  class Serializer
-    # @api private
-    class CollectionReflection < Reflection
-    end
-  end
-end

data/lib/active_model/serializer/configuration.rb

@@ -1,35 +0,0 @@
-module ActiveModel
-  class Serializer
-    module Configuration
-      include ActiveSupport::Configurable
-      extend ActiveSupport::Concern
-
-      # Configuration options may also be set in
-      # Serializers and Adapters
-      included do |base|
-        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.jsonapi_version = '1.0'
-        config.jsonapi_toplevel_meta = {}
-        # Make JSON API top-level jsonapi member opt-in
-        # ref: http://jsonapi.org/format/#document-top-level
-        config.jsonapi_include_toplevel_object = false
-        config.key_transform = nil
-
-        config.schema_path = 'test/support/schemas'
-      end
-    end
-  end
-end

data/lib/active_model/serializer/include_tree.rb

@@ -1,111 +0,0 @@
-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

data/lib/active_model/serializer/links.rb

@@ -1,35 +0,0 @@
-module ActiveModel
-  class Serializer
-    module Links
-      extend ActiveSupport::Concern
-
-      included do
-        with_options instance_writer: false, instance_reader: true do |serializer|
-          serializer.class_attribute :_links # @api private
-          self._links ||= {}
-        end
-
-        extend ActiveSupport::Autoload
-      end
-
-      module ClassMethods
-        def inherited(base)
-          super
-          base._links = _links.dup
-        end
-
-        # Define a link on a serializer.
-        # @example
-        #   link(:self) { resource_url(object) }
-        # @example
-        #   link(:self) { "http://example.com/resource/#{object.id}" }
-        # @example
-        #   link :resource, "http://example.com/resource"
-        #
-        def link(name, value = nil, &block)
-          _links[name] = block || value
-        end
-      end
-    end
-  end
-end

data/lib/active_model/serializer/meta.rb

@@ -1,29 +0,0 @@
-module ActiveModel
-  class Serializer
-    module Meta
-      extend ActiveSupport::Concern
-
-      included do
-        with_options instance_writer: false, instance_reader: true do |serializer|
-          serializer.class_attribute :_meta # @api private
-        end
-
-        extend ActiveSupport::Autoload
-      end
-
-      module ClassMethods
-        # Set the JSON API meta attribute of a serializer.
-        # @example
-        #   class AdminAuthorSerializer < ActiveModel::Serializer
-        #     meta { stuff: 'value' }
-        # @example
-        #     meta do
-        #       { comment_count: object.comments.count }
-        #     end
-        def meta(value = nil, &block)
-          self._meta = block || value
-        end
-      end
-    end
-  end
-end

data/lib/active_model/serializer/singular_reflection.rb

@@ -1,7 +0,0 @@
-module ActiveModel
-  class Serializer
-    # @api private
-    class SingularReflection < Reflection
-    end
-  end
-end

data/lib/active_model/serializer/type.rb

@@ -1,25 +0,0 @@
-module ActiveModel
-  class Serializer
-    module Type
-      extend ActiveSupport::Concern
-
-      included do
-        with_options instance_writer: false, instance_reader: true do |serializer|
-          serializer.class_attribute :_type # @api private
-        end
-
-        extend ActiveSupport::Autoload
-      end
-
-      module ClassMethods
-        # Set the JSON API type of a serializer.
-        # @example
-        #   class AdminAuthorSerializer < ActiveModel::Serializer
-        #     type 'authors'
-        def type(type)
-          self._type = type && type.to_s
-        end
-      end
-    end
-  end
-end

data/lib/active_model_serializers/key_transform.rb

@@ -1,70 +0,0 @@
-require 'active_support/core_ext/hash/keys'
-
-module ActiveModelSerializers
-  module KeyTransform
-    module_function
-
-    # Transforms values to UpperCamelCase or PascalCase.
-    #
-    # @example:
-    #    "some_key" => "SomeKey",
-    # @see {https://github.com/rails/rails/blob/master/activesupport/lib/active_support/inflector/methods.rb#L66-L76 ActiveSupport::Inflector.camelize}
-    def camel(value)
-      case value
-      when Hash then value.deep_transform_keys! { |key| camel(key) }
-      when Symbol then camel(value.to_s).to_sym
-      when String then value.underscore.camelize
-      else value
-      end
-    end
-
-    # Transforms values to camelCase.
-    #
-    # @example:
-    #    "some_key" => "someKey",
-    # @see {https://github.com/rails/rails/blob/master/activesupport/lib/active_support/inflector/methods.rb#L66-L76 ActiveSupport::Inflector.camelize}
-    def camel_lower(value)
-      case value
-      when Hash then value.deep_transform_keys! { |key| camel_lower(key) }
-      when Symbol then camel_lower(value.to_s).to_sym
-      when String then value.underscore.camelize(:lower)
-      else value
-      end
-    end
-
-    # Transforms values to dashed-case.
-    # This is the default case for the JsonApi adapter.
-    #
-    # @example:
-    #    "some_key" => "some-key",
-    # @see {https://github.com/rails/rails/blob/master/activesupport/lib/active_support/inflector/methods.rb#L185-L187 ActiveSupport::Inflector.dasherize}
-    def dash(value)
-      case value
-      when Hash then value.deep_transform_keys! { |key| dash(key) }
-      when Symbol then dash(value.to_s).to_sym
-      when String then value.underscore.dasherize
-      else value
-      end
-    end
-
-    # Transforms values to underscore_case.
-    # This is the default case for deserialization in the JsonApi adapter.
-    #
-    # @example:
-    #    "some-key" => "some_key",
-    # @see {https://github.com/rails/rails/blob/master/activesupport/lib/active_support/inflector/methods.rb#L89-L98 ActiveSupport::Inflector.underscore}
-    def underscore(value)
-      case value
-      when Hash then value.deep_transform_keys! { |key| underscore(key) }
-      when Symbol then underscore(value.to_s).to_sym
-      when String then value.underscore
-      else value
-      end
-    end
-
-    # Returns the value unaltered
-    def unaltered(value)
-      value
-    end
-  end
-end