active_model_serializers 0.8.3 → 0.10.8

data/lib/active_model_serializers/adapter/null.rb

@@ -0,0 +1,9 @@
+module ActiveModelSerializers
+  module Adapter
+    class Null < Base
+      def serializable_hash(*)
+        {}
+      end
+    end
+  end
+end

data/lib/active_model_serializers/adapter.rb

@@ -0,0 +1,98 @@
+module ActiveModelSerializers
+  module Adapter
+    UnknownAdapterError = Class.new(ArgumentError)
+    ADAPTER_MAP = {} # rubocop:disable Style/MutableConstant
+    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)
+      end
+
+      def create(resource, options = {})
+        override = options.delete(:adapter)
+        klass = override ? adapter_class(override) : configured_adapter
+        klass.new(resource, options)
+      end
+
+      # @see ActiveModelSerializers::Adapter.lookup
+      def adapter_class(adapter)
+        ActiveModelSerializers::Adapter.lookup(adapter)
+      end
+
+      # @return [Hash<adapter_name, adapter_class>]
+      def adapter_map
+        ADAPTER_MAP
+      end
+
+      # @return [Array<Symbol>] list of adapter names
+      def adapters
+        adapter_map.keys.sort
+      end
+
+      # Adds an adapter 'klass' with 'name' to the 'adapter_map'
+      # Names are stringified and underscored
+      # @param name [Symbol, String, Class] name of the registered adapter
+      # @param klass [Class] adapter class itself, optional if name is the class
+      # @example
+      #     AMS::Adapter.register(:my_adapter, MyAdapter)
+      # @note The registered name strips out 'ActiveModelSerializers::Adapter::'
+      #   so that registering 'ActiveModelSerializers::Adapter::Json' and
+      #   'Json' will both register as 'json'.
+      def register(name, klass = name)
+        name = name.to_s.gsub(/\AActiveModelSerializers::Adapter::/, ''.freeze)
+        adapter_map[name.underscore] = klass
+        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]
+      def lookup(adapter)
+        # 1. return if is a class
+        return adapter if adapter.is_a?(Class)
+        adapter_name = adapter.to_s.underscore
+        # 2. return if registered
+        adapter_map.fetch(adapter_name) do
+          # 3. try to find adapter class from environment
+          adapter_class = find_by_name(adapter_name)
+          register(adapter_name, adapter_class)
+          adapter_class
+        end
+      rescue NameError, ArgumentError => e
+        failure_message =
+          "NameError: #{e.message}. Unknown adapter: #{adapter.inspect}. Valid adapters are: #{adapters}"
+        raise UnknownAdapterError, failure_message, e.backtrace
+      end
+
+      # @api private
+      def find_by_name(adapter_name)
+        adapter_name = adapter_name.to_s.classify.tr('API', 'Api')
+        "ActiveModelSerializers::Adapter::#{adapter_name}".safe_constantize ||
+          "ActiveModelSerializers::Adapter::#{adapter_name.pluralize}".safe_constantize or # rubocop:disable Style/AndOr
+          fail UnknownAdapterError
+      end
+      private :find_by_name
+    end
+
+    # Gotta be at the bottom to use the code above it :(
+    extend ActiveSupport::Autoload
+    autoload :Base
+    autoload :Null
+    autoload :Attributes
+    autoload :Json
+    autoload :JsonApi
+  end
+end

data/lib/active_model_serializers/callbacks.rb

