active_model_serializers 0.8.3 → 0.10.0.rc5

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

@@ -0,0 +1,87 @@
+module ActiveModelSerializers
+  class CachedSerializer
+    UndefinedCacheKey = Class.new(StandardError)
+
+    def initialize(serializer)
+      @cached_serializer = serializer
+      @klass             = @cached_serializer.class
+    end
+
+    def cache_check(adapter_instance)
+      if cached?
+        @klass._cache.fetch(cache_key(adapter_instance), @klass._cache_options) do
+          yield
+        end
+      elsif fragment_cached?
+        FragmentCache.new(adapter_instance, @cached_serializer, adapter_instance.instance_options).fetch
+      else
+        yield
+      end
+    end
+
+    def cached?
+      @klass.cache_enabled?
+    end
+
+    def fragment_cached?
+      @klass.fragment_cache_enabled?
+    end
+
+    def cache_key(adapter_instance)
+      return @cache_key if defined?(@cache_key)
+
+      parts = []
+      parts << object_cache_key
+      parts << adapter_instance.cached_name
+      parts << @klass._cache_digest unless @klass._skip_digest?
+      @cache_key = parts.join('/')
+    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 @cached_serializer.object.respond_to?(:cache_key)
+        @cached_serializer.object.cache_key
+      elsif (cache_key = (@klass._cache_key || @klass._cache_options[:key]))
+        object_time_safe = @cached_serializer.object.updated_at
+        object_time_safe = object_time_safe.strftime('%Y%m%d%H%M%S%9N') if object_time_safe.respond_to?(:strftime)
+        "#{cache_key}/#{@cached_serializer.object.id}-#{object_time_safe}"
+      else
+        fail UndefinedCacheKey, "#{@cached_serializer.object.class} must define #cache_key, or the 'key:' option must be passed into '#{@klass}.cache'"
+      end
+    end
+
+    # find all cache_key for the collection_serializer
+    # @param serializers [ActiveModel::Serializer::CollectionSerializer]
+    # @param adapter_instance [ActiveModelSerializers::Adapter::Base]
+    # @param include_tree [ActiveModel::Serializer::IncludeTree]
+    # @return [Array] all cache_key of collection_serializer
+    def self.object_cache_keys(serializers, adapter_instance, include_tree)
+      cache_keys = []
+
+      serializers.each do |serializer|
+        cache_keys << object_cache_key(serializer, adapter_instance)
+
+        serializer.associations(include_tree).each do |association|
+          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 self.object_cache_key(serializer, adapter_instance)
+      return unless serializer.present? && serializer.object.present?
+
+      cached_serializer = new(serializer)
+      cached_serializer.cached? ? cached_serializer.cache_key(adapter_instance) : nil
+    end
+  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/fragment_cache.rb

@@ -0,0 +1,118 @@
+module ActiveModelSerializers
+  class FragmentCache
+    attr_reader :serializer
+
+    def initialize(adapter, serializer, options)
+      @instance_options = options
+      @adapter    = adapter
+      @serializer = serializer
+    end
+
+    # 1. Create a CachedSerializer and NonCachedSerializer from the serializer class
+    # 2. Serialize the above two with the given adapter
+    # 3. Pass their serializations to the adapter +::fragment_cache+
+    def fetch
+      object = serializer.object
+
+      # It will split the serializer into two, one that will be cached and one that will not
+      serializers = fragment_serializer
+
+      # Get serializable hash from both
+      cached_hash     = serialize(object, serializers[:cached])
+      non_cached_hash = serialize(object, serializers[:non_cached])
+
+      # Merge both results
+      adapter.fragment_cache(cached_hash, non_cached_hash)
+    end
+
+    protected
+
+    attr_reader :instance_options, :adapter
+
+    private
+
+    def serialize(object, serializer_class)
+      SerializableResource.new(
+        object,
+        serializer: serializer_class,
+        adapter: adapter.class
+      ).serializable_hash
+    end
+
+    # Given a hash of its cached and non-cached serializers
+    # 1. Determine cached attributes from serializer class options
+    # 2. Add cached attributes to cached Serializer
+    # 3. Add non-cached attributes to non-cached Serializer
+    def cache_attributes(serializers)
+      klass                 = serializer.class
+      attributes            = klass._attributes
+      cache_only            = klass._cache_only
+      cached_attributes     = cache_only ? cache_only : attributes - klass._cache_except
+      non_cached_attributes = attributes - cached_attributes
+      attributes_keys       = klass._attributes_keys
+
+      add_attributes_to_serializer(serializers[:cached], cached_attributes, attributes_keys)
+      add_attributes_to_serializer(serializers[:non_cached], non_cached_attributes, attributes_keys)
+    end
+
+    def add_attributes_to_serializer(serializer, attributes, attributes_keys)
+      attributes.each do |attribute|
+        options = attributes_keys[attribute] || {}
+        serializer.attribute(attribute, options)
+      end
+    end
+
+    # Given a resource name
+    # 1. Dynamically creates a CachedSerializer and NonCachedSerializer
+    #   for a given class 'name'
+    # 2. Call
+    #       CachedSerializer.cache(serializer._cache_options)
+    #       CachedSerializer.fragmented(serializer)
+    #       NonCachedSerializer.cache(serializer._cache_options)
+    # 3. Build a hash keyed to the +cached+ and +non_cached+ serializers
+    # 4. Call +cached_attributes+ on the serializer class and the above hash
+    # 5. Return the hash
+    #
+    # @example
+    #   When +name+ is <tt>User::Admin</tt>
+    #   creates the Serializer classes (if they don't exist).
+    #     CachedUser_AdminSerializer
+    #     NonCachedUser_AdminSerializer
+    #
+    def fragment_serializer
+      klass                 = serializer.class
+      serializer_class_name = to_valid_const_name(klass.name)
+
+      cached     = "Cached#{serializer_class_name}"
+      non_cached = "NonCached#{serializer_class_name}"
+
+      cached_serializer     = get_or_create_serializer(cached)
+      non_cached_serializer = get_or_create_serializer(non_cached)
+
+      klass._cache_options ||= {}
+      cache_key = klass._cache_key
+      klass._cache_options[:key] = cache_key if cache_key
+      cached_serializer.cache(klass._cache_options)
+
+      type = klass._type
+      cached_serializer.type(type)
+      non_cached_serializer.type(type)
+
+      non_cached_serializer.fragmented(serializer)
+      cached_serializer.fragmented(serializer)
+
+      serializers = { cached: cached_serializer, non_cached: non_cached_serializer }
+      cache_attributes(serializers)
+      serializers
+    end
+
+    def get_or_create_serializer(name)
+      return Object.const_get(name) if Object.const_defined?(name)
+      Object.const_set(name, Class.new(ActiveModel::Serializer))
+    end
+
+    def to_valid_const_name(name)
+      name.gsub('::', '_')
+    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