active_model_serializers 0.8.3 → 0.10.0

data/lib/active_model_serializers/adapter.rb

@@ -0,0 +1,92 @@
+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
+      def new(*args)
+        fail ArgumentError, 'Adapters inherit from Adapter::Base.' \
+          "Adapter.new called with args: '#{args.inspect}', from" \
+          "'caller[0]'."
+      end
+
+      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
+
+      # @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,55 @@
+##
+# 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,13 @@
+module ActiveModelSerializers
+  module Deserialization
+    module_function
+
+    def jsonapi_parse(*args)
+      Adapter::JsonApi::Deserialization.parse(*args)
+    end
+
+    def jsonapi_parse!(*args)
+      Adapter::JsonApi::Deserialization.parse!(*args)
+    end
+  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/key_transform.rb

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

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/model.rb

@@ -0,0 +1,49 @@
+# ActiveModelSerializers::Model is a convenient
+# serializable class to inherit from when making
+# serializable non-activerecord objects.
+module ActiveModelSerializers
+  class Model
+    include ActiveModel::Model
+    include ActiveModel::Serializers::JSON
+
+    attr_reader :attributes, :errors
+
+    def initialize(attributes = {})
+      @attributes = attributes
+      @errors = ActiveModel::Errors.new(self)
+      super
+    end
+
+    # Defaults to the downcased model name.
+    def id
+      attributes.fetch(:id) { self.class.name.downcase }
+    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")}" }
+    end
+
+    # Defaults to the time the serializer file was modified.
+    def updated_at
+      attributes.fetch(:updated_at) { File.mtime(__FILE__) }
+    end
+
+    def read_attribute_for_serialization(key)
+      if key == :id || key == 'id'
+        attributes.fetch(key) { id }
+      else
+        attributes[key]
+      end
+    end
+
+    # The following methods are needed to be minimally implemented for ActiveModel::Errors
+    def self.human_attribute_name(attr, _options = {})
+      attr
+    end
+
+    def self.lookup_ancestors
+      [self]
+    end
+  end
+end

data/lib/active_model_serializers/railtie.rb

@@ -0,0 +1,46 @@
+require 'rails/railtie'
+require 'action_controller'
+require 'action_controller/railtie'
+require 'action_controller/serialization'
+
+module ActiveModelSerializers
+  class Railtie < Rails::Railtie
+    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
+
+    generators do |app|
+      Rails::Generators.configure!(app.config.generators)
+      Rails::Generators.hidden_namespaces.uniq!
+      require 'generators/rails/resource_override'
+    end
+
+    if Rails.env.test?
+      ActionController::TestCase.send(:include, ActiveModelSerializers::Test::Schema)
+      ActionController::TestCase.send(:include, ActiveModelSerializers::Test::Serializer)
+    end
+  end
+end

data/lib/active_model_serializers/register_jsonapi_renderer.rb