@@ -0,0 +1,55 @@
+# Adapted from
+# https://github.com/rails/rails/blob/7f18ea14c8/activejob/lib/active_job/callbacks.rb
+require 'active_support/callbacks'
+
+module ActiveModelSerializers
+  # = ActiveModelSerializers Callbacks
+  #
+  # ActiveModelSerializers provides hooks during the life cycle of serialization and
+  # allow you to trigger logic. Available callbacks are:
+  #
+  # * <tt>around_render</tt>
+  #
+  module Callbacks
+    extend ActiveSupport::Concern
+    include ActiveSupport::Callbacks
+
+    included do
+      define_callbacks :render
+    end
+
+    # These methods will be included into any ActiveModelSerializers object, adding
+    # callbacks for +render+.
+    module ClassMethods
+      # Defines a callback that will get called around the render method,
+      # whether it is as_json, to_json, or serializable_hash
+      #
+      #   class ActiveModelSerializers::SerializableResource
+      #     include ActiveModelSerializers::Callbacks
+      #
+      #     around_render do |args, block|
+      #       tag_logger do
+      #         notify_render do
+      #           block.call(args)
+      #         end
+      #       end
+      #     end
+      #
+      #     def as_json
+      #       run_callbacks :render do
+      #         adapter.as_json
+      #       end
+      #     end
+      #     # Note: So that we can re-use the instrumenter for as_json, to_json, and
+      #     # serializable_hash, we aren't using the usual format, which would be:
+      #     # def render(args)
+      #     #   adapter.as_json
+      #     # end
+      #   end
+      #
+      def around_render(*filters, &blk)
+        set_callback(:render, :around, *filters, &blk)
+      end
+    end
+  end
+end

data/lib/active_model_serializers/deprecate.rb

@@ -0,0 +1,54 @@
+##
+# Provides a single method +deprecate+ to be used to declare when
+# something is going away.
+#
+#     class Legacy
+#       def self.klass_method
+#         # ...
+#       end
+#
+#       def instance_method
+#         # ...
+#       end
+#
+#       extend ActiveModelSerializers::Deprecate
+#       deprecate :instance_method, "ActiveModelSerializers::NewPlace#new_method"
+#
+#       class << self
+#         extend ActiveModelSerializers::Deprecate
+#         deprecate :klass_method, :none
+#       end
+#     end
+#
+# Adapted from https://github.com/rubygems/rubygems/blob/1591331/lib/rubygems/deprecate.rb
+module ActiveModelSerializers
+  module Deprecate
+    ##
+    # Simple deprecation method that deprecates +name+ by wrapping it up
+    # in a dummy method. It warns on each call to the dummy method
+    # telling the user of +replacement+ (unless +replacement+ is :none) that it is planned to go away.
+
+    def deprecate(name, replacement)
+      old = "_deprecated_#{name}"
+      alias_method old, name
+      class_eval do
+        define_method(name) do |*args, &block|
+          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(':')}"]
+          warn "#{msg.join}."
+          send old, *args, &block
+        end
+      end
+    end
+
+    def delegate_and_deprecate(method, delegee)
+      delegate method, to: delegee
+      deprecate method, "#{delegee.name}."
+    end
+
+    module_function :deprecate
+    module_function :delegate_and_deprecate
+  end
+end

data/lib/active_model_serializers/deserialization.rb

@@ -0,0 +1,15 @@
+module ActiveModelSerializers
+  module Deserialization
+    module_function
+
+    def jsonapi_parse(*args)
+      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

@@ -0,0 +1,14 @@
+module ActiveModelSerializers
+  module JsonPointer
+    module_function
+
+    POINTERS = {
+      attribute:    '/data/attributes/%s'.freeze,
+      primary_data: '/data%s'.freeze
+    }.freeze
+
+    def new(pointer_type, value = nil)
+      format(POINTERS[pointer_type], value)
+    end
+  end
+end

data/lib/active_model_serializers/logging.rb

@@ -0,0 +1,122 @@
+##
+# ActiveModelSerializers::Logging
+#
+#   https://github.com/rails/rails/blob/280654ef88/activejob/lib/active_job/logging.rb
+#
+module ActiveModelSerializers
+  module Logging
+    RENDER_EVENT = 'render.active_model_serializers'.freeze
+    extend ActiveSupport::Concern
+
+    included do
+      include ActiveModelSerializers::Callbacks
+      extend Macros
+      instrument_rendering
+    end
+
+    module ClassMethods
+      def instrument_rendering
+        around_render do |args, block|
+          tag_logger do
+            notify_render do
+              block.call(args)
+            end
+          end
+        end
+      end
+    end
+
+    # Macros that can be used to customize the logging of class or instance methods,
+    # by extending the class or its singleton.
+    #
+    # Adapted from:
+    #   https://github.com/rubygems/rubygems/blob/cb28f5e991/lib/rubygems/deprecate.rb
+    #
+    # Provides a single method +notify+ to be used to declare when
+    # something a method notifies, with the argument +callback_name+ of the notification callback.
+    #
+    #     class Adapter
+    #       def self.klass_method
+    #         # ...
+    #       end
+    #
+    #       def instance_method
+    #         # ...
+    #       end
+    #
+    #       include ActiveModelSerializers::Logging::Macros
+    #       notify :instance_method, :render
+    #
+    #       class << self
+    #         extend ActiveModelSerializers::Logging::Macros
+    #         notify :klass_method, :render
+    #       end
+    #     end
+    module Macros
+      ##
+      # Simple notify method that wraps up +name+
+      # in a dummy method. It notifies on with the +callback_name+ notifier on
+      # each call to the dummy method, telling what the current serializer and adapter
+      # are being rendered.
+      # Adapted from:
+      #   https://github.com/rubygems/rubygems/blob/cb28f5e991/lib/rubygems/deprecate.rb
+      def notify(name, callback_name)
+        class_eval do
+          old = "_notifying_#{callback_name}_#{name}"
+          alias_method old, name
+          define_method name do |*args, &block|
+            run_callbacks callback_name do
+              send old, *args, &block
+            end
+          end
+        end
+      end
+    end
+
+    def notify_render(*)
+      event_name = RENDER_EVENT
+      ActiveSupport::Notifications.instrument(event_name, notify_render_payload) do
+        yield
+      end
+    end
+
+    def notify_render_payload
+      {
+        serializer: serializer || ActiveModel::Serializer::Null,
+        adapter: adapter || ActiveModelSerializers::Adapter::Null
+      }
+    end
+
+    private
+
+    def tag_logger(*tags)
+      if ActiveModelSerializers.logger.respond_to?(:tagged)
+        tags.unshift 'active_model_serializers'.freeze unless logger_tagged_by_active_model_serializers?
+        ActiveModelSerializers.logger.tagged(*tags) { yield }
+      else
+        yield
+      end
+    end
+
+    def logger_tagged_by_active_model_serializers?
+      ActiveModelSerializers.logger.formatter.current_tags.include?('active_model_serializers'.freeze)
+    end
+
+    class LogSubscriber < ActiveSupport::LogSubscriber
+      def render(event)
+        info do
+          serializer = event.payload[:serializer]
+          adapter = event.payload[:adapter]
+          duration = event.duration.round(2)
+          "Rendered #{serializer.name} with #{adapter.class} (#{duration}ms)"
+        end
+      end
+
+      def logger
+        ActiveModelSerializers.logger
+      end
+    end
+  end
+end
+
+ActiveModelSerializers::Logging::LogSubscriber.attach_to :active_model_serializers

data/lib/active_model_serializers/lookup_chain.rb

@@ -0,0 +1,80 @@
+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.rb

@@ -0,0 +1,130 @@
+# 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::Serializers::JSON
+    include ActiveModel::Model
+
+    # 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 = []
+
+    # 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
+
+    # Opt-in to breaking change
+    def self.derive_attributes_from_names_and_fix_accessors
+      unless included_modules.include?(DeriveAttributesFromNamesAndFixAccessors)
+        prepend(DeriveAttributesFromNamesAndFixAccessors)
+      end
+    end
+
+    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
+
+    # 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
+
+    # 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
+
+    # 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
+
+    # 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

@@ -0,0 +1,50 @@
+require 'rails/railtie'
+require 'action_controller'
+require 'action_controller/railtie'
+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
+
+    initializer 'active_model_serializers.action_controller' do
+      ActiveSupport.on_load(:action_controller) do
+        include(::ActionController::Serialization)
+      end
+    end
+
+    initializer 'active_model_serializers.prepare_serialization_context' do
+      SerializationContext.url_helpers = Rails.application.routes.url_helpers
+      SerializationContext.default_url_options = Rails.application.routes.default_url_options
+    end
+
+    # 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
+      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.
+      ActiveSupport.on_load(:action_controller) do
+        ActiveModelSerializers.config.cache_store = ActionController::Base.cache_store
+      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)
+      ActionController::TestCase.send(:include, ActiveModelSerializers::Test::Serializer)
+    end
+  end
+end