@@ -0,0 +1,65 @@
+# Based on discussion in https://github.com/rails/rails/pull/23712#issuecomment-184977238,
+# the JSON API media type will have its own format/renderer.
+#
+# > We recommend the media type be registered on its own as jsonapi
+# when a jsonapi Renderer and deserializer (Http::Parameters::DEFAULT_PARSERS) are added.
+#
+# Usage:
+#
+# ActiveSupport.on_load(:action_controller) do
+#   require 'active_model_serializers/register_jsonapi_renderer'
+# end
+#
+# And then in controllers, use `render jsonapi: model` rather than `render json: model, adapter: :json_api`.
+#
+# For example, in a controller action, we can:
+# respond_to do |format|
+#   format.jsonapi { render jsonapi: model }
+# end
+#
+# or
+#
+# render jsonapi: model
+#
+# No wrapper format needed as it does not apply (i.e. no `wrap_parameters format: [jsonapi]`)
+
+module ActiveModelSerializers::Jsonapi
+  MEDIA_TYPE = 'application/vnd.api+json'.freeze
+  HEADERS = {
+    response: { 'CONTENT_TYPE'.freeze => MEDIA_TYPE },
+    request:  { 'ACCEPT'.freeze => MEDIA_TYPE }
+  }.freeze
+  module ControllerSupport
+    def serialize_jsonapi(json, options)
+      options[:adapter] = :json_api
+      options.fetch(:serialization_context) { options[:serialization_context] = ActiveModelSerializers::SerializationContext.new(request) }
+      get_serializer(json, options)
+    end
+  end
+end
+
+# actionpack/lib/action_dispatch/http/mime_types.rb
+Mime::Type.register ActiveModelSerializers::Jsonapi::MEDIA_TYPE, :jsonapi
+
+parsers = Rails::VERSION::MAJOR >= 5 ? ActionDispatch::Http::Parameters : ActionDispatch::ParamsParser
+media_type = Mime::Type.lookup(ActiveModelSerializers::Jsonapi::MEDIA_TYPE)
+
+# Proposal: should actually deserialize the JSON API params
+# to the hash format expected by `ActiveModel::Serializers::JSON`
+# actionpack/lib/action_dispatch/http/parameters.rb
+parsers::DEFAULT_PARSERS[media_type] = lambda do |body|
+  data = JSON.parse(body)
+  data = { :_json => data } unless data.is_a?(Hash)
+  data.with_indifferent_access
+end
+
+# ref https://github.com/rails/rails/pull/21496
+ActionController::Renderers.add :jsonapi do |json, options|
+  json = serialize_jsonapi(json, options).to_json(options) unless json.is_a?(String)
+  self.content_type ||= media_type
+  self.response_body = json
+end
+
+ActiveSupport.on_load(:action_controller) do
+  include ActiveModelSerializers::Jsonapi::ControllerSupport
+end

data/lib/active_model_serializers/serializable_resource.rb

@@ -0,0 +1,81 @@
+require 'set'
+
+module ActiveModelSerializers
+  class SerializableResource
+    ADAPTER_OPTION_KEYS = Set.new([:include, :fields, :adapter, :meta, :meta_key, :links, :serialization_context, :key_transform])
+    include ActiveModelSerializers::Logging
+
+    delegate :serializable_hash, :as_json, :to_json, to: :adapter
+    notify :serializable_hash, :render
+    notify :as_json, :render
+    notify :to_json, :render
+
+    # Primary interface to composing a resource with a serializer and adapter.
+    # @return the serializable_resource, ready for #as_json/#to_json/#serializable_hash.
+    def initialize(resource, options = {})
+      @resource = resource
+      @adapter_opts, @serializer_opts =
+        options.partition { |k, _| ADAPTER_OPTION_KEYS.include? k }.map { |h| Hash[h] }
+    end
+
+    def serialization_scope=(scope)
+      serializer_opts[:scope] = scope
+    end
+
+    def serialization_scope
+      serializer_opts[:scope]
+    end
+
+    def serialization_scope_name=(scope_name)
+      serializer_opts[:scope_name] = scope_name
+    end
+
+    # NOTE: if no adapter is available, returns the resource itself. (i.e. adapter is a no-op)
+    def adapter
+      @adapter ||= find_adapter
+    end
+    alias adapter_instance adapter
+
+    def find_adapter
+      return resource unless serializer?
+      ActiveModelSerializers::Adapter.create(serializer_instance, adapter_opts)
+    rescue ActiveModel::Serializer::CollectionSerializer::NoSerializerError
+      resource
+    end
+
+    def serializer_instance
+      @serializer_instance ||= serializer.new(resource, serializer_opts)
+    end
+
+    # Get serializer either explicitly :serializer or implicitly from resource
+    # Remove :serializer key from serializer_opts
+    # Replace :serializer key with :each_serializer if present
+    def serializer
+      @serializer ||=
+        begin
+          @serializer = serializer_opts.delete(:serializer)
+          @serializer ||= ActiveModel::Serializer.serializer_for(resource)
+
+          if serializer_opts.key?(:each_serializer)
+            serializer_opts[:serializer] = serializer_opts.delete(:each_serializer)
+          end
+          @serializer
+        end
+    end
+    alias serializer_class serializer
+
+    # True when no explicit adapter given, or explicit appear is truthy (non-nil)
+    # False when explicit adapter is falsy (nil or false)
+    def use_adapter?
+      !(adapter_opts.key?(:adapter) && !adapter_opts[:adapter])
+    end
+
+    def serializer?
+      use_adapter? && !serializer.nil?
+    end
+
+    protected
+
+    attr_reader :resource, :adapter_opts, :serializer_opts
+  end
+end